# Cedar Design Web

> Vue 3 component library. Package: @cedar-design/ui. Component prefix: C / c-.

Read the quick start and the relevant component page before generating code. Follow the documented props, events, slots, imports and styles. Do not substitute APIs from another component library.


---

Document: llms/zh-CN/components/affix.md

<!-- Source: src/affix/README.md; locale: zh-CN; page: /components/affix/ -->

# Affix

与 Maple 使用相同场景、参数和交互顺序；示例源码仅替换组件前缀，主题与站点外壳各自保留。

## 基础示例

### 基础用法

Example source: src/affix/__demos__/basic.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const containerRef = ref<HTMLElement>()
</script>

<template>
  <p>Scroll inside the bordered area.</p>
  <div ref="containerRef" class="scroller">
    <div class="scroll-content">
      <c-affix :target="containerRef"><c-button status="primary">Basic usage</c-button></c-affix>
    </div>
  </div>
</template>

<style scoped>
.scroller {
  height: 200px;
  overflow: auto;
  border: 1px solid currentColor;
}
.scroll-content {
  min-height: 600px;
  padding: 16px;
}
</style>
```

## 布局与排列

### 吸附方向、偏移与容器

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `target` | 滚动容器或选择器；省略时寻找最近滚动父元素，找不到则使用 window | 吸附方向、偏移与容器 |
| `offset-top` | 相对滚动容器顶部的吸附距离，支持 CSS 长度 | 吸附方向、偏移与容器 |
| `offset-bottom` | 相对滚动容器底部的吸附距离；设置后优先于 offset-top，0 也有效 | 吸附方向、偏移与容器 |
<!-- demo-config-notes:end -->

分别滚动三个有边框的区域，比较顶部/底部吸附和不同偏移；每个预览独立指定滚动容器。

Example source: src/affix/__demos__/offset-container-comparison.vue

```vue
<script setup lang="ts">
import { ref } from "vue"
import { proxyRefs as demoProxyRefs } from 'vue'

const scene1 = demoProxyRefs((() => {

const containerRef = ref<HTMLElement>()
return { containerRef }
})())

const scene2 = demoProxyRefs((() => {

const containerRef = ref<HTMLElement>()
return { containerRef }
})())

const scene3 = demoProxyRefs((() => {

const containerRef = ref<HTMLElement>()
return { containerRef }
})())
</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="top">
    <h4><span lang="zh-CN">顶部偏移</span><span lang="en-US">Top offset</span></h4>
    <p>Scroll inside the bordered area.</p>
      <div :ref="element => (scene1.containerRef = element)" class="scroller">
        <div class="scroll-content">
          <c-affix :target="scene1.containerRef" :offset-top="80"
            ><c-button status="primary">Top offset</c-button></c-affix
          >
        </div>
      </div>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="bottom">
    <h4><span lang="zh-CN">底部偏移</span><span lang="en-US">Bottom offset</span></h4>
    <p>Scroll inside the bordered area.</p>
      <div :ref="element => (scene2.containerRef = element)" class="scroller">
        <div class="scroll-content">
          <div style="height: 240px"></div>
          <c-affix :target="scene2.containerRef" :offset-bottom="20"
            ><c-button status="primary">Bottom offset</c-button></c-affix
          >
        </div>
      </div>
  </section>

  <section class="demo-comparison-case demo-comparison-case--3" data-comparison-scene="container">
    <h4><span lang="zh-CN">指定滚动容器</span><span lang="en-US">Scroll container</span></h4>
    <p>Scroll inside the bordered area.</p>
      <div :ref="element => (scene3.containerRef = element)" class="scroller">
        <div class="scroll-content">
          <div style="height: 40px"></div>
          <c-affix :target="scene3.containerRef" :offset-top="20"
            ><c-button status="primary">Scroll container</c-button></c-affix
          >
        </div>
      </div>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }
.demo-comparison-case--1 {

.scroller {
  height: 200px;
  overflow: auto;
  border: 1px solid currentColor;
}
.scroll-content {
  min-height: 600px;
  padding: 16px;
}

}
.demo-comparison-case--2 {

.scroller {
  height: 200px;
  overflow: auto;
  border: 1px solid currentColor;
}
.scroll-content {
  min-height: 600px;
  padding: 16px;
}

}
.demo-comparison-case--3 {

.scroller {
  height: 200px;
  overflow: auto;
  border: 1px solid currentColor;
}
.scroll-content {
  min-height: 600px;
  padding: 16px;
}

}
</style>
```

## 交互与控制

### 吸附状态变化

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `target` | 滚动容器或选择器；省略时寻找最近滚动父元素，找不到则使用 window | 吸附状态变化、禁用、CSS 模式与手动更新 |
| `offset-top` | 相对滚动容器顶部的吸附距离，支持 CSS 长度 | 吸附状态变化、禁用、CSS 模式与手动更新 |
| `disabled` | 禁用吸附 | 禁用、CSS 模式与手动更新 |
| `css-mode` | 使用原生 position: sticky，受祖先 overflow 和容器边界影响 | 禁用、CSS 模式与手动更新 |
| `z-index` | 固钉层级 | 禁用、CSS 模式与手动更新 |
<!-- demo-config-notes:end -->

Example source: src/affix/__demos__/fix-change.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const containerRef = ref<HTMLElement>()
const fixed = ref(false)
</script>

<template>
  <p>Scroll inside the bordered area.</p>
  <div ref="containerRef" class="scroller">
    <div class="scroll-content">
      <div style="height: 40px"></div>
      <c-affix :target="containerRef" :offset-top="20" @change="fixed = $event"
        ><c-button status="primary">Change event</c-button></c-affix
      >
    </div>
  </div>
  <p role="status">Fixed: {{ fixed }}</p>
</template>

<style scoped>
.scroller {
  height: 200px;
  overflow: auto;
  border: 1px solid currentColor;
}
.scroll-content {
  min-height: 600px;
  padding: 16px;
}
</style>
```

上述示例通过 `target` 指定独立滚动容器，便于在 PC 页面和移动模拟器中复现；省略 `target` 时寻找最近滚动父元素，找不到则监听窗口。`offset-top` / `offset-bottom` 也接受 CSS 长度。

### 禁用、CSS 模式与手动更新

Example source: src/affix/__demos__/controls.vue

```vue
<script setup lang="ts">
import { nextTick, ref } from "vue";
const containerRef = ref<HTMLElement>();
const affixRef = ref<{ updatePosition: () => Promise<void> }>();
const disabled = ref(false);
const cssMode = ref(false);
const spacerHeight = ref(40);
const updates = ref(0);
async function updateLayout() {
  spacerHeight.value = spacerHeight.value === 40 ? 100 : 40;
  await nextTick();
  await affixRef.value?.updatePosition();
  updates.value++;
}
</script>

<template>
  <c-space wrap size="12px" style="margin-bottom: 12px">
    <c-checkbox v-model="disabled"> Disabled</c-checkbox>
    <c-checkbox v-model="cssMode"> CSS sticky</c-checkbox>
    <c-button @click="updateLayout">Change layout and update position</c-button>
  </c-space>
  <p aria-live="polite">Position updates: {{ updates }}</p>
  <div ref="containerRef" class="scroller">
    <div class="scroll-content">
      <div :style="{ height: `${spacerHeight}px` }"></div>
      <c-affix
        ref="affixRef"
        :target="containerRef"
        :disabled="disabled"
        :css-mode="cssMode"
        :offset-top="12"
        :z-index="2"
      >
        <c-button status="primary">Scroll to pin</c-button>
      </c-affix>
    </div>
  </div>
</template>

<style scoped>
.scroller {
  height: 200px;
  overflow: auto;
  border: 1px solid currentColor;
}
.scroll-content {
  min-height: 600px;
  padding: 16px;
}
</style>
```

## API

<!-- same-source-api:start -->
### Props

| 属性 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| offset-top | 相对滚动容器顶部的吸附距离，支持 CSS 长度 | `number / string` | `0` |
| offset-bottom | 相对滚动容器底部的吸附距离；设置后优先于 offset-top，0 也有效 | `number / string` | `undefined` |
| target | 滚动容器或选择器；省略时寻找最近滚动父元素，找不到则使用 window | `string / HTMLElement / Window` | `undefined` |
| target-container | 额外监听的外层滚动容器或选择器；不传则不额外监听，也不作为裁剪边界 | `string / HTMLElement / Window` | `undefined` |
| z-index | 固钉层级 | `number / string` | `10` |
| disabled | 禁用吸附 | `boolean` | `false` |
| css-mode | 使用原生 position: sticky，受祖先 overflow 和容器边界影响 | `boolean` | `false` |

### Events

| 事件 | 参数与时机 |
| --- | --- |
| change | `(fixed: boolean, offset: number)`，固定状态变化时触发；固定时 offset 为吸附阈值，未固定时为距离对应容器边缘的距离，禁用解除固定时为 0 |

### Slots

| 插槽 | 说明 | 参数 |
| --- | --- | --- |
| default | 需要吸附的内容 | — |

### Methods

| 方法 | 说明 | 参数 | 返回值 |
| --- | --- | --- | --- |
| updatePosition | 下一动画帧重新绑定滚动容器并计算位置 | — | `Promise<void>` |

### 跨端说明

属性、事件参数、插槽与公开方法一致。CSS 模式遵循浏览器 sticky 规则；示例统一使用独立滚动容器。
<!-- same-source-api:end -->

### 类型定义

组件导出以下类型定义

```ts
import type { AffixInstance } from '@cedar-design/ui'
```

`change` 只通知固定状态变化：已固定时重复测量不重复发送 true，禁用解除固定发送 false、0。视口单位随测量重新求值。CSS 模式将有效长度交给原生 sticky；JS 模式解析数字、数值字符串、px、rem、vw、vh、vmin、vmax。target 控制监听及 JS 测量，原生 sticky 仍受实际 CSS 祖先约束。停用后，待完成的 `updatePosition()` 不会恢复旧激活代次的监听。

---

Document: llms/zh-CN/components/alert.md

<!-- Source: src/alert/README.md; locale: zh-CN; page: /components/alert/ -->

# Alert

向用户显示警告的信息时，通过警告提示，展现需要关注的信息。

## 基础示例

### 基础用法

展现需要关注的信息，适用于简短的警告提示。

Example source: src/alert/__demos__/basic.vue

```vue
<template>
  <c-alert>This is an info alert.</c-alert>
</template>

<script lang="ts" setup>
</script>
```

## 外观与状态

### 外观配置对比

选择一个对比维度后，同屏展示它的全部可选值；其余配置和内容保持一致。可切换其他配置检查组合效果；输入类预览共享一个值。

<details>
<summary>配置说明与使用限制</summary>

#### 视觉变体

`variant` 支持 `standard`（默认，浅色填充 + 描边）、`tonal`（浅色填充无描边）、`outline`（透明背景 + 描边）。

#### 外观组合

适用于提示信息的强调程度。调整变体、状态，用相同数据观察变化。内容保持一致，便于比较不同设置的实际效果。

#### 提示类型

警告提示有 `info`、`success`、`warning`、`danger`、`default` 五种类型。`default` 类型下默认不展示图标，可通过 `#icon` 插槽自定义。

</details>

Example source: src/alert/__demos__/appearance-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";

const __demoAppearance = __demoReactive({
  variant: "tonal",
  status: "default",
});

import { computed as demoComputed, ref as demoRef } from 'vue'
const demoCompareFields = [{"name":"variant","values":["tonal","outline","standard"]},{"name":"status","values":["info","success","warning","danger","default"]}]
const demoCompareAxis = demoRef("variant")
const demoComparedOptions = demoComputed(() => demoCompareFields.find(field => field.name === demoCompareAxis.value)?.values ?? [])
</script>
<template>
  <c-space direction="column" :size="16">
    <c-form layout="vertical">
      <c-form-item layout="vertical" size="sm" label="variant">
        <c-radio-group
          v-model="__demoAppearance['variant']"
          aria-label="variant"
          :options="[
            { label: 'tonal', value: 'tonal' },
            { label: 'outline', value: 'outline' },
            { label: 'standard', value: 'standard' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
      <c-form-item layout="vertical" size="sm" label="status">
        <c-radio-group
          v-model="__demoAppearance['status']"
          aria-label="status"
          :options="[
            { label: 'info', value: 'info' },
            { label: 'success', value: 'success' },
            { label: 'warning', value: 'warning' },
            { label: 'danger', value: 'danger' },
            { label: 'default', value: 'default' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
    </c-form>
    <p class="demo-config-comparison-hint"><span lang="zh-CN">选择一个对比维度；其他配置和内容保持一致。输入类示例共享同一个值，便于比较外观。</span><span lang="en-US">Compare one dimension while keeping the other settings and content identical. Input specimens share the same value.</span></p>
<c-radio-group v-model="demoCompareAxis" aria-label="Compare configuration" :options="demoCompareFields.map(field => ({ label: field.name, value: field.name }))" />
<div class="demo-config-comparison">
<section v-for="sample in demoComparedOptions" :key="String(sample)">
<p><code>{{ demoCompareAxis }}={{ sample }}</code></p>
<c-alert v-bind="{ ...__demoAppearance, [demoCompareAxis]: sample }">This is an info alert.</c-alert>
</section>
</div>
  </c-space>
</template>

<style scoped>
.demo-config-comparison { display: grid; grid-template-columns: repeat(auto-fit, minmax(min(100%, 220px), 1fr)); gap: 20px; min-width: 0; max-width: 100%; }
.demo-config-comparison > section { min-width: 0; }
.demo-config-comparison p { margin: 0 0 8px; }
html:not([lang='en-US']) .demo-config-comparison-hint > [lang='en-US'],
html[lang='en-US'] .demo-config-comparison-hint > [lang='zh-CN'] { display: none; }
</style>
```

## 内容与展示

### 标题、对齐与通栏

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `title` | 警告提示的标题 | 标题、对齐与通栏、操作项 |
| `status` | 警告提示的类型 | 标题、对齐与通栏、隐藏图标 |
| `center` | 内容是否居中显示 | 标题、对齐与通栏 |
| `banner` | 是否作为顶部公告使用（去除边框和圆角） | 标题、对齐与通栏 |
| `show-icon` | 是否展示图标 | 隐藏图标 |
| `closable` | 是否展示关闭按钮 | 操作项 |
<!-- demo-config-notes:end -->

比较标题层级、内容居中与通栏布局。通栏用于页面级提示；操作和关闭能力另见后续示例。

<details>
<summary>配置说明与使用限制</summary>

#### 提示标题

通过设置 `title` 可以给警告提示添加标题。

#### 居中

通过设置 `center`，内容居中显示。

#### 顶部公告

通过设置 `banner`，可将警告提示作为顶部公告使用（去除边框和圆角）。

</details>

Example source: src/alert/__demos__/content-comparison.vue

```vue
<script setup lang="ts">


</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="title">
    <h4><span lang="zh-CN">提示标题</span><span lang="en-US">title</span></h4>
    <c-row :gutter="[40, 20]">
        <c-col :span="12">
          <c-alert title="Info">This is an info alert.</c-alert>
        </c-col>
        <c-col :span="12">
          <c-alert title="Success" status="success">This is an success alert.</c-alert>
        </c-col>
        <c-col :span="12">
          <c-alert status="warning">
            <template #title> Warning </template>
            This is an warning alert.
          </c-alert>
        </c-col>
        <c-col :span="12">
          <c-alert status="danger">
            <template #title> Error </template>
            This is a danger alert.
          </c-alert>
        </c-col>
      </c-row>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="center">
    <h4><span lang="zh-CN">居中</span><span lang="en-US">center</span></h4>
    <c-alert center>This is a centered alert.</c-alert>
  </section>

  <section class="demo-comparison-case demo-comparison-case--3" data-comparison-scene="banner">
    <h4><span lang="zh-CN">顶部公告</span><span lang="en-US">banner</span></h4>
    <c-alert banner>This is a banner alert.</c-alert>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

### 隐藏图标

通过设置 `:show-icon="false"` 来隐藏图标。

Example source: src/alert/__demos__/show-icon.vue

```vue
<template>
  <c-row :gutter="[40, 20]">
    <c-col :span="12">
      <c-alert :show-icon="false">This is an info alert.</c-alert>
    </c-col>
    <c-col :span="12">
      <c-alert status="success" :show-icon="false">This is an success alert.</c-alert>
    </c-col>
    <c-col :span="12">
      <c-alert status="warning" :show-icon="false">
        <template #title> Warning </template>
        This is an warning alert.
      </c-alert>
    </c-col>
    <c-col :span="12">
      <c-alert status="danger" :show-icon="false">
        <template #title> Error </template>
        This is a danger alert.
      </c-alert>
    </c-col>
  </c-row>
</template>

<script lang="ts" setup>
</script>
```

### 操作项

通过 `#action` 插槽自定义操作按钮。

Example source: src/alert/__demos__/action.vue

```vue
<template>
  <c-space direction="column" size="lg" style="width: 100%">
    <c-alert closable>
      This is an info alert.
      <template #action>
        <c-button size="sm" status="primary">Detail</c-button>
      </template>
    </c-alert>
    <c-alert title="Example" closable>
      This is an info alert.
      <template #action>
        <c-button size="sm" status="primary">Detail</c-button>
      </template>
    </c-alert>
  </c-space>
</template>

<script lang="ts" setup>
</script>
```

## 自定义与插槽

### 自定义图标

通过 `#icon` 插槽自定义前置图标。

Example source: src/alert/__demos__/custom-icon.vue

```vue
<template>
  <c-space direction="column" size="lg" style="width: 100%">
    <c-alert>
      <template #icon>
        <c-icon-face-smile-fill />
      </template>
      This is an alert with a custom icon.
    </c-alert>
    <c-alert status="default">
      <template #icon>
        <c-icon-exclamation-circle-fill />
      </template>
      Default type can still show a custom icon via slot.
    </c-alert>
  </c-space>
</template>

<script lang="ts" setup>
</script>
```

## 交互与控制

### 关闭入口与自定义图标

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `closable` | 是否展示关闭按钮 | 关闭入口与自定义图标 |
| `status` | 警告提示的类型 | 关闭入口与自定义图标 |
<!-- demo-config-notes:end -->

分别操作默认与自定义关闭入口，比较相同关闭能力的呈现方式。

<details>
<summary>配置说明与使用限制</summary>

#### 可关闭

关闭按钮支持点击、Space 与 Enter。close 表示开始关闭，closed 在退出动画结束后触发；若业务在 close 中直接卸载组件，就不能继续观察该实例的动画结束。每个 Alert 独立关闭；需要重开时由业务以新实例重建，不代表旧实例的内部可见状态自动恢复。

通过设置 `closable`，可开启关闭按钮。

#### 自定义关闭图标

指定 `close-icon` slot，自定义关闭元素。

</details>

Example source: src/alert/__demos__/dismiss-comparison.vue

```vue
<script setup lang="ts">


</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="closable">
    <h4><span lang="zh-CN">可关闭</span><span lang="en-US">closable</span></h4>
    <c-row :gutter="[40, 20]">
        <c-col :span="12">
          <c-alert closable>This is an info alert.</c-alert>
        </c-col>
        <c-col :span="12">
          <c-alert status="success" closable>This is an success alert.</c-alert>
        </c-col>
        <c-col :span="12">
          <c-alert status="warning" closable>
            <template #title> Warning </template>
            This is an warning alert.
          </c-alert>
        </c-col>
        <c-col :span="12">
          <c-alert status="danger" closable>
            <template #title> Error </template>
            This is a danger alert.
          </c-alert>
        </c-col>
      </c-row>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="close-icon">
    <h4><span lang="zh-CN">自定义关闭图标</span><span lang="en-US">close icon</span></h4>
    <c-row :gutter="[40, 20]">
        <c-col :span="12">
          <c-alert closable>
            <template #close-icon>
              <c-icon-close-circle />
            </template>
            This is an info alert.
          </c-alert>
        </c-col>
        <c-col :span="12">
          <c-alert closable>
            <template #close-icon> Close </template>
            This is an info alert.
          </c-alert>
        </c-col>
      </c-row>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

## API

### `<Alert>` Props

| 属性      | 说明                                                                  | 类型                                                | 默认值       |
| --------- | --------------------------------------------------------------------- | --------------------------------------------------- | ------------ |
| status | 警告提示的类型                                                        | `'info' \| 'success' \| 'warning' \| 'danger' \| 'default'` | `'info'`     |
| variant   | 视觉变体                                                              | `'standard' \| 'tonal' \| 'outline'`               | `'standard'` |
| color     | 自定义背景色（覆盖 type 派生背景）                                    | `string`                                            | -            |
| title     | 警告提示的标题                                                        | `string`                                            | -            |
| message   | 内容文本（亦可使用默认插槽）                                          | `string`                                            | -            |
| show-icon | 是否展示图标                                                          | `boolean`                                           | `true`       |
| closable  | 是否展示关闭按钮                                                      | `boolean`                                           | `false`      |
| banner    | 是否作为顶部公告使用（去除边框和圆角）                                | `boolean`                                           | `false`      |
| center    | 内容是否居中显示                                                      | `boolean`                                           | `false`      |
| elevation | 阴影层级，可选 `true` / `false` 或 `0-24`                             | `boolean \| number`                       | `false`      |

### `<Alert>` Events

| 事件名      | 说明               | 参数                          |
| ----------- | ------------------ | ----------------------------- |
| close       | 点击关闭按钮时触发 | `(event: MouseEvent) => void` |
| closed | 关闭动画结束后触发 | -                             |

### `<Alert>` Slots

| 插槽名     | 说明     | 参数 |
| ---------- | -------- | ---- |
| default    | 内容     | -    |
| icon       | 图标     | -    |
| title      | 标题     | -    |
| action     | 操作项   | -    |
| close-icon | 关闭图标 | -    |

### 类型定义

组件导出以下类型定义：

```ts
import type {
  AlertInstance,
  AlertProps,
  AlertStatus,
  AlertVariant,
} from '@cedar-design/ui'
```

### 样式变量

参见 `style/token.less`，所有变量以 `--c-alert-` 为前缀。覆盖示例：

```css
:root {
  --c-alert-padding-vertical: 12px;
  --c-alert-padding-horizontal: 20px;
}
```

## 升级提示（Breaking）

| 旧 | 新 |
| -- | -- |
| `type="error"` | `type="danger"` |
| `type="normal"` | `type="default"` |
| `closeable` | `closable` |
| `#close-element` slot | `#close-icon` slot |

新增能力：`variant` / `color` / `elevation` / `default` 类型 / `closed` 事件。

`type="default"` 不渲染内置图标；需要图标时用 `#icon`。

## 同源实现与平台边界

两端各自保存完整源码，不引用公共核心，不共享组件实例或响应式状态；修改时同步维护两份实现。主体、Props、关键样式及配对测试纳入只读源码一致性检查，主题 token 和安装入口各自维护。

关闭按钮支持键盘操作，close 只触发一次，closed 在离场动画完成后触发。Maple 内部关闭类由 __close-icon 调整为 __close-btn；默认图标资源由各库本地适配。

### 完整变量默认值

彩色标题、正文、图标及 outline 描边使用可读 system content。standard 与 tonal 使用同一第 1 阶浅底，前者额外带弱装饰描边；默认标题为 content-primary，正文、图标为 content-secondary。content 变量同时控制根容器继承色，关闭图标及未显式设色的操作内容跟随它。Maple 暗色继承同一套颜色，但保留原有几何覆盖（内边距 16px、图标 22px、图标/关闭间距 12px、正文行高 1.5）。color 仅改背景，调用方须同时验证前景对比度。下表为 :root 默认值，不是主题覆盖值。

| 变量 | 默认值 |
| --- | --- |
| `--c-alert-padding-vertical` | `var(--c-sys-space-4)` |
| `--c-alert-padding-horizontal` | `var(--c-sys-space-6)` |
| `--c-alert-padding-vertical-with-title` | `var(--c-sys-space-6)` |
| `--c-alert-padding-horizontal-with-title` | `var(--c-sys-space-6)` |
| `--c-alert-border-radius` | `var(--c-sys-radius-md)` |
| `--c-alert-border-width` | `1px` |
| `--c-alert-font-size-content` | `var(--c-sys-font-size-md)` |
| `--c-alert-font-size-title` | `var(--c-sys-font-size-lg)` |
| `--c-alert-font-weight-title` | `var(--c-sys-font-weight-medium)` |
| `--c-alert-line-height` | `1.5715` |
| `--c-alert-line-height-title` | `1.5` |
| `--c-alert-title-margin-bottom` | `var(--c-sys-space-2)` |
| `--c-alert-icon-size` | `16px` |
| `--c-alert-icon-margin-right` | `var(--c-sys-space-4)` |
| `--c-alert-action-margin-left` | `var(--c-sys-space-5)` |
| `--c-alert-close-margin-left` | `var(--c-sys-space-4)` |
| `--c-alert-standard-info-bg` | `rgb(var(--c-blue-1))` |
| `--c-alert-standard-info-border` | `rgb(var(--c-blue-3))` |
| `--c-alert-standard-info-title` | `var(--c-sys-color-content-info)` |
| `--c-alert-standard-info-content` | `var(--c-sys-color-content-info)` |
| `--c-alert-standard-info-icon` | `var(--c-sys-color-content-info)` |
| `--c-alert-standard-success-bg` | `rgb(var(--c-success-1))` |
| `--c-alert-standard-success-border` | `rgb(var(--c-success-3))` |
| `--c-alert-standard-success-title` | `var(--c-sys-color-content-success)` |
| `--c-alert-standard-success-content` | `var(--c-sys-color-content-success)` |
| `--c-alert-standard-success-icon` | `var(--c-sys-color-content-success)` |
| `--c-alert-standard-warning-bg` | `rgb(var(--c-warning-1))` |
| `--c-alert-standard-warning-border` | `rgb(var(--c-warning-3))` |
| `--c-alert-standard-warning-title` | `var(--c-sys-color-content-warning)` |
| `--c-alert-standard-warning-content` | `var(--c-sys-color-content-warning)` |
| `--c-alert-standard-warning-icon` | `var(--c-sys-color-content-warning)` |
| `--c-alert-standard-danger-bg` | `rgb(var(--c-danger-1))` |
| `--c-alert-standard-danger-border` | `rgb(var(--c-danger-3))` |
| `--c-alert-standard-danger-title` | `var(--c-sys-color-content-danger)` |
| `--c-alert-standard-danger-content` | `var(--c-sys-color-content-danger)` |
| `--c-alert-standard-danger-icon` | `var(--c-sys-color-content-danger)` |
| `--c-alert-standard-default-bg` | `var(--c-color-fill-2)` |
| `--c-alert-standard-default-border` | `var(--c-sys-color-border-default)` |
| `--c-alert-standard-default-title` | `var(--c-sys-color-content-primary)` |
| `--c-alert-standard-default-content` | `var(--c-sys-color-content-secondary)` |
| `--c-alert-standard-default-icon` | `var(--c-sys-color-content-secondary)` |
| `--c-alert-tonal-info-bg` | `rgb(var(--c-blue-1))` |
| `--c-alert-tonal-info-title` | `var(--c-sys-color-content-info)` |
| `--c-alert-tonal-info-content` | `var(--c-sys-color-content-info)` |
| `--c-alert-tonal-info-icon` | `var(--c-sys-color-content-info)` |
| `--c-alert-tonal-success-bg` | `rgb(var(--c-success-1))` |
| `--c-alert-tonal-success-title` | `var(--c-sys-color-content-success)` |
| `--c-alert-tonal-success-content` | `var(--c-sys-color-content-success)` |
| `--c-alert-tonal-success-icon` | `var(--c-sys-color-content-success)` |
| `--c-alert-tonal-warning-bg` | `rgb(var(--c-warning-1))` |
| `--c-alert-tonal-warning-title` | `var(--c-sys-color-content-warning)` |
| `--c-alert-tonal-warning-content` | `var(--c-sys-color-content-warning)` |
| `--c-alert-tonal-warning-icon` | `var(--c-sys-color-content-warning)` |
| `--c-alert-tonal-danger-bg` | `rgb(var(--c-danger-1))` |
| `--c-alert-tonal-danger-title` | `var(--c-sys-color-content-danger)` |
| `--c-alert-tonal-danger-content` | `var(--c-sys-color-content-danger)` |
| `--c-alert-tonal-danger-icon` | `var(--c-sys-color-content-danger)` |
| `--c-alert-tonal-default-bg` | `var(--c-color-fill-2)` |
| `--c-alert-tonal-default-title` | `var(--c-sys-color-content-primary)` |
| `--c-alert-tonal-default-content` | `var(--c-sys-color-content-secondary)` |
| `--c-alert-tonal-default-icon` | `var(--c-sys-color-content-secondary)` |
| `--c-alert-outline-info-border` | `var(--c-sys-color-content-info)` |
| `--c-alert-outline-info-title` | `var(--c-sys-color-content-info)` |
| `--c-alert-outline-info-content` | `var(--c-sys-color-content-info)` |
| `--c-alert-outline-info-icon` | `var(--c-sys-color-content-info)` |
| `--c-alert-outline-success-border` | `var(--c-sys-color-content-success)` |
| `--c-alert-outline-success-title` | `var(--c-sys-color-content-success)` |
| `--c-alert-outline-success-content` | `var(--c-sys-color-content-success)` |
| `--c-alert-outline-success-icon` | `var(--c-sys-color-content-success)` |
| `--c-alert-outline-warning-border` | `var(--c-sys-color-content-warning)` |
| `--c-alert-outline-warning-title` | `var(--c-sys-color-content-warning)` |
| `--c-alert-outline-warning-content` | `var(--c-sys-color-content-warning)` |
| `--c-alert-outline-warning-icon` | `var(--c-sys-color-content-warning)` |
| `--c-alert-outline-danger-border` | `var(--c-sys-color-content-danger)` |
| `--c-alert-outline-danger-title` | `var(--c-sys-color-content-danger)` |
| `--c-alert-outline-danger-content` | `var(--c-sys-color-content-danger)` |
| `--c-alert-outline-danger-icon` | `var(--c-sys-color-content-danger)` |
| `--c-alert-outline-default-border` | `var(--c-sys-color-border-default)` |
| `--c-alert-outline-default-title` | `var(--c-sys-color-content-primary)` |
| `--c-alert-outline-default-content` | `var(--c-sys-color-content-secondary)` |
| `--c-alert-outline-default-icon` | `var(--c-sys-color-content-secondary)` |

### 动效变量

内置动效遵循 `prefers-reduced-motion: reduce`；减少动效不会阻止加载状态或关闭事件更新。

| Token | Default |
| --- | --- |
| `--c-alert-close-duration` | `var(--c-sys-motion-duration-slow)` |

---

Document: llms/zh-CN/components/anchor.md

<!-- Source: src/anchor/README.md; locale: zh-CN; page: /components/anchor/ -->

# Anchor

通过锚点可快速找到信息内容在当前页面的位置。

## 基础示例

### 基础用法

锚点的基本用法

Example source: src/anchor/__demos__/basic.vue

```vue
<template>
  <c-anchor :show-background="false">
    <c-anchor-link href="#基础用法">基础用法</c-anchor-link>
    <c-anchor-link href="#无轴线模式">无轴线模式</c-anchor-link>
    <c-anchor-link href="#固钉位置">固钉位置
      Affix
      <template #sublist>
        <c-anchor-link href="#boundary"
          >Scroll Boundary
          <template #sublist>
            <c-anchor-link href="#boundary1">Scroll Boundary1</c-anchor-link>
            <c-anchor-link href="#hash1">Hash mode1</c-anchor-link>
          </template>
        </c-anchor-link>
        <c-anchor-link href="#是否改变hash">是否改变hash</c-anchor-link>
      </template>
    </c-anchor-link>
  </c-anchor>
</template>

<script lang="ts" setup></script>
```

## 布局与排列

### 固钉位置

使用 `affix` 组件可以让锚点固定在页面之内。

Example source: src/anchor/__demos__/affix.vue

```vue
<template>
  <c-affix :offsetTop="80">
    <c-anchor :style="{ backgroundColor: 'var(--color-bg-1)' }">
      <c-anchor-link href="#basic">Basic</c-anchor-link>
      <c-anchor-link href="#show-line">Show Rail</c-anchor-link>
      <c-anchor-link href="#affix">
        Affix
        <template #sublist>
          <c-anchor-link href="#boundary">Scroll Boundary</c-anchor-link>
          <c-anchor-link href="#hash">Hash mode</c-anchor-link>
        </template>
      </c-anchor-link>
    </c-anchor>
  </c-affix>
</template>
<script lang="ts" setup>
</script>
```

## 内容与展示

### 无轴线模式

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `show-line` | 是否显示左侧轴线 | 无轴线模式 |
| `change-hash` | 是否改变hash。设置为 `false` 时点击锚点不会改变页面的 hash | 是否改变hash |
<!-- demo-config-notes:end -->

当页面滚动或浏览器窗口改变时，元素向下滚动到距底部一定距离时固定。

Example source: src/anchor/__demos__/show-line.vue

```vue
<template>
  <c-anchor :show-line="false">
    <c-anchor-link href="#basic">Basic</c-anchor-link>
    <c-anchor-link href="#show-line">Show Rail</c-anchor-link>
    <c-anchor-link href="#affix">
      Affix
      <template #sublist>
        <c-anchor-link href="#boundary">Scroll Boundary</c-anchor-link>
        <c-anchor-link href="#hash">Hash mode</c-anchor-link>
      </template>
    </c-anchor-link>
  </c-anchor>
</template>

<script lang="ts" setup>
</script>
```

### 是否改变hash

可以设置点击锚点而不改变浏览器历史。

Example source: src/anchor/__demos__/hash.vue

```vue
<template>
  <c-anchor :change-hash="false">
    <c-anchor-link href="#basic">Basic</c-anchor-link>
    <c-anchor-link href="#show-line">Show Line</c-anchor-link>
    <c-anchor-link href="#affix">
      Affix
      <template #sublist>
        <c-anchor-link href="#boundary">Scroll Boundary</c-anchor-link>
        <c-anchor-link href="#hash">Hash mode</c-anchor-link>
      </template>
    </c-anchor-link>
  </c-anchor>
</template>

<script lang="ts" setup>
</script>
```

## 生命周期与边界

### 锚点滚动偏移量

可以设置 `boundary` 来定制锚点滚动偏移量。

Example source: src/anchor/__demos__/boundary.vue

```vue
<template>
  <c-anchor boundary="center">
    <c-anchor-link href="#basic">Basic</c-anchor-link>
    <c-anchor-link href="#show-line">Show Rail</c-anchor-link>
    <c-anchor-link href="#affix">
      Affix
      <template #sublist>
        <c-anchor-link href="#boundary">Scroll Boundary</c-anchor-link>
        <c-anchor-link href="#hash">Hash mode</c-anchor-link>
      </template>
    </c-anchor-link>
  </c-anchor>
</template>

<script lang="ts" setup>
</script>
```

### 滚动消费者生命周期

Example source: src/anchor/__demos__/scroll-lifecycle.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import Anchor, { AnchorLink } from "../index";

const active = ref(true);
const mounted = ref(true);
const container = ref<HTMLElement>();
const changes = ref(0);
</script>

<template>
  <div>
    <c-button html-type="button" @click="active = !active"
      >切换 KeepAlive</c-button
    >
    <c-button html-type="button" @click="mounted = !mounted"
      >卸载／挂载</c-button
    >
    <p>
      切换链接后立即停用或卸载；激活后再次点击，检查旧滚动不会恢复。change
      通知：{{ changes }}
    </p>
    <KeepAlive v-if="mounted">
      <Anchor
        v-if="active"
        :scroll-container="container"
        :change-hash="false"
        @change="changes++"
      >
        <AnchorLink href="#anchor-lifecycle-first" title="第一段" />
        <AnchorLink href="#anchor-lifecycle-second" title="第二段" />
      </Anchor>
    </KeepAlive>
    <div ref="container" style="height: 180px; overflow: auto">
      <section id="anchor-lifecycle-first" style="min-height: 240px">
        第一段内容
      </section>
      <section id="anchor-lifecycle-second" style="min-height: 240px">
        第二段内容
      </section>
    </div>
  </div>
</template>
```

连续点击会取消上一次滚动；KeepAlive 停用、卸载、滚动容器或 boundary 改变会取消当前滚动与测量帧，移除原容器监听。激活只重新绑定和测量，不恢复旧动画。旧通知、旧滚动完成和重复帧不能覆盖新阶段；同一目标的重复点击仍保留一次有效的待发 change 通知。失效的保留点击不阻止默认导航，也不发 select。

私有视觉滚动保留 300ms／quartOut；它不是 CSS transition 完成计时，不新增时长 Token。帧由目标所属窗口创建／取消，每帧检查当前减少动效偏好；已开启时直接定位，运行中开启则下一帧完成。取消停在当前位置，不跳到目标、不发完成通知。nextTick 通知只能逻辑失效，不能物理撤销已排队续体或回滚已执行滚动。

AnchorLink 卸载及 href 变化会注销原节点；旧节点清理不会删除同 hash 的新注册。测量／几何读取后再次核对归属，防止停用、卸载或新请求重入后提交旧结果。公开 Props／Events、颜色和 CSS 变量保持不变；Maple 没有对应 Anchor 运行时。

## 阅读方向

轴线和高亮位于阅读起点，链接缩进使用逻辑位置，纵向滚动和锚点目标保持不变。

## API

### `<anchor>` Props

| 参数名           | 描述                                                                         | 类型                                                  |  默认值   |
| ---------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------- | :-------: |
| boundary         | 滚动边界值，设置该值为数字后，将会在距离滚动容器 `boundary` 距离时停止滚动。 | `'start' \| 'end' \| 'center' \| 'nearest' \| number` | `'start'` |
| show-line        | 是否显示左侧轴线                                                             | `boolean`                                             |  `true`   |
| show-background  | 是否显示背景                                                                 | `boolean`                                             |  `true`   |
| scroll-container | 滚动容器                                                                     | `string \| HTMLElement \| Window`                     |    `-`    |
| change-hash      | 是否改变hash。设置为 `false` 时点击锚点不会改变页面的 hash                   | `boolean`                                             |  `true`   |

### `<anchor>` Events

| 事件名 | 描述               | 参数                                             |
| ------ | ------------------ | ------------------------------------------------ |
| select | 用户点击链接时触发 | hash: `string \| undefined`<br>preHash: `string` |
| change | 链接发生改变时触发 | hash: `string`                                   |

### `<anchor-link>` Props

| 参数名 | 描述               | 类型     | 默认值 |
| ------ | ------------------ | -------- | :----: |
| title  | 锚点链接的文本内容 | `string` |  `-`   |
| href   | 锚点链接的地址     | `string` |  `-`   |

### 类型定义

组件导出以下类型定义

```ts
import type { AnchorInstance } from '@cedar-design/ui'
```

---

Document: llms/zh-CN/components/auto-complete.md

<!-- Source: src/auto-complete/README.md; locale: zh-CN; page: /components/auto-complete/ -->

# AutoComplete 自动补全

允许自由输入的单行文本框，候选只是快捷填写方式。两端独立维护同源主体、Props、Menu 和样式；触控与 hover 差异由本地 Input 处理，没有跨库运行时或 platform 配置。

shouldOpen 控制是否允许展开，filterOption 控制逐项过滤；它们不是同一个设置。没有候选、禁用或只读时不会打开。自动补全不提供 list/picker 展示。

## 阅读方向

输入框与候选弹层继承来源 dir，自定义挂载容器不覆盖来源方向。左右光标键保持原生编辑行为，上下键选择候选、Enter 提交、Escape 关闭。候选更新期间保留正在组合的原生文本；组合结束后提交，不因重绘覆盖为旧模型值。

## 基础示例

### 基础输入与选择

Example source: src/auto-complete/__demos__/basic.vue

```vue
<template>
  <c-auto-complete
    v-model="value"
    :options="options"
    placeholder="输入或选择城市"
    clearable
    style="width: 100%; max-width: 320px"
  />
  <p>当前值：{{ value || '-' }}</p>
</template>

<script setup lang="ts">
import { ref } from 'vue'

const value = ref('')
const options = [
  'Beijing',
  { value: 310000, label: 'Shanghai' },
  { value: 'chengdu', label: 'Chengdu' },
  { value: 'wuhan', label: 'Wuhan', disabled: true },
]
</script>
```

## 外观与状态

### 外观配置对比

<!-- demo-config-notes:start -->

#### 本组配置对照

| 配置        | 作用                                         | 相关示例     |
| ----------- | -------------------------------------------- | ------------ |
| `options`   | 候选；支持分组，value 唯一，选择后转为字符串 | 外观配置对比 |
| `clearable` | 允许清除可编辑的非空值                       | 外观配置对比 |

<!-- demo-config-notes:end -->

选择一个对比维度后，同屏展示它的全部可选值；其余配置和内容保持一致。可切换其他配置检查组合效果；输入类预览共享一个值。

<details>
<summary>配置说明与使用限制</summary>

#### 外观组合

适用于允许自由输入的候选提示。调整变体、尺寸，用相同数据观察变化。内容保持一致，便于比较不同设置的实际效果。

</details>

Example source: src/auto-complete/__demos__/appearance-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref("研发");
const options = [{ value: "研发" }, { value: "研发平台" }, { value: "设计" }];
const __demoAppearance = __demoReactive({ variant: "filled", size: "md" });

import { computed as demoComputed, ref as demoRef } from 'vue'
const demoCompareFields = [{"name":"variant","values":["filled","outline","standard"]},{"name":"size","values":["xs","sm","md","lg","xl"]}]
const demoCompareAxis = demoRef("variant")
const demoComparedOptions = demoComputed(() => demoCompareFields.find(field => field.name === demoCompareAxis.value)?.values ?? [])
</script>
<template>
  <c-space direction="column" :size="16">
    <c-form layout="vertical">
      <c-form-item layout="vertical" size="sm" label="variant">
        <c-radio-group
          v-model="__demoAppearance['variant']"
          aria-label="variant"
          :options="[
            { label: 'filled', value: 'filled' },
            { label: 'outline', value: 'outline' },
            { label: 'standard', value: 'standard' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
      <c-form-item layout="vertical" size="sm" label="size">
        <c-radio-group
          v-model="__demoAppearance['size']"
          aria-label="size"
          :options="[
            { label: 'xs', value: 'xs' },
            { label: 'sm', value: 'sm' },
            { label: 'md', value: 'md' },
            { label: 'lg', value: 'lg' },
            { label: 'xl', value: 'xl' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
    </c-form>
    <p class="demo-config-comparison-hint"><span lang="zh-CN">选择一个对比维度；其他配置和内容保持一致。输入类示例共享同一个值，便于比较外观。</span><span lang="en-US">Compare one dimension while keeping the other settings and content identical. Input specimens share the same value.</span></p>
<c-radio-group v-model="demoCompareAxis" aria-label="Compare configuration" :options="demoCompareFields.map(field => ({ label: field.name, value: field.name }))" />
<div class="demo-config-comparison">
<section v-for="sample in demoComparedOptions" :key="String(sample)">
<p><code>{{ demoCompareAxis }}={{ sample }}</code></p>
<c-auto-complete
      v-model="value"
      :options="options"
      clearable
      v-bind="{ ...__demoAppearance, [demoCompareAxis]: sample }"
    ></c-auto-complete>
</section>
</div>
  </c-space>
</template>

<style scoped>
.demo-config-comparison { display: grid; grid-template-columns: repeat(auto-fit, minmax(min(100%, 220px), 1fr)); gap: 20px; min-width: 0; max-width: 100%; }
.demo-config-comparison > section { min-width: 0; }
.demo-config-comparison p { margin: 0 0 8px; }
html:not([lang='en-US']) .demo-config-comparison-hint > [lang='en-US'],
html[lang='en-US'] .demo-config-comparison-hint > [lang='zh-CN'] { display: none; }
</style>
```

## 匹配与候选列表

### 展开条件与过滤

<!-- demo-config-notes:start -->

#### 本组配置对照

| 配置             | 作用                                                | 相关示例                             |
| ---------------- | --------------------------------------------------- | ------------------------------------ |
| `options`        | 候选；支持分组，value 唯一，选择后转为字符串        | 展开条件与过滤、大小写匹配、分组间距 |
| `placeholder`    | 占位文字或浮动提示内容                              | 展开条件与过滤、大小写匹配、分组间距 |
| `should-open`    | 允许展开的条件，不负责过滤候选                      | 展开条件与过滤、分组间距、虚拟列表   |
| `filter-option`  | 按标签过滤；false 用于远程筛选                      | 展开条件与过滤                       |
| `case-sensitive` | 内置过滤是否区分大小写                              | 大小写匹配                           |
| `trigger-props`  | 弹层配置；不能覆盖内部 open / disabled / 容器优先级 | 分组间距                             |

<!-- demo-config-notes:end -->

Example source: src/auto-complete/__demos__/opening-policy.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
const value = ref("");
const allowEmpty = ref(false);
const filter = ref(true);
const shouldOpen = (text: string) => allowEmpty.value || text.length >= 2;
const options = ["Cedar", "Maple", "Vue"];
</script>
<template>
  <c-space direction="column" size="md">
    <c-checkbox v-model="allowEmpty"> 允许空输入展开</c-checkbox>
    <c-checkbox v-model="filter"> 按输入过滤候选</c-checkbox>
    <c-auto-complete
      v-model="value"
      :options="options"
      :filter-option="filter"
      :should-open="shouldOpen"
      placeholder="默认输入两个字符后展开"
    />
    <p>展开条件不负责过滤；即使允许展开，没有匹配候选也不显示菜单。</p>
  </c-space>
</template>
```

### 大小写匹配

Example source: src/auto-complete/__demos__/case-sensitive.vue

```vue
<template>
  <c-space direction="column" size="md">
    <c-auto-complete v-model="looseValue" :options="options" placeholder="默认：输入 ar" style="width: 100%; max-width: 320px" />
    <c-auto-complete v-model="caseSensitiveValue" :options="options" case-sensitive placeholder="区分大小写：输入 Ar" style="width: 100%; max-width: 320px" />
  </c-space>
</template>

<script setup lang="ts">
import { ref } from 'vue'

const options = ['Arco', 'Maple', 'Cedar']
const looseValue = ref('')
const caseSensitiveValue = ref('')
</script>
```

### 分组间距

Example source: src/auto-complete/__demos__/group-spacing.vue

```vue
<script setup lang="ts">
const options = [
  {
    isGroup: true,
    label: "华北",
    options: [
      { value: "beijing", label: "北京" },
      { value: "tianjin", label: "天津" },
    ],
  },
  {
    isGroup: true,
    label: "华东",
    options: [
      { value: "shanghai", label: "上海" },
      { value: "hangzhou", label: "杭州" },
    ],
  },
];
</script>

<template>
  <c-space direction="column" size="md">
    <c-auto-complete
      :options="options"
      :should-open="() => true"
      placeholder="分组候选"
      :style="{ width: '280px' }"
    />
    <c-auto-complete
      :options="options"
      :should-open="() => true"
      placeholder="自定义缩进的分组候选"
      :style="{ width: '280px' }"
      :trigger-props="{ popupStyle: { '--c-auto-complete-option-padding-horizontal': '20px' } }"
    />
  </c-space>
</template>
```

### 虚拟列表

Example source: src/auto-complete/__demos__/virtual-list.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const value = ref('')
const options = Array.from({ length: 500 }, (_, index) => ({ value: `device-${index + 1}`, label: `Device ${index + 1}` }))
</script>
<template>
  <c-auto-complete v-model="value" :options="options" :should-open="() => true"
    :virtual-list-props="{ height: 180 }" placeholder="搜索 500 个设备" />
</template>
```

## 内容与字段定制

### 自定义字段与内容

<!-- demo-config-notes:start -->

#### 本组配置对照

| 配置          | 作用                                         | 相关示例                         |
| ------------- | -------------------------------------------- | -------------------------------- |
| `options`     | 候选；支持分组，value 唯一，选择后转为字符串 | 自定义字段与内容、外观与浮动提示 |
| `placeholder` | 占位文字或浮动提示内容                       | 自定义字段与内容、外观与浮动提示 |
| `field-names` | 映射 value、label、disabled 等字段           | 自定义字段与内容                 |
| `variant`     | 输入外观；未设置时继承 Group                 | 外观与浮动提示                   |
| `hint`        | 启用 Input 的浮动提示                        | 外观与浮动提示                   |
| `clearable`   | 允许清除可编辑的非空值                       | 外观与浮动提示                   |

<!-- demo-config-notes:end -->

Example source: src/auto-complete/__demos__/footer.vue

```vue
<template>
  <c-auto-complete
    v-model="value"
    :options="options"
    :field-names="{ value: 'code', label: 'name', disabled: 'unavailable' }"
    placeholder="输入城市"
    style="width: 100%; max-width: 320px"
  >
    <template #option="{ data }">{{ data.label }} · {{ data.raw.country }}</template>
    <template #footer>
      <div style="padding: 6px 12px; color: var(--c-sys-color-content-tertiary)">选择候选或继续自由输入</div>
    </template>
  </c-auto-complete>
</template>

<script setup lang="ts">
import { ref } from 'vue'

const value = ref('')
const options = [
  { code: 'PEK', name: 'Beijing', country: 'CN' },
  { code: 'SHA', name: 'Shanghai', country: 'CN' },
  { code: 'NRT', name: 'Tokyo', country: 'JP', unavailable: true },
]
</script>
```

### 外观与浮动提示

Example source: src/auto-complete/__demos__/decorator.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const value = ref('')
const options = ['Cedar', 'Maple']
</script>
<template>
  <c-space direction="column" size="md">
    <c-auto-complete v-for="variant in (['filled', 'outline', 'standard'] as const)" :key="variant"
      v-model="value" :options="options" :variant="variant" :placeholder="variant" hint clearable />
    <c-auto-complete v-model="value" :options="options" hint placeholder="自定义颜色"
      focus-color="#6750a4" text-color="#386a20" enterkeyhint="search">
      <template #prefix>@</template><template #suffix>.com</template>
    </c-auto-complete>
  </c-space>
</template>
```

## 交互与键盘

### 交互状态对比

<!-- demo-config-notes:start -->

#### 本组配置对照

| 配置          | 作用                                         | 相关示例                   |
| ------------- | -------------------------------------------- | -------------------------- |
| `options`     | 候选；支持分组，value 唯一，选择后转为字符串 | 交互状态对比、键盘与无障碍 |
| `clearable`   | 允许清除可编辑的非空值                       | 交互状态对比               |
| `disabled`    | 禁用；未设置时继承，显式 false 覆盖          | 交互状态对比               |
| `readonly`    | 只读，可聚焦复制，不展开候选                 | 交互状态对比               |
| `error`       | 错误状态；未设置时继承 FormItem              | 交互状态对比               |
| `input-attrs` | 原生 input 属性，combobox 状态由组件维护     | 键盘与无障碍               |

<!-- demo-config-notes:end -->

在同一实例上切换禁用、只读和错误状态后再操作控件，比较可编辑性和交互反馈。恢复开关位于目标控件外；错误外观本身不会执行校验。

<details>
<summary>配置说明与使用限制</summary>

#### 交互状态切换

适用于允许自由输入的候选提示。调整禁用、只读、错误反馈，用相同数据观察变化。控制区始终可用，可以随时恢复编辑；错误外观本身不会触发表单校验。

</details>

Example source: src/auto-complete/__demos__/state-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref("研发");
const options = [{ value: "研发" }, { value: "研发平台" }, { value: "设计" }];
const __demoState = __demoReactive({
  disabled: false,
  readonly: false,
  error: false,
});
</script>
<template>
  <c-space direction="column" :size="16">
    <c-space wrap>
      <c-checkbox v-model="__demoState['disabled']">disabled</c-checkbox>
      <c-checkbox v-model="__demoState['readonly']">readonly</c-checkbox>
      <c-checkbox v-model="__demoState['error']">error</c-checkbox>
    </c-space>
    <c-auto-complete
      v-model="value"
      :options="options"
      clearable
      v-bind="__demoState"
    ></c-auto-complete>
  </c-space>
</template>
```

### 键盘与无障碍

Example source: src/auto-complete/__demos__/accessibility.vue

```vue
<template>
  <label :for="inputId">前端框架</label>
  <c-auto-complete
    v-model="value"
    :options="options"
    :input-attrs="{ id: inputId, 'aria-describedby': helpId }"
    style="width: 100%; max-width: 320px"
  />
  <p :id="helpId">使用方向键浏览建议，Enter 选择，Escape 关闭。</p>
</template>

<script setup lang="ts">
import { ref, useId } from 'vue'

const inputId = useId()
const helpId = useId()
const value = ref('')
const options = ['Vue', 'React', 'Angular']
</script>
```

选项分组与 Menu 使用一致的间距逻辑：标题行高 20px，上下各 4px 留白（总高 28px）；后续分组前额外留 8px，首组不添加组间距。标题与选项文字左对齐；AutoComplete 的标题缩进跟随其选项水平 padding 配置。

## 异步与配置

### 异步建议

<!-- demo-config-notes:start -->

#### 本组配置对照

| 配置            | 作用                                                | 相关示例                       |
| --------------- | --------------------------------------------------- | ------------------------------ |
| `options`       | 候选；支持分组，value 唯一，选择后转为字符串        | 异步建议、透传配置边界与优先级 |
| `filter-option` | 按标签过滤；false 用于远程筛选                      | 异步建议                       |
| `placeholder`   | 占位文字或浮动提示内容                              | 异步建议                       |
| `disabled`      | 禁用；未设置时继承，显式 false 覆盖                 | 透传配置边界与优先级           |
| `should-open`   | 允许展开的条件，不负责过滤候选                      | 透传配置边界与优先级           |
| `trigger-props` | 弹层配置；不能覆盖内部 open / disabled / 容器优先级 | 透传配置边界与优先级           |

<!-- demo-config-notes:end -->

Example source: src/auto-complete/__demos__/remote.vue

```vue
<template>
  <c-auto-complete
    v-model="value"
    :options="options"
    :filter-option="false"
    placeholder="输入关键字获取远程建议"
    style="width: 100%; max-width: 320px"
    @search="handleSearch"
  />
</template>

<script setup lang="ts">
import { onBeforeUnmount, ref } from 'vue'

const value = ref('')
const options = ref<string[]>([])

let requestId = 0
onBeforeUnmount(() => requestId++)
const handleSearch = async (keyword: string) => {
  const current = ++requestId
  const result = await Promise.resolve(keyword ? Array.from({ length: 4 }, (_, index) => `${keyword}-${index + 1}`) : [])
  if (current === requestId) options.value = result
}
</script>
```

### 透传配置边界与优先级

建议使用 `AutoCompleteTriggerOptions` 声明 trigger-props。展开由内部输入/焦点与 shouldOpen 管理；AutoComplete 不公开顶层 open/defaultOpen/update:open。disabled 归顶层管理；不能用嵌套配置绕过只读/禁用。placement、popupOffset、样式等普通 Trigger 属性延续原透传。popup-container 顶层明确传入时优先（包括 false），否则回退 triggerProps.popupContainer。内部 Trigger 展开监听继续执行；不要通过嵌套监听替代内部展开协议。

本次仅新增可主动选用的专用类型，不收窄已发布的宽属性类型，不增加运行时过滤、不改变覆盖顺序；旧业务写法继续可编译。若直接使用旧宽属性，内部托管字段仍可能通过类型检查，但不代表能控制内部状态。

```ts
import type { AutoCompleteTriggerOptions } from "@cedar-design/ui";
```

Example source: src/auto-complete/__demos__/passthrough-options.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import type { AutoCompleteTriggerOptions } from "@cedar-design/ui";
const disabled = ref(false);
const triggerOptions: AutoCompleteTriggerOptions = {
  placement: "top-start",
  popupOffset: 8,
  popupContainer: false,
};
const options = [
  { value: "USER_A", label: "Apple" },
  { value: "USER_B", label: "Banana" },
];
</script>
<template>
  <c-space direction="column" fill>
    <c-button @click="disabled = !disabled">{{
      disabled ? "启用输入" : "禁用输入"
    }}</c-button>
    <c-auto-complete
      edit-mode="direct"
      :disabled="disabled"
      :should-open="() => true"
      :options="options"
      :trigger-props="triggerOptions"
      aria-label="透传配置示例"
    />
    <p role="status">
      顶层 disabled：{{ disabled }}；聚焦输入框查看向上展开的候选。
    </p>
  </c-space>
</template>
```

### 共享字段加载

`loading` 控制共享字段加载状态；`loading-mode` 为 `default`（指示器）或 `line`（底部不定进度线），默认 `default`。渲染统一由 FieldDecorator 负责，不隐式改变 disabled/readonly；需要禁止编辑时单独设置。

## API

### 空值识别与阅读空文案

`empty-values` 用于空值识别，`empty-value` 保留原清空输出；`empty-text` 仅在 `read-pretty` 空内容下展示，默认 `'-'`，字段 > FormItem > Form，自定义 read 插槽优先。显式配置 empty-values 后，内置 required 接入该策略，自定义校验仍收到原值。详见[统一说明](llms/zh-CN/guide/empty-values.md)。

| 参数         | 类型               | 缺省与范围                                            |
| ------------ | ------------------ | ----------------------------------------------------- |
| empty-values | readonly unknown[] | 字段 > FormItem > Form > 组件族默认；完整覆盖，不合并 |
| empty-text   | string             | 字段 > FormItem > Form > '-'；显式 '' 有效            |

以上是字段展示层 API；纯面板不因此新增阅读模式。Form 与 FormItem 提供继承配置。empty-value 的现有类型与默认输出仍按该组件原 API 执行。

### Props

| 属性                 | 说明                                                | 类型                                                                                     | 默认值                       |
| -------------------- | --------------------------------------------------- | ---------------------------------------------------------------------------------------- | ---------------------------- |
| `model-value`        | 受控文本值                                          | `string`                                                                                 | `—`                          |
| `default-value`      | 非受控初始文本                                      | `string`                                                                                 | `''`                         |
| `options`            | 候选；支持分组，value 唯一，选择后转为字符串        | `(AutoCompleteOption \| SelectOptionGroup)[]` / `(query, { signal }) => Array / Promise` | `undefined`                  |
| `field-names`        | 映射 value、label、disabled 等字段                  | `AutoCompleteFieldNames`                                                                 | `—`                          |
| `should-open`        | 允许展开的条件，不负责过滤候选                      | `(value: string) => boolean`                                                             | `value.length > 0`           |
| `filter-option`      | 按标签过滤；false 用于远程筛选                      | `AutoCompleteFilterOption`                                                               | 自动：数组开启，加载函数关闭 |
| `case-sensitive`     | 内置过滤是否区分大小写                              | `boolean`                                                                                | `false`                      |
| `popup-container`    | 弹层挂载容器，与 Trigger 一致                       | `PopupContainer`                                                                         | `—`                          |
| `trigger-props`      | 弹层配置；不能覆盖内部 open / disabled / 容器优先级 | `TriggerProps`                                                                           | `—`                          |
| `virtual-list-props` | 传入后启用虚拟列表                                  | `VirtualListProps`                                                                       | `—`                          |
| `size`               | 五档尺寸；未设置时继承 Group / Form / 全局配置      | `xs \| sm \| md \| lg \| xl`                                                             | `md`                         |
| `variant`            | 输入外观；未设置时继承 Group                        | `filled \| outline \| standard`                                                          | `outline`                    |
| `disabled`           | 禁用；未设置时继承，显式 false 覆盖                 | `boolean`                                                                                | `undefined`                  |
| `readonly`           | 只读，可聚焦复制，不展开候选                        | `boolean`                                                                                | `undefined`                  |
| `error`              | 错误状态；未设置时继承 FormItem                     | `boolean`                                                                                | `undefined`                  |
| `clearable`          | 允许清除可编辑的非空值                              | `boolean`                                                                                | `false`                      |
| `placeholder`        | 占位文字或浮动提示内容                              | `string`                                                                                 | `—`                          |
| `hint`               | 启用 Input 的浮动提示                               | `boolean`                                                                                | `undefined`                  |
| `line`               | 显示边框或底线                                      | `boolean`                                                                                | `true`                       |
| `text-color`         | 实例文字颜色                                        | `string`                                                                                 | `—`                          |
| `focus-color`        | 实例聚焦颜色                                        | `string`                                                                                 | `—`                          |
| `blur-color`         | 实例失焦提示颜色                                    | `string`                                                                                 | `—`                          |
| `enterkeyhint`       | 移动虚拟键盘回车提示                                | `InputHTMLAttributes['enterKeyHint']`                                                    | `—`                          |
| `aria-label`         | 输入框可访问名称                                    | `string`                                                                                 | `—`                          |
| `max-length`         | 输入与候选选择使用相同的截断规则                    | `number \| { length: number; errorOnly?: boolean }`                                      | `0`                          |
| `show-word-limit`    | 显示字数统计                                        | `boolean`                                                                                | `false`                      |
| `word-length`        | 自定义长度计算                                      | `(value: string) => number`                                                              | `—`                          |
| `word-slice`         | 自定义截断                                          | `(value: string, maxLength: number) => string`                                           | `—`                          |
| `input-attrs`        | 原生 input 属性，combobox 状态由组件维护            | `Record<string, unknown>`                                                                | `—`                          |

### Events

| 事件                                      | 参数                                                          |
| ----------------------------------------- | ------------------------------------------------------------- |
| `update:model-value`                      | `value: string`                                               |
| `input / search / change`                 | `value: string, event: Event`                                 |
| `select`                                  | `value: string, option: AutoCompleteOptionInfo, event: Event` |
| `clear`                                   | `event: Event`                                                |
| `focus / blur`                            | `event: FocusEvent`                                           |
| `dropdown-scroll / dropdown-reach-bottom` | `event: Event`                                                |

输入顺序：`input → update:modelValue → search`；选择：`update:modelValue → select → change`；清除：`clear → input → update:modelValue → change`。同值选择只发 select。change 表示失焦、Enter 或候选选择产生的提交。Input 负责输入、焦点与清除的 Form 通知，AutoComplete 仅对候选提交通知一次。选择也遵守 maxLength；select 的 value 是最终提交字符串，option.value 保留原始候选。clear 参数为事件，不再是字符串。

### Slots

| 插槽              | 说明                               |
| ----------------- | ---------------------------------- |
| `option`          | `{ data: AutoCompleteOptionInfo }` |
| `footer`          | 菜单底部                           |
| `prefix / suffix` | 输入框前后缀                       |
| `clear-icon`      | `{ clear }`                        |

### Methods

`focus()` / `blur()`

label 使用文本；复杂候选通过 option 插槽或选项 render 实现，不保留旧的函数/VNode label 写法。方向键浏览、Enter 选择、Escape 关闭，Tab 保留原生焦点导航。使用 Vue useId 保证 SSR 标识稳定。

## 类型定义

```ts
import type {
  AutoCompleteProps,
  AutoCompleteInstance,
  AutoCompleteOption,
  AutoCompleteOptionData,
  AutoCompleteOptionInfo,
  AutoCompleteFieldNames,
  AutoCompleteFilterOption,
} from "@cedar-design/ui";
```

## 样式变量

| Token                                           | 默认值                                              |
| ----------------------------------------------- | --------------------------------------------------- |
| `--c-auto-complete-popup-max-height`            | `var(--c-select-popup-max-height)`                  |
| `--c-auto-complete-popup-bg`                    | `var(--c-select-popup-bg)`                          |
| `--c-auto-complete-popup-border-radius`         | `var(--c-select-popup-border-radius)`               |
| `--c-auto-complete-popup-padding-vertical`      | `var(--c-select-popup-padding-vertical)`            |
| `--c-auto-complete-popup-font-size`             | `var(--c-select-popup-font-size)`                   |
| `--c-auto-complete-popup-border-color`          | `var(--c-select-popup-border-color)`                |
| `--c-auto-complete-popup-box-shadow`            | `var(--c-select-popup-box-shadow)`                  |
| `--c-auto-complete-option-height`               | `var(--c-select-popup-option-height)`               |
| `--c-auto-complete-option-font-weight-selected` | `var(--c-select-popup-option-font-weight-selected)` |
| `--c-auto-complete-option-padding-horizontal`   | `var(--c-select-popup-option-padding-horizontal)`   |
| `--c-auto-complete-option-bg-default`           | `var(--c-select-popup-option-bg)`                   |
| `--c-auto-complete-option-bg-hover`             | `var(--c-select-popup-option-bg-hover)`             |
| `--c-auto-complete-option-bg-selected`          | `var(--c-select-popup-option-bg-selected)`          |
| `--c-auto-complete-option-bg-disabled`          | `var(--c-select-popup-option-bg-disabled)`          |
| `--c-auto-complete-option-text-color-default`   | `var(--c-select-popup-option-text-color)`           |
| `--c-auto-complete-option-text-color-hover`     | `var(--c-select-popup-option-text-color-hover)`     |
| `--c-auto-complete-option-text-color-selected`  | `var(--c-select-popup-option-text-color-selected)`  |
| `--c-auto-complete-option-text-color-disabled`  | `var(--c-select-popup-option-text-color-disabled)`  |

清空不发 search，也不重新展开候选面板，包括从键盘聚焦的清空按钮回到输入框。受控值由父级决定：连续被拒绝的清空或选择仍各自发出 change 提议；已接受的候选选择只通知 Form 一次。

### Form 字段展示与确认

本组件支持 `edit-mode`，字段 > FormItem > Form 逐层继承；未指定时为 `direct`，保留原有交互。支持值：`direct / click / dblclick`。非 direct 编辑模式通过字段值入口打开编辑面板，并维护单份草稿；确认后才更新 v-model，取消、重置或启用 readPretty 时丢弃草稿。

Cedar 使用 edit-mode="click" / "dblclick" 在字段附近打开编辑浮层，Enter/F2 也可进入；取消/Escape 丢弃草稿，确认后提交。readPretty 为独立阅读属性，与 readonly、disabled 分开。

`before-commit(value, { previousValue, signal })` 可拦截弹层保存；FormItem 先校验候选值，失败保持编辑。`open / default-open / update:open` 控制编辑层。`#read="{ value, text }"` 可自定义阅读内容。集中示例见 Form 的“各类字段统一展示”。

`read-pretty` 为独立布尔属性，与 `readonly`、`disabled` 同级；字段 > FormItem > Form 继承，显式 `false` 覆盖父级。默认 `false`。纯阅读不显示编辑器。

候选列表与 Select 统一使用分组、选中、禁用样式，AutoComplete 样式变量默认跟随对应的 Select 变量。`inline` 列表默认在输入框下方展开，随滚动更新位置；可通过 `trigger-props` 显式调整方向或开启自动翻转。`popup` 候选列表使用与 Select 相同的完整编辑面板样式。

### 公开类型入口

根入口和组件入口均导出 `AutoCompleteEmits`、`AutoCompleteSlots`、`AutoCompleteExpose`，与 Props、Instance 配套。Emits 为从运行时事件声明推导的参数元组映射；Expose 包含 focus/blur。

`case-sensitive` 只使内置本地过滤区分大小写：默认 false 时输入 `ap` 可以匹配 `Apple`，true 时不能。它不限制必须选择候选，不校验输入值。自定义 `filterOption` 优先；`filterOption=false` 关闭本地过滤，此时 case-sensitive 不起作用。

### strict 迁移 / Migration

旧 `strict` 已移除，直接改为 `case-sensitive`（TS 属性为 `caseSensitive`）。true/false 语义和默认 false 保持不变；该删除标记为下个 major，不保留兼容别名。

### 内置搜索字段配置

`searchFields` / `search-fields` 是只读 `('label' | 'value')[]`，默认 `['label']`；多字段为 OR 匹配，大小写默认不敏感。配置 `['value', 'label']` 可同时搜索编码和名称，fieldNames 将语义字段映射到业务字段；空数组对非空查询不匹配任何项。value 采用字符串比较，不做对象深层搜索，对象值或拼音等复杂规则仍用自定义回调。自定义回调优先并自行决定大小写；远程结果使用原有关闭本地过滤协议。Cascader 保留路径语义，会检查路径各节点的配置字段。

## 配置清空后的值

`empty-value` 指定当前组件已有清空动作的输出；省略时采用该组件默认返回。具体类型以组件 API 为准。它不改变 empty-values 的识别规则，也不改变 Form reset 的初始值。

## 函数属性加载候选

直接传 options(query, { signal })，无需调用 useAsyncData。options 继续接收数组，显式数组（包括 []）优先。组件内部管理 loading、旧结果隔离与请求取消；load-error 通知失败，实例 refresh() 重试。业务函数可只接收 query，忽略第二参数。

filterable 表示允许输入搜索词。filterOption 只控制本地候选匹配，从不发请求。使用 options 加载函数时默认不再二次过滤远程结果；仅传数组时默认启用本地匹配。业务通常无需设置 filter-option。

```vue
<c-auto-complete v-model="text" :options="loadSuggestions" />
```

`empty-value` 可显式设为 `null`（或 `() => null`），清空时原样提交 null；省略时保留组件原默认值。界面把 null 显示为空，不会把普通输入的空字符串自动转成 null。支持弹出编辑的字段中，清空先修改草稿，确认后提交，取消则保留原值。

---

Document: llms/zh-CN/components/avatar.md

<!-- Source: src/avatar/README.md; locale: zh-CN; page: /components/avatar/ -->

# Avatar 头像

用于展示用户或事物的头像，支持图片、文字、图标和头像组。

## 基础示例

### 基础用法

头像默认使用圆形、默认尺寸。没有图片时，可以通过默认插槽展示文字或图标；也可以直接传入图片。

Example source: src/avatar/__demos__/basic.vue

```vue
<template>
  <c-space align="center" :size="16" wrap>
    <c-avatar>C</c-avatar>
    <c-avatar>CD</c-avatar>
    <c-avatar shape="square">Cedar</c-avatar>
    <c-avatar color="#00bebe">U</c-avatar>
    <c-avatar image-url="/cat.jpg" alt="一只猫" />
  </c-space>
</template>
```

## 外观与状态

### 尺寸与形状对比

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `shape` | 头像形状 | 尺寸与形状对比、颜色与边框、头像可悬停 |
| `image-url` | 图片地址 | 尺寸与形状对比、头像可悬停 |
| `alt` | 图片替代文本 | 尺寸与形状对比、头像可悬停 |
| `bordered` | 是否显示描边 | 颜色与边框、头像可悬停 |
| `size` | 头像宽高；数字为 px，字符串为 CSS 长度 | 尺寸与形状对比 |
| `color` | 头像背景色 | 颜色与边框 |
<!-- demo-config-notes:end -->

先比较相同内容在各尺寸下的占位，再比较圆形和方形边界；图片适配与错误回退保持独立。

<details>
<summary>配置说明与使用限制</summary>

#### 尺寸

`size` 控制头像宽高：数字为 px，字符串为 CSS 长度（如 `3rem`）。未设置时使用 `--c-avatar-size-default`。可同时用于文字头像和图片头像。

#### 形状

`shape` 支持圆形和方形。

</details>

Example source: src/avatar/__demos__/shape-size-comparison.vue

```vue
<script setup lang="ts">
import { proxyRefs as demoProxyRefs } from 'vue'

const scene1 = demoProxyRefs((() => {

const numericSizes = [24, 32, 40, 48, 64] as const

const labels = { 24: 'A', 32: 'B', 40: 'C', 48: 'D', 64: 'E' } as const

const imageSizes = [28, 36, 48, 64, 78] as const

const cssSizes = ['3rem', '2.5em', '48px'] as const
return { numericSizes, labels, imageSizes, cssSizes }
})())
</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="size">
    <h4><span lang="zh-CN">尺寸</span><span lang="en-US">size</span></h4>
    <c-space direction="column" :size="20">
        <c-space align="flex-end" :size="16" wrap>
          <c-space v-for="size in scene1.numericSizes" :key="size" direction="column" align="center" :size="8">
            <c-avatar :size="size">{{ scene1.labels[size] }}</c-avatar>
            <span class="label">{{ size }}px</span>
          </c-space>
        </c-space>
    
        <c-space align="flex-end" :size="16" wrap>
          <c-space v-for="size in scene1.imageSizes" :key="size" direction="column" align="center" :size="8">
            <c-avatar image-url="/cat.jpg" :alt="`${size}px`" :size="size" />
            <span class="label">{{ size }}px</span>
          </c-space>
        </c-space>
    
        <c-space align="flex-end" :size="16" wrap>
          <c-space v-for="size in scene1.cssSizes" :key="size" direction="column" align="center" :size="8">
            <c-avatar :size="size">Aa</c-avatar>
            <span class="label">{{ size }}</span>
          </c-space>
        </c-space>
      </c-space>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="shape">
    <h4><span lang="zh-CN">形状</span><span lang="en-US">shape</span></h4>
    <c-space align="flex-end" :size="16" wrap>
        <c-space direction="column" align="center" :size="8">
          <c-avatar>圆</c-avatar>
          <span class="label">circle</span>
        </c-space>
        <c-space direction="column" align="center" :size="8">
          <c-avatar shape="square">方</c-avatar>
          <span class="label">square</span>
        </c-space>
        <c-space direction="column" align="center" :size="8">
          <c-avatar image-url="/cat.jpg" alt="圆形图片" />
          <span class="label">circle · 图片</span>
        </c-space>
        <c-space direction="column" align="center" :size="8">
          <c-avatar image-url="/cat.jpg" alt="方形图片" shape="square" />
          <span class="label">square · 图片</span>
        </c-space>
      </c-space>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }
.demo-comparison-case--1 {

.label {
  color: var(--c-color-text-3);
  font-size: var(--c-font-size-sm);
}

}
.demo-comparison-case--2 {

.label {
  color: var(--c-color-text-3);
  font-size: var(--c-font-size-sm);
}

}
</style>
```

### 颜色与边框

使用 `color` 设置背景色，可传入主题色变量。`bordered` / `borderColor` 控制描边。

Example source: src/avatar/__demos__/style.vue

```vue
<template>
  <c-space align="center" :size="16" wrap>
    <c-avatar color="var(--c-color-warning)">火</c-avatar>
    <c-avatar color="var(--c-color-danger)">Cedar</c-avatar>
    <c-avatar color="#00bebe">CD</c-avatar>
    <c-avatar color="#7b61ff" shape="square">A</c-avatar>
    <c-avatar bordered>B</c-avatar>
    <c-avatar bordered border-color="#00bebe" color="#e6fffb">C</c-avatar>
  </c-space>
</template>
```

### 头像可悬停

设置 `hoverable` 后，鼠标悬停时头像会放大，可单独使用，也可以用在头像组里。

Example source: src/avatar/__demos__/hoverable.vue

```vue
<template>
  <c-space direction="column" :size="24">
    <c-space align="center" :size="16" wrap>
      <c-avatar hoverable>H</c-avatar>
      <c-avatar hoverable image-url="/cat.jpg" alt="悬停放大" />
      <c-avatar hoverable shape="square">方</c-avatar>
    </c-space>
    <c-avatar-group>
      <c-avatar hoverable image-url="/cat.jpg" alt="用户一" bordered />
      <c-avatar hoverable image-url="/cat2.jpg" alt="用户二" bordered />
      <c-avatar hoverable image-url="/cat.jpg" alt="用户三" bordered />
      <c-avatar hoverable bordered>+2</c-avatar>
    </c-avatar-group>
  </c-space>
</template>
```

## 布局与排列

### 头像组排列与溢出

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `image-url` | 图片地址 | 头像组排列与溢出 |
| `alt` | 图片替代文本 | 头像组排列与溢出 |
| `bordered` | 是否显示描边 | 头像组排列与溢出 |
| `color` | 头像背景色 | 头像组排列与溢出 |
<!-- demo-config-notes:end -->

比较横向和纵向头像组，观察最大数量、重叠顺序和溢出提示。

<details>
<summary>配置说明与使用限制</summary>

#### 头像组

`AvatarGroup` 会自动堆叠子头像。可以用 `bordered` 做出叠层描边，`maxCount` 将超出的头像收纳到 Popover，`maxStyle` 定制汇总头像，`zIndexAscend` 按顺序递增层级。`shape` / `size` / `offset` 会作用到组内全部子头像。

#### 纵向头像组

`vertical` 改为纵向堆叠，`offset` 控制重叠间距，数字为 px。

</details>

Example source: src/avatar/__demos__/group-comparison.vue

```vue
<script setup lang="ts">


</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="group">
    <h4><span lang="zh-CN">头像组</span><span lang="en-US">group</span></h4>
    <c-space direction="column" :size="24">
        <c-space direction="column" :size="8">
          <span class="label">默认叠层</span>
          <c-avatar-group>
            <c-avatar image-url="/cat.jpg" alt="用户一" bordered />
            <c-avatar image-url="/cat2.jpg" alt="用户二" bordered />
            <c-avatar image-url="/cat.jpg" alt="用户三" bordered />
            <c-avatar bordered>+2</c-avatar>
          </c-avatar-group>
        </c-space>
    
        <c-space direction="column" :size="8">
          <span class="label">max-count + max-style</span>
          <c-avatar-group
            :max-count="3"
            :size="48"
            :max-style="{
      backgroundColor: '#1d2129',
      color: '#fff'
    }"
          >
            <c-avatar image-url="/cat.jpg" alt="用户一" />
            <c-avatar image-url="/cat2.jpg" alt="用户二" />
            <c-avatar color="#00bebe">A</c-avatar>
            <c-avatar color="#f59e0b">B</c-avatar>
            <c-avatar color="#ef4444">C</c-avatar>
          </c-avatar-group>
        </c-space>
    
        <c-space direction="column" :size="8">
          <span class="label">z-index-ascend</span>
          <c-avatar-group z-index-ascend>
            <c-avatar image-url="/cat.jpg" alt="用户一" />
            <c-avatar image-url="/cat2.jpg" alt="用户二" />
            <c-avatar color="#7b61ff">CD</c-avatar>
          </c-avatar-group>
        </c-space>
    
        <c-space direction="column" :size="8">
          <span class="label">shape="square" · offset="-16"</span>
          <c-avatar-group shape="square" :offset="-16" :size="40">
            <c-avatar image-url="/cat.jpg" alt="用户一" />
            <c-avatar image-url="/cat2.jpg" alt="用户二" />
            <c-avatar color="#00bebe">A</c-avatar>
            <c-avatar color="#7b61ff">B</c-avatar>
          </c-avatar-group>
        </c-space>
      </c-space>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="group-vertical">
    <h4><span lang="zh-CN">纵向头像组</span><span lang="en-US">group vertical</span></h4>
    <c-space align="flex-end" :size="32" wrap>
        <c-space direction="column" :size="8">
          <span class="label">offset = -12</span>
          <c-avatar-group vertical :offset="-12">
            <c-avatar image-url="/cat.jpg" alt="用户一" bordered />
            <c-avatar image-url="/cat2.jpg" alt="用户二" bordered />
            <c-avatar image-url="/cat.jpg" alt="用户三" bordered />
            <c-avatar bordered>+2</c-avatar>
          </c-avatar-group>
        </c-space>
        <c-space direction="column" :size="8">
          <span class="label">offset = -20</span>
          <c-avatar-group vertical :offset="-20" :size="48">
            <c-avatar image-url="/cat.jpg" alt="用户一" bordered />
            <c-avatar image-url="/cat2.jpg" alt="用户二" bordered />
            <c-avatar color="#00bebe">A</c-avatar>
          </c-avatar-group>
        </c-space>
      </c-space>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }
.demo-comparison-case--1 {

.label {
  color: var(--c-color-text-3);
  font-size: var(--c-font-size-sm);
}

}
.demo-comparison-case--2 {

.label {
  color: var(--c-color-text-3);
  font-size: var(--c-font-size-sm);
}

}
</style>
```

## 内容与展示

### 文字自适应

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `image-url` | 图片地址 | 图片头像、图片填充、加载与回退 |
| `alt` | 图片替代文本 | 图片头像、图片填充、加载与回退 |
| `size` | 头像宽高；数字为 px，字符串为 CSS 长度 | 图片头像、图片填充、加载与回退 |
| `shape` | 头像形状 | 文字自适应、图片头像 |
| `auto-fix-font-size` | 是否自动缩放过长的文字内容 | 文字自适应 |
| `object-fit` | 图片填充方式 | 图片填充 |
<!-- demo-config-notes:end -->

默认会按头像宽度缩放过长文字。插槽文本更新后会重新测量；改回可容纳的短文本时恢复原始比例。将 `auto-fix-font-size` 设为 `false` 后保持原始字号。

Example source: src/avatar/__demos__/auto-fix.vue

```vue
<template>
  <c-space direction="column" :size="16">
    <c-space align="center" :size="16" wrap>
      <c-space direction="column" align="center" :size="8">
        <c-avatar>{{ text }}</c-avatar>
        <span class="label">圆形 · 自适应</span>
      </c-space>
      <c-space direction="column" align="center" :size="8">
        <c-avatar shape="square">{{ text }}</c-avatar>
        <span class="label">方形 · 自适应</span>
      </c-space>
      <c-space direction="column" align="center" :size="8">
        <c-avatar :auto-fix-font-size="false">{{ text }}</c-avatar>
        <span class="label">关闭自适应</span>
      </c-space>
    </c-space>
    <c-input v-model="text" :style="{ width: '240px' }" placeholder="输入更长的文字看缩放" clearable />
  </c-space>
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const text = ref('Cedar')
</script>

<style scoped>
.label {
  color: var(--c-color-text-3);
  font-size: var(--c-font-size-sm);
}
</style>
```

### 图片头像

使用 `imageUrl` 设置图片，并通过 `alt` 提供可访问的替代文本。也可以在默认插槽里放 `img` / `picture`，组件会按图片头像处理。

Example source: src/avatar/__demos__/image.vue

```vue
<template>
  <c-space align="center" :size="16" wrap>
    <c-space direction="column" align="center" :size="8">
      <c-avatar image-url="/cat.jpg" alt="一只猫" />
      <span class="label">image-url</span>
    </c-space>
    <c-space direction="column" align="center" :size="8">
      <c-avatar image-url="/cat2.jpg" alt="一只猫" :size="48" shape="square" />
      <span class="label">方形图片</span>
    </c-space>
    <c-space direction="column" align="center" :size="8">
      <c-avatar :size="48">
        <img src="/cat.jpg" alt="默认插槽中的图片" />
      </c-avatar>
      <span class="label">默认插槽 img</span>
    </c-space>
  </c-space>
</template>

<style scoped>
.label {
  color: var(--c-color-text-3);
  font-size: var(--c-font-size-sm);
}
</style>
```

### 图片填充

`objectFit` 控制图片在头像区域内的填充方式。

Example source: src/avatar/__demos__/fit.vue

```vue
<template>
  <c-space align="flex-end" :size="24" wrap>
    <c-space v-for="fit in fits" :key="fit" direction="column" align="center" :size="8">
      <c-avatar image-url="/cat.jpg" :alt="fit" :object-fit="fit" :size="56" />
      <span class="label">{{ fit }}</span>
    </c-space>
  </c-space>
</template>

<script lang="ts" setup>
const fits = ['fill', 'contain', 'cover', 'none', 'scale-down'] as const
</script>

<style scoped>
.label {
  color: var(--c-color-text-3);
  font-size: var(--c-font-size-sm);
}
</style>
```

### 加载与回退

`lazy` 开启懒加载，`loading` 指定加载中占位图。失败时可用 `error` 占位图，或使用 `error` 插槽自定义内容。

Example source: src/avatar/__demos__/fallback.vue

```vue
<template>
  <c-space align="flex-end" :size="24" wrap>
    <c-space direction="column" align="center" :size="8">
      <c-avatar lazy image-url="/cat.jpg" loading="/cat2.jpg" alt="懒加载与占位图" :size="48" />
      <span class="label">lazy + loading</span>
    </c-space>
    <c-space direction="column" align="center" :size="8">
      <c-avatar image-url="data:image/png;base64,AA==" error="/cat.jpg" alt="失败时回退到占位图" :size="48" />
      <span class="label">error 图片</span>
    </c-space>
    <c-space direction="column" align="center" :size="8">
      <c-avatar image-url="data:image/png;base64,AA==" alt="失败插槽" :size="48">
        <template #error>NA</template>
      </c-avatar>
      <span class="label">error 插槽</span>
    </c-space>
  </c-space>
</template>

<style scoped>
.label {
  color: var(--c-color-text-3);
  font-size: var(--c-font-size-sm);
}
</style>
```

## 交互与控制

### 交互图标

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `image-url` | 图片地址 | 交互图标 |
| `alt` | 图片替代文本 | 交互图标 |
| `size` | 头像宽高；数字为 px，字符串为 CSS 长度 | 交互图标 |
| `trigger-type` | 交互图标展示方式 | 交互图标 |
<!-- demo-config-notes:end -->

使用 `trigger-icon` 插槽添加交互入口。`triggerType` 支持独立按钮（`button`）和悬浮背景层（`overlay`）两种形式；点击会触发 `click`。

Example source: src/avatar/__demos__/trigger.vue

```vue
<template>
  <c-space align="flex-end" :size="32" wrap>
    <c-space direction="column" align="center" :size="8">
      <c-avatar image-url="/cat.jpg" alt="编辑头像" :size="56" @click="onClick('button')">
        <template #trigger-icon>+</template>
      </c-avatar>
      <span class="label">{{ last === 'button' ? 'click · button' : 'trigger-type="button"' }}</span>
    </c-space>

    <c-space direction="column" align="center" :size="8">
      <c-avatar
        image-url="/cat2.jpg"
        alt="更换头像"
        :size="56"
        trigger-type="overlay"
        @click="onClick('overlay')"
      >
        <template #trigger-icon>+</template>
      </c-avatar>
      <span class="label">{{ last === 'overlay' ? 'click · overlay' : 'trigger-type="overlay"' }}</span>
    </c-space>
  </c-space>
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const last = ref('')

function onClick(type: string) {
  last.value = type
}
</script>

<style scoped>
.label {
  color: var(--c-color-text-3);
  font-size: var(--c-font-size-sm);
}
</style>
```

## API

<!-- same-source-api:start -->
### Props

| 属性 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| shape | 头像形状 | `circle / square` | `circle` |
| image-url | 图片地址 | `string` | `-` |
| alt | 图片替代文本 | `string` | `''` |
| size | 头像宽高；数字为 px，字符串为 CSS 长度 | `number / string` | `-` |
| auto-fix-font-size | 是否自动缩放过长的文字内容 | `boolean` | `true` |
| trigger-type | 交互图标展示方式 | `button / overlay` | `button` |
| trigger-icon-style | 交互图标的自定义样式 | `CSSProperties` | `-` |
| object-fit | 图片填充方式 | `fill / contain / cover / none / scale-down` | `cover` |
| color | 头像背景色 | `string` | `-` |
| bordered | 是否显示描边 | `boolean` | `false` |
| border-color | 描边颜色 | `string` | `-` |
| loading | 图片加载中的占位图地址 | `string` | `-` |
| error | 图片加载失败的占位图地址 | `string` | `-` |
| lazy | 是否懒加载图片 | `boolean` | `false` |
| hoverable | 是否开启悬停放大效果 | `boolean` | `false` |

### Events

| 事件 | 说明 | 参数 |
| --- | --- | --- |
| click | 点击头像时触发 | `(event: MouseEvent) => void` |
| load | 图片加载成功触发 | `() => void` |
| error | 图片加载失败触发 | `() => void` |

### Slots

| 插槽 | 说明 |
| --- | --- |
| default | 文字、图标或图片加载中内容 |
| error | 图片加载失败时的回退内容 |
| trigger-icon | 头像上的交互图标 |

### Methods

无自定义公开方法。
<!-- same-source-api:end -->

### AvatarGroup Props

| 属性 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| shape | 子头像形状 | `circle / square` | `circle` |
| size | 子头像宽高；数字为 px，字符串为 CSS 长度 | `number / string` | `-` |
| auto-fix-font-size | 是否自动缩放子头像中的文字 | `boolean` | `true` |
| max-count | 最多直接展示的头像数，`0` 表示不限 | `number` | `0` |
| z-index-ascend | 头像层级是否按顺序递增 | `boolean` | `false` |
| max-style | 数量汇总头像的自定义样式 | `CSSProperties` | `-` |
| max-popover-props | 汇总 Popover 的属性 | `PopoverProps` | `-` |
| offset | 组内头像的重叠偏移量 | `number / string` | `-` |
| vertical | 是否纵向堆叠 | `boolean` | `false` |

### AvatarGroup Slots

| 插槽 | 说明 |
| --- | --- |
| default | 头像列表 |

### 类型定义

```ts
import type {
  AvatarGroupInstance,
  AvatarGroupProps,
  AvatarInstance,
  AvatarProps,
  AvatarObjectFit,
  AvatarShape,
  AvatarTriggerType,
} from "@cedar-design/ui";
```

### 样式变量

| 变量 | 默认值 |
| --- | --- |
| `--c-avatar-size-default` | `40px` |
| `--c-avatar-font-size-text` | `20px` |
| `--c-avatar-text-color` | `var(--c-sys-color-content-primary)` |
| `--c-avatar-text-padding-inline` | `4px` |
| `--c-avatar-bg` | `var(--c-color-fill-4)` |
| `--c-avatar-border-width` | `2px` |
| `--c-avatar-border-color` | `var(--c-sys-color-surface-default)` |
| `--c-avatar-group-item-border` | `var(--c-sys-color-surface-default)` |
| `--c-avatar-group-item-border-width` | `2px` |
| `--c-avatar-group-offset` | `-10px` |
| `--c-avatar-group-popover-item-spacing` | `8px` |
| `--c-avatar-font-weight-text` | `500` |
| `--c-avatar-circle-border-radius` | `50%` |
| `--c-avatar-square-border-radius` | `4px` |
| `--c-avatar-size-trigger-button` | `20px` |
| `--c-avatar-trigger-button-bg` | `var(--c-color-fill-2)` |
| `--c-avatar-trigger-button-bg-hover` | `var(--c-color-fill-3)` |
| `--c-avatar-trigger-overlay-icon` | `var(--c-sys-color-content-on-dark)` |
| `--c-avatar-trigger-overlay-bg` | `color-mix(in srgb, var(--c-color-black) 60%, transparent)` |
| `--c-avatar-trigger-icon-button` | `var(--c-sys-color-content-primary)` |
| `--c-avatar-spacing-trigger-button-right` | `4px` |
| `--c-avatar-spacing-trigger-button-bottom` | `4px` |
| `--c-avatar-size-trigger-icon` | `12px` |
| `--c-avatar-trigger-button-border-radius` | `50%` |
| `--c-avatar-font-size-max-count` | `20px` |
| `--c-avatar-max-count-text-color` | `var(--c-sys-color-content-primary)` |
| `--c-avatar-trigger-overlay-font-size` | `16px` |
| `--c-avatar-hover-transform` | `scale(1.1)` |
| `--c-avatar-motion-duration` | `0.2s` |
| `--c-avatar-z-index-trigger` | `1` |
| `--c-avatar-z-index-overlay` | `0` |
| `--c-avatar-z-index-overlay-hover` | `2` |

文字、汇总数量和按钮式触发图标默认使用主要内容色；描边跟随容器表面；只有深色交互遮罩上的图标使用 `content-on-dark`。头像背景的 `fill-4`、按钮背景与 hover 阶梯、黑色半透明遮罩保留为组件视觉值。使用 `color` 属性覆盖头像背景时，应同步检查文字对比度，必要时覆盖 `text-color`。

### 减少动态效果

内置 CSS 过渡遵循 `prefers-reduced-motion: reduce`。关闭过渡不改变最终显隐、选中／展开状态及事件语义；插槽内自定义动画由应用自行控制。

---

Document: llms/zh-CN/components/back-top.md

<!-- Source: src/back-top/README.md; locale: zh-CN; page: /components/back-top/ -->

# BackTop 回到顶部

滚动页面或指定容器的回顶按钮，支持原生键盘操作。

## 基础示例

### 基础用法

Example source: src/back-top/__demos__/basic.vue

```vue
<script setup lang="ts">
import { onMounted, ref } from 'vue'

const scroller = ref<HTMLElement>()
onMounted(() => {
  if (scroller.value) {
    scroller.value.scrollTop = 240
    scroller.value.dispatchEvent(new Event('scroll'))
  }
})
</script>

<template>
  <div class="back-top-demo">
    <p>在面板内滚动，超过 120px 时显示按钮。</p>
    <div class="back-top-demo__frame">
      <div ref="scroller" class="back-top-demo__scroll">
        <p v-for="row in 30" :key="row">A · 滚动内容 {{ row }}</p>
      </div>
      <c-back-top
        :target-container="() => scroller"
        :popup-container="false"
        :visible-height="120"
        :right="16"
        :bottom="16"
        aria-label="回到顶部"
      />
    </div>
  </div>
</template>

<style scoped>
.back-top-demo { display: flex; flex-direction: column; gap: 12px; }
.back-top-demo > p { margin: 0; }
.back-top-demo__frame { position: relative; display: flex; gap: 12px; }
.back-top-demo__scroll { flex: 1; min-width: 0; height: 240px; overflow: auto; border: 1px solid #ddd; border-radius: 8px; }
.back-top-demo__scroll p { padding: 8px 12px; margin: 0; }
</style>
```

## 自定义与插槽

### 自定义位置

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `target-container` | 滚动容器；省略时为页面 | 自定义位置 |
| `popup-container` | 挂载容器；false 原地渲染 | 自定义位置 |
| `visible-height` | 显示阈值（含边界）；数字字符串按 px，不支持 CSS 单位 | 自定义位置 |
| `right` | 右侧偏移；数字按 px，字符串支持 CSS 长度 | 自定义位置 |
| `bottom` | 底部偏移；数字按 px，字符串支持 CSS 长度 | 自定义位置 |
| `aria-label` | 无障碍名称 | 自定义位置 |
<!-- demo-config-notes:end -->

Example source: src/back-top/__demos__/custom-position.vue

```vue
<script setup lang="ts">
import { onMounted, ref } from 'vue'

const scroller = ref<HTMLElement>()
onMounted(() => {
  if (scroller.value) {
    scroller.value.scrollTop = 240
    scroller.value.dispatchEvent(new Event('scroll'))
  }
})
</script>

<template>
  <div class="back-top-demo">
    <p>在面板内滚动，超过 120px 时显示按钮。</p>
    <div class="back-top-demo__frame">
      <div ref="scroller" class="back-top-demo__scroll">
        <p v-for="row in 30" :key="row">A · 滚动内容 {{ row }}</p>
      </div>
      <c-back-top
        :target-container="() => scroller"
        :popup-container="false"
        :visible-height="120"
        :right="64"
        :bottom="32"
        aria-label="回到顶部"
      />
    </div>
  </div>
</template>

<style scoped>
.back-top-demo { display: flex; flex-direction: column; gap: 12px; }
.back-top-demo > p { margin: 0; }
.back-top-demo__frame { position: relative; display: flex; gap: 12px; }
.back-top-demo__scroll { flex: 1; min-width: 0; height: 240px; overflow: auto; border: 1px solid #ddd; border-radius: 8px; }
.back-top-demo__scroll p { padding: 8px 12px; margin: 0; }
</style>
```

## 交互与控制

### 切换滚动容器

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `target-container` | 滚动容器；省略时为页面 | 切换滚动容器、自定义内容与事件 |
| `popup-container` | 挂载容器；false 原地渲染 | 切换滚动容器、自定义内容与事件 |
| `visible-height` | 显示阈值（含边界）；数字字符串按 px，不支持 CSS 单位 | 切换滚动容器、自定义内容与事件 |
| `right` | 右侧偏移；数字按 px，字符串支持 CSS 长度 | 切换滚动容器、自定义内容与事件 |
| `bottom` | 底部偏移；数字按 px，字符串支持 CSS 长度 | 切换滚动容器、自定义内容与事件 |
| `aria-label` | 无障碍名称 | 切换滚动容器、自定义内容与事件 |
<!-- demo-config-notes:end -->

Example source: src/back-top/__demos__/container.vue

```vue
<script setup lang="ts">
import { onMounted, ref } from 'vue'

const scroller = ref<HTMLElement>()
const second = ref<HTMLElement>()
const useSecond = ref(false)
onMounted(() => {
  if (scroller.value) {
    scroller.value.scrollTop = 240
    scroller.value.dispatchEvent(new Event('scroll'))
  }
})
</script>

<template>
  <div class="back-top-demo">
    <p>在面板内滚动，超过 120px 时显示按钮。</p>
    <c-button @click="useSecond = !useSecond">切换滚动目标 {{ useSecond ? 'B' : 'A' }}</c-button>
    <div class="back-top-demo__frame">
      <div ref="scroller" class="back-top-demo__scroll">
        <p v-for="row in 30" :key="row">A · 滚动内容 {{ row }}</p>
      </div>
      <div ref="second" class="back-top-demo__scroll">
        <p v-for="row in 30" :key="row">B · 滚动内容 {{ row }}</p>
      </div>
      <c-back-top
        :target-container="() => useSecond ? second : scroller"
        :popup-container="false"
        :visible-height="120"
        :right="16"
        :bottom="16"
        aria-label="回到顶部"
      />
    </div>
  </div>
</template>

<style scoped>
.back-top-demo { display: flex; flex-direction: column; gap: 12px; }
.back-top-demo > p { margin: 0; }
.back-top-demo__frame { position: relative; display: flex; gap: 12px; }
.back-top-demo__scroll { flex: 1; min-width: 0; height: 240px; overflow: auto; border: 1px solid #ddd; border-radius: 8px; }
.back-top-demo__scroll p { padding: 8px 12px; margin: 0; }
</style>
```

### 自定义内容与事件

Example source: src/back-top/__demos__/custom.vue

```vue
<script setup lang="ts">
import { onMounted, ref } from 'vue'

const scroller = ref<HTMLElement>()
const clicks = ref(0)
onMounted(() => {
  if (scroller.value) {
    scroller.value.scrollTop = 240
    scroller.value.dispatchEvent(new Event('scroll'))
  }
})
</script>

<template>
  <div class="back-top-demo">
    <p>在面板内滚动，超过 120px 时显示按钮。 {{ '点击次数：' }}{{ clicks }}</p>
    <div class="back-top-demo__frame">
      <div ref="scroller" class="back-top-demo__scroll">
        <p v-for="row in 30" :key="row">A · 滚动内容 {{ row }}</p>
      </div>
      <c-back-top
        :target-container="() => scroller"
        :popup-container="false"
        :visible-height="120"
        :right="16"
        :bottom="16"
        @click="clicks++"
        aria-label="回到顶部"
      >TOP</c-back-top>
    </div>
  </div>
</template>

<style scoped>
.back-top-demo { display: flex; flex-direction: column; gap: 12px; }
.back-top-demo > p { margin: 0; }
.back-top-demo__frame { position: relative; display: flex; gap: 12px; }
.back-top-demo__scroll { flex: 1; min-width: 0; height: 240px; overflow: auto; border: 1px solid #ddd; border-radius: 8px; }
.back-top-demo__scroll p { padding: 8px 12px; margin: 0; }
</style>
```

示例使用独立局部容器，避免多个卡片争用页面回顶按钮。不传 `target-container` 时监听页面，不自动查找滚动祖先。无效或未匹配的选择器会隐藏按钮；异步容器使用返回元素的响应式 getter。`popup-container` 只控制按钮挂载位置，不改变滚动目标。

## 生命周期与边界

### 调度生命周期

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `target-container` | 滚动容器；省略时为页面 | 调度生命周期 |
| `popup-container` | 挂载容器；false 原地渲染 | 调度生命周期 |
| `duration` | 回顶动画毫秒数，0 立即回顶 | 调度生命周期 |
| `easing` | 内置曲线或输入/输出 0–1 的自定义缓动函数 | 调度生命周期 |
<!-- demo-config-notes:end -->

Example source: src/back-top/__demos__/scheduler-lifecycle.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import type { BackTopInstance } from "@cedar-design/ui";
const first = ref<HTMLElement>();
const second = ref<HTMLElement>();
const active = ref(true);
const alternate = ref(false);
let retained: BackTopInstance | undefined;
const capture = (instance: BackTopInstance | null) => {
  if (instance) retained = instance;
};
const lower = () => {
  if (first.value) first.value.scrollTop = 300;
  if (second.value) second.value.scrollTop = 300;
};
</script>
<template>
  <div style="position: relative">
    <c-button @click="lower">Scroll down / 滚动到底部</c-button>
    <c-button @click="alternate = !alternate"
      >Switch target / 切换目标</c-button
    >
    <c-button @click="active = !active">Activate / 停用与激活</c-button>
    <c-button @click="retained?.scrollToTop()"
      >Retained command / 保留命令</c-button
    >
    <p>
      Start an animation, switch or deactivate before completion. Old work must
      not resume.
    </p>
    <div ref="first" style="height: 100px; overflow: auto">
      <div style="height: 500px">Target A</div>
    </div>
    <div ref="second" style="height: 100px; overflow: auto">
      <div style="height: 500px">Target B</div>
    </div>
    <KeepAlive>
      <c-back-top
        v-if="active"
        :ref="capture"
        :target-container="() => (alternate ? second : first)"
        :popup-container="false"
        :duration="1000"
        easing="linear"
      />
    </KeepAlive>
  </div>
</template>
```

## API

### Props

| 属性 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| `target-container` | 滚动容器；省略时为页面 | `string \| HTMLElement \| (() => HTMLElement \| null \| undefined)` | `—` |
| `popup-container` | 挂载容器；false 原地渲染 | `string \| HTMLElement \| false` | `body` |
| `visible-height` | 显示阈值（含边界）；数字字符串按 px，不支持 CSS 单位 | `number \| string` | `200` |
| `duration` | 回顶动画毫秒数，0 立即回顶 | `number` | `200` |
| `easing` | 内置曲线或输入/输出 0–1 的自定义缓动函数 | `'linear' \| 'quartOut' \| 'easeInOutCubic' \| ((progress: number) => number)` | `'quartOut'` |
| `right` | 右侧偏移；数字按 px，字符串支持 CSS 长度 | `number \| string` | `—` |
| `bottom` | 底部偏移；数字按 px，字符串支持 CSS 长度 | `number \| string` | `—` |
| `elevation` | 阴影等级；true 为 2，false 关闭 | `boolean \| number` | `true` |
| `aria-label` | 无障碍名称 | `string` | `'Back to top'` |

`popup-container=false` 时按钮绝对定位，父级需 `position: relative`。重复点击替换前次动画；切换目标、KeepAlive 停用和卸载都会清理监听与动画。系统开启减少动态效果时立即回顶，不改变横向滚动位置。

### 事件 / 插槽 / 方法

- `click(event: MouseEvent)`：每次激活通知一次。
- 默认插槽：文字、图标等非交互内容；根节点已是原生 button，不再嵌套 Button 或链接。
- `scrollToTop()`：滚动当前目标，不额外触发 click。
- 键盘：Tab 聚焦可见按钮，Enter / Space 激活；隐藏时不可聚焦。

### 类型

```ts
import type { BackTopProps, BackTopInstance, BackTopTarget, BackTopEasing } from '@cedar-design/ui'
```

### 样式变量

| Token | 默认值 |
| --- | --- |
| `--c-back-top-right` | `40px` |
| `--c-back-top-bottom` | `40px` |
| `--c-back-top-button-size` | `var(--c-sys-control-touch-target)` |
| `--c-back-top-button-border-radius` | `50%` |
| `--c-back-top-font-size` | `var(--c-sys-font-size-md)` |
| `--c-back-top-icon-size` | `20px` |
| `--c-back-top-background` | `var(--c-sys-color-surface-raised)` |
| `--c-back-top-text-color` | `var(--c-sys-color-content-brand)` |
| `--c-back-top-hover-background` | `var(--c-sys-color-state-hover)` |
| `--c-back-top-focus-color` | `var(--c-sys-color-content-brand)` |
| `--c-back-top-focus-width` | `2px` |
| `--c-back-top-focus-offset` | `2px` |
| `--c-back-top-z-index` | `var(--c-z-index-local-sticky)` |

预发布迁移：Cedar 的 `margin-right/bottom` → `right/bottom`、`button-size-width` → `button-size`、`button-size-font/icon` → `font-size/icon-size`、`button-bg/bg-hover/text-color` → `background/hover-background/text-color`（均带组件前缀）。Maple 默认动画改为 200ms，默认目标为页面。旧 BTween 任意曲线字符串改用上述枚举或函数；不保留兼容别名。

---

Document: llms/zh-CN/components/badge.md

<!-- Source: src/badge/README.md; locale: zh-CN; page: /components/badge/ -->

# Badge

与 Maple 使用相同场景、参数和交互顺序；示例源码仅替换组件前缀，主题与站点外壳各自保留。

## 基础示例

### 基础用法

Example source: src/badge/__demos__/basic.vue

```vue
<template>
  <c-space wrap :size="24"
    ><c-badge :content="9"
      ><span style="display: inline-block; padding: 12px; border: 1px solid currentColor; border-radius: 4px"
        >Inbox</span
      ></c-badge
    ><c-badge :content="9" dot
      ><span style="display: inline-block; padding: 12px; border: 1px solid currentColor; border-radius: 4px"
        >Inbox</span
      ></c-badge
    ><c-badge
      ><template #content><span aria-label="New activity">!</span></template
      ><span style="display: inline-block; padding: 12px; border: 1px solid currentColor; border-radius: 4px"
        >Inbox</span
      ></c-badge
    ></c-space
  >
</template>
```

## 外观与状态

### 状态和颜色

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `content` | 徽标显示的内容 | 状态和颜色、外观配置对比 |
| `status` | 徽标的状态 | 状态和颜色 |
| `mode` | 徽标的类型 | 状态和颜色 |
| `description` | 徽标的描述文本 | 状态和颜色 |
| `color` | 徽标的背景色，也可以设置自定义色值 | 状态和颜色 |
| `text-color` | 徽标显示的内容颜色 | 状态和颜色 |
<!-- demo-config-notes:end -->

Example source: src/badge/__demos__/color.vue

```vue
<script setup lang="ts">
const statuses = [
  'default',
  'primary',
  'secondary',
  'tertiary',
  'info',
  'success',
  'warning',
  'danger',
] as const
</script>

<template>
  <c-space direction="column">
    <c-space wrap
      ><c-badge
        v-for="status in statuses"
        :key="status"
        :status="status"
        mode="inline"
        :description="status"
        :content="1"
    /></c-space>
    <c-space wrap
      ><c-badge v-for="status in statuses" :key="status" :status="status" :content="status"
    /></c-space>
    <c-space wrap
      ><c-badge color="#7816ff" text-color="#ffffff" content="Purple" /><c-badge
        color="#005f73"
        text-color="#ffffff"
        content="Teal"
    /></c-space>
  </c-space>
</template>
```

### 外观配置对比

选择一个对比维度后，同屏展示它的全部可选值；其余配置和内容保持一致。可切换其他配置检查组合效果；输入类预览共享一个值。

<details>
<summary>配置说明与使用限制</summary>

#### 外观组合

适用于通知数量和标记。调整变体、状态、尺寸，用相同数据观察变化。内容保持一致，便于比较不同设置的实际效果。

</details>

Example source: src/badge/__demos__/appearance-lab.vue

```vue
<script setup lang="ts">
import { reactive as __demoReactive } from "vue";

const __demoAppearance = __demoReactive({
  variant: "default",
  status: "default",
  size: "md",
});

import { computed as demoComputed, ref as demoRef } from 'vue'
const demoCompareFields = [{"name":"variant","values":["default","outline"]},{"name":"status","values":["default","primary","secondary","tertiary","info","success","warning","danger"]},{"name":"size","values":["xs","sm","md","lg","xl"]}]
const demoCompareAxis = demoRef("variant")
const demoComparedOptions = demoComputed(() => demoCompareFields.find(field => field.name === demoCompareAxis.value)?.values ?? [])
</script>
<template>
  <c-space direction="column" :size="16">
    <c-form layout="vertical">
      <c-form-item layout="vertical" size="sm" label="variant">
        <c-radio-group
          v-model="__demoAppearance['variant']"
          aria-label="variant"
          :options="[
            { label: 'default', value: 'default' },
            { label: 'outline', value: 'outline' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
      <c-form-item layout="vertical" size="sm" label="status">
        <c-select
          v-model="__demoAppearance['status']"
          :clearable="false"
          :options="[
            { label: 'default', value: 'default' },
            { label: 'primary', value: 'primary' },
            { label: 'secondary', value: 'secondary' },
            { label: 'tertiary', value: 'tertiary' },
            { label: 'info', value: 'info' },
            { label: 'success', value: 'success' },
            { label: 'warning', value: 'warning' },
            { label: 'danger', value: 'danger' },
          ]"
          aria-label="status"
        />
      </c-form-item>
      <c-form-item layout="vertical" size="sm" label="size">
        <c-radio-group
          v-model="__demoAppearance['size']"
          aria-label="size"
          :options="[
            { label: 'xs', value: 'xs' },
            { label: 'sm', value: 'sm' },
            { label: 'md', value: 'md' },
            { label: 'lg', value: 'lg' },
            { label: 'xl', value: 'xl' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
    </c-form>
    <p class="demo-config-comparison-hint"><span lang="zh-CN">选择一个对比维度；其他配置和内容保持一致。输入类示例共享同一个值，便于比较外观。</span><span lang="en-US">Compare one dimension while keeping the other settings and content identical. Input specimens share the same value.</span></p>
<c-radio-group v-model="demoCompareAxis" aria-label="Compare configuration" :options="demoCompareFields.map(field => ({ label: field.name, value: field.name }))" />
<div class="demo-config-comparison">
<section v-for="sample in demoComparedOptions" :key="String(sample)">
<p><code>{{ demoCompareAxis }}={{ sample }}</code></p>
<c-badge :content="1000" v-bind="{ ...__demoAppearance, [demoCompareAxis]: sample }" />
</section>
</div>
  </c-space>
</template>

<style scoped>
.demo-config-comparison { display: grid; grid-template-columns: repeat(auto-fit, minmax(min(100%, 220px), 1fr)); gap: 20px; min-width: 0; max-width: 100%; }
.demo-config-comparison > section { min-width: 0; }
.demo-config-comparison p { margin: 0 0 8px; }
html:not([lang='en-US']) .demo-config-comparison-hint > [lang='en-US'],
html[lang='en-US'] .demo-config-comparison-hint > [lang='zh-CN'] { display: none; }
</style>
```

## 布局与排列

### 位置与偏移

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `position` | 浮动徽标在宿主盒子中的物理角落或左右中点，默认 top-right；只在 floating 模式生效，RTL 不反转 | 位置与偏移 |
| `content` | 徽标显示的内容 | 位置与偏移 |
| `dot` | 显示为小红点 | 位置与偏移 |
| `offset-x` | 设置徽标位置的偏移X，mode为inline时无效。 | 位置与偏移 |
| `offset-y` | 设置徽标位置的偏移Y。 | 位置与偏移 |
| `mode` | 徽标的类型 | 位置与偏移 |
<!-- demo-config-notes:end -->

Example source: src/badge/__demos__/position.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const offset = ref(0)
const dot = ref(false)
const positions = ['top-right', 'top-left', 'bottom-right', 'bottom-left', 'left', 'right'] as const
const inlinePositions = ['start', 'end'] as const
</script>

<template>
  <c-space direction="column" :size="24">
    <c-space wrap
      ><c-button @click="offset++">Offset +1</c-button><c-button @click="offset--">Offset -1</c-button
      ><c-button @click="offset = 0">Reset</c-button><c-switch v-model="dot" aria-label="Toggle dot"
    /></c-space>
    <output aria-live="polite">Offset: {{ offset }}px</output>
    <c-space wrap :size="32"
      ><c-badge
        v-for="position in positions"
        :key="position"
        :position="position"
        :content="100"
        :dot="dot"
        :offset-x="offset"
        :offset-y="offset"
        ><span style="display: inline-block; padding: 12px; border: 1px solid currentColor">{{
          position
        }}</span></c-badge
      ></c-space
    >
    <c-space wrap :size="24"
      ><c-badge
        v-for="position in inlinePositions"
        :key="position"
        mode="inline"
        :inline-position="position"
        :content="9"
        :dot="dot"
        :offset-y="offset"
        :description="position"
    /></c-space>
  </c-space>
</template>
```

## 内容与展示

### 内联与独立展示

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `content` | 徽标显示的内容 | 内联与独立展示、小圆点、最大值与零值 |
| `dot` | 显示为小红点 | 内联与独立展示、小圆点、显示与隐藏 |
| `description` | 徽标的描述文本 | 内联与独立展示、显示与隐藏 |
| `show-zero` | 徽标为0时是否显示 | 最大值与零值、显示与隐藏 |
| `mode` | 徽标的类型 | 内联与独立展示 |
| `inline-position` | 内联徽标位于宿主内容的逻辑 start 或 end，默认 end；仅 inline 模式生效 | 内联与独立展示 |
<!-- demo-config-notes:end -->

Example source: src/badge/__demos__/inline.vue

```vue
<script setup lang="ts">
const positions = ['start', 'end'] as const
</script>

<template>
  <c-space direction="column" :size="16">
    <c-space wrap><c-badge :content="1000" /><c-badge :content="1000" dot /></c-space>
    <c-space v-for="position in positions" :key="position" wrap>
      <c-badge mode="inline" :inline-position="position" :content="9" description="Messages" />
      <c-badge mode="inline" :inline-position="position" dot :content="9" description="Messages" />
    </c-space>
  </c-space>
</template>
```

### 小圆点

Example source: src/badge/__demos__/dot.vue

```vue
<template>
  <c-space wrap :size="24"
    ><c-badge dot :content="1"
      ><span
        style="
          display: inline-block;
          padding: 12px;
          border: 1px solid currentColor;
          border-radius: 4px;
        "
        >Inbox</span
      ></c-badge
    ><c-badge dot :content="1" :offset-x="6" :offset-y="-2"
      ><c-link href="#" @click.prevent>Messages</c-link></c-badge
    ></c-space
  >
</template>
```

### 最大值与零值

Example source: src/badge/__demos__/max.vue

```vue
<template>
  <c-space wrap :size="24"
    ><c-badge :content="0"
      ><span style="display: inline-block; padding: 12px; border: 1px solid currentColor; border-radius: 4px"
        >Inbox</span
      ></c-badge
    ><c-badge :content="0" show-zero
      ><span style="display: inline-block; padding: 12px; border: 1px solid currentColor; border-radius: 4px"
        >Inbox</span
      ></c-badge
    ><c-badge :content="100" :max="10"
      ><span style="display: inline-block; padding: 12px; border: 1px solid currentColor; border-radius: 4px"
        >Inbox</span
      ></c-badge
    ><c-badge :content="100"
      ><span style="display: inline-block; padding: 12px; border: 1px solid currentColor; border-radius: 4px"
        >Inbox</span
      ></c-badge
    ><c-badge :content="1000" :max="999"
      ><span style="display: inline-block; padding: 12px; border: 1px solid currentColor; border-radius: 4px"
        >Inbox</span
      ></c-badge
    ></c-space
  >
</template>
```

### 显示与隐藏

Example source: src/badge/__demos__/show.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const show = ref(true)
const content = ref(1)
</script>

<template>
  <c-space direction="column">
    <c-space wrap
      ><c-switch v-model="show" aria-label="Show badge" /><c-button @click="content++">Add</c-button
      ><c-button @click="content = Math.max(0, content - 1)">Subtract</c-button></c-space
    >
    <c-badge :content="0" :show="show" show-zero description="show-zero true" />
    <c-badge :content="0" :show="show" :show-zero="false" description="show-zero false" />
    <c-badge :content="content" :show="show" description="Messages" />
    <c-badge :content="content" :show="show" dot description="Activity" />
  </c-space>
</template>
```

## 自定义与插槽

### 自定义内容

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `content` | 徽标显示的内容 | 自定义内容 |
| `mode` | 徽标的类型 | 自定义内容 |
| `inline-position` | 内联徽标位于宿主内容的逻辑 start 或 end，默认 end；仅 inline 模式生效 | 自定义内容 |
<!-- demo-config-notes:end -->

Example source: src/badge/__demos__/content.vue

```vue
<template>
  <c-space wrap :size="24"
    ><c-badge content="NEW"
      ><span style="display: inline-block; padding: 12px; border: 1px solid currentColor; border-radius: 4px"
        >Inbox</span
      ></c-badge
    ><c-badge content="HOT" mode="inline" inline-position="start"
      ><span style="display: inline-block; padding: 12px; border: 1px solid currentColor; border-radius: 4px"
        >Inbox</span
      ></c-badge
    ><c-badge content="HOT" mode="inline" inline-position="end"
      ><span style="display: inline-block; padding: 12px; border: 1px solid currentColor; border-radius: 4px"
        >Inbox</span
      ></c-badge
    ></c-space
  >
</template>
```

## API

<!-- same-source-api:start -->
### Props

| 参数名          | 描述                                                                               | 类型                                                           |   默认值    |
| --------------- | ---------------------------------------------------------------------------------- | -------------------------------------------------------------- | :---------: |
| description     | 徽标的描述文本                                                                     | `string`                                                       |     `-`     |
| content         | 徽标显示的内容                                                                     | `number \| string`                                             |     `-`     |
| max             | 徽标最大显示数值，如果content超过这个数值会显示为`${max}+`，content 为数字时有效。 | `number`                                                       |    `99`     |
| dot             | 显示为小红点                                                                       | `boolean`                                                      |   `false`   |
| offset-x        | 设置徽标位置的偏移X，mode为inline时无效。                                          | `number`                                                       |     `0`     |
| offset-y        | 设置徽标位置的偏移Y。                                                              | `number`                                                       |     `0`     |
| color           | 徽标的背景色，也可以设置自定义色值                                                 | `string`                                                       |     `-`     |
| text-color      | 徽标显示的内容颜色                                                                 | `string`                                                       |     `-`     |
| mode            | 徽标的类型                                                                         | `'floating' \| 'inline'`                                       | `floating`  |
| position        | 浮动徽标在宿主盒子中的物理角落或左右中点，默认 top-right；只在 floating 模式生效，RTL 不反转 | `'top-right' \| 'top-left' \| 'bottom-right' \| 'bottom-left' \| 'left' \| 'right'` | `top-right` |
| inline-position | 内联徽标位于宿主内容的逻辑 start 或 end，默认 end；仅 inline 模式生效 | `'start' \| 'end'`                                             |    `end`    |
| size            | 徽标的尺寸                                                                         | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'`                         |    `md`     |
| status          | 徽标的状态                                                                         | `SemanticStatus`                                               |  `danger`   |
| show            | 是否显示徽标                                                                       | `boolean`                                                      |   `true`    |
| show-zero       | 徽标为0时是否显示                                                                  | `boolean`                                                      |   `false`   |
| variant         | 徽标的变体                                                                         | `'outline' \| 'default'`                                       |  `default`  |

### Events

无组件自定义事件。

### Slots

| 插槽名  | 说明             | 参数 |
| ------- | ---------------- | ---- |
| default | 徽标的描述文本   | -    |
| content | 徽标中显示的内容 | -    |

### Methods

无公开方法。

### 跨端说明

属性和插槽契约一致。没有 default 插槽且 description 为空时自动独立内联展示；未提供 content 时显示圆点。两端分别通过各自配置读取文字方向，主题颜色和 CSS 前缀由各端提供。
<!-- same-source-api:end -->

### 样式变量

以下为组件使用的 css 变量，可以使用 [StyleProvider 组件](#/zh-CN/style-provider) 进行样式定制。

| 变量 | 默认值 |
| --- | --- |
| `--c-badge-font-weight` | `var(--c-sys-font-weight-medium)` |
| `--c-badge-description-size-xs-font-size` | `var(--c-sys-font-size-xs)` |
| `--c-badge-description-size-sm-font-size` | `var(--c-sys-font-size-xs)` |
| `--c-badge-description-size-md-font-size` | `var(--c-sys-font-size-md)` |
| `--c-badge-description-size-lg-font-size` | `var(--c-sys-font-size-lg)` |
| `--c-badge-description-size-xl-font-size` | `var(--c-sys-font-size-xl)` |
| `--c-badge-description-text-color` | `var(--c-sys-color-content-primary)` |
| `--c-badge-size-xs-font-size` | `var(--c-sys-font-size-xs)` |
| `--c-badge-size-sm-font-size` | `var(--c-sys-font-size-xs)` |
| `--c-badge-size-md-font-size` | `var(--c-sys-font-size-xs)` |
| `--c-badge-size-lg-font-size` | `var(--c-sys-font-size-md)` |
| `--c-badge-size-xl-font-size` | `var(--c-sys-font-size-lg)` |
| `--c-badge-size-xs-scale` | `0.6667` |
| `--c-badge-size-sm-scale` | `0.8333` |
| `--c-badge-size-md-scale` | `1` |
| `--c-badge-size-lg-scale` | `1` |
| `--c-badge-size-xl-scale` | `1` |
| `--c-badge-size-xs-dot-width` | `4px` |
| `--c-badge-size-sm-dot-width` | `5px` |
| `--c-badge-size-md-dot-width` | `6px` |
| `--c-badge-size-lg-dot-width` | `7px` |
| `--c-badge-size-xl-dot-width` | `8px` |
| `--c-badge-size-xs-dot-height` | `4px` |
| `--c-badge-size-sm-dot-height` | `5px` |
| `--c-badge-size-md-dot-height` | `6px` |
| `--c-badge-size-lg-dot-height` | `7px` |
| `--c-badge-size-xl-dot-height` | `8px` |
| `--c-badge-size-xs-space` | `0px` |
| `--c-badge-size-sm-space` | `var(--c-sys-space-1)` |
| `--c-badge-size-md-space` | `var(--c-sys-space-3)` |
| `--c-badge-size-lg-space` | `var(--c-sys-space-3)` |
| `--c-badge-size-xl-space` | `var(--c-sys-space-4)` |
| `--c-badge-size-xs-padding` | `0 var(--c-sys-space-3)` |
| `--c-badge-size-sm-padding` | `0 var(--c-sys-space-3)` |
| `--c-badge-size-md-padding` | `0 var(--c-sys-space-4)` |
| `--c-badge-size-lg-padding` | `0 var(--c-sys-space-4)` |
| `--c-badge-size-xl-padding` | `0 10px` |
| `--c-badge-size-xs-height` | `20px` |
| `--c-badge-size-sm-height` | `20px` |
| `--c-badge-size-md-height` | `24px` |
| `--c-badge-size-lg-height` | `28px` |
| `--c-badge-size-xl-height` | `32px` |
| `--c-badge-size-xs-border-radius` | `20px` |
| `--c-badge-size-sm-border-radius` | `20px` |
| `--c-badge-size-md-border-radius` | `24px` |
| `--c-badge-size-lg-border-radius` | `28px` |
| `--c-badge-size-xl-border-radius` | `32px` |
| `--c-badge-bg-color` | `rgb(var(--c-danger-7))` |
| `--c-badge-text-color` | `var(--c-sys-color-content-on-dark)` |
| `--c-badge-status-default-bg-color` | `#e0e0e0` |
| `--c-badge-status-default-text-color` | `var(--c-sys-color-content-on-bright)` |
| `--c-badge-status-info-bg-color` | `var(--c-sys-color-status-info)` |
| `--c-badge-status-info-text-color` | `var(--c-sys-color-content-on-dark)` |
| `--c-badge-status-success-bg-color` | `var(--c-sys-color-status-success)` |
| `--c-badge-status-success-text-color` | `var(--c-sys-color-content-on-dark)` |
| `--c-badge-status-warning-bg-color` | `var(--c-sys-color-status-warning)` |
| `--c-badge-status-warning-text-color` | `var(--c-sys-color-content-on-dark)` |
| `--c-badge-status-danger-bg-color` | `rgb(var(--c-danger-7))` |
| `--c-badge-status-danger-text-color` | `var(--c-sys-color-content-on-dark)` |
| `--c-badge-status-primary-bg-color` | `var(--c-sys-color-action-primary)` |
| `--c-badge-status-primary-text-color` | `var(--c-sys-color-content-on-dark)` |
| `--c-badge-status-secondary-bg-color` | `rgb(var(--c-gray-6))` |
| `--c-badge-status-secondary-text-color` | `var(--c-sys-color-content-on-dark)` |
| `--c-badge-status-tertiary-bg-color` | `rgb(var(--c-gray-7))` |
| `--c-badge-status-tertiary-text-color` | `var(--c-sys-color-content-on-dark)` |
| `--c-badge-variant-outline-bg-color` | `transparent` |
| `--c-badge-variant-outline-text-color` | `var(--c-sys-color-content-danger)` |
| `--c-badge-variant-outline-status-info-text-color` | `var(--c-sys-color-content-info)` |
| `--c-badge-variant-outline-status-success-text-color` | `var(--c-sys-color-content-success)` |
| `--c-badge-variant-outline-status-warning-text-color` | `var(--c-sys-color-content-warning)` |
| `--c-badge-variant-outline-status-danger-text-color` | `var(--c-sys-color-content-danger)` |
| `--c-badge-variant-outline-status-primary-text-color` | `var(--c-sys-color-content-brand)` |
| `--c-badge-variant-outline-status-default-text-color` | `var(--c-sys-color-content-primary)` |
| `--c-badge-variant-outline-status-secondary-text-color` | `var(--c-sys-color-content-secondary)` |
| `--c-badge-variant-outline-status-tertiary-text-color` | `var(--c-sys-color-content-secondary)` |
| `--c-badge-border-color` | `var(--c-sys-color-surface-default)` |
| `--c-badge-offset` | `2px` |
| `--c-badge-ring-width` | `2px` |

填充徽标的文字配色以 Button 为准：primary、info、success、warning、danger、secondary 使用 `content-on-dark`；tertiary 在亮色使用 `content-on-dark`，暗色使用 `content-on-bright`。默认通知徽标使用红底白字，中性背景 `#e0e0e0` 为固定浅灰色。

彩色轮廓文字和描边与 Button 一致，使用对应的 `content-brand` / `content-info` / `content-success` / `content-warning` / `content-danger` 语义色；secondary 与 tertiary 轮廓均使用 `content-secondary` 保持可读性。`variant-outline-bg-color` 对所有状态均生效，默认透明。`color` 属性覆盖轮廓文字和描边，`text-color` 进一步覆盖文字；二者均保留背景变量的控制权。自定义前景或背景后须重新验证对比度。

### 类型定义

组件导出以下类型定义

```ts
import type { BadgeInstance } from '@cedar-design/ui'
```

### 颜色覆盖边界

bg-color 兜底和 danger 填充均使用红色背景与白色文字：浅色主题为 danger 第 7 阶，暗色主题为第 4 阶。中性固定浅灰与 secondary/tertiary 灰阶是有意的组件配色；border-color 隔离环可按宿主表面覆盖。自定义 color/text-color 由调用方保证对比度。

---

Document: llms/zh-CN/components/breadcrumb.md

<!-- Source: src/breadcrumb/README.md; locale: zh-CN; page: /components/breadcrumb/ -->

# Breadcrumb

面包屑是辅助导航模式，用于识别页面在层次结构内的位置，并根据需要向上返回。

当前位置（最后一级）默认使用主文字色，不额外加粗，并标记 `aria-current="page"`。纯文本无点击反馈；配置 `href` 的链接、绑定 `@click` 的操作和下拉入口显示品牌色、手型及悬停 / 按下反馈，键盘聚焦时显示焦点轮廓。`@click` 操作支持 Enter 和空格。最后一级通常保持纯文本；显式提供链接或操作时仍可交互。

触屏设备上，可点击项的触摸区域至少为 44 × 44px；按下显示底色和下划线，松手后恢复，不保留鼠标悬停效果。省略图标支持点击查看隐藏路径。

## 基础示例

### 基本用法

面包屑的基本用法

Example source: src/breadcrumb/__demos__/basic.vue

```vue
<template>
  <c-breadcrumb>
    <c-breadcrumb-item>Home</c-breadcrumb-item>
    <c-breadcrumb-item>Channel</c-breadcrumb-item>
    <c-breadcrumb-item>News</c-breadcrumb-item>
  </c-breadcrumb>
</template>

<script lang="ts">
</script>
```

## 内容与展示

### 参数化配置

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `routes` | 设置路径 | 参数化配置、带有下拉菜单、显示省略 |
| `max-count` | 最多展示的正常面包屑项数量，不包含 more（0 表示不限制） | 显示省略 |
<!-- demo-config-notes:end -->

通过`routes`来传递面包屑数据。若是要自定义面包屑的话，建议使用`BreadcrumbItem`
组件默认仅为前面的层级渲染链接，最后一级保持文本；可通过 `item-render` 插槽自定义渲染。

Example source: src/breadcrumb/__demos__/routes.vue

```vue
<template>
  <c-space direction="column">
    <c-breadcrumb :routes="routes" @click.prevent />
    <c-breadcrumb :routes="routes">
      <template #item-render="{ route, routes, paths }">
        <span v-if="route === routes[routes.length - 1]">{{ route.label }}</span>
        <c-link v-else :href="paths.join('/')" @click.prevent>
          {{ route.label }}
        </c-link>
      </template>
    </c-breadcrumb>
    <c-breadcrumb :routes="routes">
      <template #item-render="{ route, routes }">
        <span v-if="route === routes[routes.length - 1]">{{ route.label }}</span>
        <RouterLink v-else :to="route.to">
          {{ route.label }}
        </RouterLink>
      </template>
    </c-breadcrumb>
  </c-space>
</template>

<script lang="ts">
import { RouterLink } from 'vue-router'

export default {
  components: { RouterLink },
  setup() {
    const routes = [
      {
        path: '/',
        to: { query: { breadcrumb: 'home' } },
        label: 'Home',
      },
      {
        path: '/channel',
        to: { query: { breadcrumb: 'channel' } },
        label: 'Channel',
      },
      {
        path: '/news',
        to: { query: { breadcrumb: 'news' } },
        label: 'News',
      },
    ]
    return { routes }
  },
}
</script>
```

### 带有下拉菜单

通过`droplist`或者`routes`来指定下拉菜单。

Example source: src/breadcrumb/__demos__/droplist.vue

```vue
<template>
  <c-space direction="column">
    <c-breadcrumb :routes="routes" @click.prevent />
    <c-breadcrumb>
      <c-breadcrumb-item>Home</c-breadcrumb-item>
      <c-breadcrumb-item :droplist="droplist"> Channel </c-breadcrumb-item>
      <c-breadcrumb-item>News</c-breadcrumb-item>
    </c-breadcrumb>
    <c-breadcrumb>
      <c-breadcrumb-item>Home</c-breadcrumb-item>
      <c-breadcrumb-item>
        <template #droplist>
          <c-menu-option>Option 1</c-menu-option>
          <c-menu-option>Option 2</c-menu-option>
          <c-menu-option>Option 3</c-menu-option>
        </template>
        Channel
      </c-breadcrumb-item>
      <c-breadcrumb-item>News</c-breadcrumb-item>
    </c-breadcrumb>
  </c-space>
</template>

<script lang="ts">
export default {
  setup() {
    const routes = [
      {
        path: '/',
        label: 'Home',
      },
      {
        path: '/channel',
        label: 'Channel',
        children: [
          { path: '/goods', label: 'Goods' },
          { path: '/wallet', label: 'Wallet' },
        ],
      },
      {
        path: '/news',
        label: 'News',
      },
    ]
    const droplist = [
      {
        path: '/goods',
        label: 'Goods',
      },
      {
        path: '/wallet',
        label: 'Wallet',
      },
    ]
    return { routes, droplist }
  },
}
</script>
```

### 显示省略

通过`max-count`来指定面包屑的最多渲染数量，超出的部分将显示为省略号

Example source: src/breadcrumb/__demos__/max-count.vue

```vue
<template>
  <c-space direction="column">
    <c-breadcrumb :max-count="3">
      <c-breadcrumb-item>Home</c-breadcrumb-item>
      <c-breadcrumb-item>Sub Home</c-breadcrumb-item>
      <c-breadcrumb-item>All Channel</c-breadcrumb-item>
      <c-breadcrumb-item>Channel</c-breadcrumb-item>
      <c-breadcrumb-item>News</c-breadcrumb-item>
      <c-breadcrumb-item>Post</c-breadcrumb-item>
    </c-breadcrumb>
    <c-breadcrumb :routes="maxRoutes" :max-count="3" @click.prevent>
      <template #more-icon="{ omittedItems }">
        <c-tooltip :trigger="['hover', 'focus', 'click']" :content="omittedItems.map((item) => item.label).join(' / ')">
          <c-icon-more />
        </c-tooltip>
      </template>
    </c-breadcrumb>
  </c-space>
</template>

<script lang="ts">
export default {
  setup() {
    const maxRoutes = [
      { path: '/', label: 'Home' },
      { path: '/sub-home', label: 'Sub Home' },
      { path: '/all-channel', label: 'All Channel' },
      { path: '/channel', label: 'Channel' },
      { path: '/news', label: 'News' },
      { path: '/post', label: 'Post' },
    ]
    return { maxRoutes }
  },
}
</script>
```

### 链接与点击

对比纯文本、`href` 链接和 `@click` 操作。点击后下方显示选择结果；最后一级默认保持纯文本。省略项不会触发 `click`。

Example source: src/breadcrumb/__demos__/link.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'

const lastAction = ref('尚未操作')
const record = (label: string) => { lastAction.value = `已选择 ${label}` }
</script>

<template>
  <c-space direction="column">
    <div>纯文本：仅展示路径</div>
    <c-breadcrumb>
      <c-breadcrumb-item>Home</c-breadcrumb-item>
      <c-breadcrumb-item>Channel</c-breadcrumb-item>
      <c-breadcrumb-item>News</c-breadcrumb-item>
    </c-breadcrumb>
    <div>链接：悬停或聚焦查看反馈</div>
    <c-breadcrumb>
      <c-breadcrumb-item href="#/home" @click.prevent="record('Home')">Home</c-breadcrumb-item>
      <c-breadcrumb-item href="#/channel" @click.prevent="record('Channel')">Channel</c-breadcrumb-item>
      <c-breadcrumb-item>News</c-breadcrumb-item>
    </c-breadcrumb>
    <div>点击操作：支持 Enter / 空格</div>
    <c-breadcrumb>
      <c-breadcrumb-item @click="record('Home')">Home</c-breadcrumb-item>
      <c-breadcrumb-item @click="record('Channel')">Channel</c-breadcrumb-item>
      <c-breadcrumb-item>News</c-breadcrumb-item>
    </c-breadcrumb>
    <span role="status">{{ lastAction }}</span>
  </c-space>
</template>
```

## 自定义与插槽

### 自定义分隔符

通过`separator`属性或插槽自定义分隔符，面包屑子项也可通过`separator`属性或插槽自定义分隔符，且优先级高于父项。

Example source: src/breadcrumb/__demos__/custom-split.vue

```vue
<template>
  <c-space direction="column">
    <c-breadcrumb>
      <template #separator>
        <c-icon-oblique-line />
      </template>
      <c-breadcrumb-item>Home</c-breadcrumb-item>
      <c-breadcrumb-item>Channel</c-breadcrumb-item>
      <c-breadcrumb-item>News</c-breadcrumb-item>
    </c-breadcrumb>
    <c-breadcrumb separator="~">
      <c-breadcrumb-item>Home</c-breadcrumb-item>
      <c-breadcrumb-item>Channel</c-breadcrumb-item>
      <c-breadcrumb-item>News</c-breadcrumb-item>
    </c-breadcrumb>
    <c-breadcrumb>
      <template #separator>
        <c-icon-oblique-line />
      </template>
      <c-breadcrumb-item separator="->">Home</c-breadcrumb-item>
      <c-breadcrumb-item>Channel</c-breadcrumb-item>
      <c-breadcrumb-item>News</c-breadcrumb-item>
    </c-breadcrumb>
  </c-space>
</template>

<script lang="ts">
</script>
```

### 自定义图标

可以在内容中使用自定义图标

Example source: src/breadcrumb/__demos__/custom-icon.vue

```vue
<template>
  <c-space direction="column">
    <c-breadcrumb>
      <c-breadcrumb-item>
        <c-icon-home />
      </c-breadcrumb-item>
      <c-breadcrumb-item>Channel</c-breadcrumb-item>
      <c-breadcrumb-item>News</c-breadcrumb-item>
    </c-breadcrumb>
    <c-breadcrumb>
      <c-breadcrumb-item>
        <c-icon-home />
      </c-breadcrumb-item>
      <c-breadcrumb-item>
        <c-icon-link />
        Channel
      </c-breadcrumb-item>
      <c-breadcrumb-item>News</c-breadcrumb-item>
    </c-breadcrumb>
  </c-space>
</template>

<script lang="ts">
</script>
```

## API

### Breadcrumb Props

| 属性            | 说明                                                                                                                              | 类型                              | 默认值 |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ------ |
| max-count       | 最多展示的正常面包屑项数量，不包含 more（0 表示不限制）                                                                           | `number`                          | `0`    |
| routes          | 设置路径                                                                                                                          | `BreadcrumbRoute[]`               | `-`    |
| separator       | 分隔符文字                                                                                                                        | `string \| number`                | `/`    |

### Breadcrumb Slots

| 插槽名      | 说明                               | 参数                                                                        |
| ----------- | ---------------------------------- | --------------------------------------------------------------------------- |
| more-icon   | 自定义更多图标                     | `omittedItems` `count` `start` `end`                                        |
| item-render | routes设置时生效，自定义渲染面包屑 | `route:BreadcrumbRoute`<br/>`routes:BreadcrumbRoute[]`<br/>`paths:string[]` |
| separator   | 自定义分隔符                       | `-`                                                                         |

### BreadcrumbItem Props

| 属性           | 说明         | 类型                          | 默认值 |
| -------------- | ------------ | ----------------------------- | ------ |
| separator      | 分隔符文字   | `string \| number`            | `-`    |
| href           | 跳转链接     | `string`                      | `-`    |
| droplist       | 下拉菜单内容 | `BreadcrumbRoute['children']` | `-`    |
| dropdown-props | 下拉菜单属性 | `MenuProps`           | `-`    |

### BreadcrumbItem Events

| 事件名 | 说明     | 参数           |
| ------ | -------- | -------------- |
| click  | 点击事件（省略项不触发） | `event: MouseEvent` |
| select | 选择内置下拉项时触发 | `route: BreadcrumbRoute, event?: Event` |

### BreadcrumbItem Slots

| 插槽名    | 说明           | 参数 |
| --------- | -------------- | ---- |
| droplist  | 自定义下拉菜单 | `-`  |
| separator | 自定义分隔符   | `-`  |

### BreadcrumbRoute

| 参数名   | 描述                      | 类型                           | 默认值 |
| -------- | ------------------------- | ------------------------------ | ------ |
| label    | 面包屑名称                | `string`                       | `-`    |
| path     | 跳转路径(`a`标签的`href`) | `string`                       |
| children | 下拉菜单展示项            | `{label:string,path:string}[]` | `-`    |

## 类型定义

组件导出以下类型定义

```ts
import type { BreadcrumbProps, BreadcrumbItemProps, BreadcrumbRoute } from '@cedar-design/ui'
```

## 同源实现与平台边界

Breadcrumb 与 BreadcrumbItem 在 Cedar / Maple 中独立复制维护，主体、Props、上下文、类型、关键样式及配对测试纳入 `design-ui/bin/copied-components-check.mjs`。图标、安装入口、菜单实现和主题 token 由各库本地提供。

- 非空 `routes` 优先于默认插槽；空数组回退到插槽。默认路由渲染仅前面的项目带链接，最后一项标记 `aria-current="page"`；`item-render` 自行控制链接。
- 分隔符优先级：子项插槽 → 子项属性 → 父级插槽 → 父级属性；支持 `0` 和空字符串。
- `max-count` 沿用现有边界：总数大于 `max-count + 1` 才折叠；保留首项和尾部项目，省略位置不触发原项的点击、链接或下拉菜单。
- 内置下拉选择派发 `select(route, event)`。动态增删、重排及 SSR 会同步计算索引和分隔符。
- Cedar 项内容新增 `__content` 包装，属性透传到该内容节点；Maple 原有主题变量继续通过 token 映射生效。

---

Document: llms/zh-CN/components/button.md

<!-- Source: src/button/README.md; locale: zh-CN; page: /components/button/ -->

Button 的禁用配色按变体区分：彩色实心使用淡化状态背景；text/outline 保持透明背景并淡化状态文字；tonal 保留浅色背景。中性按钮使用中性禁用色。禁用时暂停 color/text-color 覆盖，关闭 hover/active 反馈和阴影。

# Button

两端使用同一份实现和示例，组件前缀、主题基础变量与注册入口各自保留。

## 基础示例

### 八种主题色

Example source: src/button/__demos__/basic.vue

```vue
<script setup lang="ts">
const statuses = [
  "default",
  "primary",
  "secondary",
  "tertiary",
  "info",
  "success",
  "warning",
  "danger",
] as const;
</script>
<template>
  <c-space wrap size="12px">
    <c-button v-for="status in statuses" :key="status" :status="status">{{
      status
    }}</c-button>
  </c-space>
</template>
```

## 外观与状态

### 变体、状态与尺寸

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `variant` | 外观；省略时继承按钮组，否则 default | 变体、状态与尺寸、自定义颜色 |
| `size` | 尺寸；省略时继承按钮组，否则 md | 变体、状态与尺寸、五档尺寸 |
| `status` | 主题色；省略时继承按钮组，否则 default | 变体、状态与尺寸 |
| `disabled` | 禁用；省略时继承按钮组，显式 false 可覆盖 | 禁用与链接拦截 |
| `component` | 根标签，链接属性通过 attrs 传入 | 禁用与链接拦截 |
| `loading` | 加载状态，禁止点击和链接跳转 | 禁用与链接拦截 |
<!-- demo-config-notes:end -->

选择变体和尺寸，同时对比八种状态色。实心适合主要操作，text 和 outline 适合次要操作；可切换卡片背景，对照透明按钮在不同背景上的表现。 变体、尺寸和背景选项较少，使用按钮式 RadioGroup 直接展示；Form/FormItem 提供标准字段布局，Card 承载背景对照。

Example source: src/button/__demos__/variants.vue

```vue
<script setup lang="ts">
import { computed, ref } from "vue";

const variant = ref("default");
const size = ref("md");
const background = ref("navy");
const variants = ["default", "text", "outline", "tonal"];
const sizes = ["xs", "sm", "md", "lg", "xl"];
const statuses = [
  "default",
  "primary",
  "secondary",
  "tertiary",
  "info",
  "success",
  "warning",
  "danger",
];
const backgrounds = [
  { label: "Navy / 深蓝", value: "navy", color: "#17224B" },
  { label: "White / 白色", value: "light", color: "#FFFFFF" },
  { label: "Light gray / 浅灰", value: "muted", color: "#F5F5F5" },
  { label: "Dark gray / 深灰", value: "dark", color: "#252525" },
];
const cardBackground = computed(
  () => backgrounds.find((item) => item.value === background.value)?.color,
);
</script>
<template>
  <c-space direction="column" block align="stretch" :size="16">
    <c-form layout="vertical" size="sm">
      <c-form-item label="Variant" field="variant">
        <c-radio-group
          v-model="variant"
          :options="variants"
          aria-label="Button variant"
          variant="button"
        />
      </c-form-item>
      <c-form-item label="Size" field="size">
        <c-radio-group
          v-model="size"
          :options="sizes"
          aria-label="Button size"
          variant="button"
        />
      </c-form-item>
      <c-form-item label="Background" field="background">
        <c-radio-group
          v-model="background"
          :options="backgrounds"
          aria-label="Button background"
          variant="button"
        />
      </c-form-item>
    </c-form>
    <c-card
      class="button-variant-card"
      :data-background="background"
      :elevation="false"
      :style="{ '--c-card-background': cardBackground }"
    >
      <c-space wrap>
        <c-button
          v-for="status in statuses"
          :key="status"
          :status="status"
          :variant="variant"
          :size="size"
          >{{ status }}</c-button
        >
      </c-space>
    </c-card>
  </c-space>
</template>
```

### 五档尺寸

同一平台的水平 Button 与 Input 默认按相同 size 对齐高度和字号。Cedar 高度为 24/28/32/36/44px，Maple 为 32/40/48/56/64px；按钮单侧内边距为 8/12/16/20/24px，图标与文字间距为 6px。堆叠按钮使用独立的内容高度规则。组件局部样式覆盖仍各自生效。

Example source: src/button/__demos__/size.vue

```vue
<script setup lang="ts">
const sizes = ["xs", "sm", "md", "lg", "xl"] as const;
</script>
<template>
  <c-space direction="column" :size="16">
    <c-space v-for="size in sizes" :key="size" align="center" wrap :size="12">
      <span>{{ size }}</span>
      <c-input
        :size="size"
        :aria-label="`Input ${size}`"
        placeholder="Input"
        style="width: 140px"
      />
      <c-button :size="size">Button</c-button>
      <c-button :size="size"
        ><template #icon><c-icon-search /></template>Search</c-button
      >
    </c-space>
  </c-space>
</template>
```

### 禁用与链接拦截

Example source: src/button/__demos__/disabled.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
const clicks = ref(0);
</script>
<template>
  <c-space wrap size="12px">
    <c-button disabled @click="clicks++">Disabled button</c-button>
    <c-button
      component="a"
      href="#blocked-button-link"
      disabled
      @click="clicks++"
      >Disabled link</c-button
    >
    <c-button
      component="a"
      href="#blocked-button-link"
      loading
      @click="clicks++"
      >Loading link</c-button
    >
  </c-space>
  <p aria-live="polite">Blocked clicks: {{ clicks }}</p>
</template>
```

### 自定义颜色

Example source: src/button/__demos__/custom-color.vue

```vue
<template>
  <c-space wrap size="12px">
    <c-button color="#6750a4" text-color="white">Custom filled</c-button>
    <c-button
      color="linear-gradient(to bottom right, #6750a4, #d0bcff)"
      text-color="white"
      >Gradient</c-button
    >
    <c-button color="#6750a4" variant="text">Custom text</c-button>
    <c-button color="#6750a4" variant="outline">Custom outline</c-button>
    <c-button color="#6750a4" variant="tonal">Custom tonal</c-button>
  </c-space>
</template>
```

## 图标与布局

### 图标与图文布局

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `status` | 主题色；省略时继承按钮组，否则 default | 图标与图文布局 |
| `variant` | 外观；省略时继承按钮组，否则 default | 图标与图文布局 |
| `size` | 尺寸；省略时继承按钮组，否则 md | 图标与图文布局 |
| `stacked` | 图标文字纵向排列；省略时继承按钮组 | 图标与图文布局 |
| `round` | 圆形按钮 | 图标与图文布局 |
| `block` | 占满可用宽度 | 块级按钮 |
<!-- demo-config-notes:end -->

使用内置图标，切换四种变体和五档尺寸，对比纯图标、横排图文、上下堆叠。堆叠按钮按内容撑高，上下至少保留 8px 内边距。纯图标只传 icon 插槽；round 控制圆形，stacked 控制上下排列。

Example source: src/button/__demos__/icons.vue

```vue
<script setup lang="ts">
import { ref } from "vue";

const sizes = ["xs", "sm", "md", "lg", "xl"] as const;
const variants = ["default", "text", "outline", "tonal"] as const;
const layouts = ["icon", "inline", "stacked"] as const;
const size = ref<(typeof sizes)[number]>("md");
const variant = ref<(typeof variants)[number]>("tonal");
const items = [
  { status: "default", icon: "plus", label: "Add" },
  { status: "primary", icon: "reply", label: "Reply" },
  { status: "info", icon: "info-circle", label: "Info" },
  { status: "success", icon: "check", label: "Confirm" },
  { status: "warning", icon: "delete", label: "Delete" },
  { status: "danger", icon: "close", label: "Close" },
] as const;
</script>
<template>
  <c-space direction="column" :size="16">
    <c-form layout="vertical" size="sm">
      <c-form-item label="Variant" field="variant">
        <c-radio-group
          v-model="variant"
          :options="variants"
          aria-label="Icon button variant"
          variant="button"
        />
      </c-form-item>
      <c-form-item label="Size" field="size">
        <c-radio-group
          v-model="size"
          :options="sizes"
          aria-label="Icon button size"
          variant="button"
        />
      </c-form-item>
    </c-form>
    <c-space
      v-for="layout in layouts"
      :key="layout"
      direction="column"
      :size="8"
    >
      <span>{{
        layout === "icon"
          ? "Icon only / 纯图标"
          : layout === "inline"
            ? "Icon and text / 横排图文"
            : "Stacked / 上下堆叠"
      }}</span>
      <c-space wrap>
        <c-button
          v-for="item in items"
          :key="item.label"
          :status="item.status"
          :variant="variant"
          :size="size"
          :stacked="layout === 'stacked'"
          :round="layout === 'icon'"
          :aria-label="item.label"
        >
          <template #icon>
            <c-icon-plus v-if="item.icon === 'plus'" />
            <c-icon-reply v-else-if="item.icon === 'reply'" />
            <c-icon-info-circle v-else-if="item.icon === 'info-circle'" />
            <c-icon-check v-else-if="item.icon === 'check'" />
            <c-icon-delete v-else-if="item.icon === 'delete'" />
            <c-icon-close v-else-if="item.icon === 'close'" />
          </template>
          <template v-if="layout !== 'icon'" #default>{{
            item.label
          }}</template>
        </c-button>
      </c-space>
    </c-space>
  </c-space>
</template>
```

### 块级按钮

Example source: src/button/__demos__/block.vue

```vue
<template>
  <c-button block>Full width</c-button>
</template>
```

## 按钮组

### 按钮组继承与覆盖

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `status` | 主题色；省略时继承按钮组，否则 default | 按钮组继承与覆盖 |
| `disabled` | 禁用；省略时继承按钮组，显式 false 可覆盖 | 按钮组继承与覆盖 |
| `loading` | 加载状态，禁止点击和链接跳转 | 按钮组图文与加载 |
<!-- demo-config-notes:end -->

切换组尺寸和禁用状态，观察子按钮继承配置。子按钮可独立覆盖状态色，显式 disabled=false 可覆盖组禁用。

Example source: src/button/__demos__/button-group.vue

```vue
<script setup lang="ts">
import { ref } from "vue";

const size = ref("md");
const disabled = ref(false);
</script>
<template>
  <c-space direction="column" :size="16" class="button-group-demo">
    <c-form layout="vertical" size="sm">
      <c-form-item label="Size" field="size">
        <c-radio-group
          v-model="size"
          aria-label="Button group size"
          :options="['xs', 'sm', 'md', 'lg', 'xl']"
          variant="button"
        />
      </c-form-item>
      <c-form-item label="State" field="disabled"
        ><c-checkbox v-model="disabled">Disable group</c-checkbox></c-form-item
      >
    </c-form>
    <div class="button-group-demo__scroll">
      <c-button-group aria-label="Document actions" status="primary" :size="size" :disabled="disabled">
        <c-button>Inherited</c-button>
        <c-button status="success">Status override</c-button>
        <c-button :disabled="false">Enabled override</c-button>
      </c-button-group>
    </div>
  </c-space>
</template>
<style scoped>
.button-group-demo {
  width: 100%;
}
.button-group-demo__scroll {
  max-width: 100%;
  overflow-x: auto;
}
</style>
```

### 按钮组布局

切换 Mixed variants，让中间操作使用 text 外观，对照横向与纵向的接缝。

在水平和垂直排列中比较变体和尺寸。尺寸、变体与排列方向共同组成三个外观维度。

Example source: src/button/__demos__/button-group-layout.vue

```vue
<script setup lang="ts">
import { ref } from "vue";

const mixed = ref(false)
const variant = ref("default");
const size = ref("md");
</script>
<template>
  <c-space direction="column" :size="16">
    <c-form layout="vertical" size="sm">
      <c-form-item label="Variant" field="variant">
        <c-radio-group
          v-model="variant"
          aria-label="Button group variant"
          :options="['default', 'text', 'outline', 'tonal']"
          variant="button"
        />
      </c-form-item>
      <c-form-item label="Size" field="size">
        <c-radio-group
          v-model="size"
          aria-label="Button group size"
          :options="['xs', 'sm', 'md', 'lg', 'xl']"
          variant="button"
        />
      </c-form-item>
      <c-form-item label="Mixed variants"><c-checkbox v-model="mixed">Text override in middle</c-checkbox></c-form-item>
    </c-form>
    <c-space wrap align="flex-start" :size="24">
      <c-button-group
        v-for="vertical in [false, true]"
        :key="String(vertical)"
        :aria-label="vertical ? 'Vertical page actions' : 'Horizontal page actions'"
        :vertical="vertical"
        :variant="variant"
        :size="size"
        status="primary"
      >
        <c-button>Prev</c-button><c-button :variant="mixed ? 'text' : undefined">Info</c-button><c-button>Next</c-button>
      </c-button-group>
    </c-space>
  </c-space>
</template>
```

### 按钮组图文与加载

切换图文堆叠和排列方向，再启用第一个按钮的加载状态；其他操作仍可独立使用。竖向按钮组的横排图文按起始边对齐，避免文字长度不同导致图标错位。

Example source: src/button/__demos__/button-group-content.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
const stacked = ref(false);
const vertical = ref(false);
const loading = ref(false);
</script>
<template>
  <c-space direction="column" :size="16">
    <c-space wrap>
      <c-checkbox v-model="stacked">Stacked labels</c-checkbox>
      <c-checkbox v-model="vertical">Vertical group</c-checkbox>
      <c-checkbox v-model="loading">Load first action</c-checkbox>
    </c-space>
    <c-button-group aria-label="Save or cancel" status="primary" :stacked="stacked" :vertical="vertical">
      <c-button :loading="loading"
        ><template #icon><c-icon-check /></template>Save</c-button
      >
      <c-button
        ><template #icon><c-icon-close /></template>Cancel</c-button
      >
    </c-button-group>
  </c-space>
</template>
```

## 表单与事件

### 表单控件尺寸对照

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `size` | 尺寸；省略时继承按钮组，否则 md | 表单控件尺寸对照 |
| `variant` | 外观；省略时继承按钮组，否则 default | 表单控件尺寸对照 |
| `html-type` | 原生按钮类型 | 原生表单、焦点与触摸事件 |
| `focusable` | 允许 Tab 顺序聚焦；不影响通过代码聚焦 | 原生表单、焦点与触摸事件 |
<!-- demo-config-notes:end -->

切换五档 size 和三种字段变体，比较 Input、Button、Select、日期时间及其他单行表单控件的高度。Button 在这里固定使用 outline。DatePicker/TimePicker 是面板，此处使用带输入框的 Date/Time 字段。示例同时展示有值、可清空、标签删除与长标签多选；Select/Cascader 设置 tag-nowrap 时保持同档高度，长标签文字省略、删除图标保留；标签行可横向滚动，清空按钮和箭头固定在外侧。被省略的标签正文支持悬停、键盘聚焦或点按查看完整文字，点外部或按 Esc 关闭，不改变选中值。可清空后恢复选中值重复比较。多行文本和允许换行的多选内容按内容撑高。

Example source: src/field-decorator/__demos__/control-sizes.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
const sizes = ["xs", "sm", "md", "lg", "xl"] as const;
const variants = ["outline", "filled", "standard"] as const;
const size = ref<(typeof sizes)[number]>("md");
const variant = ref<(typeof variants)[number]>("outline");
const options = [
  { value: "beijing", label: "Beijing" },
  { value: "shanghai", label: "Shanghai" },
];
const cascaderOptions = [{ value: "china", label: "China", children: options }];

const inputValue = ref("Beijing");
const selectValue = ref("beijing");
const cascaderValue = ref("beijing");
const selectMultiple = ref(["beijing", "shanghai"]);
const cascaderMultiple = ref(["beijing", "shanghai"]);
const selectOverflow = ref(["long", "beijing", "shanghai"]);
const cascaderOverflow = ref(["long", "beijing", "shanghai"]);
const selectedOptions = [
  ...options,
  {
    value: "long",
    label:
      "A very long selected option label for overflow comparison — full text preview keeps the selected value unchanged.",
  },
];
const selectedCascaderOptions = [
  { value: "china", label: "China", children: selectedOptions },
];
function resetSelections() {
  inputValue.value = "Beijing";
  selectValue.value = "beijing";
  cascaderValue.value = "beijing";
  selectMultiple.value = ["beijing", "shanghai"];
  cascaderMultiple.value = ["beijing", "shanghai"];
  selectOverflow.value = ["long", "beijing", "shanghai"];
  cascaderOverflow.value = ["long", "beijing", "shanghai"];
}
</script>
<template>
  <section
    aria-label="Form control size comparison"
    class="control-size-comparison"
  >
    <c-space wrap :size="12">
      <c-radio-group v-model="size" aria-label="Comparison size">
        <c-radio v-for="item in sizes" :key="item" :value="item">{{
          item
        }}</c-radio>
      </c-radio-group>
      <c-radio-group v-model="variant" aria-label="Comparison variant">
        <c-radio v-for="item in variants" :key="item" :value="item">{{
          item
        }}</c-radio>
      </c-radio-group>
    </c-space>
    <div class="control-size-comparison__grid">
      <div data-control="Input">
        <p>Input</p>
        <c-input :size="size" :variant="variant" placeholder="Input" />
      </div>
      <div data-control="Button">
        <p>Button</p>
        <c-button :size="size" variant="outline">Button</c-button>
      </div>
      <div data-control="Select">
        <p>Select</p>
        <c-select
          :size="size"
          :variant="variant"
          :options="options"
          placeholder="Select"
        />
      </div>
      <div data-control="Date">
        <p>Date</p>
        <c-date :size="size" :variant="variant" placeholder="Date" />
      </div>
      <div data-control="Time">
        <p>Time</p>
        <c-time :size="size" :variant="variant" placeholder="Time" />
      </div>
      <div data-control="InputNumber">
        <p>InputNumber</p>
        <c-input-number :size="size" :variant="variant" placeholder="Number" />
      </div>
      <div data-control="AutoComplete">
        <p>AutoComplete</p>
        <c-auto-complete
          :size="size"
          :variant="variant"
          :options="options"
          placeholder="AutoComplete"
        />
      </div>
      <div data-control="Cascader">
        <p>Cascader</p>
        <c-cascader
          :size="size"
          :variant="variant"
          :options="cascaderOptions"
          placeholder="Cascader"
        />
      </div>
      <div data-control="DateRange">
        <p>DateRange</p>
        <c-date-range
          :size="size"
          :variant="variant"
          :placeholder="['Start', 'End']"
        />
      </div>
      <div data-control="TimeRange">
        <p>TimeRange</p>
        <c-time-range
          :size="size"
          :variant="variant"
          :placeholder="['Start', 'End']"
        />
      </div>
    </div>

    <section
      aria-label="Selected control size comparison"
      class="control-size-comparison__states"
    >
      <c-space wrap align="center" :size="12">
        <span>Selected / Clearable / Multiple — 有值、可清空与多选不换行</span>
        <span
          >Hover or focus truncated text; tap on touch screens /
          悬停或聚焦省略正文查看全文；触屏点按查看，点外部关闭</span
        >
        <c-button size="sm" variant="outline" @click="resetSelections"
          >Reset / 恢复选中值</c-button
        >
      </c-space>
      <div class="control-size-comparison__grid">
        <div data-control="InputValue">
          <p>Input · clearable</p>
          <c-input
            v-model="inputValue"
            :size="size"
            :variant="variant"
            clearable
            placeholder="Input value"
          />
        </div>
        <div data-control="ButtonReference">
          <p>Button · reference</p>
          <c-button :size="size" variant="outline">Button</c-button>
        </div>
        <div data-control="SelectValue">
          <p>Select · clearable</p>
          <c-select
            v-model="selectValue"
            :size="size"
            :variant="variant"
            :options="selectedOptions"
            clearable
            placeholder="Select value"
          />
        </div>
        <div data-control="CascaderValue">
          <p>Cascader · clearable</p>
          <c-cascader
            v-model="cascaderValue"
            :size="size"
            :variant="variant"
            :options="selectedCascaderOptions"
            clearable
            placeholder="Cascader value"
          />
        </div>
        <div data-control="SelectMultiple">
          <p>Select · multiple / nowrap</p>
          <c-select
            v-model="selectMultiple"
            :size="size"
            :variant="variant"
            :options="selectedOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Select multiple"
          />
        </div>
        <div data-control="CascaderMultiple">
          <p>Cascader · multiple / nowrap</p>
          <c-cascader
            v-model="cascaderMultiple"
            :size="size"
            :variant="variant"
            :options="selectedCascaderOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Cascader multiple"
          />
        </div>
        <div data-control="SelectOverflow">
          <p>Select · long values / nowrap</p>
          <c-select
            v-model="selectOverflow"
            edit-mode="direct"
            :size="size"
            :variant="variant"
            :options="selectedOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Select long values"
          />
        </div>
        <div data-control="CascaderOverflow">
          <p>Cascader · long values / nowrap</p>
          <c-cascader
            v-model="cascaderOverflow"
            edit-mode="direct"
            :size="size"
            :variant="variant"
            :options="selectedCascaderOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Cascader long values"
          />
        </div>
      </div>
    </section>
  </section>
</template>
<style scoped>
.control-size-comparison,
.control-size-comparison__states {
  display: grid;
  gap: 24px;
}
.control-size-comparison__grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
  align-items: start;
  gap: 24px 16px;
}
.control-size-comparison__grid > div {
  min-width: 0;
}
.control-size-comparison__grid p {
  margin: 0 0 12px;
  font-size: 14px;
  line-height: 20px;
}
.control-size-comparison__grid :deep(.c-input-number),
.control-size-comparison__grid :deep(.c-auto-complete) {
  width: 100%;
}
</style>
```

### 原生表单、焦点与触摸事件

Example source: src/button/__demos__/native-events.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const value = ref('Editable')
const submissions = ref(0)
const event = ref('Use Tab, Enter or touch')
</script>
<template>
  <c-form @submit="submissions++" @reset="value = 'Editable'" style="display: flex; flex-wrap: wrap; gap: 12px">
    <c-input v-model="value" aria-label="Example field" placeholder="Example field" style="width: 100%; max-width: 280px" />
    <c-button html-type="submit">Submit</c-button>
    <c-button html-type="reset">Reset</c-button>
    <c-button :focusable="false">Skip Tab</c-button>
    <c-button @touchstart="event = 'touchstart'" @focus="event = 'focus'" @blur="event = 'blur'" @click="event = 'click'">Event target</c-button>
  </c-form>
  <p aria-live="polite">Submissions: {{ submissions }}; {{ event }}</p>
</template>
```

## 加载与操作反馈

### 加载动画、布局与尺寸

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `loading` | 加载状态，禁止点击和链接跳转 | 加载动画、布局与尺寸、加载指示器样式 |
| `loading-size` | 指示器尺寸；xs/sm/md/lg/xl 对应 12/14/16/18/20px，数字为 px；省略时跟随按钮尺寸，line 模式不适用 | 加载动画、布局与尺寸、加载指示器样式 |
| `loading-type` | 加载动画；与 Loading 的 type 相同，line 模式不适用 | 加载动画、布局与尺寸 |
| `loading-mode` | 行内、覆盖或底部进度线；line 只使用 loading-color | 加载动画、布局与尺寸 |
| `loading-color` | 加载指示器颜色 | 加载指示器样式 |
| `ripple` | 点击水波 | 水波与阴影反馈 |
<!-- demo-config-notes:end -->

选择加载布局和指示器尺寸，对比五种动画。加载时按钮保留文案并阻止重复操作。

Example source: src/button/__demos__/loading.vue

```vue
<script setup lang="ts">
import { ref } from "vue";

const stacked = ref(false)
const mode = ref("default");
const size = ref("md");
const modes = ["default", "fill", "line"];
const sizes = ["xs", "sm", "md", "lg", "xl"];
const types = ["circle", "wave", "cube", "rect", "disappear"];
</script>
<template>
  <c-space direction="column" :size="16">
    <c-form layout="vertical" size="sm">
      <c-form-item label="Layout" field="mode">
        <c-radio-group
          v-model="mode"
          :options="modes"
          aria-label="Loading mode"
          variant="button"
        />
      </c-form-item>
      <c-form-item label="Size" field="size">
        <c-radio-group
          v-model="size"
          :disabled="mode === 'line'"
          :options="sizes"
          aria-label="Loading size"
          variant="button"
        />
      </c-form-item>
    </c-form>
    <label><input v-model="stacked" type="checkbox" />图文堆叠（stacked）</label>
    <p v-if="mode === 'line'">
      line 使用底部进度线，loading-type 和 loading-size 不适用；可通过
      loading-color 调整颜色。
    </p>
    <c-space wrap
      ><c-button
        v-for="type in mode === 'line' ? ['line'] : types"
        :key="type"
        loading
        :stacked="stacked"
        :loading-type="mode === 'line' ? 'circle' : type"
        :loading-mode="mode"
        :loading-size="size"
        ><template #icon><svg width="16" height="16" viewBox="0 0 16 16" aria-hidden="true"><path d="M8 1v14M1 8h14" stroke="currentColor" /></svg></template>{{ type }}</c-button
      ></c-space
    >
  </c-space>
</template>
```

### 加载指示器样式

Example source: src/button/__demos__/loading-appearance.vue

```vue
<template>
  <c-space wrap
    ><c-button loading loading-color="#e05279">Custom color</c-button
    ><c-button loading :loading-size="16">Custom size</c-button></c-space
  >
</template>
```

### 水波与阴影反馈

点击按钮观察水波，调整阴影等级比较层次感。关闭水波不会影响点击事件。

Example source: src/button/__demos__/feedback.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
const ripple = ref(true);
const elevation = ref(2);
</script>
<template>
  <c-space direction="column" :size="16">
    <c-space wrap>
      <c-checkbox v-model="ripple">Ripple</c-checkbox>
      <label
        >Elevation<c-input-number
          v-model="elevation"
          :min="0"
          :max="24"
          aria-label="Button elevation"
      /></label>
    </c-space>
    <c-button :ripple="ripple" :elevation="elevation"
      >Click to compare feedback</c-button
    >
  </c-space>
</template>
```

### 受控加载与失败恢复

Example source: src/button/__demos__/controlled-loading.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const saving = ref(false)
const failing = ref(false)
const message = ref('点击保存，观察业务控制的 loading / Click Save to start')
const delay = () => new Promise(resolve => setTimeout(resolve, 800))
async function save() {
  if (saving.value) return
  saving.value = true
  try { await delay(); message.value = '保存完成 / Saved' }
  finally { saving.value = false }
}
async function recover() {
  if (failing.value) return
  failing.value = true
  try { await delay(); throw new Error('模拟请求失败 / Simulated failure') }
  catch (error) { message.value = (error as Error).message }
  finally { failing.value = false }
}
</script>
<template>
  <c-space direction="column" :size="12">
    <p>click 支持 async 回调；业务通过 loading 展示等待，在 finally 中恢复。Async click handlers own their loading state.</p>
    <c-space wrap :size="12">
      <c-button :loading="saving" @click="save">保存 / Save</c-button>
      <c-button :loading="failing" @click="recover">失败与恢复 / Failure recovery</c-button>
    </c-space>
    <p aria-live="polite">{{ message }}</p>
  </c-space>
</template>
```

## 阅读方向

继承最近的 `dir="ltr|rtl"`，支持运行时切换和局部覆盖。图标与内容按阅读顺序排列，stacked 仍由上到下排列，不整体镜像插槽图形。ButtonGroup 的横向排列、拼接边框与首尾圆角由组方向决定，子按钮可以单独设置文字方向；单个按钮保留完整圆角，纵向组保持上下顺序。使用原生 Tab、Enter、Space 操作，普通按钮组不额外接管左右键；禁用和加载规则保持不变。

## API

<!-- same-source-api:start -->

### Props

| 属性          | 说明                                                                                             | 类型                                      | 默认值         |
| ------------- | ------------------------------------------------------------------------------------------------ | ----------------------------------------- | -------------- |
| status        | 主题色；省略时继承按钮组，否则 default                                                           | `SemanticStatus`                          | `undefined`    |
| variant       | 外观；省略时继承按钮组，否则 default                                                             | `default / text / outline / tonal`        | `undefined`    |
| size          | 尺寸；省略时继承按钮组，否则 md                                                                  | `xs / sm / md / lg / xl`                  | `undefined`    |
| html-type     | 原生按钮类型                                                                                     | `button / submit / reset`                 | `button`       |
| component     | 根标签，链接属性通过 attrs 传入                                                                  | `button / a`                              | `button`       |
| round         | 圆形按钮                                                                                         | `boolean`                                 | `false`        |
| block         | 占满可用宽度                                                                                     | `boolean`                                 | `false`        |
| loading       | 加载状态，禁止点击和链接跳转                                                                     | `boolean`                                 | `false`        |
| loading-type  | 加载动画；与 Loading 的 type 相同，line 模式不适用                                               | `circle / wave / cube / rect / disappear` | `circle`       |
| loading-mode  | 行内、覆盖或底部进度线；line 只使用 loading-color                                                | `default / fill / line`                   | `default`      |
| loading-size  | 指示器尺寸；xs/sm/md/lg/xl 对应 12/14/16/18/20px，数字为 px；省略时跟随按钮尺寸，line 模式不适用 | `ComponentSize / number`                  | `undefined`    |
| loading-color | 加载指示器颜色                                                                                   | `string`                                  | `currentColor` |
| disabled      | 禁用；省略时继承按钮组，显式 false 可覆盖                                                        | `boolean`                                 | `undefined`    |
| ripple        | 点击水波                                                                                         | `boolean`                                 | `true`         |
| focusable     | 允许 Tab 顺序聚焦；不影响通过代码聚焦                                                            | `boolean`                                 | `true`         |
| autofocus     | 原生自动聚焦                                                                                     | `boolean`                                 | `false`        |
| text-color    | 自定义文字色                                                                                     | `string`                                  | `undefined`    |
| color         | 自定义背景／变体基色                                                                             | `string`                                  | `undefined`    |
| elevation     | default 变体阴影；true 为 2，false 关闭，数字四舍五入并限制 0～24；组内由组控制                  | `boolean / number`                        | `true`         |
| stacked       | 图标文字纵向排列；省略时继承按钮组                                                               | `boolean`                                 | `undefined`    |

### Events

| 事件       | 参数与行为                                  |
| ---------- | ------------------------------------------- |
| click      | `(event: MouseEvent) => void` |
| touchstart | `(event: TouchEvent) => void` |

click 是普通事件通知，支持 async 回调；loading 由业务状态控制，建议在 finally 中恢复。事件监听器的 Promise 不会自动驱动加载。禁用／加载链接移除有效 href。

### Slots

| 插槽    | 说明                             | 参数 |
| ------- | -------------------------------- | ---- |
| default | 按钮内容；加载时保留             | —    |
| icon    | 前置图标；stacked 时位于文字上方 | —    |

### Methods

无自定义公开方法。
<!-- same-source-api:end -->

## ButtonGroup

### ButtonGroup Props

| 属性 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| status | 子按钮默认语义状态；子按钮可覆盖 | SemanticStatus | default |
| size | 子按钮默认尺寸；子按钮可覆盖 | xs / sm / md / lg / xl | md |
| variant | 子按钮默认外观；相邻按钮按生效变体拼接，允许混合 | default / text / outline / tonal | default |
| color | 子按钮默认自定义色；子按钮可覆盖 | string | undefined |
| text-color | 子按钮默认文字色；子按钮可覆盖 | string | undefined |
| disabled | 子按钮默认禁用状态；显式 false 可覆盖组 true | boolean | false |
| stacked | 默认图文纵排；子按钮可显式 false 覆盖 | boolean | false |
| vertical | 按钮组纵向排列，独立于按钮内部 stacked | boolean | false |
| elevation | 组整体阴影；true 为 2，数值归一化到 0–24；仅 default 变体且组未禁用时生效 | boolean / number | true |

根元素默认 `role="group"`；使用 `aria-label` 或 `aria-labelledby` 为需要命名的操作组提供名称。原生属性可覆盖 role，普通按钮组仍使用 Tab / Enter / Space，不自动接管方向键。

**继承边界：** status、size、variant、color、text-color、disabled、stacked 按子按钮显式值优先。elevation 始终由组管理，子按钮自己的 elevation 不生效。嵌套组使用最近组的配置和默认值，不自动叠加外层禁用。

### ButtonGroup Events

无自定义事件。`@click` 是根元素的原生事件透传，可以接收后代冒泡；各操作继续监听对应 Button 的 click。组不收集事件 Promise，也不管理任务或选中值。

### ButtonGroup Slots

| 插槽 | 说明 | 参数 |
| --- | --- | --- |
| default | 连体样式支持组根元素下直接相邻的 Button DOM 节点 | — |

**组合边界：** 额外的 DOM 包装层、前后文本和其他控件不属于连体外观契约。包装层内的按钮仍可能继承配置，但不会获得相同拼接效果。组接管首尾圆角，不保留独立 round 按钮的圆形外观。需要分离排列或任意内容混排时组合 Space；较窄区域由业务选择滚动、缩短文案或切换纵向，不自动换行。

### ButtonGroup Expose

| 名称 | 说明 |
| --- | --- |
| buttonGroupProvider | 响应式组配置对象，各字段为只读 ComputedRef；elevation 为 boolean / number，其余字段与 Props 对齐 |

无额外的组级动作方法。

## 类型

ButtonProps、ButtonVariant、ButtonLoadingMode、ButtonInstance、ButtonGroupProps、ButtonGroupInstance。

## CSS 变量职责与完整默认值

Button 保留 58 个外观变量。`{status}-color` 控制实心背景，`{status}-foreground-color` 控制 text/outline/tonal 的文字和图标，`{status}-tonal-color` 控制浅色背景。语义状态共用 `solid-text-color` 和 `solid-state-layer-color`；default/tertiary 前景与 primary/tertiary 状态层保留必要的主题差异。

尺寸统一使用 xs/sm/md/lg/xl。字号、过渡时长、焦点宽度与偏移、堆叠高度增量直接复用系统变量；按钮组与堆叠圆角共用 border-radius。四个状态透明度变量保留 hover/active 的差异。loading-duration 仅控制底部进度线；其他加载动画由 Loading 负责。内部变量与固定动画几何细节不再作为公共定制项。

| 变量名                                  | 默认值                                    |
| --------------------------------------- | ----------------------------------------- |
| `--c-button-border-radius`              | `var(--c-sys-radius-md)`                  |
| `--c-button-content-gap`                | `var(--c-sys-space-3)`                    |
| `--c-button-danger-color`               | `var(--c-sys-color-status-danger)`        |
| `--c-button-danger-disabled-color`      | `rgb(var(--c-danger-3))`                  |
| `--c-button-danger-foreground-color`    | `var(--c-sys-color-content-danger)`       |
| `--c-button-danger-tonal-color`         | `rgb(var(--c-danger-1))`                  |
| `--c-button-default-color`              | `var(--c-sys-color-surface-default)`      |
| `--c-button-default-foreground-color`   | `var(--c-sys-color-content-primary)`      |
| `--c-button-default-tonal-color`        | `var(--c-sys-color-surface-muted)`        |
| `--c-button-disabled-color`             | `var(--c-color-fill-2)`                   |
| `--c-button-disabled-solid-text-color`  | `var(--c-sys-color-content-on-dark)`      |
| `--c-button-disabled-text-color`        | `var(--c-sys-color-content-disabled)`     |
| `--c-button-focus-color`                | `var(--c-sys-color-content-brand)`        |
| `--c-button-info-color`                 | `var(--c-sys-color-status-info)`          |
| `--c-button-info-disabled-color`        | `rgb(var(--c-blue-3))`                    |
| `--c-button-info-foreground-color`      | `var(--c-sys-color-content-info)`         |
| `--c-button-info-tonal-color`           | `rgb(var(--c-blue-1))`                    |
| `--c-button-lg-height`                  | `36px`                                    |
| `--c-button-lg-padding`                 | `0 var(--c-sys-space-7)`                  |
| `--c-button-loading-duration`           | `1s`                                      |
| `--c-button-loading-line-height`        | `3px`                                     |
| `--c-button-md-height`                  | `32px`                                    |
| `--c-button-md-padding`                 | `0 var(--c-sys-space-6)`                  |
| `--c-button-plain-state-opacity-active` | `1`                                       |
| `--c-button-plain-state-opacity-hover`  | `0.5`                                     |
| `--c-button-primary-color`              | `var(--c-sys-color-action-primary)`       |
| `--c-button-primary-disabled-color`     | `rgb(var(--c-primary-3))`                 |
| `--c-button-primary-foreground-color`   | `var(--c-sys-color-content-brand)`        |
| `--c-button-primary-state-layer-color`  | `var(--c-button-solid-state-layer-color)` |
| `--c-button-primary-tonal-color`        | `rgb(var(--c-primary-1))`                 |
| `--c-button-secondary-color`            | `rgb(var(--c-gray-6))`                    |
| `--c-button-secondary-foreground-color` | `var(--c-sys-color-content-secondary)`    |
| `--c-button-secondary-tonal-color`      | `rgb(var(--c-gray-2))`                    |
| `--c-button-sm-height`                  | `28px`                                    |
| `--c-button-sm-padding`                 | `0 var(--c-sys-space-5)`                  |
| `--c-button-solid-state-layer-color`    | `var(--c-sys-color-content-on-dark)`      |
| `--c-button-solid-text-color`           | `var(--c-sys-color-content-on-dark)`      |
| `--c-button-stacked-gap`                | `var(--c-sys-space-2)`                    |
| `--c-button-state-layer-color`          | `var(--c-sys-color-surface-page)`         |
| `--c-button-state-opacity-active`       | `0.12`                                    |
| `--c-button-state-opacity-hover`        | `0.08`                                    |
| `--c-button-success-color`              | `var(--c-sys-color-status-success)`       |
| `--c-button-success-disabled-color`     | `rgb(var(--c-success-3))`                 |
| `--c-button-success-foreground-color`   | `var(--c-sys-color-content-success)`      |
| `--c-button-success-tonal-color`        | `rgb(var(--c-success-1))`                 |
| `--c-button-tertiary-color`             | `rgb(var(--c-gray-7))`                    |
| `--c-button-tertiary-foreground-color`  | `var(--c-sys-color-content-secondary)`    |
| `--c-button-tertiary-state-layer-color` | `var(--c-sys-color-content-on-bright)`    |
| `--c-button-tertiary-text-color`        | `var(--c-sys-color-content-on-dark)`      |
| `--c-button-tertiary-tonal-color`       | `rgb(var(--c-gray-1))`                    |
| `--c-button-warning-color`              | `var(--c-sys-color-status-warning)`       |
| `--c-button-warning-disabled-color`     | `rgb(var(--c-warning-3))`                 |
| `--c-button-warning-foreground-color`   | `var(--c-sys-color-content-warning)`      |
| `--c-button-warning-tonal-color`        | `rgb(var(--c-warning-1))`                 |
| `--c-button-xl-height`                  | `44px`                                    |
| `--c-button-xl-padding`                 | `0 var(--c-sys-space-8)`                  |
| `--c-button-xs-height`                  | `24px`                                    |
| `--c-button-xs-padding`                 | `0 var(--c-sys-space-4)`                  |

---

Document: llms/zh-CN/components/calendar.md

<!-- Source: src/calendar/README.md; locale: zh-CN; page: /components/calendar/ -->

# Calendar

用于展示月历或年历，并支持单日期选择、自定义日期内容和受控状态。表单中的日期输入请使用 Date，带选择面板的复杂选择请使用 DatePicker，日程编排请使用 Scheduler。

## 基础示例

### 基础用法

展示并选择日期。

Example source: src/calendar/__demos__/basic.vue

```vue
<template>
  <c-calendar v-model="value" />
  <p class="demo-result">当前选择：{{ format(value) }}</p>
</template>

<script lang="ts" setup>
import { ref } from "vue";

const value = ref(new Date());
const format = (value: Date) =>
  value.toLocaleDateString("zh-CN", {
    year: "numeric",
    month: "long",
    day: "numeric",
    weekday: "long",
  });
</script>

<style scoped>
.demo-result {
  margin: 12px 0 0;
  color: var(--c-color-text-2);
}
</style>
```

## 视图与日期展示

### 月视图与年视图

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `mode` | 模式 | 月视图与年视图 |
| `modes` | 显示的模式 | 月视图与年视图 |
| `day-start-of-week` | 一周开始日 | 一周起始与周序号 |
| `is-week` | 是否显示周序号 | 一周起始与周序号 |
<!-- demo-config-notes:end -->

使用 `mode` 控制视图。未传入 `mode` 时，也可以通过头部的模式切换器改变内部视图。

Example source: src/calendar/__demos__/modes.vue

```vue
<template>
  <c-space wrap>
    <c-button
      :status="mode === 'month' ? 'primary' : 'default'"
      @click="mode = 'month'"
      >月视图</c-button
    >
    <c-button
      :status="mode === 'year' ? 'primary' : 'default'"
      @click="mode = 'year'"
      >年视图</c-button
    >
  </c-space>
  <c-calendar
    v-model="value"
    class="calendar-demo"
    :mode="mode"
    :modes="['month', 'year']"
  />
</template>

<script lang="ts" setup>
import { ref } from "vue";

const value = ref(new Date());
const mode = ref<"month" | "year">("month");
</script>

<style scoped>
.calendar-demo {
  margin-top: 12px;
}
</style>
```

### 一周起始与周序号

`day-start-of-week` 控制星期排列，`is-week` 在日期前显示周序号。

Example source: src/calendar/__demos__/week-options.vue

```vue
<template>
  <c-space wrap>
    <c-checkbox v-model="mondayFirst">周一作为一周开始</c-checkbox>
    <c-checkbox v-model="showWeek">显示周序号</c-checkbox>
  </c-space>
  <c-calendar
    v-model="value"
    class="calendar-demo"
    :day-start-of-week="mondayFirst ? 1 : 0"
    :is-week="showWeek"
  />
</template>

<script lang="ts" setup>
import { ref } from "vue";

const value = ref(new Date());
const mondayFirst = ref(true);
const showWeek = ref(false);
</script>

<style scoped>
.calendar-demo {
  margin-top: 12px;
}
</style>
```

## 交互与内容定制

### 受控状态与事件

通过 `v-model` 从外部设置日期，并通过 `change`、`panel-change` 区分日期选择和面板翻页。

Example source: src/calendar/__demos__/controlled.vue

```vue
<template>
  <c-space wrap>
    <c-button @click="selectToday">选择今天</c-button>
    <c-button @click="selectTomorrow">选择明天</c-button>
  </c-space>
  <c-calendar
    v-model="value"
    class="calendar-demo"
    @change="lastAction = `选择了 ${format($event)}`"
    @panel-change="lastAction = `面板切换到 ${formatMonth($event)}`"
  />
  <c-alert status="info">{{ lastAction }}</c-alert>
</template>

<script lang="ts" setup>
import { ref } from "vue";

const value = ref(new Date());
const lastAction = ref("可点击日期或切换月份");
const format = (date: Date) => date.toLocaleDateString("zh-CN");
const formatMonth = (date: Date) =>
  date.toLocaleDateString("zh-CN", { year: "numeric", month: "long" });
function selectToday() {
  value.value = new Date();
  lastAction.value = `外部设置为 ${format(value.value)}`;
}
function selectTomorrow() {
  const tomorrow = new Date();
  tomorrow.setDate(tomorrow.getDate() + 1);
  value.value = tomorrow;
  lastAction.value = `外部设置为 ${format(value.value)}`;
}
</script>

<style scoped>
.calendar-demo {
  margin: 12px 0;
}
</style>
```

### 自定义日期单元格

默认插槽可在日期数字下方展示标记、摘要等轻量内容。点击自定义内容所在单元格仍会选择日期。

Example source: src/calendar/__demos__/custom-cell.vue

```vue
<template>
  <c-calendar v-model="value">
    <template #default="{ year, month, date }">
      <div v-if="items[key(year, month, date)]" class="cell-items">
        <span
          v-for="item in items[key(year, month, date)]"
          :key="item.label"
          class="cell-item"
          :style="{ '--item-color': item.color }"
          >{{ item.label }}</span
        >
      </div>
    </template>
  </c-calendar>
</template>

<script lang="ts" setup>
import { ref } from "vue";

const value = ref(new Date());
const today = new Date();
const key = (year: number, month: number, date: number) =>
  `${year}-${month}-${date}`;
const relativeKey = (offset: number) => {
  const date = new Date(today);
  date.setDate(date.getDate() + offset);
  return key(date.getFullYear(), date.getMonth() + 1, date.getDate());
};
const items: Record<string, Array<{ label: string; color: string }>> = {
  [relativeKey(0)]: [
    { label: "产品评审", color: "rgb(var(--c-primary-6))" },
    { label: "版本发布", color: "rgb(var(--c-success-6))" },
  ],
  [relativeKey(2)]: [{ label: "客户回访", color: "rgb(var(--c-warning-6))" }],
  [relativeKey(5)]: [{ label: "团队周会", color: "rgb(var(--c-purple-6))" }],
};
</script>

<style scoped>
.cell-items {
  display: flex;
  flex-direction: column;
  gap: 4px;
  margin-top: 6px;
}
.cell-item {
  overflow: hidden;
  color: var(--c-color-text-2);
  font-size: 12px;
  line-height: 20px;
  text-overflow: ellipsis;
  white-space: nowrap;
}
.cell-item::before {
  display: inline-block;
  width: 6px;
  height: 6px;
  margin-right: 6px;
  background: var(--item-color);
  border-radius: 50%;
  content: "";
}
</style>
```

### 自定义头部标题

`header` 插槽替换中间标题，上一页、下一页、今天和模式切换仍由 Calendar 管理。

Example source: src/calendar/__demos__/custom-header.vue

```vue
<template>
  <c-calendar v-model="value">
    <template #header="{ year, month }">
      <span class="custom-title">{{ year }} 年 {{ month }} 月工作日历</span>
    </template>
  </c-calendar>
</template>

<script lang="ts" setup>
import { ref } from "vue";

const value = ref(new Date());
</script>

<style scoped>
.custom-title {
  margin: 0 8px;
  color: var(--c-color-text-1);
  font-weight: 600;
}
</style>
```

## API

### `<calendar>` Props

| 参数名                    | 描述                 | 类型                    |       默认值        |
| ------------------------- | -------------------- | ----------------------- | :-----------------: |
| model-value **(v-model)** | 绑定值               | `date`                  |         `-`         |
| default-value             | 默认值（非受控状态） | `date`                  |         `-`         |
| mode                      | 模式                 | `'month' \| 'year'`     |         `-`         |
| default-mode              | 默认模式             | `'month' \| 'year'`     |      `'month'`      |
| modes                     | 显示的模式           | `('month' \| 'year')[]` | `['month', 'year']` |
| day-start-of-week         | 一周开始日           | `0 \| 1`                |         `0`         |
| is-week                   | 是否显示周序号       | `boolean`                |       `false`       |

### `<calendar>` Events

| 事件名       | 描述                 | 参数         |
| ------------ | -------------------- | ------------ |
| change       | 选择的日期改变时触发 | date: `Date` |
| panel-change | 日期面板改变时触发   | date: `Date` |

### `<calendar>` Slots

| 插槽名  |       描述       | 参数                                                | 版本   |
| ------- | :--------------: | --------------------------------------------------- | :----- |
| header  |  自定义头部内容  | year: `number`<br>month: `number`                   | 2.53.0 |
| default | 自定义单元格内容 | year: `number`<br>month: `number`<br>date: `number` | 2.53.0 |

### 类型定义

组件导出以下类型定义

```ts
import type { CalendarInstance } from "@cedar-design/ui";
```

---

Document: llms/zh-CN/components/card.md

<!-- Source: src/card/README.md; locale: zh-CN; page: /components/card/ -->

# Card

## 基础示例

### 基础用法与副标题

Example source: src/card/__demos__/basic.vue

```vue
<template>
  <c-space direction="column" style="width: 100%">
    <c-card title="Project overview" description="Keep the team informed." />
    <c-card
      title="Project overview"
      subtitle="Updated today"
      description="Keep the team informed."
      top-divider
      bottom-divider
    >
      Release checklist and project updates.
      <template #title-action><c-button size="sm">More</c-button></template>
      <template #footer><c-button status="primary">View details</c-button></template>
    </c-card>
  </c-space>
</template>
```

## 外观与状态

### 外观配置对比

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `title` | 标题 | 外观配置对比、悬浮样式 |
| `description` | 描述 | 外观配置对比 |
| `hoverable` | 悬浮样式 | 悬浮样式 |
<!-- demo-config-notes:end -->

选择一个对比维度后，同屏展示它的全部可选值；其余配置和内容保持一致。可切换其他配置检查组合效果；输入类预览共享一个值。

<details>
<summary>配置说明与使用限制</summary>

#### 外观组合

适用于信息分组和内容层次。调整变体、尺寸，用相同数据观察变化。内容保持一致，便于比较不同设置的实际效果。

</details>

Example source: src/card/__demos__/appearance-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";

const __demoAppearance = __demoReactive({ variant: "default", size: "md" });

import { computed as demoComputed, ref as demoRef } from 'vue'
const demoCompareFields = [{"name":"variant","values":["default","outline","tonal"]},{"name":"size","values":["sm","md"]}]
const demoCompareAxis = demoRef("variant")
const demoComparedOptions = demoComputed(() => demoCompareFields.find(field => field.name === demoCompareAxis.value)?.values ?? [])

__demoAppearance['elevation'] = 2
demoCompareFields.push({ name: 'elevation', values: [0, 2, 6] })
</script>
<template>
  <c-space direction="column" :size="16">
    <c-form layout="vertical">
      <c-form-item layout="vertical" size="sm" label="variant">
        <c-radio-group
          v-model="__demoAppearance['variant']"
          aria-label="variant"
          :options="[
            { label: 'default', value: 'default' },
            { label: 'outline', value: 'outline' },
            { label: 'tonal', value: 'tonal' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
      <c-form-item layout="vertical" size="sm" label="size">
        <c-radio-group
          v-model="__demoAppearance['size']"
          aria-label="size"
          :options="[
            { label: 'sm', value: 'sm' },
            { label: 'md', value: 'md' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
    <c-form-item label="elevation"><c-radio-group v-model="__demoAppearance['elevation']" aria-label="elevation" :options="[{ label: '0', value: 0 }, { label: '2', value: 2 }, { label: '6', value: 6 }]" /></c-form-item>
</c-form>
    <p class="demo-config-comparison-hint"><span lang="zh-CN">选择一个对比维度；其他配置和内容保持一致。输入类示例共享同一个值，便于比较外观。</span><span lang="en-US">Compare one dimension while keeping the other settings and content identical. Input specimens share the same value.</span></p>
<c-radio-group v-model="demoCompareAxis" aria-label="Compare configuration" :options="demoCompareFields.map(field => ({ label: field.name, value: field.name }))" />
<div class="demo-config-comparison">
<section v-for="sample in demoComparedOptions" :key="String(sample)">
<p><code>{{ demoCompareAxis }}={{ sample }}</code></p>
<c-card
      title="Project overview"
      description="Keep the team informed."
      v-bind="{ ...__demoAppearance, [demoCompareAxis]: sample }"
    />
</section>
</div>
  </c-space>
</template>

<style scoped>
.demo-config-comparison { display: grid; grid-template-columns: repeat(auto-fit, minmax(min(100%, 220px), 1fr)); gap: 20px; min-width: 0; max-width: 100%; }
.demo-config-comparison > section { min-width: 0; }
.demo-config-comparison p { margin: 0 0 8px; }
html:not([lang='en-US']) .demo-config-comparison-hint > [lang='en-US'],
html[lang='en-US'] .demo-config-comparison-hint > [lang='zh-CN'] { display: none; }
</style>
```

### 悬浮样式

Example source: src/card/__demos__/hoverable.vue

```vue
<template>
  <c-card hoverable title="Hover over this card" style="width: 100%; max-width: 360px"
    >Hover feedback on pointer devices.</c-card
  >
</template>
```

## 布局与排列

### 图片与三种布局

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `direction` | 封面与正文的排列顺序，默认 column；支持 row、column、row-reverse，不表示卡片自身位置 | 图片与三种布局 |
| `title` | 标题 | 图片与三种布局 |
| `src` | 封面图片地址；cover 插槽优先 | 图片与三种布局 |
| `alt` | 封面图片替代文本 | 图片与三种布局 |
| `image-height` | 封面图片高度，数字单位为 px | 图片与三种布局 |
| `image-width` | 封面图片宽度，数字单位为 px | 图片与三种布局 |
<!-- demo-config-notes:end -->

Example source: src/card/__demos__/image.vue

```vue
<script setup lang="ts">
const imageSrc = `${import.meta.env.BASE_URL}cat.jpg`
const directions = ['column', 'row', 'row-reverse'] as const
</script>

<template>
  <c-space direction="column" style="width: 100%">
    <c-card
      v-for="direction in directions"
      :key="direction"
      :direction="direction"
      :title="direction"
      :src="imageSrc"
      alt="Cat"
      :image-height="120"
      :image-width="direction === 'column' ? '100%' : 100"
      fit="cover"
      >Card content</c-card
    >
    <c-card title="Custom cover"
      ><template #cover
        ><img :src="imageSrc" alt="Cat" style="width: 100%; height: 120px; object-fit: cover" /></template
      >Cover slot overrides the image.</c-card
    >
  </c-space>
</template>
```

## 内容与展示

### 长标题与提示

Example source: src/card/__demos__/tooltip.vue

```vue
<script setup lang="ts">
const title = 'Project overview with a long title that does not fit on one line'
</script>

<template>
  <c-card style="width: 100%; max-width: 280px">
    <template #title
      ><span class="long-title" :title="title">{{ title }}</span></template
    >
    <template #description
      ><span class="long-title" :title="title">{{ title }}</span></template
    >
    Native title tooltip on pointer devices; the full text remains in the DOM.
  </c-card>
</template>

<style scoped>
.long-title {
  display: block;
  overflow: hidden;
  white-space: nowrap;
  text-overflow: ellipsis;
}
</style>
```

## 自定义与插槽

### 自定义标题区域

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `title` | 标题 | 自定义标题区域 |
| `top-divider` | 上分割线 | 内容插槽 |
| `bottom-divider` | 下分割线 | 内容插槽 |
<!-- demo-config-notes:end -->

Example source: src/card/__demos__/no-padding.vue

```vue
<template>
  <c-card title="Fallback title">
    <template #header
      ><header style="padding: 16px">
        <strong>Custom header</strong>
        <p>Replaces the title and subtitle region.</p>
      </header></template
    >
    Card content
  </c-card>
</template>
```

### 内容插槽

Example source: src/card/__demos__/slots.vue

```vue
<template>
  <c-card top-divider bottom-divider>
    <template #cover><div style="padding: 16px">Custom cover</div></template>
    <template #title="{ slotClass }"><strong :class="slotClass">Custom title</strong></template>
    <template #title-action><c-button size="sm">More</c-button></template>
    <template #subtitle="{ slotClass }"><span :class="slotClass">Custom subtitle</span></template>
    <template #description="{ slotClass }"><p :class="slotClass">Custom description</p></template>
    Default content
    <template #footer><c-button status="primary">Confirm</c-button></template>
  </c-card>
</template>
```

## 交互与控制

### 水波与点击事件

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `title` | 标题 | 水波与点击事件、全屏展开与关闭 |
| `ripple` | 点击水波 | 水波与点击事件 |
| `floating` | 全屏展开状态，支持 v-model:floating | 全屏展开与关闭 |
| `floating-duration` | 全屏展开与关闭动画时长，单位 ms | 全屏展开与关闭 |
<!-- demo-config-notes:end -->

Example source: src/card/__demos__/ripple.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const clicks = ref(0)
</script>

<template>
  <c-card ripple title="Click this card" @click="clicks++"
    >Clicks: <output aria-live="polite">{{ clicks }}</output></c-card
  >
</template>
```

### 全屏展开与关闭

Example source: src/card/__demos__/floating.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const floating = ref(false)
</script>

<template>
  <c-card v-model:floating="floating" title="Project overview" :floating-duration="250">
    Summary content
    <template #footer><c-button status="primary" @click="floating = true">Expand</c-button></template>
    <template #floating-content><p style="padding: 16px">Expanded project details.</p></template>
    <template #close-button
      ><c-button aria-label="Close expanded card" @click.stop="floating = false">Close</c-button></template
    >
  </c-card>
</template>
```

长标题示例通过插槽内的 CSS 和原生 `title` 提供提示；Card 本身没有 `ellipsis` / `tooltip` 属性。

## 生命周期与边界

### Floating scheduler lifecycle / 浮起调度生命周期

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `floating` | 全屏展开状态，支持 v-model:floating | Floating scheduler lifecycle / 浮起调度生命周期 |
| `ripple` | 点击水波 | Floating scheduler lifecycle / 浮起调度生命周期 |
| `floating-duration` | 全屏展开与关闭动画时长，单位 ms | Floating scheduler lifecycle / 浮起调度生命周期 |
| `title` | 标题 | Floating scheduler lifecycle / 浮起调度生命周期 |
<!-- demo-config-notes:end -->

Example source: src/card/__demos__/scheduler-lifecycle.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const active = ref(true)
const mounted = ref(true)
const floating = ref(false)
const ripple = ref(true)
const duration = ref(250)
</script>
<template>
  <div>
    <c-button @click="floating = !floating">Float / 浮起与回落</c-button>
    <c-button @click="active = !active">Activate / 停用与激活</c-button>
    <c-button @click="mounted = !mounted">Mount / 卸载与挂载</c-button>
    <c-button @click="ripple = !ripple">Ripple wait / 涟漪等待</c-button>
    <c-button @click="duration = duration ? 0 : 250">Duration / 零与默认时长</c-button>
    <p>Toggle floating rapidly, suspend during500ms ripple wait or layout settlement, then activate. Old tasks must not reset a newer phase. Underlying doubleRaf frames are not physically canceled.</p>
    <KeepAlive v-if="mounted">
      <c-card v-if="active" v-model:floating="floating" :ripple="ripple" :floating-duration="duration" title="Floating lifecycle / 浮起生命周期">
        Card content / 卡片内容
        <template #floating-content>
          <c-button @click.stop="floating = false">Collapse / 回落</c-button>
          <c-button @click.stop="active = false">Deactivate / 停用</c-button>
          <c-button @click.stop="mounted = false">Unmount / 卸载</c-button>
        </template>
      </c-card>
    </KeepAlive>
  </div>
</template>
```

与 Maple 使用相同场景、参数和交互顺序；示例源码仅替换组件前缀，主题与站点外壳各自保留。

## 阅读方向

标题、内容和操作沿阅读顺序排列，默认浮动操作位于阅读终点，不镜像图片或自定义插槽。

## API

<!-- same-source-api:start -->
### Props

| 属性 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| variant | 卡片外观 | `default / outline / tonal` | `default` |
| size | 内容密度；省略时按平台规则回退，见下方说明 | `sm / md` | `undefined` |
| direction | 封面与正文的排列顺序，默认 column；支持 row、column、row-reverse，不表示卡片自身位置 | `row / column / row-reverse` | `column` |
| hoverable | 悬浮样式 | `boolean` | `false` |
| title-style | 标题行样式 | `CSSProperties` | `undefined` |
| title | 标题 | `string` | `undefined` |
| subtitle | 副标题 | `string` | `undefined` |
| description | 描述 | `string` | `undefined` |
| top-divider | 上分割线 | `boolean` | `false` |
| bottom-divider | 下分割线 | `boolean` | `false` |
| src | 封面图片地址；cover 插槽优先 | `string` | `undefined` |
| fit | 封面图片填充方式 | `fill / contain / cover / none / scale-down` | `cover` |
| image-height | 封面图片高度，数字单位为 px | `string / number` | `undefined` |
| image-width | 封面图片宽度，数字单位为 px | `string / number` | `undefined` |
| alt | 封面图片替代文本 | `string` | `undefined` |
| elevation | default 变体阴影；true 为等级 1，false 为无阴影，数字范围 0～24 | `boolean / number` | `true` |
| ripple | 点击水波 | `boolean` | `false` |
| floating | 全屏展开状态，支持 v-model:floating | `boolean` | `false` |
| floating-duration | 全屏展开与关闭动画时长，单位 ms | `number` | `250` |

### Events

| 事件 | 参数与时机 |
| --- | --- |
| click | `(event: Event)`，点击卡片时触发 |
| update:floating | `(value: boolean)`，内置关闭按钮请求关闭时发送 false；展开由父级设置 |

### Slots

| 插槽 | 说明 | 参数 |
| --- | --- | --- |
| default | 正文 | — |
| cover | 封面，覆盖 src 图片 | — |
| header | 整个标题区域，覆盖 title、title-action 和 subtitle | — |
| title | 标题 | `{ slotClass: string }` |
| title-action | 标题右侧操作 | — |
| subtitle | 副标题 | `{ slotClass: string }` |
| description | 描述 | `{ slotClass: string }` |
| footer | 底部操作 | — |
| floating-content | 全屏扩展内容，仅 column 布局渲染 | — |
| close-button | 自定义关闭按钮；需自行更新 floating | — |

### Methods

无公开方法。

### 跨端说明

属性、事件参数及插槽契约一致。Cedar 省略 size 时继承全局尺寸（xs/sm 映射 sm，其余映射 md）；Maple 回退 md。需要一致密度时显式传入 size。主题和 CSS 前缀分别使用各端配置。
Card 不再提供 loading 属性；加载遮罩使用 Loading 指令组合。
<!-- same-source-api:end -->

### `<Card>` CSS 变量

| 变量名 | 默认值 |
| --- | --- |
| `--c-card-hover-shadow` | `0 4px 12px rgb(0 0 0 / 12%)` |
| `--c-card-size-sm-title-font-size` | `16px` |
| `--c-card-size-sm-section-margin` | `8px 0 0` |
| `--c-card-size-sm-section-padding` | `0 12px` |
| `--c-card-padding` | `0 0 15px 0` |
| `--c-card-background` | `var(--c-sys-color-surface-default)` |
| `--c-card-filled-background` | `var(--c-sys-color-surface-muted)` |
| `--c-card-outline-color` | `var(--c-sys-color-border-default)` |
| `--c-card-border-radius` | `4px` |
| `--c-card-image-width` | `100%` |
| `--c-card-row-image-width` | `140px` |
| `--c-card-image-height` | `200px` |
| `--c-card-row-height` | `140px` |
| `--c-card-title-color` | `var(--c-sys-color-content-primary)` |
| `--c-card-title-font-size` | `20px` |
| `--c-card-title-padding` | `0 12px` |
| `--c-card-title-margin` | `15px 0 0 0` |
| `--c-card-title-row-margin` | `12px 0` |
| `--c-card-content-padding` | `0 16px` |
| `--c-card-content-margin` | `16px 0 0 0` |
| `--c-card-content-color` | `var(--c-sys-color-content-tertiary)` |
| `--c-card-content-font-size` | `14px` |
| `--c-card-content-row-margin` | `16px 0 0 0` |
| `--c-card-subtitle-color` | `var(--c-sys-color-content-secondary)` |
| `--c-card-subtitle-font-size` | `14px` |
| `--c-card-subtitle-padding` | `0 12px` |
| `--c-card-subtitle-margin` | `10px 0 0 0` |
| `--c-card-subtitle-row-margin` | `-8px 0 0 0` |
| `--c-card-description-color` | `var(--c-sys-color-content-secondary)` |
| `--c-card-description-font-size` | `14px` |
| `--c-card-description-margin` | `20px 0 0 0` |
| `--c-card-description-padding` | `0 13px` |
| `--c-card-footer-padding` | `0 12px` |
| `--c-card-footer-right` | `13px` |
| `--c-card-footer-bottom` | `9px` |
| `--c-card-footer-margin` | `30px 0 0 0` |
| `--c-card-line-height` | `22px` |
| `--c-card-row-line-height` | `1.5` |
| `--c-card-floating-buttons-bottom` | `16px` |
| `--c-card-floating-buttons-right` | `16px` |
| `--c-card-floating-buttons-color` | `var(--c-sys-color-content-primary)` |
| `--c-card-close-button-icon-size` | `24px` |
| `--c-card-close-button-size` | `56px` |
| `--c-card-close-button-background` | `#212121` |
| `--c-card-close-button-text-color` | `var(--c-sys-color-content-on-dark)` |
| `--c-card-close-button-border-radius` | `50%` |

Card 主体颜色按 system 语义分层：普通背景、filled 背景和描边分别使用 `surface-default`、`surface-muted`、`border-default`；标题、正文、辅助文字分别使用 `content-primary`、`content-tertiary`、`content-secondary`。展开后的悬浮按钮容器位于卡片表面，使用 `content-primary`；深色关闭按钮上的文字与图标使用 `content-on-dark`。关闭按钮背景 `#212121` 是 Card 专属值，并非全局主操作色。旧变量名的迁移关系见 Design Token 规范。

### 类型定义

组件导出以下类型定义

```ts
import type { CardProps } from '@cedar-design/ui'
```

尺寸与跨端迁移约定见仓库根目录 `API-MIGRATION.md`。只支持文档列出的档位，不代表支持全部 ComponentSize。

### 变量消费约定

横向内容区独立消费 `--c-card-content-row-margin`，不再误用标题间距。Card 的密度 API 明确只支持 sm/md，不套用表单控件五档。动效时长 `--c-card-animation-duration` 默认为 `var(--c-sys-motion-duration-slow)`，曲线 `--c-card-animation-easing` 默认为 `var(--c-sys-motion-easing-standard)`。reduced-motion 关闭所有 Card 动画分区的过渡。

---

Document: llms/zh-CN/components/carousel.md

<!-- Source: src/carousel/README.md; locale: zh-CN; page: /components/carousel/ -->

# Carousel

自动播放的间隔是业务播放节奏（business-clock），不是 CSS 动效时长；默认关闭，启用 true 时默认3000ms，数字／配置间隔、hover/focus/隐藏暂停规则保持。取消或重排使旧播放任务失效；当前回调消费一次后才调用导航。停用／卸载保留 next／prev／to、键盘和滚轮入口无效，不能翻页或拦截输入。激活建立新观察器／事件绑定，解绑前迟交付不得借新 active 状态重新排任务。

## 基础示例

### 基础用法

Example source: src/carousel/__demos__/basic.vue

```vue
<template>
  <c-carousel :style="{ width: '600px', height: '240px' }" >
    <c-carousel-item>
      <img src="/cat.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none">
    </c-carousel-item>
    <c-carousel-item>
      <img src="/cat2.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none">
    </c-carousel-item>
    <c-carousel-item>
      <img src="/cat3.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none">
    </c-carousel-item>
  </c-carousel>
</template>
```

## 方向与布局

### 垂直轮播

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `slides-per-view` | 同时显示页数；auto使用子项宽高 | 多图同屏、centered-slides、auto-sized |
| `space-between` | 项间距；数字/数字字符串为px | 多图同屏、centered-slides、auto-sized |
| `draggable` | 鼠标拖动，可与触摸并存 | 多图同屏、auto-sized |
| `centered-slides` | 当前页居中 | centered-slides、auto-sized |
| `orientation` | 轮播内容滑动的横纵轴向，默认 horizontal；不决定指示器所在位置 | 垂直轮播 |
| `model-value` | 受控页序号，从 1 开始 | 多图同屏 |
<!-- demo-config-notes:end -->

通过 `orientation` 属性可以控制轮播方向，支持 `horizontal` 和 `vertical`。

Example source: src/carousel/__demos__/vertical.vue

```vue
<template>
  <c-carousel orientation="vertical" :style="{ width: '600px', height: '300px' }">
    <c-carousel-item>
      <img src="/cat.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none">
    </c-carousel-item>
    <c-carousel-item>
      <img src="/cat2.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none">
    </c-carousel-item>
    <c-carousel-item>
      <img src="/cat3.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none">
    </c-carousel-item>
  </c-carousel>
</template>
```

### 多图同屏

示例同时显示2.5项，可用鼠标拖拽并切换“接受切换”和“循环”。Current为父级已接受的从 1 开始的页序号，Proposal记录切换请求，Changes统计change事件；受控拒绝时仍可能发出提案及change，不等于模型已更新。接受后可正反拖动，首项向前循环到末项；关闭循环后末端继续拖动不越界、不重复通知。此处是鼠标组合示例，不代表真机触屏或所有居中/自动宽度组合均已验收。

通过 `slides-per-view` 和 `space-between` 属性可以控制每屏显示的 slide 数量及间距。

Example source: src/carousel/__demos__/multi-slides.vue

```vue
<script setup>
import { ref } from "vue";
const current = ref(1);
const proposal = ref(1);
const changes = ref(0);
const accept = ref(true);
const loop = ref(true);
function update(value) {
  proposal.value = value;
  if (accept.value) current.value = value;
}
</script>

<template>
  <section class="multi-slides-demo">
    <c-checkbox v-model="accept"> Accept changes / 接受切换</c-checkbox>
    <c-checkbox v-model="loop"> Loop / 循环</c-checkbox>
    <p role="status">
      Current: {{ current }} · Proposal: {{ proposal }} · Changes: {{ changes }}
    </p>
    <c-carousel
      :slides-per-view="2.5"
      :space-between="10"
      :style="{ width: '600px', height: '200px' }"
      :model-value="current"
      :loop="loop"
      draggable
      keyboard
      @update:modelValue="update"
      @change="changes++"
    >
      <c-carousel-item v-for="i in 6" :key="i">
        <div
          style="
            width: 100%;
            height: 100%;
            display: flex;
            align-items: center;
            justify-content: center;
            background: #4a90d9;
            color: #fff;
            font-size: 24px;
            font-weight: bold;
          "
        >
          {{ i }}
        </div>
      </c-carousel-item>
    </c-carousel>
  </section>
</template>
```

### centered-slides

Example source: src/carousel/__demos__/centered-slides.vue

```vue
<script setup></script>

<template>
  <c-carousel class="carousel" :slides-per-view="1.5" :space-between="10" centered-slides>
    <c-carousel-item v-for="i in 5" :key="i">
      <div class="carousel-custom-slide">{{ i }}</div>
    </c-carousel-item>
  </c-carousel>
</template>

<style lang="less" scoped>
.carousel {
  height: 160px;
}

.carousel-example {
  height: 160px;
}

.carousel-item {
  width: 100%;
  height: 100%;
  object-fit: cover;
  pointer-events: none;
}

.carousel-custom-slide {
  width: 100%;
  height: 100%;
  display: flex;
  align-items: center;
  justify-content: center;
  background: #4a90d9;
  color: #fff;
  font-size: 24px;
  font-weight: bold;
}

.carousel-custom-indicators {
  position: absolute;
  bottom: 10px;
  left: 50%;
  transform: translateX(-50%);
  display: flex;
  gap: 4px;
}

.carousel-custom-indicator {
  width: 20px;
  height: 20px;
  display: flex;
  align-items: center;
  justify-content: center;
  background: rgba(0, 0, 0, 0.3);
  color: #fff;
  font-size: 12px;
  border-radius: 50%;
}

.carousel-custom--active {
  background: #4a90d9;
}

.space {
  height: 20px;
}
</style>
```

### auto-sized

“反转顺序”以卡片宽度作为本示例的唯一key，反转同一批卡片。current 按页序号而非业务卡片身份解释：页序号 2从220px变成180px，索引与change次数不变；向左拖到页序号 3后恢复顺序，当前位置对应180px，向右拖回页序号 2。重排本身不提交切换；任意插入排序、身份保持、持按中重排和物理触屏仍未覆盖。

Reverse cards reorders the same uniquely keyed cards (their distinct widths are the Demo keys). Current is positional, not a business-card identity: slide number 2 changes from 220px to 180px without changing the index or event count. Drag left to slide number 3, restore order to show 180px there, then drag right to slide number 2. Reordering alone emits no change. Arbitrary insertion/sorting, identity-following selection, reordering during a held gesture and physical touch remain unverified.

活动第五项删除组合：选中新增第五项后关闭“增加末项”，父级Current仍4、Changes不增加；显示层将越界索引限制到剩余第四项并居中。随后向左拖动才按四项循环到 1，回写模型并增加一次change。这里不自动修正父级受控值；业务若需要删除即重写索引，应自行更新current。未覆盖任意重排或持按手势中删除。

When the active fifth card is removed, parent Current stays 5 without another change; the view clamps it to the remaining fourth card and centers that card. A subsequent left drag wraps to 1 and updates the model once. Applications that need immediate parent-index correction must update current themselves. Arbitrary reordering and deletion during a held gesture remain unverified.

从末项页序号 4清空再恢复时，父级Current保留3、Changes不增加；恢复后末项仍居中，随后向左拖动才循环到 1并增加一次change。空态不把受控父级值强制回写0。此记录不覆盖活动末项删除、任意越界值或手势中清空。

Clearing from slide number 4 retains the parent Current and change count. Restoring centers the last card; the next left drag wraps to 1 and emits once. Empty content does not force the controlled parent value to 0. Active-card deletion, arbitrary invalid indices and clearing during a held gesture remain unverified.

“清空项目”临时移除所有卡片，空态导航禁用、拖动不发切换；解除后恢复此前配置的卡片，不自动切换。从初始页序号 1清空再恢复后，向右拖动可正常循环到末项。此流程未覆盖非零越界受控索引或清空途中仍按住指针。

“增加末项”追加200px第五项，不改变当前有效索引或增加change；从首项向右拖到新增项，再向右拖回原末项后移除第五项，仍保持原末项和次数。此时向左拖可按恢复后的四项循环回首项。这里只覆盖移除非活动末项，未认证删除当前项、任意重排或手势途中增删。

先拖到末项，再开启“加宽卡片”（各项增加80px）和“窄容器”（300px），当前模型与change次数不因尺寸变化而增加；观察当前340px卡片重新居中，再向左拖动循环到首项。恢复开关后应继续居中。本段描述真实ResizeObserver响应已结束手势后的尺寸变化，不代表按住拖动期间改变尺寸。

居中自动宽度示例包含140/220/180/260px四个独立项目，间隔12px。鼠标拖拽逐项切换，首尾均可循环；Current显示已接受的从 1 开始的模型，Changes记录change事件次数。当前项宽度不同仍保持居中。本示例不代表真机触屏、手势中尺寸变化或动态增删项目已全部验收。

Example source: src/carousel/__demos__/auto-sized.vue

```vue
<script setup>
import { computed, ref } from "vue";
const current = ref(1);
const changes = ref(0);
const wider = ref(false);
const compact = ref(false);
const extra = ref(false);
const empty = ref(false);
const reversed = ref(false);
const widths = computed(() => {
  const items = empty.value
    ? []
    : [140, 220, 180, 260, ...(extra.value ? [200] : [])];
  return (reversed.value ? items.reverse() : items).map(
    (width) => width + (wider.value ? 80 : 0),
  );
});
</script>

<template>
  <section class="auto-sized-demo">
    <c-checkbox v-model="wider"> Wider cards / 加宽卡片</c-checkbox>
    <c-checkbox v-model="compact"> 300px viewport / 窄容器</c-checkbox>
    <c-checkbox v-model="extra"> Extra card / 增加末项</c-checkbox>
    <c-checkbox v-model="empty"> Empty / 清空项目</c-checkbox>
    <c-checkbox v-model="reversed"> Reverse cards / 反转顺序</c-checkbox>
    <p role="status">Current: {{ current }} · Changes: {{ changes }}</p>
    <c-carousel
      v-model="current"
      slides-per-view="auto"
      :space-between="12"
      :style="{ width: compact ? '300px' : '100%' }"
      height="180px"
      centered-slides
      draggable
      @change="changes++"
    >
      <c-carousel-item
        v-for="width in widths"
        :key="width"
        :style="{ width: width + 'px' }"
      >
        <div class="carousel-demo-panel">{{ width }}px</div>
      </c-carousel-item>
    </c-carousel>
  </section>
</template>
<style scoped>
.carousel-demo-panel {
  display: grid;
  place-items: center;
  height: 100%;
  background: #e0e7ff;
  color: #312e81;
}
</style>
```

## 切换控件与效果

### 切换箭头

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `show-arrow` | 箭头显示策略 | 切换箭头 |
| `indicator-type` | 指示器样式 | 指示器样式与位置 |
| `indicator-position` | 指示器在轮播容器中的边缘或 outer 外部区域，默认 bottom；不是浮层相对触发器的方位 | 指示器样式与位置 |
| `effect` | 视觉效果，两端全部支持 | 切换效果对比 |
<!-- demo-config-notes:end -->

通过 `show-arrow` 控制切换箭头的显示时机，支持 `always`、`hover`、`never`。PC 端默认 `always`。

Example source: src/carousel/__demos__/navigation.vue

```vue
<template>
  <div>
    <h4 style="margin:0 0 8px">Always</h4>
    <c-carousel show-arrow="always" :style="{width:'600px',height:'200px',marginBottom:'20px'}">
      <c-carousel-item><img src="/cat.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none"></c-carousel-item>
      <c-carousel-item><img src="/cat2.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none"></c-carousel-item>
      <c-carousel-item><img src="/cat3.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none"></c-carousel-item>
    </c-carousel>
    <h4 style="margin:0 0 8px">Hover</h4>
    <c-carousel show-arrow="hover" :style="{width:'600px',height:'200px'}">
      <c-carousel-item><img src="/cat.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none"></c-carousel-item>
      <c-carousel-item><img src="/cat2.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none"></c-carousel-item>
      <c-carousel-item><img src="/cat3.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none"></c-carousel-item>
    </c-carousel>
  </div>
</template>
```

### 指示器样式与位置

所有指示器方案使用相同的三张本地幻灯片和当前页模型。点击任一方案的指示器或翻页箭头，其他方案同步切换。第一组比较 dot、line、slider 样式，第二组比较 top、outer 位置；窄屏下自动纵向排列。

<details>
<summary>配置说明与使用限制</summary>

#### 指示器类型

通过 `indicator-type` 设置指示器类型，支持 `dot`、`line`、`slider`。隐藏指示器请使用 `indicator`。

#### 指示器位置

通过 `indicator-position` 属性可以设置指示器位置。

</details>

Example source: src/carousel/__demos__/indicator-comparison.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const current = ref(1)
const groups = [{"name":"indicator-type","zh":"指示器样式","en":"Indicator types","values":[{"label":"dot","type":"dot","position":"bottom"},{"label":"line","type":"line","position":"bottom"},{"label":"slider","type":"slider","position":"bottom"}]},{"name":"indicator-position","zh":"指示器位置","en":"Indicator positions","values":[{"label":"top","type":"dot","position":"top"},{"label":"outer","type":"dot","position":"outer"}]}] as const
const slides = ["data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20width%3D%22640%22%20height%3D%22240%22%3E%3Crect%20width%3D%22640%22%20height%3D%22240%22%20fill%3D%22%23286b72%22%2F%3E%3Ctext%20x%3D%22320%22%20y%3D%22130%22%20text-anchor%3D%22middle%22%20fill%3D%22white%22%20font-size%3D%2236%22%3ESlide%201%3C%2Ftext%3E%3C%2Fsvg%3E","data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20width%3D%22640%22%20height%3D%22240%22%3E%3Crect%20width%3D%22640%22%20height%3D%22240%22%20fill%3D%22%234b5694%22%2F%3E%3Ctext%20x%3D%22320%22%20y%3D%22130%22%20text-anchor%3D%22middle%22%20fill%3D%22white%22%20font-size%3D%2236%22%3ESlide%202%3C%2Ftext%3E%3C%2Fsvg%3E","data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20width%3D%22640%22%20height%3D%22240%22%3E%3Crect%20width%3D%22640%22%20height%3D%22240%22%20fill%3D%22%23965734%22%2F%3E%3Ctext%20x%3D%22320%22%20y%3D%22130%22%20text-anchor%3D%22middle%22%20fill%3D%22white%22%20font-size%3D%2236%22%3ESlide%203%3C%2Ftext%3E%3C%2Fsvg%3E"]
</script>
<template>
<div class="indicator-comparison">
<p role="status">Slide: {{ current }}</p>
<section v-for="group in groups" :key="group.name" :data-comparison-scene="group.name">
<h4><span lang="zh-CN">{{ group.zh }}</span><span lang="en-US">{{ group.en }}</span></h4>
<div class="indicator-comparison-grid">
<div v-for="preset in group.values" :key="preset.label">
<p><code>{{ preset.label }}</code></p>
<c-carousel v-model="current" :indicator-type="preset.type" :indicator-position="preset.position" style="height: 150px">
<c-carousel-item v-for="(src, index) in slides" :key="src"><img :src="src" :alt="'Slide ' + (index + 1)" /></c-carousel-item>
</c-carousel>
</div>
</div>
</section>
</div>
</template>
<style scoped>
.indicator-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.indicator-comparison-grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(min(100%, 240px), 1fr)); gap: 16px; }
.indicator-comparison > section, .indicator-comparison-grid, .indicator-comparison-grid > div { min-width: 0; max-width: 100%; }
p, h4 { margin: 0 0 8px; }
img { width: 100%; height: 100%; object-fit: cover; pointer-events: none; }
html:not([lang='en-US']) h4 > [lang='en-US'], html[lang='en-US'] h4 > [lang='zh-CN'] { display: none; }
</style>
```

### 切换效果对比

在各预览中切换相邻项，比较淡入淡出、卡片与滑动效果；自动播放和输入方式不混入效果配置。

<details>
<summary>配置说明与使用限制</summary>

#### effect-fade

通过指示器按钮切换；非活动页透明且退出交互。各页重叠在同一网格位置，活动页占满视口宽度而不是分列。示例图片使用站点根路径，避免组件子路由下解析为相对资源。

#### effect-card

活动项恢复原始比例和不透明度，相邻项缩小、降低不透明度；上一页/下一页按钮支持原生键盘操作。

</details>

Example source: src/carousel/__demos__/effect-comparison.vue

```vue
<script setup lang="ts">


</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="effect-fade">
    <h4><span lang="zh-CN">effect-fade</span><span lang="en-US">effect fade</span></h4>
    <c-carousel class="carousel" effect="fade">
        <c-carousel-item>
          <img class="carousel-item" :src="'/cat.jpg'" alt="" />
        </c-carousel-item>
        <c-carousel-item>
          <img class="carousel-item" :src="'/cat2.jpg'" alt="" />
        </c-carousel-item>
        <c-carousel-item>
          <img class="carousel-item" :src="'/cat3.jpg'" alt="" />
        </c-carousel-item>
      </c-carousel>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="effect-card">
    <h4><span lang="zh-CN">effect-card</span><span lang="en-US">effect card</span></h4>
    <c-carousel class="carousel" effect="card">
        <c-carousel-item>
          <img class="carousel-item" :src="'/cat.jpg'" alt="" />
        </c-carousel-item>
        <c-carousel-item>
          <img class="carousel-item" :src="'/cat2.jpg'" alt="" />
        </c-carousel-item>
        <c-carousel-item>
          <img class="carousel-item" :src="'/cat3.jpg'" alt="" />
        </c-carousel-item>
      </c-carousel>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }
.demo-comparison-case--1 {

.carousel {
  height: 160px;
}

.carousel-example {
  height: 160px;
}

.carousel-item {
  width: 100%;
  height: 100%;
  object-fit: cover;
  pointer-events: none;
}

.carousel-custom-slide {
  width: 100%;
  height: 100%;
  display: flex;
  align-items: center;
  justify-content: center;
  background: #4a90d9;
  color: #fff;
  font-size: 24px;
  font-weight: bold;
}

.carousel-custom-indicators {
  position: absolute;
  bottom: 10px;
  left: 50%;
  transform: translateX(-50%);
  display: flex;
  gap: 4px;
}

.carousel-custom-indicator {
  width: 20px;
  height: 20px;
  display: flex;
  align-items: center;
  justify-content: center;
  background: rgba(0, 0, 0, 0.3);
  color: #fff;
  font-size: 12px;
  border-radius: 50%;
}

.carousel-custom--active {
  background: #4a90d9;
}

.space {
  height: 20px;
}

}
.demo-comparison-case--2 {

.carousel {
  height: 160px;
}

.carousel-example {
  height: 160px;
}

.carousel-item {
  width: 100%;
  height: 100%;
  object-fit: cover;
  pointer-events: none;
}

.carousel-custom-slide {
  width: 100%;
  height: 100%;
  display: flex;
  align-items: center;
  justify-content: center;
  background: #4a90d9;
  color: #fff;
  font-size: 24px;
  font-weight: bold;
}

.carousel-custom-indicators {
  position: absolute;
  bottom: 10px;
  left: 50%;
  transform: translateX(-50%);
  display: flex;
  gap: 4px;
}

.carousel-custom-indicator {
  width: 20px;
  height: 20px;
  display: flex;
  align-items: center;
  justify-content: center;
  background: rgba(0, 0, 0, 0.3);
  color: #fff;
  font-size: 12px;
  border-radius: 50%;
}

.carousel-custom--active {
  background: #4a90d9;
}

.space {
  height: 20px;
}

}
</style>
```

### 自定义指示器

通过 `#indicator` 插槽可以自定义指示器。

Example source: src/carousel/__demos__/custom-indicator.vue

```vue
<template>
  <c-carousel :style="{ width: '600px', height: '240px' }">
    <c-carousel-item
      ><img
        src="/cat.jpg"
        style="
          width: 100%;
          height: 100%;
          object-fit: cover;
          pointer-events: none;
        "
    /></c-carousel-item>
    <c-carousel-item
      ><img
        src="/cat2.jpg"
        style="
          width: 100%;
          height: 100%;
          object-fit: cover;
          pointer-events: none;
        "
    /></c-carousel-item>
    <c-carousel-item
      ><img
        src="/cat3.jpg"
        style="
          width: 100%;
          height: 100%;
          object-fit: cover;
          pointer-events: none;
        "
    /></c-carousel-item>
    <template #indicator="{ slideNumber, length, to }">
      <div
        style="
          position: absolute;
          bottom: 10px;
          left: 50%;
          transform: translateX(-50%);
          display: flex;
          gap: 4px;
        "
      >
        <c-button
          v-for="i in length"
          :key="i"
          size="xs"
          round
          :variant="i === slideNumber ? 'default' : 'tonal'"
          :status="i === slideNumber ? 'primary' : 'default'"
          :aria-label="`跳转至第 ${i} 页`"
          @click="to(i)"
          >{{ i }}</c-button
        >
      </div>
    </template>
  </c-carousel>
</template>
```

## 播放与交互

### 禁止循环

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `height` | 容器高度，数字为px | 自动播放、controlled、interactive-content |
| `keyboard` | 组件内方向键/Home/End | 键盘控制、controlled、interactive-content |
| `auto-play` | 自动播放及间隔 | 自动播放、悬停暂停自动播放 |
| `draggable` | 鼠标拖动，可与触摸并存 | controlled、interactive-content |
| `loop` | 循环，跨边界不复制实例 | 禁止循环 |
| `trigger` | 指示器触发方式 | 悬停触发 |
<!-- demo-config-notes:end -->

通过 `loop` 属性可以控制是否循环轮播。

Example source: src/carousel/__demos__/forbid-loop.vue

```vue
<template>
  <c-carousel :style="{ width: '600px', height: '240px' }" :loop="false">
    <c-carousel-item>
      <img src="/cat.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none">
    </c-carousel-item>
    <c-carousel-item>
      <img src="/cat2.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none">
    </c-carousel-item>
    <c-carousel-item>
      <img src="/cat3.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none">
    </c-carousel-item>
  </c-carousel>
</template>
```

### 自动播放

通过 `auto-play` 开启自动播放。传入 `true` 使用默认间隔 3000ms；传入数字则作为间隔（毫秒）。

Example source: src/carousel/__demos__/autoplay.vue

```vue
<script setup>
import { ref } from "vue";
const current = ref(1);
const playing = ref(true);
const changes = ref(0);
const sources = ["/cat.jpg", "/cat2.jpg", "/cat3.jpg"];
</script>

<template>
  <section class="carousel-autoplay-demo">
    <c-checkbox v-model="playing"> 自动播放</c-checkbox>
    <p role="status">当前页：{{ current + 1 }}；切换次数：{{ changes }}</p>
    <c-carousel
      v-model="current"
      height="180px"
      :auto-play="playing ? 2000 : false"
      @change="changes += 1"
    >
      <c-carousel-item v-for="(source, index) in sources" :key="source">
        <img
          class="carousel-autoplay-demo__image"
          :src="source"
          :alt="'示例图片 ' + (index + 1)"
        />
      </c-carousel-item>
    </c-carousel>
  </section>
</template>

<style scoped>
.carousel-autoplay-demo__image {
  width: 100%;
  height: 100%;
  object-fit: cover;
  pointer-events: none;
}
</style>
```

示例使用 2000ms 间隔，下方页码按 1 开始显示（API 序号同样从 1 开始）。取消勾选立即停止自动播放，重新开启后继续；焦点在轮播内部时也会暂停。

### 悬停暂停自动播放

`auto-play` 支持传入对象 `{ interval, hoverToPause }` 进行高级配置。

Example source: src/carousel/__demos__/auto-play-hover.vue

```vue
<template>
  <c-carousel :style="{ width: '600px', height: '240px' }" :auto-play="{ interval: 2000, hoverToPause: true }">
    <c-carousel-item>
      <img src="/cat.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none">
    </c-carousel-item>
    <c-carousel-item>
      <img src="/cat2.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none">
    </c-carousel-item>
    <c-carousel-item>
      <img src="/cat3.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none">
    </c-carousel-item>
  </c-carousel>
</template>
```

### 悬停触发

通过 `trigger` 属性可以设置指示器的触发方式，支持 `click` 和 `hover`。

Example source: src/carousel/__demos__/trigger.vue

```vue
<template>
  <c-carousel :style="{ width: '600px', height: '240px' }" trigger="hover">
    <c-carousel-item>
      <img src="/cat.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none">
    </c-carousel-item>
    <c-carousel-item>
      <img src="/cat2.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none">
    </c-carousel-item>
    <c-carousel-item>
      <img src="/cat3.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none">
    </c-carousel-item>
  </c-carousel>
</template>
```

### 鼠标滚轮控制

通过 `mousewheel` 属性可以开启鼠标滚轮切换。滚轮作用在轮播区域时切换页，不滚动外层页面；开启 loop 时从首项向前切换到末项。该能力不等同于触屏拖拽。

Example source: src/carousel/__demos__/mousewheel.vue

```vue
<template>
  <c-carousel :style="{ width: '600px', height: '240px' }" mousewheel>
    <c-carousel-item>
      <img src="/cat.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none">
    </c-carousel-item>
    <c-carousel-item>
      <img src="/cat2.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none">
    </c-carousel-item>
    <c-carousel-item>
      <img src="/cat3.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none">
    </c-carousel-item>
  </c-carousel>
</template>
```

### 键盘控制

通过 `keyboard` 属性可以开启键盘方向键切换。

Example source: src/carousel/__demos__/keyboard.vue

```vue
<template>
  <c-carousel :style="{ width: '600px', height: '240px' }" keyboard>
    <c-carousel-item>
      <img src="/cat.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none">
    </c-carousel-item>
    <c-carousel-item>
      <img src="/cat2.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none">
    </c-carousel-item>
    <c-carousel-item>
      <img src="/cat3.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none">
    </c-carousel-item>
  </c-carousel>
</template>
```

### 监听切换事件

通过 `change` 事件可以监听幻灯片切换。

Example source: src/carousel/__demos__/change-event.vue

```vue
<template>
  <c-carousel :style="{ width: '600px', height: '240px' }" @change="handleChange">
    <c-carousel-item>
      <img src="/cat.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none">
    </c-carousel-item>
    <c-carousel-item>
      <img src="/cat2.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none">
    </c-carousel-item>
    <c-carousel-item>
      <img src="/cat3.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none">
    </c-carousel-item>
  </c-carousel>
</template>

<script setup>
const handleChange = (slideNumber) => {
  console.log('slide:', slideNumber)
}
</script>
```

### controlled

Example source: src/carousel/__demos__/controlled.vue

```vue
<script setup>
import { ref } from "vue";
const current = ref(1);
const accept = ref(true);
const proposal = ref(1);
function update(value) {
  proposal.value = value;
  if (accept.value) current.value = value;
}
</script>
<template>
  <c-checkbox v-model="accept"> Accept changes / 接受切换</c-checkbox>
  <p>Current: {{ current }} · Proposal: {{ proposal }}</p>
  <c-carousel
    :model-value="current"
    height="180px"
    keyboard
    draggable
    @update:modelValue="update"
  >
    <c-carousel-item v-for="item in 4" :key="item"
      ><div class="carousel-demo-panel">Slide {{ item }}</div></c-carousel-item
    >
  </c-carousel>
</template>
<style scoped>
.carousel-demo-panel {
  display: grid;
  place-items: center;
  height: 100%;
  background: #dbeafe;
  color: #1e3a8a;
}
</style>
```

### interactive-content

当前索引和变更次数展示受控模型。输入框内的方向键、Home/End和鼠标拖选文字保留原生编辑，不切换轮播；拖动背景，或聚焦轮播容器后按方向键，才切换页面。返回原页面仍保留输入文字；示例不涉及外部保存或物理触屏文字选择。

Example source: src/carousel/__demos__/interactive-content.vue

```vue
<script setup>
import { ref } from "vue";

const current = ref(1);
const changes = ref(0);
</script>

<template>
  <p>
    Drag the background; inputs retain normal editing. /
    拖动背景切换，输入框保留原生编辑。
  </p>
  <p role="status">Current: {{ current }} · Changes: {{ changes }}</p>
  <c-carousel
    v-model="current"
    class="carousel-interactive-demo"
    height="180px"
    draggable
    touchable
    keyboard
    @change="changes++"
  >
    <c-carousel-item v-for="item in 3" :key="item">
      <div class="carousel-demo-panel">
        <label
          >Slide {{ item }}
          <c-input :aria-label="'Slide ' + item" placeholder="Type here"
        /></label>
      </div>
    </c-carousel-item>
  </c-carousel>
</template>
<style scoped>
.carousel-demo-panel {
  display: grid;
  place-items: center;
  height: 100%;
  background: #dcfce7;
  color: #14532d;
}
input {
  max-width: 150px;
}
</style>
```

## 生命周期

### Scheduler lifecycle / 调度生命周期

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `auto-play` | 自动播放及间隔 | Scheduler lifecycle / 调度生命周期 |
| `move-speed` | 显式切换时长（毫秒） | Scheduler lifecycle / 调度生命周期 |
| `height` | 容器高度，数字为px | Scheduler lifecycle / 调度生命周期 |
| `keyboard` | 组件内方向键/Home/End | Scheduler lifecycle / 调度生命周期 |
| `mousewheel` | 滚轮切换 | Scheduler lifecycle / 调度生命周期 |
<!-- demo-config-notes:end -->

Example source: src/carousel/__demos__/scheduler-lifecycle.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const active = ref(true)
const mounted = ref(true)
const current = ref(1)
const playing = ref(false)
const moves = ref(0)
</script>
<template>
  <div>
    <c-button @click="playing = !playing">Autoplay / 自动播放</c-button>
    <c-button @click="active = !active">Activate / 停用与激活</c-button>
    <c-button @click="mounted = !mounted">Mount / 卸载与挂载</c-button>
    <p>Current / 当前: {{ current }}; changes / 通知: {{ moves }}. Suspend during autoplay or loop settlement, then activate. Old work must not replay.</p>
    <KeepAlive v-if="mounted">
      <c-carousel v-if="active" v-model="current" :auto-play="playing ? { interval: 1000 } : false" :move-speed="600" :height="180" keyboard mousewheel @change="moves++">
        <c-carousel-item v-for="item in 3" :key="item">Slide / 幻灯片 {{ item }}</c-carousel-item>
      </c-carousel>
    </KeepAlive>
  </div>
</template>
```

用于展示多张图片、视频或内嵌框架等内容的循环播放，支持系统自动播放或用户手动切换。

## API

### 主值与默认值

使用普通 `v-model`。`modelValue` 表示当前页序号，从 1 开始；`defaultValue` 仅在创建时初始化非受控值，后续修改不会重置当前状态。显式绑定值优先，初始化不发出 `update:modelValue`。

### Carousel Props

| 属性 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| `model-value` | 受控页序号，从 1 开始 | `number` | `undefined` |
| `default-value` | 非受控初始页序号（从 1 开始） | `number` | `1` |
| `loop` | 循环，跨边界不复制实例 | `boolean` | `true` |
| `auto-play` | 自动播放及间隔 | `boolean \| number \| CarouselAutoPlayConfig` | `false` |
| `move-speed` | 显式切换时长（毫秒） | `number` | `undefined (token)` |
| `trigger` | 指示器触发方式 | `click \| hover` | `click` |
| `orientation` | 轮播内容滑动的横纵轴向，默认 horizontal；不决定指示器所在位置 | `horizontal \| vertical` | `horizontal` |
| `show-arrow` | 箭头显示策略 | `always \| hover \| never` | `always` |
| `arrow-class` | 箭头附加类 | `string` | `undefined` |
| `indicator` | 显示指示器 | `boolean` | `true` |
| `indicator-type` | 指示器样式 | `dot \| line \| slider` | `dot` |
| `indicator-position` | 指示器在轮播容器中的边缘或 outer 外部区域，默认 bottom；不是浮层相对触发器的方位 | `bottom \| top \| left \| right \| outer` | `bottom` |
| `indicator-class` | 指示器附加类 | `string` | `undefined` |
| `indicator-color` | 自定义指示器背景 | `string` | `undefined` |
| `height` | 容器高度，数字为px | `number \| string` | `undefined` |
| `transition-timing-function` | 显式缓动曲线 | `string` | `undefined (token)` |
| `touchable` | 触摸拖动 | `boolean` | `true` |
| `draggable` | 鼠标拖动，可与触摸并存 | `boolean` | `false` |
| `mousewheel` | 滚轮切换 | `boolean` | `false` |
| `keyboard` | 组件内方向键/Home/End | `boolean` | `false` |
| `slides-per-view` | 同时显示页数；auto使用子项宽高 | `number \| auto` | `1` |
| `space-between` | 项间距；数字/数字字符串为px | `number \| string` | `0` |
| `effect` | 视觉效果，两端全部支持 | `slide \| fade \| card` | `slide` |
| `centered-slides` | 当前页居中 | `boolean` | `false` |
| `aria-label` | 轮播可访问名称 | `string` | Locale |
| `previous-button-aria-label` | 上一页按钮名称 | `string` | Locale |
| `next-button-aria-label` | 下一页按钮名称 | `string` | Locale |

### 模型与交互
公开页序号从 1 开始。受控操作先发 update:model-value，再发 change(slideNumber, previousSlideNumber, isManual)，父级接受 current 前不移动；外部赋值不补发 change。方法 options 的 event:false 只关闭 change，不吞掉模型提议。用户操作的 isManual 为 true，自动播放为 false。

loop 跨边界移动原有子项，不复制组件实例。非循环且未居中时，末尾视区钳制以避免留白，选中项可能在最后一组可见项内移动而不再移动轨道。部分可见页保持可访问，完全离屏页 inert。fade 固定展示一页；auto 使用 CarouselItem 显式 width（横向）或 height（纵向），纵向需提供容器高度。默认插槽只统计 CarouselItem（可包在 Vue Fragment 中），注释、普通元素不成为页。

auto-play=true 使用 3000ms 且悬停暂停，数字指定毫秒且不启用悬停暂停；对象配置 interval/hoverToPause。焦点在组件内、拖动中、文档/祖先隐藏、KeepAlive 停用始终暂停。尊重减少动态效果偏好。输入框、按钮等交互子项保留原生行为，自定义交互区域可加 data-carousel-no-drag。show-arrow=hover 在键盘聚焦时也显示。

### Events
| 事件 | 参数 |
| --- | --- |
| update:model-value | slideNumber: number |
| change | slideNumber: number, previousSlideNumber: number, isManual: boolean |

### Slots
| 插槽 | 参数 |
| --- | --- |
| default | CarouselItem |
| prev / next / indicator | { slideNumber, length, hovering, prev, next, to, resize } |

### Methods
| 方法 | 签名 |
| --- | --- |
| prev / next | (options?: CarouselToOptions) => void |
| to | (slideNumber: number, options?: CarouselToOptions) => void |
| resize | () => void |

CarouselItem 无自有 Props、事件或方法；默认插槽为页面内容。

### Types
CarouselProps, CarouselItemProps, CarouselInstance, CarouselItemInstance, CarouselEmits, CarouselSlots, CarouselItemSlots, CarouselExpose, CarouselSlotScope, CarouselToOptions, CarouselChangeData, CarouselOrientation, CarouselEffect, CarouselAutoPlayConfig, CarouselArrowType, CarouselIndicatorType, CarouselIndicatorPosition, CarouselTriggerEvent.

### 样式变量

| Token | 默认值 |
| --- | --- |
| `--c-carousel-indicator-dot-size` | `8px` |
| `--c-carousel-indicator-position` | `var(--c-sys-space-4)` |
| `--c-carousel-indicator-gap` | `var(--c-sys-space-3)` |
| `--c-carousel-indicator-color-default` | `rgb(255 255 255 / 35%)` |
| `--c-carousel-indicator-color-active` | `var(--c-sys-color-content-on-dark)` |
| `--c-carousel-indicator-outer-margin-bottom` | `var(--c-sys-space-8)` |
| `--c-carousel-indicator-line-width` | `20px` |
| `--c-carousel-indicator-line-height` | `3px` |
| `--c-carousel-indicator-line-border-radius` | `var(--c-sys-radius-sm)` |
| `--c-carousel-arrow-size` | `var(--c-sys-control-height-md)` |
| `--c-carousel-arrow-font-size` | `var(--c-sys-font-size-xl)` |
| `--c-carousel-arrow-margin` | `var(--c-sys-space-4)` |
| `--c-carousel-arrow-color` | `var(--c-sys-color-content-on-dark)` |
| `--c-carousel-arrow-background` | `rgb(0 0 0 / 35%)` |
| `--c-carousel-arrow-background-hover` | `rgb(0 0 0 / 55%)` |
| `--c-carousel-arrow-disabled-opacity` | `0.4` |
| `--c-carousel-navigation-z-index` | `10` |
| `--c-carousel-transition-duration` | `var(--c-sys-motion-duration-standard)` |
| `--c-carousel-transition-timing-function` | `ease` |
| `--c-carousel-fade-duration` | `var(--c-sys-motion-duration-standard)` |
| `--c-carousel-card-duration` | `var(--c-sys-motion-duration-standard)` |
| `--c-carousel-card-scale` | `0.85` |
| `--c-carousel-card-opacity` | `0.6` |
| `--c-carousel-focus-width` | `2px` |
| `--c-carousel-focus-offset` | `2px` |
| `--c-carousel-focus-color` | `var(--c-sys-color-content-brand)` |

### 循环过渡边界

每个轮播项始终只有一个组件实例。普通上一页/下一页在出场项离开后回收位置；跨多页或居中跳转若需要同一项同时占据两个位置，则直接无动画定位，不复制交互内容，也不排队执行无限过渡。项目数量小于可视页数时不会复制项目填满。可访问名称跟随全局 Locale，显式标签属性优先。

根节点的 `keydown`、`mouseenter`、`mouseleave`、`focusin`、`focusout` 原生监听器与内部翻页、自动播放暂停逻辑同时生效；原生 `.once` 监听器在该根元素生命周期内只执行一次。

---

Document: llms/zh-CN/components/cascader.md

<!-- Source: src/cascader/README.md; locale: zh-CN; page: /components/cascader/ -->

# Cascader

多选时，`inline` 下拉只显示选项；已选内容、单项移除和清空由输入框承担。确认式编辑面板保留“已选／清空”，选择为草稿，确认后提交。

指在选择器选项数量较多时，采用多级分类的方式将选项进行分隔。

## 阅读方向

继承来源 dir；子列沿阅读方向展开，展开图标及列分隔线随方向变化。左右键按可见方向进入已加载子级或返回父级，并跳过禁用子项；上下键保持逻辑顺序。搜索状态保留原生左右光标编辑，不反转路径或多选数组。关闭状态清空最后值后，重开从根级恢复导航。

## 基础示例

### 基本使用

逐级选择地区，选择叶子节点后收起并回填完整路径。下方显示当前绑定值；禁用状态放在独立案例中。

Example source: src/cascader/__demos__/basic.vue

```vue
<template>
  <c-space direction="column" size="lg">
    <c-cascader v-model="value" :options="options" placeholder="请选择地区" />
    <p role="status">当前值：{{ value ?? '未选择' }}</p>
  </c-space>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import type { CascaderProps } from '@cedar-design/ui'

const value = ref<CascaderProps['modelValue']>()

const options = [
  {
    value: 'beijing',
    label: 'Beijing',
    children: [
      {
        value: 'chaoyang',
        label: 'ChaoYang',
        children: [
          {
            value: 'datunli',
            label: 'Datunli',
          },
        ],
      },
      {
        value: 'haidian',
        label: 'Haidian',
      },
      {
        value: 'dongcheng',
        label: 'Dongcheng',
      },
      {
        value: 'xicheng',
        label: 'Xicheng',
        children: [
          {
            value: 'jinrongjie',
            label: 'Jinrongjie',
          },
          {
            value: 'tianqiao',
            label: 'Tianqiao',
          },
        ],
      },
    ],
  },
  {
    value: 'shanghai',
    label: 'Shanghai',
    children: [
      {
        value: 'huangpu',
        label: 'Huangpu',
      },
    ],
  },
]
</script>
```

## 外观与状态

### 外观配置对比

<!-- demo-config-notes:start -->

#### 本组配置对照

| 配置          | 作用                                                   | 相关示例                       |
| ------------- | ------------------------------------------------------ | ------------------------------ |
| `options`     | 树形选项；叶值模式要求叶值唯一，路径模式可区分不同分支 | 外观配置对比、表单控件尺寸对照 |
| `clearable`   | 允许清除，保留禁用的已选项                             | 外观配置对比、表单控件尺寸对照 |
| `size`        | 完整支持 xs、sm、md、lg、xl，未设置时继承分组与表单    | 表单控件尺寸对照               |
| `variant`     | filled、outline、standard；未设置时继承 InputGroup     | 表单控件尺寸对照               |
| `placeholder` | 占位文本                                               | 表单控件尺寸对照               |
| `multiple`    | 多选；默认启用搜索                                     | 表单控件尺寸对照               |

<!-- demo-config-notes:end -->

选择一个对比维度后，同屏展示它的全部可选值；其余配置和内容保持一致。可切换其他配置检查组合效果；输入类预览共享一个值。

<details>
<summary>配置说明与使用限制</summary>

#### 尺寸

完整支持 xs、sm、md、lg、xl 五档尺寸

#### 外观组合

适用于地区等层级选项。调整变体、尺寸，用相同数据观察变化。内容保持一致，便于比较不同设置的实际效果。

</details>

Example source: src/cascader/__demos__/appearance-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref("shanghai");
const options = [
  {
    label: "华东",
    value: "east",
    children: [
      { label: "上海", value: "shanghai" },
      { label: "杭州", value: "hangzhou" },
    ],
  },
];
const __demoAppearance = __demoReactive({ variant: "filled", size: "md" });

import { computed as demoComputed, ref as demoRef } from 'vue'
const demoCompareFields = [{"name":"variant","values":["filled","outline","standard"]},{"name":"size","values":["xs","sm","md","lg","xl"]}]
const demoCompareAxis = demoRef("variant")
const demoComparedOptions = demoComputed(() => demoCompareFields.find(field => field.name === demoCompareAxis.value)?.values ?? [])
</script>
<template>
  <c-space direction="column" :size="16">
    <c-form layout="vertical">
      <c-form-item layout="vertical" size="sm" label="variant">
        <c-radio-group
          v-model="__demoAppearance['variant']"
          aria-label="variant"
          :options="[
            { label: 'filled', value: 'filled' },
            { label: 'outline', value: 'outline' },
            { label: 'standard', value: 'standard' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
      <c-form-item layout="vertical" size="sm" label="size">
        <c-radio-group
          v-model="__demoAppearance['size']"
          aria-label="size"
          :options="[
            { label: 'xs', value: 'xs' },
            { label: 'sm', value: 'sm' },
            { label: 'md', value: 'md' },
            { label: 'lg', value: 'lg' },
            { label: 'xl', value: 'xl' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
    </c-form>
    <p class="demo-config-comparison-hint"><span lang="zh-CN">选择一个对比维度；其他配置和内容保持一致。输入类示例共享同一个值，便于比较外观。</span><span lang="en-US">Compare one dimension while keeping the other settings and content identical. Input specimens share the same value.</span></p>
<c-radio-group v-model="demoCompareAxis" aria-label="Compare configuration" :options="demoCompareFields.map(field => ({ label: field.name, value: field.name }))" />
<div class="demo-config-comparison">
<section v-for="sample in demoComparedOptions" :key="String(sample)">
<p><code>{{ demoCompareAxis }}={{ sample }}</code></p>
<c-cascader
      v-model="value"
      :options="options"
      clearable
      v-bind="{ ...__demoAppearance, [demoCompareAxis]: sample }"
    ></c-cascader>
</section>
</div>
  </c-space>
</template>

<style scoped>
.demo-config-comparison { display: grid; grid-template-columns: repeat(auto-fit, minmax(min(100%, 220px), 1fr)); gap: 20px; min-width: 0; max-width: 100%; }
.demo-config-comparison > section { min-width: 0; }
.demo-config-comparison p { margin: 0 0 8px; }
html:not([lang='en-US']) .demo-config-comparison-hint > [lang='en-US'],
html[lang='en-US'] .demo-config-comparison-hint > [lang='zh-CN'] { display: none; }
</style>
```

### 表单控件尺寸对照

切换 size 和字段变体，对比有值、可清空、多选不换行的 Cascader、Select、Input 与 Button。长标签文字省略，删除图标保留，标签行可横向滚动；清空按钮和箭头固定在外侧。被省略的标签正文支持悬停、键盘聚焦或点按查看完整文字，点外部或按 Esc 关闭，不改变选中值。

Example source: src/field-decorator/__demos__/control-sizes.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
const sizes = ["xs", "sm", "md", "lg", "xl"] as const;
const variants = ["outline", "filled", "standard"] as const;
const size = ref<(typeof sizes)[number]>("md");
const variant = ref<(typeof variants)[number]>("outline");
const options = [
  { value: "beijing", label: "Beijing" },
  { value: "shanghai", label: "Shanghai" },
];
const cascaderOptions = [{ value: "china", label: "China", children: options }];

const inputValue = ref("Beijing");
const selectValue = ref("beijing");
const cascaderValue = ref("beijing");
const selectMultiple = ref(["beijing", "shanghai"]);
const cascaderMultiple = ref(["beijing", "shanghai"]);
const selectOverflow = ref(["long", "beijing", "shanghai"]);
const cascaderOverflow = ref(["long", "beijing", "shanghai"]);
const selectedOptions = [
  ...options,
  {
    value: "long",
    label:
      "A very long selected option label for overflow comparison — full text preview keeps the selected value unchanged.",
  },
];
const selectedCascaderOptions = [
  { value: "china", label: "China", children: selectedOptions },
];
function resetSelections() {
  inputValue.value = "Beijing";
  selectValue.value = "beijing";
  cascaderValue.value = "beijing";
  selectMultiple.value = ["beijing", "shanghai"];
  cascaderMultiple.value = ["beijing", "shanghai"];
  selectOverflow.value = ["long", "beijing", "shanghai"];
  cascaderOverflow.value = ["long", "beijing", "shanghai"];
}
</script>
<template>
  <section
    aria-label="Form control size comparison"
    class="control-size-comparison"
  >
    <c-space wrap :size="12">
      <c-radio-group v-model="size" aria-label="Comparison size">
        <c-radio v-for="item in sizes" :key="item" :value="item">{{
          item
        }}</c-radio>
      </c-radio-group>
      <c-radio-group v-model="variant" aria-label="Comparison variant">
        <c-radio v-for="item in variants" :key="item" :value="item">{{
          item
        }}</c-radio>
      </c-radio-group>
    </c-space>
    <div class="control-size-comparison__grid">
      <div data-control="Input">
        <p>Input</p>
        <c-input :size="size" :variant="variant" placeholder="Input" />
      </div>
      <div data-control="Button">
        <p>Button</p>
        <c-button :size="size" variant="outline">Button</c-button>
      </div>
      <div data-control="Select">
        <p>Select</p>
        <c-select
          :size="size"
          :variant="variant"
          :options="options"
          placeholder="Select"
        />
      </div>
      <div data-control="Date">
        <p>Date</p>
        <c-date :size="size" :variant="variant" placeholder="Date" />
      </div>
      <div data-control="Time">
        <p>Time</p>
        <c-time :size="size" :variant="variant" placeholder="Time" />
      </div>
      <div data-control="InputNumber">
        <p>InputNumber</p>
        <c-input-number :size="size" :variant="variant" placeholder="Number" />
      </div>
      <div data-control="AutoComplete">
        <p>AutoComplete</p>
        <c-auto-complete
          :size="size"
          :variant="variant"
          :options="options"
          placeholder="AutoComplete"
        />
      </div>
      <div data-control="Cascader">
        <p>Cascader</p>
        <c-cascader
          :size="size"
          :variant="variant"
          :options="cascaderOptions"
          placeholder="Cascader"
        />
      </div>
      <div data-control="DateRange">
        <p>DateRange</p>
        <c-date-range
          :size="size"
          :variant="variant"
          :placeholder="['Start', 'End']"
        />
      </div>
      <div data-control="TimeRange">
        <p>TimeRange</p>
        <c-time-range
          :size="size"
          :variant="variant"
          :placeholder="['Start', 'End']"
        />
      </div>
    </div>

    <section
      aria-label="Selected control size comparison"
      class="control-size-comparison__states"
    >
      <c-space wrap align="center" :size="12">
        <span>Selected / Clearable / Multiple — 有值、可清空与多选不换行</span>
        <span
          >Hover or focus truncated text; tap on touch screens /
          悬停或聚焦省略正文查看全文；触屏点按查看，点外部关闭</span
        >
        <c-button size="sm" variant="outline" @click="resetSelections"
          >Reset / 恢复选中值</c-button
        >
      </c-space>
      <div class="control-size-comparison__grid">
        <div data-control="InputValue">
          <p>Input · clearable</p>
          <c-input
            v-model="inputValue"
            :size="size"
            :variant="variant"
            clearable
            placeholder="Input value"
          />
        </div>
        <div data-control="ButtonReference">
          <p>Button · reference</p>
          <c-button :size="size" variant="outline">Button</c-button>
        </div>
        <div data-control="SelectValue">
          <p>Select · clearable</p>
          <c-select
            v-model="selectValue"
            :size="size"
            :variant="variant"
            :options="selectedOptions"
            clearable
            placeholder="Select value"
          />
        </div>
        <div data-control="CascaderValue">
          <p>Cascader · clearable</p>
          <c-cascader
            v-model="cascaderValue"
            :size="size"
            :variant="variant"
            :options="selectedCascaderOptions"
            clearable
            placeholder="Cascader value"
          />
        </div>
        <div data-control="SelectMultiple">
          <p>Select · multiple / nowrap</p>
          <c-select
            v-model="selectMultiple"
            :size="size"
            :variant="variant"
            :options="selectedOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Select multiple"
          />
        </div>
        <div data-control="CascaderMultiple">
          <p>Cascader · multiple / nowrap</p>
          <c-cascader
            v-model="cascaderMultiple"
            :size="size"
            :variant="variant"
            :options="selectedCascaderOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Cascader multiple"
          />
        </div>
        <div data-control="SelectOverflow">
          <p>Select · long values / nowrap</p>
          <c-select
            v-model="selectOverflow"
            edit-mode="direct"
            :size="size"
            :variant="variant"
            :options="selectedOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Select long values"
          />
        </div>
        <div data-control="CascaderOverflow">
          <p>Cascader · long values / nowrap</p>
          <c-cascader
            v-model="cascaderOverflow"
            edit-mode="direct"
            :size="size"
            :variant="variant"
            :options="selectedCascaderOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Cascader long values"
          />
        </div>
      </div>
    </section>
  </section>
</template>
<style scoped>
.control-size-comparison,
.control-size-comparison__states {
  display: grid;
  gap: 24px;
}
.control-size-comparison__grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
  align-items: start;
  gap: 24px 16px;
}
.control-size-comparison__grid > div {
  min-width: 0;
}
.control-size-comparison__grid p {
  margin: 0 0 12px;
  font-size: 14px;
  line-height: 20px;
}
.control-size-comparison__grid :deep(.c-input-number),
.control-size-comparison__grid :deep(.c-auto-complete) {
  width: 100%;
}
</style>
```

## 选择模式与路径

### 多选模式

<!-- demo-config-notes:start -->

#### 本组配置对照

| 配置             | 作用                                                   | 相关示例                         |
| ---------------- | ------------------------------------------------------ | -------------------------------- |
| `options`        | 树形选项；叶值模式要求叶值唯一，路径模式可区分不同分支 | 多选模式、严格选择模式、路径模式 |
| `placeholder`    | 占位文本                                               | 多选模式、严格选择模式、路径模式 |
| `multiple`       | 多选；默认启用搜索                                     | 多选模式、严格选择模式           |
| `default-value`  | 默认值（非受控状态）                                   | 严格选择模式、路径模式           |
| `expand-trigger` | Menu / List 的展开交互：click 或 hover                 | 严格选择模式、路径模式           |
| `check-strictly` | 允许选中父节点；多选不关联父子节点                     | 严格选择模式                     |

<!-- demo-config-notes:end -->

设置属性`multiple` 开启多选模式。

Example source: src/cascader/__demos__/multiple.vue

```vue
<template>
  <c-space direction="column" size="lg">
    <c-cascader :options="options" :style="{ width: '320px' }" placeholder="Please select ..." multiple />
  </c-space>
</template>

<script lang="ts">
import { defineComponent } from 'vue'
export default defineComponent({
  setup() {
    const options = [
      {
        value: 'beijing',
        label: 'Beijing',
        children: [
          {
            value: 'chaoyang',
            label: 'ChaoYang',
          },
          {
            value: 'haidian',
            label: 'Haidian',
            isLeaf: true,
          },
          {
            value: 'dongcheng',
            label: 'Dongcheng',
            isLeaf: true,
          },
          {
            value: 'xicheng',
            label: 'Xicheng',
          },
        ],
      },
      {
        value: 'shanghai',
        label: 'Shanghai',
        children: [
          {
            value: 'huangpu',
            label: 'Huangpu',
            isLeaf: true,
          },
        ],
      },
    ]
    return {
      options,
    }
  },
})
</script>
```

### 严格选择模式

设置属性 `check-strictly`，开启严格选择模式，点击任何结点都可以选择。多选时将会解除父子节点的关联。

Example source: src/cascader/__demos__/check-strictly.vue

```vue
<template>
  <c-space direction="column" size="lg">
    <c-cascader :options="options" :style="{ width: '320px' }" placeholder="Please select ..." check-strictly />
    <c-cascader
      :options="options"
      default-value="datunli"
      expand-trigger="hover"
      :style="{ width: '320px' }"
      placeholder="Please select ..."
      multiple
      check-strictly />
  </c-space>
</template>

<script lang="ts">
import { defineComponent } from 'vue'
export default defineComponent({
  setup() {
    const options = [
      {
        value: 'beijing',
        label: 'Beijing',
        children: [
          {
            value: 'chaoyang',
            label: 'ChaoYang',
            children: [
              {
                value: 'datunli',
                label: 'Datunli',
              },
            ],
          },
          {
            value: 'haidian',
            label: 'Haidian',
          },
          {
            value: 'dongcheng',
            label: 'Dongcheng',
          },
          {
            value: 'xicheng',
            label: 'Xicheng',
            children: [
              {
                value: 'jinrongjie',
                label: 'Jinrongjie',
              },
              {
                value: 'tianqiao',
                label: 'Tianqiao',
              },
            ],
          },
        ],
      },
      {
        value: 'shanghai',
        label: 'Shanghai',
        children: [
          {
            value: 'huangpu',
            label: 'Huangpu',
          },
        ],
      },
    ]
    return {
      options,
    }
  },
})
</script>
```

### 路径模式

modelValue 使用路径作为值。

Example source: src/cascader/__demos__/path-mode.vue

```vue
<template>
  <c-space direction="column" size="lg">
    <c-cascader
      :options="options"
      :style="{ width: '320px' }"
      placeholder="Please select ..."
      path-mode
      @change="handleChange" />
    <c-cascader
      :options="options"
      default-value="datunli"
      expand-trigger="hover"
      :style="{ width: '320px' }"
      placeholder="Please select ..."
      path-mode
      @change="handleChange" />
  </c-space>
</template>

<script lang="ts">
import { defineComponent } from 'vue'
export default defineComponent({
  setup() {
    const handleChange = (path: any) => {
      console.log(path)
    }
    const options = [
      {
        value: 'beijing',
        label: 'Beijing',
        children: [
          {
            value: 'chaoyang',
            label: 'ChaoYang',
            children: [
              {
                value: 'datunli',
                label: 'Datunli',
              },
            ],
          },
          {
            value: 'haidian',
            label: 'Haidian',
          },
          {
            value: 'dongcheng',
            label: 'Dongcheng',
          },
          {
            value: 'xicheng',
            label: 'Xicheng',
            children: [
              {
                value: 'jinrongjie',
                label: 'Jinrongjie',
              },
              {
                value: 'tianqiao',
                label: 'Tianqiao',
              },
            ],
          },
        ],
      },
      {
        value: 'shanghai',
        label: 'Shanghai',
        children: [
          {
            value: 'huangpu',
            label: 'Huangpu',
          },
        ],
      },
    ]
    return {
      options,
      handleChange,
    }
  },
})
</script>
```

### 管理已选项

确认式多选编辑面板顶部提供已选数量与清空。Cedar 在列表上方显示可删除标签；Maple 点击数量查看已选明细，支持逐项移除并返回可选项。popup/popover 与 dialog 共用该内容。移除和清空先修改草稿，关闭取消会恢复原值，确认后才提交；禁用项保留，异步确认期间禁用操作。面板的清空入口独立于字段清空图标。

### 允许清除

设置属性 `clearable` 允许清除输入框的内容。

Example source: src/cascader/__demos__/clearable.vue

```vue
<template>
  <c-cascader :options="options" v-model="value" placeholder="Please select ..." clearable />
</template>

<script lang="ts">
import { ref, defineComponent } from 'vue'
export default defineComponent({
  setup() {
    const value = ref('datunli')

    const options = [
      {
        value: 'beijing',
        label: 'Beijing',
        children: [
          {
            value: 'chaoyang',
            label: 'ChaoYang',
            children: [
              {
                value: 'datunli',
                label: 'Datunli',
              },
            ],
          },
          {
            value: 'haidian',
            label: 'Haidian',
          },
          {
            value: 'dongcheng',
            label: 'Dongcheng',
          },
          {
            value: 'xicheng',
            label: 'Xicheng',
            children: [
              {
                value: 'jinrongjie',
                label: 'Jinrongjie',
              },
              {
                value: 'tianqiao',
                label: 'Tianqiao',
              },
            ],
          },
        ],
      },
      {
        value: 'shanghai',
        label: 'Shanghai',
        children: [
          {
            value: 'huangpu',
            label: 'Huangpu',
          },
        ],
      },
    ]
    return {
      value,
      options,
    }
  },
})
</script>
```

## 搜索与展示

### 允许搜索

<!-- demo-config-notes:start -->

#### 本组配置对照

| 配置             | 作用                                                   | 相关示例                                     |
| ---------------- | ------------------------------------------------------ | -------------------------------------------- |
| `options`        | 树形选项；叶值模式要求叶值唯一，路径模式可区分不同分支 | 允许搜索、搜索匹配规则、自定义输入框的展示值 |
| `placeholder`    | 占位文本                                               | 允许搜索、搜索匹配规则、自定义输入框的展示值 |
| `filterable`     | 开启搜索                                               | 允许搜索、搜索匹配规则                       |
| `case-sensitive` | 内置本地过滤是否区分大小写，自定义过滤函数优先         | 搜索匹配规则                                 |
| `format-label`   | 格式化已选标签；VNode 使用 label 插槽                  | 自定义输入框的展示值                         |

<!-- demo-config-notes:end -->

通过设置 filterable 让输入框支持搜索功能。

Example source: src/cascader/__demos__/filterable.vue

```vue
<template>
  <c-space direction="column" size="lg">
    <c-cascader :options="options" placeholder="Please select ..." filterable />
  </c-space>
</template>

<script lang="ts">
import { defineComponent } from 'vue'
export default defineComponent({
  setup() {
    const options = [
      {
        value: 'beijing',
        label: 'Beijing',
        children: [
          {
            value: 'chaoyang',
            label: 'ChaoYang',
            children: [
              {
                value: 'datunli',
                label: 'Datunli',
              },
            ],
          },
          {
            value: 'haidian',
            label: 'Haidian',
          },
          {
            value: 'dongcheng',
            label: 'Dongcheng',
          },
          {
            value: 'xicheng',
            label: 'Xicheng',
            children: [
              {
                value: 'jinrongjie',
                label: 'Jinrongjie',
              },
              {
                value: 'tianqiao',
                label: 'Tianqiao',
              },
            ],
          },
        ],
      },
      {
        value: 'shanghai',
        label: 'Shanghai',
        children: [
          {
            value: 'huangpu',
            label: 'Huangpu',
          },
        ],
      },
    ]
    return {
      options,
    }
  },
})
</script>
```

### 搜索匹配规则

`case-sensitive` 默认 false，只控制内置本地匹配是否区分大小写；自定义过滤函数优先。保留原有路径标签和 checkStrictly 行为；远程结果不需本地筛选时可使用 `:filter-option="() => true"`，该属性仍是原有函数协议。

Example source: src/cascader/__demos__/case-sensitive.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const value = ref<string[]>([])
const caseSensitive = ref(false)
const options = [{ value: 'fruit', label: 'Fruit', children: [{ value: 'apple', label: 'Apple' }] }]
</script>
<template>
  <c-space direction="column" fill>
    <c-space><c-switch v-model="caseSensitive" /><span>区分大小写</span></c-space>
    <c-cascader v-model="value" :options="options" :case-sensitive="caseSensitive" filterable placeholder="输入 fruit、Fruit、apple 或 Apple" />
    <p>保留原有路径标签匹配。启用区分大小写后，输入 fruit 不匹配 Fruit。</p>
  </c-space>
</template>
```

### 自定义输入框的展示值

利用 formatLabel 对显示的内容进行自定义处理。

Example source: src/cascader/__demos__/format-label.vue

```vue
<template>
  <c-space direction="column" size="lg">
    <c-cascader :options="options" :style="{ width: '320px' }" placeholder="Please select ..." :format-label="format" />
  </c-space>
</template>

<script lang="ts">
import { defineComponent } from 'vue'
export default defineComponent({
  setup() {
    const options = [
      {
        value: 'beijing',
        label: 'Beijing',
        children: [
          {
            value: 'chaoyang',
            label: 'ChaoYang',
            children: [
              {
                value: 'datunli',
                label: 'Datunli',
              },
            ],
          },
          {
            value: 'haidian',
            label: 'Haidian',
          },
          {
            value: 'dongcheng',
            label: 'Dongcheng',
          },
          {
            value: 'xicheng',
            label: 'Xicheng',
            children: [
              {
                value: 'jinrongjie',
                label: 'Jinrongjie',
              },
              {
                value: 'tianqiao',
                label: 'Tianqiao',
              },
            ],
          },
        ],
      },
      {
        value: 'shanghai',
        label: 'Shanghai',
        children: [
          {
            value: 'huangpu',
            label: 'Huangpu',
          },
        ],
      },
    ]
    interface Option {
      value: string
      label: string
    }

    const format = (options: Option[]) => {
      const labels = options.map((option) => option.label)
      return labels.join('-')
    }
    return {
      options,
      format,
    }
  },
})
</script>
```

## 交互与控制

### 交互状态对比

<!-- demo-config-notes:start -->

#### 本组配置对照

| 配置        | 作用                                                   | 相关示例     |
| ----------- | ------------------------------------------------------ | ------------ |
| `options`   | 树形选项；叶值模式要求叶值唯一，路径模式可区分不同分支 | 交互状态对比 |
| `clearable` | 允许清除，保留禁用的已选项                             | 交互状态对比 |
| `disabled`  | 是否禁用                                               | 交互状态对比 |

<!-- demo-config-notes:end -->

在同一实例上切换禁用、只读和错误状态后再操作控件，比较可编辑性和交互反馈。恢复开关位于目标控件外；错误外观本身不会执行校验。

<details>
<summary>配置说明与使用限制</summary>

#### 禁用选项

设置属性 `disabled` 禁用选项。

#### 交互状态切换

适用于地区等层级选项。调整禁用、只读、错误反馈，用相同数据观察变化。控制区始终可用，可以随时恢复编辑；错误外观本身不会触发表单校验。

</details>

Example source: src/cascader/__demos__/state-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref("shanghai");
const options = [
  {
    label: "华东",
    value: "east",
    children: [
      { label: "上海", value: "shanghai" },
      { label: "杭州", value: "hangzhou" },
    ],
  },
];
const __demoState = __demoReactive({
  disabled: false,
  readonly: false,
  error: false,
});
</script>
<template>
  <c-space direction="column" :size="16">
    <c-space wrap>
      <c-checkbox v-model="__demoState['disabled']">disabled</c-checkbox>
      <c-checkbox v-model="__demoState['readonly']">readonly</c-checkbox>
      <c-checkbox v-model="__demoState['error']">error</c-checkbox>
    </c-space>
    <c-cascader
      v-model="value"
      :options="options"
      clearable
      v-bind="__demoState"
    ></c-cascader>
  </c-space>
</template>
```

## 配置与组合

### 透传配置边界与优先级

<!-- demo-config-notes:start -->

#### 本组配置对照

| 配置                  | 作用                                                                                   | 相关示例                         |
| --------------------- | -------------------------------------------------------------------------------------- | -------------------------------- |
| `edit-mode`           | 展示方式                                                                               | 透传配置边界与优先级、复制与编辑 |
| `options`             | 树形选项；叶值模式要求叶值唯一，路径模式可区分不同分支                                 | 透传配置边界与优先级、复制与编辑 |
| `trigger-props`       | Menu 的 Trigger 属性；展开状态由字段控制                                               | 透传配置边界与优先级             |
| `open-trigger-target` | 打开面板的点击区域；field 为整个字段，icon 仅右侧选择按钮。不影响键盘展开及受控 open。 | 复制与编辑                       |
| `filterable`          | 开启搜索                                                                               | 复制与编辑                       |

<!-- demo-config-notes:end -->

建议使用 `CascaderTriggerOptions` 声明 trigger-props。open/defaultOpen、disabled 和展开更新归 Cascader 管理。popup-container 顶层明确传入时优先（包括 false），否则回退 triggerProps.popupContainer。Trigger 的普通配置保留原顺序，嵌套 unmountOnClose 仍可覆盖顶层 unmount-on-close；默认的定位/交互配置也仍可被有效嵌套字段覆盖。内部展开监听继续执行，通知使用 Cascader 事件。

本次仅新增可主动选用的专用类型，不收窄已发布的宽属性类型，不增加运行时过滤、不改变覆盖顺序；旧业务写法继续可编译。若直接使用旧宽属性，内部托管字段仍可能通过类型检查，但不代表能控制内部状态。

```ts
import type { CascaderTriggerOptions } from "@cedar-design/ui";
```

Example source: src/cascader/__demos__/passthrough-options.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import type { CascaderTriggerOptions } from "@cedar-design/ui";
const open = ref(false);
const triggerOptions: CascaderTriggerOptions = {
  placement: "top-start",
  popupOffset: 8,
  popupContainer: false,
};
const options = [
  {
    value: "fruit",
    label: "水果",
    children: [{ value: "apple", label: "Apple" }],
  },
];
</script>
<template>
  <c-space direction="column" fill>
    <c-button @click="open = !open">{{
      open ? "关闭面板" : "打开面板"
    }}</c-button>
    <c-cascader
      edit-mode="direct"
      v-model:open="open"
      :options="options"
      :trigger-props="triggerOptions"
      aria-label="透传配置示例"
    />
    <p role="status">顶层 open：{{ open }}；嵌套配置：向上展开并调整偏移。</p>
  </c-space>
</template>
```

### 复制与编辑

open-trigger-target="icon" 时，输入区可以编辑或复制，只有右侧选择按钮响应点击打开。关闭手输或搜索后，已有文本仍可复制。

Example source: src/cascader/__demos__/open-trigger-target.vue

```vue
<template>
  <c-space direction="column">
    <c-radio-group
      v-model="target"
      :options="[
        { label: '整个字段', value: 'field' },
        { label: '仅右侧图标', value: 'icon' },
      ]"
    />
    <label><c-switch v-model="editable" /> 允许编辑 / 搜索</label>
    <c-cascader
      v-model="value"
      edit-mode="direct"
      :open-trigger-target="target"
      :filterable="editable"
      :options="[
        { value: 'a', label: 'Alpha' },
        { value: 'b', label: 'Beta' },
      ]"
    />
    <p>关闭编辑后，可以复制已有文本；仅图标模式下编辑不会展开。</p>
  </c-space>
</template>
<script setup lang="ts">
import { ref } from "vue";
const target = ref<"field" | "icon">("icon");
const editable = ref(true);
const value = ref("a");
</script>
```

## 异步加载与回显

### 加载中

<!-- demo-config-notes:start -->

#### 本组配置对照

| 配置          | 作用                                                                  | 相关示例                                 |
| ------------- | --------------------------------------------------------------------- | ---------------------------------------- |
| `options`     | 树形选项；叶值模式要求叶值唯一，路径模式可区分不同分支                | 加载中、子选项懒加载、异步设备与 ID 回显 |
| `placeholder` | 占位文本                                                              | 加载中、子选项懒加载、异步设备与 ID 回显 |
| `loading`     | 加载状态；禁止选择和确认                                              | 加载中、异步设备与 ID 回显               |
| `load-more`   | 异步加载子节点；完成后调用 done(children)，失败调用 done() 以允许重试 | 子选项懒加载                             |
| `path-mode`   | true 返回完整路径；false 返回选中节点的值                             | 异步设备与 ID 回显                       |
| `filterable`  | 开启搜索                                                              | 异步设备与 ID 回显                       |

<!-- demo-config-notes:end -->

选择框和下拉菜单显示加载状态

Example source: src/cascader/__demos__/loading.vue

```vue
<template>
  <c-space direction="column" size="lg">
    <c-cascader :options="[]" :style="{ width: '320px' }" placeholder="Please select ..." loading />
  </c-space>
</template>

<script lang="ts">
import { defineComponent } from 'vue'
export default defineComponent({
  })
</script>
```

### 子选项懒加载

通过 load-more 属性可以开启数据懒加载功能。
开启数据懒加载功能后，需要在叶子节点标注 isLeaf: true，没有标注且没有 children 属性的节点会认为需要懒加载处理。
load-more 属性有提供 done 函数进行回调，可以在回调中传入懒加载的子数据。如果 done 函数没有传入数据会认为懒加载失败，此节点可以再次触发懒加载。

Example source: src/cascader/__demos__/load-more.vue

```vue
<template>
  <c-space direction="column" size="lg">
    <c-cascader :options="options" :style="{ width: '320px' }" placeholder="Please select ..." :load-more="loadMore" />
  </c-space>
</template>

<script lang="ts">
import { defineComponent } from 'vue'
export default defineComponent({
  setup() {
    const options = [
      {
        value: 'beijing',
        label: 'Beijing',
        children: [
          {
            value: 'chaoyang',
            label: 'ChaoYang',
          },
          {
            value: 'haidian',
            label: 'Haidian',
            isLeaf: true,
          },
          {
            value: 'dongcheng',
            label: 'Dongcheng',
            isLeaf: true,
          },
          {
            value: 'xicheng',
            label: 'Xicheng',
          },
        ],
      },
      {
        value: 'shanghai',
        label: 'Shanghai',
        children: [
          {
            value: 'huangpu',
            label: 'Huangpu',
            isLeaf: true,
          },
        ],
      },
    ]
    const loadMore = (option: any, done: any) => {
      window.setTimeout(() => {
        const nodes = [
          {
            value: `${option.value}-option1`,
            label: `${option.label}-Option1`,
            isLeaf: true,
          },
          {
            value: `${option.value}-option2`,
            label: `${option.label}-Option2`,
            isLeaf: true,
          },
        ]
        done(nodes)
      }, 2000)
    }

    return {
      options,
      loadMore,
    }
  },
})
</script>
```

### 异步设备与 ID 回显

Example source: src/cascader/__demos__/async-devices.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const value = ref(['factory', 'device-2'])
const options = ref<Record<string, unknown>[]>([])
const loading = ref(false)
async function load() {
  loading.value = true
  try {
    options.value = await Promise.resolve([
      { id: 'factory', name: '工厂', nodes: [
        { id: 'device-1', name: '设备一' },
        { id: 'device-2', name: '设备二' },
        { id: 'device-3', name: '检修设备', disabled: true },
      ] },
    ])
  } finally { loading.value = false }
}
</script>
<template>
  <c-space direction="column" :size="16">
    <c-button @click="load">加载设备树</c-button>
    <c-cascader v-model="value" :options="options" :loading="loading" path-mode filterable clearable
      :field-names="{ label: 'name', value: 'id', children: 'nodes' }" placeholder="选择设备路径" />
    <p>已提交路径：{{ value }}。标签与 ID 分离，异步加载后自动回显。</p>
  </c-space>
</template>
```

单选已选项在右侧显示内置主色对勾。多选使用 Checkbox：可选后代全部未选为未选，部分选中为半选，全部可选叶子选中为全选；禁用叶子不参与全选计算。checkStrictly 开启时父子独立选择，不汇总半选。确认式编辑面板中的选择先作为草稿，确认后才提交。

### 共享字段加载

`loading` 控制共享字段加载状态；`loading-mode` 为 `default`（指示器）或 `line`（底部不定进度线），默认 `default`。渲染统一由 FieldDecorator 负责，不隐式改变 disabled/readonly；需要禁止编辑时单独设置。

## API

### 空值识别与阅读空文案

`empty-values` 用于空值识别，`empty-value` 保留原清空输出；`empty-text` 仅在 `read-pretty` 空内容下展示，默认 `'-'`，字段 > FormItem > Form，自定义 read 插槽优先。显式配置 empty-values 后，内置 required 接入该策略，自定义校验仍收到原值。详见[统一说明](llms/zh-CN/guide/empty-values.md)。

| 参数         | 类型               | 缺省与范围                                            |
| ------------ | ------------------ | ----------------------------------------------------- |
| empty-values | readonly unknown[] | 字段 > FormItem > Form > 组件族默认；完整覆盖，不合并 |
| empty-text   | string             | 字段 > FormItem > Form > '-'；显式 '' 有效            |

以上是字段展示层 API；纯面板不因此新增阅读模式。Form 与 FormItem 提供继承配置。empty-value 的现有类型与默认输出仍按该组件原 API 执行。

### Cascader 属性

分别使用 `v-model`、`v-model:open` 和 `v-model:input-value` 控制选中值、展开状态和搜索词。单选清空为 `''`，多选为 `[]`；Select 存在真实空字符串选项时，清空值为 `undefined`。

| 属性                                    | 说明                                                                                       | 类型                                                          | 默认值                   |
| --------------------------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------- | ------------------------ |
| `open-trigger-target`                   | 打开面板的点击区域；field 为整个字段，icon 仅右侧选择按钮。不影响键盘展开及受控 open。     | `'field' \| 'icon'`                                           | `'field'`                |
| `model-value / default-value`           | 受控值 / 非受控初始值                                                                      | `Value`                                                       | `单选 ''，多选 []`       |
| `open / default-open`                   | 受控展开 / 默认展开                                                                        | `boolean`                                                     | `undefined / false`      |
| `input-value / default-input-value`     | 搜索文本，独立于选中值                                                                     | `string`                                                      | `undefined / ''`         |
| `multiple`                              | 多选；默认启用搜索                                                                         | `boolean`                                                     | `false`                  |
| `size`                                  | 完整支持 xs、sm、md、lg、xl，未设置时继承分组与表单                                        | `ComponentSize`                                               | `md`                     |
| `variant`                               | filled、outline、standard；未设置时继承 InputGroup                                         | `FormControlVariant`                                          | `filled`                 |
| `disabled / readonly / error`           | 未设置时继承表单；显式 false 可覆盖                                                        | `boolean`                                                     | `undefined`              |
| `placeholder`                           | 占位文本                                                                                   | `string`                                                      | `—`                      |
| `hint / line`                           | 浮动提示 / standard 变体下划线                                                             | `boolean`                                                     | `true`                   |
| `text-color / focus-color / blur-color` | 字段颜色                                                                                   | `string`                                                      | `—`                      |
| `loading`                               | 加载状态；禁止选择和确认                                                                   | `boolean`                                                     | `false`                  |
| `show-tags`                             | 多选值以标签展示；false 改用分隔文本                                                       | `boolean`                                                     | `true`                   |
| `separator`                             | show-tags=false 时的多选分隔符                                                             | `string`                                                      | `,`                      |
| `text-align`                            | 文字对齐 left / center / right；未设置时继承 FormItem 的 content-align，独立使用默认阅读起点 start  | `'left' \| 'center' \| 'right'`                               | `-`                      |
| `max-tag-count`                         | 标签数量上限，0 不限制                                                                     | `number`                                                      | `0`                      |
| `tag-nowrap`                            | 标签单行显示；长文字省略、删除图标保留，标签行可横向滚动；悬停、聚焦或点按省略正文查看全文 | `boolean`                                                     | `false`                  |
| `popup-container`                       | 选择器、元素、返回元素的函数或 false（原地渲染）                                           | `PopupContainer`                                              | `—`                      |
| `trigger-props`                         | Menu 的 Trigger 属性；展开状态由字段控制                                                   | `TriggerProps`                                                | `—`                      |
| `virtual-list-props`                    | Menu / List 的虚拟列表参数                                                                 | `VirtualListProps`                                            | `—`                      |
| `search-delay`                          | search 事件防抖时长（毫秒）                                                                | `number`                                                      | `500`                    |
| `format-label`                          | 格式化已选标签；VNode 使用 label 插槽                                                      | `function`                                                    | `—`                      |
| `clearable`                             | 允许清除，保留禁用的已选项                                                                 | `boolean`                                                     | `false`                  |
| `options`                               | 树形选项；叶值模式要求叶值唯一，路径模式可区分不同分支                                     | `CascaderOption[]` / `(query, { signal }) => Array / Promise` | `undefined`              |
| `field-names`                           | value、label、disabled、children、isLeaf、tagProps、render 的字段映射                      | `CascaderFieldNames`                                          | `—`                      |
| `path-mode`                             | true 返回完整路径；false 返回选中节点的值                                                  | `boolean`                                                     | `false`                  |
| `check-strictly`                        | 允许选中父节点；多选不关联父子节点                                                         | `boolean`                                                     | `false`                  |
| `filterable`                            | 开启搜索                                                                                   | `boolean`                                                     | `单选 false / 多选 true` |
| case-sensitive                          | 内置本地过滤是否区分大小写，自定义过滤函数优先                                             | boolean                                                       | false                    |
| `filter-option`                         | 接收搜索词和原始节点                                                                       | `(input, option) => boolean`                                  | `—`                      |
| `expand-trigger`                        | Menu / List 的展开交互：click 或 hover                                                     | `string`                                                      | `click`                  |
| `expand-child`                          | 展开到首个子节点                                                                           | `boolean`                                                     | `false`                  |
| `load-more`                             | 异步加载子节点；完成后调用 done(children)，失败调用 done() 以允许重试                      | `(option, done) => void`                                      | `—`                      |
| `fallback-option`                       | 尚未加载的值如何反显                                                                       | `boolean 或 (value) => string`                                | `true`                   |
| `search-option-only-label`              | 搜索结果仅显示节点标签，不显示路径                                                         | `boolean`                                                     | `false`                  |
| `auto-fit-popup-width`                  | Menu 是否与字段等宽                                                                        | `boolean`                                                     | `false`                  |
| `edit-mode`                             | 展示方式                                                                                   | `menu`                                                        | `menu`                   |

### 事件与方法

- `update:modelValue`、`change(value)`：提交时触发，编辑草稿不触发。
- `update:open`、`open-change(open)`：请求改变展开状态。
- `update:inputValue`、`input-value-change(text)`、`search(text)`：搜索状态。
- `focus(event)`、`blur(event)`、`clear(event)`：原生字段事件；只有字段所有者通知 Form。
- 方法：`focus()`、`blur()`。

### 插槽与选项数据

使用 `label({ data })` 自定义已选标签，`selected` 替换整个已选区域。还支持 `prefix`、`suffix`、`clear-icon({ clear })`、`arrow-icon`、`loading-icon`、`search-icon`、`empty`、`option({ data })`。

选项 `label` 是用于搜索的纯文本；自定义选项内容使用 `render` 或 `option` 插槽，自定义反显使用 `format-label` 或 `label` 插槽。以 value 而非 label 识别选项。选项的 `disabled` 禁止选择和删除，`tagProps` 可定制已选标签。

### `<CascaderPanel>` Props

| 参数名                    | 描述                                                                              | 类型                                                                                                                                                               |         默认值          |
| ------------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :---------------------: |
| path-mode                 | 绑定值是否为路径                                                                  | `boolean`                                                                                                                                                          |         `false`         |
| multiple                  | 是否为多选状态（多选模式默认开启搜索）                                            | `boolean`                                                                                                                                                          |         `false`         |
| model-value **(v-model)** | 绑定值                                                                            | `string\| number\| Record<string, any>\| (    \| string    \| number    \| Record<string, any>    \| (string \| number \| Record<string, any>)[]  )[]\| undefined` |           `-`           |
| default-value             | 默认值（非受控状态）                                                              | `string\| number\| Record<string, any>\| (    \| string    \| number    \| Record<string, any>    \| (string \| number \| Record<string, any>)[]  )[]\| undefined` | `'' \| undefined \| []` |
| options                   | 级联选择器的选项                                                                  | `CascaderOption[]` / `(query, { signal }) => Array / Promise`                                                                                                      |       `undefined`       |
| expand-trigger            | 展开下一级的触发方式                                                              | `string`                                                                                                                                                           |        `'click'`        |
| check-strictly            | 是否开启严格选择模式                                                              | `boolean`                                                                                                                                                          |         `false`         |
| load-more                 | 数据懒加载函数，传入时开启懒加载功能                                              | `(  option: CascaderOption,  done: (children?: CascaderOption[]) => void) => void`                                                                                 |           `-`           |
| field-names               | 自定义 `CascaderOption` 中的字段；当选项值为对象时，也用其中的 `value` 作为键属性 | `CascaderFieldNames`                                                                                                                                               |           `-`           |
| expand-child              | 是否展开子菜单                                                                    | `boolean`                                                                                                                                                          |         `false`         |

### `<CascaderPanel>` Events

| 事件名 | 描述             | 参数                                                                                   |
| ------ | ---------------- | -------------------------------------------------------------------------------------- |
| change | 选中值改变时触发 | value: `string \| number \| (string \| number \| (string \| number)[])[] \| undefined` |

### `<CascaderPanel>` Slots

| 插槽名 |         描述         | 参数 |
| ------ | :------------------: | ---- |
| empty  | 选项为空时的显示内容 | -    |

### CascaderOption

| 参数名   | 描述           | 类型                                      | 默认值  |
| -------- | -------------- | ----------------------------------------- | :-----: |
| value    | 选项值         | `string \| number \| Record<string, any>` |   `-`   |
| label    | 选项文本       | `string`                                  |   `-`   |
| render   | 自定义渲染     | `RenderFunction`                          |   `-`   |
| disabled | 是否禁用       | `boolean`                                 | `false` |
| tagProps | 展示的标签属性 | `TagProps`                                |   `-`   |
| children | 下一级选项     | `CascaderOption[]`                        |   `-`   |
| isLeaf   | 是否是叶子节点 | `boolean`                                 | `false` |

## 类型定义

组件导出以下类型定义

```ts
import type { CascaderProps } from "@cedar-design/ui";
```

### Form 字段展示与确认

本组件支持 `edit-mode`，字段 > FormItem > Form 逐层继承；未指定时为 `direct`，保留原有交互。支持值：`direct / click / dblclick`。非 direct 编辑模式通过字段值入口打开编辑面板，并维护单份草稿；确认后才更新 v-model，取消、重置或启用 readPretty 时丢弃草稿。

Cedar 使用 edit-mode="click" / "dblclick" 在字段附近打开编辑浮层，Enter/F2 也可进入；取消/Escape 丢弃草稿，确认后提交。readPretty 为独立阅读属性，与 readonly、disabled 分开。

`before-commit(value, { previousValue, signal })` 可拦截弹层保存；FormItem 先校验候选值，失败保持编辑。`open / default-open / update:open` 控制编辑层。`#read="{ value, text }"` 可自定义阅读内容。集中示例见 Form 的“各类字段统一展示”。

字段编辑统一使用 edit-mode：Cedar 支持 direct/click/dblclick，Maple 支持 direct/popup；不保留 menu/list/picker 这些旧编辑枚举。弹层复用原选项索引、搜索、异步加载与虚拟列表算法。

`read-pretty` 为独立布尔属性，与 `readonly`、`disabled` 同级；字段 > FormItem > Form 继承，显式 `false` 覆盖父级。默认 `false`。纯阅读不显示编辑器。

### 单选对勾样式变量

| 变量                            | 默认值                              |
| ------------------------------- | ----------------------------------- |
| `--c-cascader-item-check-color` | `var(--c-sys-color-action-primary)` |
| `--c-cascader-item-check-size`  | `var(--c-sys-font-size-md)`         |

### 内置搜索字段配置

`searchFields` / `search-fields` 是只读 `('label' | 'value')[]`，默认 `['label']`；多字段为 OR 匹配，大小写默认不敏感。配置 `['value', 'label']` 可同时搜索编码和名称，fieldNames 将语义字段映射到业务字段；空数组对非空查询不匹配任何项。value 采用字符串比较，不做对象深层搜索，对象值或拼音等复杂规则仍用自定义回调。自定义回调优先并自行决定大小写；远程结果使用原有关闭本地过滤协议。Cascader 保留路径语义，会检查路径各节点的配置字段。

## 配置清空后的值

`empty-value` 指定当前组件已有清空动作的输出；省略时采用该组件默认返回。具体类型以组件 API 为准。它不改变 empty-values 的识别规则，也不改变 Form reset 的初始值。

`empty-value` 可显式设为 `null`（或 `() => null`），清空时原样提交 null；省略时保留组件原默认值。界面把 null 显示为空，不会把普通输入的空字符串自动转成 null。支持弹出编辑的字段中，清空先修改草稿，确认后提交，取消则保留原值。

候选属性 `options` 支持数组或 `(query, { signal }) => 数组/Promise`。加载、取消、过期结果隔离由组件内部处理，失败触发 load-error。单选/多选分组初始化以空字符串查询，搜索型字段在查询变化时调用；树形字段根数据与原有 load-more 子节点懒加载独立。

---

Document: llms/zh-CN/components/checkbox.md

<!-- Source: src/checkbox/README.md; locale: zh-CN; page: /components/checkbox/ -->

# Checkbox

独立 Checkbox 的 modelValue 在布尔模式下表示是否选中，在数组模式下表示选中选项的集合；value 是当前选项的标识。CheckboxGroup 的 modelValue 是选中值数组。defaultValue 只初始化非受控状态，不会回写父级绑定值。

在一组数据中，用户可通过复选框选择一个或多个数据。

分组示例覆盖父级接受/拒绝更新、只读和异步选项回显；移除选项不会清空业务值。示例外层 Space 的纵向布局使用 `direction="column"`，与选择组自身的 `orientation="vertical"` 分开理解。

## 阅读方向

复选框标签及分组按来源 dir 排列，业务数组顺序不变。Space 保持切换语义，禁用/只读状态不因方向变化失效；切换 LTR/RTL 不自动勾选或清空选项。

## 基础示例

### 基础用法

基础用法。

Example source: src/checkbox/__demos__/basic.vue

```vue
<template>
  <c-checkbox value="1">Option 1</c-checkbox>
</template>
<script lang="ts">
import { defineComponent } from 'vue'
export default defineComponent({
  })
</script>
```

## 分组与布局

### 选项声明方式对比

<!-- demo-config-notes:start -->

#### 本组配置对照

| 配置       | 作用                            | 相关示例               |
| ---------- | ------------------------------- | ---------------------- |
| `value`    | 数组/分组模式的选项标识         | 选项声明方式对比、布局 |
| `disabled` | 是否禁用；未设置时继承表单/分组 | 布局                   |

<!-- demo-config-notes:end -->

比较子组件声明和 options 数据声明；两种方式都使用组值，字段映射和异步选项另见对应示例。

<details>
<summary>配置说明与使用限制</summary>

#### 复选框组

通过 `CheckboxGroup`组件展示复选框组。设置`orientation="vertical"`可以展示竖向的复选框组

#### 复选框组选项

`CheckboxGroup`通过options属性设置子元素

</details>

Example source: src/checkbox/__demos__/group-declaration-comparison.vue

```vue
<script setup lang="ts">
import { ref } from "vue"
import { proxyRefs as demoProxyRefs } from 'vue'

const scene2 = demoProxyRefs((() => {


    const value1 = ref(['Plain 1'])


    const plainOptions = ['Plain 1', 'Plain 2', 'Plain 3']



    const value2 = ref(['1'])


    const options = [
      { label: 'Option 1', value: '1' },
      { label: 'Option 2', value: '2' },
      { label: 'Option 3', value: '3', disabled: true },
    ]
return { value1, plainOptions, value2, options }
})())
</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="checkbox-group">
    <h4><span lang="zh-CN">复选框组</span><span lang="en-US">checkbox group</span></h4>
    <c-space direction="column" size="lg">
        <c-checkbox-group :default-value="['1']">
          <c-checkbox value="1">Option 1</c-checkbox>
          <c-checkbox value="2">Option 2</c-checkbox>
          <c-checkbox value="3">Option 3</c-checkbox>
        </c-checkbox-group>
        <c-checkbox-group orientation="vertical">
          <c-checkbox value="1">Option 1</c-checkbox>
          <c-checkbox value="2">Option 2</c-checkbox>
          <c-checkbox value="3">Option 3</c-checkbox>
        </c-checkbox-group>
      </c-space>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="checkbox-group-options">
    <h4><span lang="zh-CN">复选框组选项</span><span lang="en-US">checkbox group options</span></h4>
    <c-space direction="column" size="lg">
        <c-checkbox-group v-model="scene2.value1" :options="scene2.plainOptions"> </c-checkbox-group>
        <c-checkbox-group v-model="scene2.value2" :options="scene2.options"> </c-checkbox-group>
        <c-checkbox-group v-model="scene2.value2" :options="scene2.options">
          <template #label="{ data }">
            <c-tag>{{ data.label }}</c-tag>
          </template>
        </c-checkbox-group>
      </c-space>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

### 布局

使用`CheckboxGroup`传入`Checkbox`，配合`Grid`组件实现灵活的布局

Example source: src/checkbox/__demos__/grid.vue

```vue
<template>
  <c-checkbox-group v-model="checkedValue">
    <c-grid :cols="3" :colGap="24" :rowGap="16">
      <c-grid-item>
        <c-checkbox value="1">Option 1</c-checkbox>
      </c-grid-item>
      <c-grid-item>
        <c-checkbox value="2" disabled>Option 2</c-checkbox>
      </c-grid-item>
      <c-grid-item>
        <c-checkbox value="3">Option 3</c-checkbox>
      </c-grid-item>
      <c-grid-item>
        <c-checkbox value="4">Option 4</c-checkbox>
      </c-grid-item>
      <c-grid-item>
        <c-checkbox value="5">Option 5</c-checkbox>
      </c-grid-item>
    </c-grid>
  </c-checkbox-group>
</template>
<script lang="ts">
import { defineComponent, ref } from 'vue'
export default defineComponent({
  setup() {
    const checkedValue = ref(['1', '2'])

    return {
      checkedValue,
    }
  },
})
</script>
```

### 分组状态与只读

`model-value !== undefined` 表示受控，父级不回写时保留原值；`default-value` 只初始化非受控值。分组内只由 Group 发出 `update:model-value → change(value, event?)`，并通知 FormItem 一次，子项不重复发值变化事件。
Group 的 `disabled`、`readonly`、`error` 未设置时继承表单，显式 `false` 可以覆盖表单；子项不能绕过 Group 的禁用或只读限制。

Example source: src/checkbox/__demos__/group-state.vue

```vue
<script setup>
import { ref } from 'vue'

const accepted = ref(['a'])
const proposed = ref([])
const readonly = ref(false)
const options = [{ label: '设备 A', value: 'a' }, { label: '设备 B', value: 'b' }]
</script>

<template>
  <c-space direction="column">
    <div>
      <p>非受控：default-value 只用于初始值</p>
      <c-checkbox-group :default-value="['a']" :options="options" />
    </div>
    <div>
      <p>受控：父级接受更新 {{ accepted }}</p>
      <c-checkbox-group v-model="accepted" :options="options" :readonly="readonly" />
      <c-button size="sm" @click="readonly = !readonly">{{ readonly ? '解除只读' : '设为只读' }}</c-button>
    </div>
    <div>
      <p>父级拒绝更新：仅记录提议 {{ proposed }}</p>
      <c-checkbox-group :model-value="[]" :options="options" @update:model-value="proposed = $event" />
    </div>
  </c-space>
</template>
```

## 选项与值模型

### 独立值模型与方法

<!-- demo-config-notes:start -->

#### 本组配置对照

| 配置            | 作用                            | 相关示例               |
| --------------- | ------------------------------- | ---------------------- |
| `default-value` | 非受控初始值                    | 独立值模型与方法、受控 |
| `value`         | 数组/分组模式的选项标识         | 独立值模型与方法       |
| `readonly`      | 是否只读；未设置时继承表单/分组 | 独立值模型与方法       |
| `disabled`      | 是否禁用；未设置时继承表单/分组 | 独立值模型与方法       |

<!-- demo-config-notes:end -->

Checkbox 的布尔模型始终返回 boolean；数组模型按 value 增删选项，不修改传入数组。indeterminate 只用于展示，由业务方计算，不会自动回写。
两端统一使用 `default-value` 初始化非受控值；受控提议被拒绝时保持原值。用户选择按 `update:model-value → change(value, event?)` 通知，命令式调用的 event 为 undefined。
提供 `toggle(checked?: boolean)`、`focus(options?)`、`blur()`。禁用禁止选择和聚焦，只读允许聚焦、禁止改值。Enter 按下与空格释放激活当前控件，长按不重复激活，失焦/停用会取消待处理的空格操作。

Example source: src/checkbox/__demos__/control-value.vue

```vue
<script setup>
import { ref } from 'vue'
const control = ref()
const value = ref(false)
const selected = ref([0])
</script>
<template>
  <c-space direction="column">
    <p>布尔模型始终返回布尔值；数组模型用 value 标识选项。 当前值：{{ value }}</p>
    <c-checkbox ref="control" v-model="value">启用通知</c-checkbox>
    <c-space wrap>
      <c-button size="sm" @click="control?.toggle()">切换选择</c-button>
      <c-button size="sm" @click="control?.focus()">聚焦</c-button>
      <c-button size="sm" @click="value = false">重置</c-button>
    </c-space>
    <p>数组模型：{{ selected }}</p>
    <c-checkbox v-model="selected" :value="0">数值 0</c-checkbox>
    <c-checkbox v-model="selected" :value="false">布尔 false</c-checkbox>
    <p>只读允许聚焦，禁用不允许操作；Enter/空格只影响当前控件。</p>
    <c-checkbox :default-value="true" readonly>只读</c-checkbox>
    <c-checkbox :default-value="true" disabled>禁用</c-checkbox>
  </c-space>
</template>
```

### 选项数据与标签

两端均支持原始值或对象选项。`field-names` 映射 `label/value/disabled/readonly/indeterminate`；只读选项允许聚焦但不能改值，Checkbox 的半选仅用于展示。
`label` 插槽接收 `{ data, checked }`，优先于标签渲染函数 `(data, checked) => VNodeChild`。data 为保留业务字段的归一化副本，不修改输入对象；未提供标签时显示值的文字。
显式传入 `options` 时替代默认插槽，包括 `[]`；不传时使用默认插槽。选项值限字符串、有限数字或布尔值；缺失/非法值及同类型重复值被忽略（保留第一项）。`false`、`0`、`''` 和 `'0'` 是不同选项。异步选项变更不反向修改模型。
CheckboxGroup 使用 `ChoiceValue[]`，`max` 只接受 number，请使用 `:max="2"`。

Example source: src/checkbox/__demos__/option-data.vue

```vue
<script setup lang="ts">
import { h, ref } from 'vue'

const value = ref<Array<string | number | boolean>>(['locked'])
const fields = { value: 'id', label: 'name', disabled: 'unavailable', readonly: 'locked' }
const options = ref([
  { id: false, name: '布尔 false' },
  { id: 0, name: '数字 0' },
  { id: '', name: '空字符串' },
  { id: 'locked', name: '只读选项', locked: true },
  { id: 'disabled', name: '禁用选项', unavailable: true },
])
const renderOptions = [
  { value: 'render', label: (_data: unknown, checked: boolean) => h('strong', checked ? '已选择' : '渲染函数标签') },
]
</script>

<template>
  <section class="option-demo">
    <p>字段映射与标签插槽；只读可聚焦，禁用不可操作。</p>
    <c-checkbox-group v-model="value" :options="options" :field-names="fields" orientation="vertical">
      <template #label="{ data, checked }">{{ data.label }} {{ checked ? '✓' : '' }}</template>
    </c-checkbox-group>
    <p>当前值：{{ JSON.stringify(value) }}</p>
    <c-button @click="value = []">清空</c-button>
    <p>标签也支持渲染函数；不传 options 时使用默认插槽，传入 [] 时保持空组。</p>
    <c-checkbox-group :options="renderOptions" />
  </section>
</template>

<style scoped>
.option-demo { display: flex; flex-direction: column; gap: 12px; }
.option-demo p { margin: 0; }
</style>
```

### 受控

通过`v-model` (`model-value`)属性控制是否选中

Example source: src/checkbox/__demos__/controlled-mode.vue

```vue
<template>
  <c-space wrap size="lg">
    <c-checkbox v-model="checked1">v-model</c-checkbox>
    <c-checkbox :model-value="true">binding value</c-checkbox>
    <c-checkbox :model-value="checked2">binding value2</c-checkbox>
    <c-checkbox :default-value="true">uncontrolled state</c-checkbox>
  </c-space>
  <div :style="{ marginTop: '20px' }">
    <c-button status="primary" @click="handleSetCheck">
      {{ checked2 ? "uncheck" : "check" }} value2
    </c-button>
  </div>
</template>
<script lang="ts">
import { defineComponent, ref } from "vue";
export default defineComponent({
  setup() {
    const checked1 = ref(false);
    const checked2 = ref(false);

    const handleSetCheck = () => {
      checked2.value = !checked2.value;
    };

    return {
      checked1,
      checked2,
      handleSetCheck,
    };
  },
});
</script>
```

## 选择与批量操作

### 限制可勾选数量

<!-- demo-config-notes:start -->

#### 本组配置对照

| 配置            | 作用                            | 相关示例                     |
| --------------- | ------------------------------- | ---------------------------- |
| `value`         | 数组/分组模式的选项标识         | 限制可勾选数量、全选         |
| `disabled`      | 是否禁用；未设置时继承表单/分组 | 限制可勾选数量、交互状态对比 |
| `indeterminate` | 是否为半选状态                  | 全选                         |
| `readonly`      | 是否只读；未设置时继承表单/分组 | 交互状态对比                 |
| `error`         | 错误态；未设置时继承表单/分组   | 交互状态对比                 |

<!-- demo-config-notes:end -->

通过设置`max`限制最多可被勾选的项目数。

Example source: src/checkbox/__demos__/max-checked.vue

```vue
<template>
  <c-space direction="column" size="lg">
    <c-checkbox-group :max="2" v-model="value1" :options="plainOptions" />
    <c-checkbox-group :max="2" :default-value="['1']">
      <c-checkbox value="1" disabled>Option 1</c-checkbox>
      <c-checkbox value="2">Option 2</c-checkbox>
      <c-checkbox value="3">Option 3</c-checkbox>
      <c-checkbox value="4">Option 4</c-checkbox>
    </c-checkbox-group>
  </c-space>
</template>
<script lang="ts">
import { defineComponent, ref } from 'vue'
export default defineComponent({
  setup() {
    const value1 = ref(['Plain 1'])
    const plainOptions = ['Plain 1', 'Plain 2', 'Plain 3', 'Plain 4']

    return {
      plainOptions,
      value1,
    }
  },
})
</script>
```

### 全选

在实现全选功能时，可以通过`indeterminate`属性展示半选效果。

Example source: src/checkbox/__demos__/checked-all-indeterminate.vue

```vue
<template>
  <c-space direction="column">
    <c-checkbox :model-value="checkedAll" :indeterminate="indeterminate" @change="handleChangeAll">Check All </c-checkbox>
    <c-checkbox-group v-model="data" @change="handleChange">
      <c-checkbox value="1">Option 1</c-checkbox>
      <c-checkbox value="2">Option 2</c-checkbox>
      <c-checkbox value="3">Option 3</c-checkbox>
    </c-checkbox-group>
  </c-space>
</template>
<script lang="ts">
import { defineComponent, ref } from 'vue'
export default defineComponent({
  setup() {
    const indeterminate = ref(false)
    const checkedAll = ref(false)
    const data = ref<string[]>([])

    const handleChangeAll = (value) => {
      indeterminate.value = false
      if (value) {
        checkedAll.value = true
        data.value = ['1', '2', '3']
      } else {
        checkedAll.value = false
        data.value = []
      }
    }

    const handleChange = (values) => {
      if (values.length === 3) {
        checkedAll.value = true
        indeterminate.value = false
      } else if (values.length === 0) {
        checkedAll.value = false
        indeterminate.value = false
      } else {
        checkedAll.value = false
        indeterminate.value = true
      }
    }

    return {
      indeterminate,
      checkedAll,
      data,
      handleChangeAll,
      handleChange,
    }
  },
})
</script>
```

### 分组批量方法

两端提供 `checkAll()` 和 `inverseAll()`，返回独立数组副本。仅操作已挂载且可编辑的子项，保留禁用、只读及未加载的已选值；重复值只要有一项被锁定，该值就不参与批量修改。
`checkAll` 保留原模型顺序，按当前 DOM 顺序追加未选值；`inverseAll` 先移除可编辑的已选值，再按 DOM 顺序加入此前未选值。新增选择遵守 `max`，不裁剪外部传入的超限值。
受控模式返回提议，需父级回写；拒绝的提议不保存。分组禁用/只读时只返回当前值副本。有实际变化才按 `update:model-value → change(value, undefined) → FormItem` 通知一次，无变化不发事件。
子项重排、挂载、卸载及 KeepAlive 激活/停用会同步更新候选；变更渲染子项后应等待 `nextTick` 再调用方法。

Example source: src/checkbox/__demos__/group-methods.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
import type { CheckboxGroupInstance } from '@cedar-design/ui'

const group = ref<CheckboxGroupInstance>()
const value = ref<Array<string | number | boolean>>(['remote', 'locked', 'a'])
const reverse = ref(false)
const proposal = ref<Array<string | number | boolean>>([])
const options = [
  { value: 'a', label: '任务 A' },
  { value: 'b', label: '任务 B' },
  { value: 'c', label: '任务 C' },
  { value: 'locked', label: '只读，保留选择', readonly: true },
  { value: 'disabled', label: '禁用，不参与操作', disabled: true },
]
</script>

<template>
  <section class="group-methods-demo">
    <p>最多选择 4 项（包含未加载的 remote）。全选/反选保留只读和未加载的已选值。</p>
    <c-checkbox-group ref="group" v-model="value" :options="reverse ? [...options].reverse() : options" :max="4" orientation="vertical" />
    <c-space wrap>
      <c-button @click="proposal = group?.checkAll() ?? []">全选</c-button>
      <c-button @click="proposal = group?.inverseAll() ?? []">反选</c-button>
      <c-button @click="reverse = !reverse">调整选项顺序</c-button>
    </c-space>
    <p>当前值：{{ JSON.stringify(value) }}</p>
    <p>方法返回值：{{ JSON.stringify(proposal) }}</p>
  </section>
</template>

<style scoped>
.group-methods-demo { display: flex; flex-direction: column; gap: 12px; }
.group-methods-demo p { margin: 0; }
</style>
```

### 交互状态对比

在同一实例上切换禁用、只读和错误状态后再操作控件，比较可编辑性和交互反馈。恢复开关位于目标控件外；错误外观本身不会执行校验。

<details>
<summary>配置说明与使用限制</summary>

#### 禁用状态

禁用复选框

#### 交互状态切换

适用于协议确认和独立勾选。调整禁用、只读、错误反馈，用相同数据观察变化。控制区始终可用，可以随时恢复编辑；错误外观本身不会触发表单校验。

</details>

Example source: src/checkbox/__demos__/state-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref(false);
const __demoState = __demoReactive({
  disabled: false,
  readonly: false,
  error: false,
});
</script>
<template>
  <c-space direction="column" :size="16">
    <c-space wrap>
      <c-checkbox v-model="__demoState['disabled']">disabled</c-checkbox>
      <c-checkbox v-model="__demoState['readonly']">readonly</c-checkbox>
      <c-checkbox v-model="__demoState['error']">error</c-checkbox>
    </c-space>
    <c-checkbox v-model="value" v-bind="__demoState">同意条款</c-checkbox>
  </c-space>
</template>
```

## 控件与插槽定制

### 原生控件与外观

<!-- demo-config-notes:start -->

#### 本组配置对照

| 配置            | 作用                            | 相关示例       |
| --------------- | ------------------------------- | -------------- |
| `name`          | 原生字段名，未设置时继承 Group  | 原生控件与外观 |
| `indeterminate` | 是否为半选状态                  | 原生控件与外观 |
| `aria-label`    | 无可见标签时的无障碍名称        | 原生控件与外观 |
| `default-value` | 非受控初始值                    | 原生控件与外观 |
| `readonly`      | 是否只读；未设置时继承表单/分组 | 原生控件与外观 |
| `disabled`      | 是否禁用；未设置时继承表单/分组 | 原生控件与外观 |

<!-- demo-config-notes:end -->

两端主体均独立复制为原生 checkbox + label。Tab 聚焦，空格/Enter 切换；只读可聚焦，禁用不可聚焦。半选通过 aria-checked="mixed" 表达，点击标签只激活一次。没有可见标签时设置 aria-label；name 传到原生输入，子项未设置时继承 Group。

icon-size 接受像素数字或 CSS 长度字符串，不是 ComponentSize 档位；默认图标 Cedar 为 14px、Maple 为 24px。实例颜色仅作用于普通状态，错误和禁用颜色优先。checkbox 插槽覆盖整个控件外观（也可在 Group 上统一设置），checked-icon、unchecked-icon、indeterminate-icon 仅替换对应图标。以上图标槽是装饰内容，不应放置另一个独立可聚焦控件。

Example source: src/checkbox/__demos__/native-control.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const value = ref(false)
const choices = ref(['read'])
</script>
<template>
  <div class="checkbox-native-demo">
    <p>按 Tab 聚焦，按空格或 Enter 切换。禁用项跳过，只读项可聚焦。</p>
    <c-checkbox v-model="value" name="agreement">接受协议：{{ value ? '已接受' : '未接受' }}</c-checkbox>
    <c-checkbox indeterminate aria-label="部分选中" />
    <c-checkbox :default-value="true" readonly>只读已选</c-checkbox>
    <c-checkbox disabled>禁用</c-checkbox>
    <c-checkbox error>错误状态</c-checkbox>
    <c-checkbox-group v-model="choices" name="permissions" aria-label="权限" :max="2" :options="[{ label: '读取', value: 'read' }, { label: '编辑', value: 'edit' }, { label: '管理', value: 'admin' }]" />
    <p>最多选择两项：{{ choices.join(', ') }}</p>
  </div>
</template>
<style scoped>
.checkbox-native-demo { display: flex; flex-direction: column; align-items: flex-start; gap: 12px; }
.checkbox-native-demo p { margin: 0; }
</style>
```

### 自定义复选框

使用`#checkbox`插槽自定义复选框的展示

Example source: src/checkbox/__demos__/checked-custom.vue

```vue
<template>
  <c-checkbox-group :default-value="['1']">
    <c-checkbox value="1">
      <template #checkbox="{ checked }">
        <c-tag :model-value="checked">This is a tag checkbox 1</c-tag>
      </template>
    </c-checkbox>
    <c-checkbox value="2">
      <template #checkbox="{ checked }">
        <c-tag :model-value="checked">This is a tag checkbox 2</c-tag>
      </template>
    </c-checkbox>
    <c-checkbox value="3">
      <template #checkbox="{ checked }">
        <c-tag :model-value="checked">This is a tag checkbox 3</c-tag>
      </template>
    </c-checkbox>
  </c-checkbox-group>

  <div :style="{ marginTop: '20px' }">
    <c-checkbox-group :default-value="[1]">
      <template v-for="item in 2" :key="item">
        <c-checkbox :value="item">
          <template #checkbox="{ checked }">
            <c-space wrap align="flex-start" class="custom-checkbox-card" :class="{ 'custom-checkbox-card-checked': checked }">
              <div class="custom-checkbox-card-mask">
                <div class="custom-checkbox-card-mask-dot" />
              </div>
              <div>
                <div class="custom-checkbox-card-title">Checkbox Card {{ item }}</div>
                <span>this is a text</span>
              </div>
            </c-space>
          </template>
        </c-checkbox>
      </template>
    </c-checkbox-group>
  </div>
</template>
<script lang="ts">
import { defineComponent } from 'vue'
export default defineComponent({
  })
</script>

<style scoped>
.custom-checkbox-card {
  padding: 10px 16px;
  border: 1px solid var(--color-border-2);
  border-radius: 4px;
  width: 250px;
  box-sizing: border-box;
}

.custom-checkbox-card-mask {
  height: 14px;
  width: 14px;
  display: inline-flex;
  align-items: center;
  justify-content: center;
  border-radius: 2px;
  border: 1px solid var(--color-border-2);
  box-sizing: border-box;
}

.custom-checkbox-card-mask-dot {
  width: 8px;
  height: 8px;
  border-radius: 2px;
}

.custom-checkbox-card-title {
  color: var(--color-text-1);
  font-size: 14px;
  font-weight: bold;
  margin-bottom: 8px;
}

.custom-checkbox-card:hover,
.custom-checkbox-card-checked,
.custom-checkbox-card:hover .custom-checkbox-card-mask,
.custom-checkbox-card-checked .custom-checkbox-card-mask {
  border-color: rgb(var(--primary-6));
}

.custom-checkbox-card-checked {
  background-color: var(--color-primary-light-1);
}

.custom-checkbox-card:hover .custom-checkbox-card-title,
.custom-checkbox-card-checked .custom-checkbox-card-title {
  color: rgb(var(--primary-6));
}

.custom-checkbox-card-checked .custom-checkbox-card-mask-dot {
  background-color: rgb(var(--primary-6));
}
</style>
```

### 自定义控件插槽

通过控件插槽替换外观，仍使用相同的值模型和键盘操作。

Example source: src/checkbox/__demos__/custom-control.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const checked = ref(true)
</script>
<template>
  <div class="checkbox-custom-demo">
    <c-checkbox v-model="checked" :icon-size="28" checked-color="#137547" unchecked-color="#656565">数字尺寸（px）与实例颜色</c-checkbox>
    <c-checkbox icon-size="1.5rem" :ripple="false">CSS 长度尺寸，无波纹</c-checkbox>
    <c-checkbox v-model="checked">
      <template #checked-icon><span class="checkbox-custom-icon" aria-hidden="true">✓</span></template>
      <template #unchecked-icon><span class="checkbox-custom-icon" aria-hidden="true">○</span></template>
      自定义图标，仍保留原生键盘与无障碍语义
    </c-checkbox>
    <c-checkbox-group :default-value="['a']" :options="[{ label: '方案 A', value: 'a' }, { label: '方案 B', value: 'b' }]">
      <template #checkbox="{ checked: selected }"><span class="checkbox-custom-icon">{{ selected ? '✓' : '○' }}</span></template>
    </c-checkbox-group>
  </div>
</template>
<style scoped>
.checkbox-custom-demo { display: flex; flex-direction: column; align-items: flex-start; gap: 12px; }
.checkbox-custom-icon { display: inline-flex; justify-content: center; align-items: center; width: 28px; height: 28px; border: 1px solid currentColor; border-radius: 4px; }
</style>
```

## 异步选项

### 异步选项

开启手动返回后，每次加载创建本地 Promise，可分别返回最早或最新任务验证两种乱序。示例业务加载器用版本保护忽略旧响应：旧结果不结束新加载、不清空选择、不释放 `max=2` 名额，也不增加用户变更次数。移除使在途结果失效，新加载仍按保留模型反显；停用或卸载会结清等待并取消定时器。此保护属于示例业务逻辑，不代表组件自动处理网络竞争；不访问外部接口。

选项载入、移除和外部值更新均不会反向触发值变化；未载入的已选值不会自动清理。示例使用 800ms 本地延迟模拟请求；加载中移除选项会取消待完成的加载，避免旧结果重新显示。已选 remote 占一个名额，再选设备 A 后达到 `max=2`，设备 B 将不可选；取消任一已选项会释放名额。外部超限值不会自动裁剪。

等待期间可用空格或 Enter 操作已有选项；同值选项重载后保留键盘焦点和最新选择。加载提示保持稳定节点，避免显隐导致分组重新挂载，取消已选项后仍可继续选择并释放名额。

Example source: src/checkbox/__demos__/async-options.vue

```vue
<script setup>
import { onDeactivated, onUnmounted, ref, shallowRef } from "vue";

const value = ref(["remote"]);
const options = ref([]);
const loading = ref(false);
let pendingTimer;
const manual = ref(false);
const waiting = shallowRef([]);
const applied = ref(0);
const ignored = ref(0);
const changeCount = ref(0);
let version = 0;
let sequence = 0;

function cancelPending() {
  version++;
  if (pendingTimer !== undefined) {
    clearTimeout(pendingTimer);
  }
  pendingTimer = undefined;
  loading.value = false;
}

function load() {
  cancelPending();
  loading.value = true;
  const ticket = version;
  const id = ++sequence;
  const complete = () => {
    if (ticket !== version) {
      ignored.value++;
      return;
    }
    applied.value = id;
    options.value = [
      { label: "异步设备", value: "remote" },
      { label: "设备 A", value: "a" },
      { label: "设备 B", value: "b" },
      { label: "停用设备", value: "locked", disabled: true },
    ];
    pendingTimer = undefined;
    loading.value = false;
  };
  if (manual.value) {
    new Promise((resolve) => {
      waiting.value = [...waiting.value, { id, resolve }];
    }).then(complete);
  } else {
    pendingTimer = setTimeout(complete, 800);
  }
}

function settle(latest) {
  const jobs = [...waiting.value];
  const job = latest ? jobs.pop() : jobs.shift();
  waiting.value = jobs;
  job?.resolve();
}

function cleanup() {
  cancelPending();
  const jobs = waiting.value;
  waiting.value = [];
  jobs.forEach((job) => job.resolve());
}

function remove() {
  cancelPending();
  options.value = [];
}

onDeactivated(cleanup);
onUnmounted(cleanup);
</script>

<template>
  <c-space class="checkbox-async-demo" direction="column">
    <p>业务值独立于当前选项，加载或移除选项不会清空已选值：{{ value }}</p>
    <c-checkbox v-model="manual" edit-mode="direct" @change="remove"
      >Manual responses / 手动返回</c-checkbox
    >
    <c-space wrap>
      <c-button size="sm" @click="load">加载选项</c-button>
      <c-button size="sm" @click="remove">移除选项</c-button>
      <c-button
        size="sm"
        :disabled="waiting.length === 0"
        @click="settle(false)"
        >返回最早加载</c-button
      >
      <c-button size="sm" :disabled="waiting.length === 0" @click="settle(true)"
        >返回最新加载</c-button
      >
    </c-space>
    <p aria-live="polite">
      {{
        loading
          ? "加载中，可在完成前移除选项以取消本次加载。"
          : "加载完成后保留当前选值和键盘焦点。"
      }}
    </p>
    <c-checkbox-group
      v-model="value"
      edit-mode="direct"
      :options="options"
      :max="2"
      @change="changeCount++"
    />
    <p>用户变更次数：{{ changeCount }}</p>
    <p role="status">
      Applied: {{ applied }} · Ignored: {{ ignored }} · Pending:
      {{ waiting.length }}
    </p>
  </c-space>
</template>
```

## API

### 空值识别与阅读空文案

`empty-values` 用于空值识别，`empty-value` 保留原清空输出；`empty-text` 仅在 `read-pretty` 空内容下展示，默认 `'-'`，字段 > FormItem > Form，自定义 read 插槽优先。显式配置 empty-values 后，内置 required 接入该策略，自定义校验仍收到原值。详见[统一说明](llms/zh-CN/guide/empty-values.md)。

| 参数         | 类型               | 缺省与范围                                            |
| ------------ | ------------------ | ----------------------------------------------------- |
| empty-values | readonly unknown[] | 字段 > FormItem > Form > 组件族默认；完整覆盖，不合并 |
| empty-text   | string             | 字段 > FormItem > Form > '-'；显式 '' 有效            |

以上是字段展示层 API；纯面板不因此新增阅读模式。Form 与 FormItem 提供继承配置。empty-value 的现有类型与默认输出仍按该组件原 API 执行。

`ChoiceValue = string | number | boolean`；`CheckboxModel = boolean | ChoiceValue[]`；`RadioModel = ChoiceValue | null`。

### Checkbox Props

| 属性                   | 说明                               | 类型                     | 默认值    |
| ---------------------- | ---------------------------------- | ------------------------ | --------- |
| model-value (v-model)  | 受控值                             | boolean \| ChoiceValue[] | undefined |
| default-value          | 非受控初始值                       | boolean \| ChoiceValue[] | false     |
| value                  | 数组/分组模式的选项标识            | string\|number\|boolean  | true      |
| disabled               | 是否禁用；未设置时继承表单/分组    | boolean                  | undefined |
| readonly               | 是否只读；未设置时继承表单/分组    | boolean                  | undefined |
| error                  | 错误态；未设置时继承表单/分组      | boolean                  | undefined |
| indeterminate          | 是否为半选状态                     | boolean                  | false     |
| checked-color          | 实例选中颜色；错误/禁用优先        | string                   | undefined |
| unchecked-color        | 实例未选中颜色；错误/禁用优先      | string                   | undefined |
| icon-size              | 数字为 px，字符串为 CSS 长度       | number \| string         | undefined |
| ripple                 | 是否启用波纹                       | boolean                  | true      |
| uninject-group-context | 脱离外层 CheckboxGroup，仍参与表单 | boolean                  | false     |
| name                   | 原生字段名，未设置时继承 Group     | string                   | undefined |
| aria-label             | 无可见标签时的无障碍名称           | string                   | undefined |

### Checkbox Events

| 事件名             | 说明             | 参数                                |
| ------------------ | ---------------- | ----------------------------------- |
| update:model-value | 提议新值         | value: CheckboxModel                |
| change             | 值变化           | value: CheckboxModel, event?: Event |
| click              | 点击；禁用不触发 | event: MouseEvent                   |
| focus              | 聚焦             | event: FocusEvent                   |
| blur               | 失焦             | event: FocusEvent                   |

### Checkbox Methods

| 方法   | 参数                   | 返回值 |
| ------ | ---------------------- | ------ |
| toggle | checked?: boolean      | void   |
| focus  | options?: FocusOptions | void   |
| blur   | -                      | void   |

### Checkbox Slots

| 插槽名             | 说明               | 参数                                                        |
| ------------------ | ------------------ | ----------------------------------------------------------- |
| checkbox           | 自定义完整控件外观 | checked: boolean, disabled: boolean, indeterminate: boolean |
| checked-icon       | 选中图标           | -                                                           |
| unchecked-icon     | 未选中图标         | -                                                           |
| indeterminate-icon | 半选图标           | -                                                           |
| default            | 标签               | checked: boolean                                            |

### CheckboxGroup Props

| 属性                  | 说明                                                        | 类型                                                                                                       | 默认值       |
| --------------------- | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ------------ |
| model-value (v-model) | 受控值                                                      | ChoiceValue[]                                                                                              | undefined    |
| default-value         | 非受控初始值                                                | ChoiceValue[]                                                                                              | []           |
| max                   | 最多可选数量                                                | number                                                                                                     | undefined    |
| options               | 选项；传入时替代默认插槽                                    | Array<ChoiceValue \| CheckboxOption \| Record<string, unknown>> / `(query, { signal }) => Array / Promise` | `undefined`  |
| orientation           | 复选组内选项的横纵排列，默认 horizontal；不表示文字阅读方向 | Orientation                                                                                                | 'horizontal' |
| disabled              | 是否禁用；未设置时继承表单/分组                             | boolean                                                                                                    | undefined    |
| readonly              | 是否只读；未设置时继承表单/分组                             | boolean                                                                                                    | undefined    |
| error                 | 错误态；未设置时继承表单/分组                               | boolean                                                                                                    | undefined    |
| field-names           | 选项字段映射                                                | ChoiceFieldNames                                                                                           | undefined    |
| name                  | 组内原生输入字段名                                          | string                                                                                                     | undefined    |
| aria-label            | 分组无障碍名称                                              | string                                                                                                     | undefined    |

### CheckboxGroup Methods

| 方法       | 参数 | 返回值        |
| ---------- | ---- | ------------- |
| checkAll   | -    | ChoiceValue[] |
| inverseAll | -    | ChoiceValue[] |

### CheckboxGroup Events

| 事件名             | 说明                        | 参数                                               |
| ------------------ | --------------------------- | -------------------------------------------------- |
| update:model-value | 提议新值                    | value: (string \| number \| boolean)[]             |
| change             | 值变化，只由 Group 通知一次 | value: (string \| number \| boolean)[], ev?: Event |

### CheckboxGroup Slots

| 插槽名   | 说明              | 参数                                   |
| -------- | ----------------- | -------------------------------------- |
| checkbox | 自定义复选框      | checked: boolean<br/>disabled: boolean |
| label    | checkbox 文案内容 | data: CheckboxOption, checked: boolean |

### CheckboxOption

| 字段          | 说明           | 类型                                                                 |
| ------------- | -------------- | -------------------------------------------------------------------- |
| value         | 选项标识       | ChoiceValue                                                          |
| label         | 标签或渲染函数 | VNodeChild \| (data: CheckboxOption, checked: boolean) => VNodeChild |
| disabled      | 禁用           | boolean                                                              |
| readonly      | 只读           | boolean                                                              |
| indeterminate | 仅展示半选状态 | boolean                                                              |

## 类型定义

组件导出以下类型定义

```ts
import type { CheckboxProps } from "@cedar-design/ui";
```

### ChoiceFieldNames

`{ label?: string; value?: string; disabled?: string; readonly?: string; indeterminate?: string }`

公开导出类型：`CheckboxOption`、`ChoiceFieldNames`。

公开方法类型：`CheckboxGroupMethods`；`CheckboxGroupInstance` 包含上述方法。

### 减少动态效果

内置 CSS 过渡遵循 `prefers-reduced-motion: reduce`。关闭过渡不改变最终显隐、选中／展开状态及事件语义；插槽内自定义动画由应用自行控制。

### 样式变量

| 变量名                                   | 默认值                                 |
| ---------------------------------------- | -------------------------------------- |
| `--c-checkbox-control-color`             | `var(--c-sys-color-content-secondary)` |
| `--c-checkbox-control-color-checked`     | `var(--c-sys-color-content-brand)`     |
| `--c-checkbox-mark-color`                | `var(--c-sys-color-surface-default)`   |
| `--c-checkbox-control-color-disabled`    | `var(--c-sys-color-content-disabled)`  |
| `--c-checkbox-control-color-error`       | `var(--c-sys-color-content-danger)`    |
| `--c-checkbox-control-size`              | `14px`                                 |
| `--c-checkbox-label-text-color`          | `var(--c-sys-color-content-primary)`   |
| `--c-checkbox-label-text-color-disabled` | `var(--c-sys-color-content-disabled)`  |
| `--c-checkbox-label-font-size`           | `var(--c-font-size-body-3)`            |
| `--c-checkbox-label-gap`                 | `var(--c-spacing-4)`                   |
| `--c-checkbox-action-padding`            | `5px`                                  |
| `--c-checkbox-group-gap`                 | `var(--c-spacing-7)`                   |
| `--c-checkbox-animation-duration`        | `var(--c-transition-duration-3)`       |

### Form 字段展示与确认

本组件支持 `edit-mode`，字段 > FormItem > Form 逐层继承；未指定时为 `direct`，保留原有交互。支持值：`direct / click / dblclick`。非 direct 编辑模式通过字段值入口打开编辑面板，并维护单份草稿；确认后才更新 v-model，取消、重置或启用 readPretty 时丢弃草稿。

Cedar 使用 edit-mode="click" / "dblclick" 在字段附近打开编辑浮层，Enter/F2 也可进入；取消/Escape 丢弃草稿，确认后提交。readPretty 为独立阅读属性，与 readonly、disabled 分开。

`before-commit(value, { previousValue, signal })` 可拦截弹层保存；FormItem 先校验候选值，失败保持编辑。`open / default-open / update:open` 控制编辑层。`#read="{ value, text }"` 可自定义阅读内容。集中示例见 Form 的“各类字段统一展示”。

`read-pretty` 为独立布尔属性，与 `readonly`、`disabled` 同级；字段 > FormItem > Form 继承，显式 `false` 覆盖父级。默认 `false`。纯阅读不显示编辑器。

`empty-value` 可显式设为 `null`（或 `() => null`），清空时原样提交 null；省略时保留组件原默认值。界面把 null 显示为空，不会把普通输入的空字符串自动转成 null。支持弹出编辑的字段中，清空先修改草稿，确认后提交，取消则保留原值。

候选属性 `options` 支持数组或 `(query, { signal }) => 数组/Promise`。加载、取消、过期结果隔离由组件内部处理，失败触发 load-error。单选/多选分组初始化以空字符串查询，搜索型字段在查询变化时调用；树形字段根数据与原有 load-more 子节点懒加载独立。

---

Document: llms/zh-CN/components/col.md

<!-- Source: src/col/README.md; locale: zh-CN; page: /components/col/ -->

# Col

24 栏 Flex 栅格。Row 管理间距与对齐，Col 管理列宽、偏移、排序与响应式配置。需要 CSS Grid 折叠与后缀时使用 Grid。

> **布局怎么选**
>
> - Grid + GridItem：适合表单分栏、卡片网格，需要统一列宽、跨列、响应式列数或折叠行与后缀时使用。
> - Row + Col：适合 24 栏 Flex 布局，需要水平/垂直对齐、控制换行、固定宽度与自适应宽度组合，或响应式排序时使用。Row 控制整行，Col 控制列宽、偏移和排序。
> - Space：适合按钮、标签、文字等简单排列，只需要间距、方向和对齐时使用；更自由的宽度分配可使用原生 Flex。

## 基础示例

### 列宽与偏移

Example source: src/col/__demos__/basic.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const span = ref(8)
const offset = ref(4)
</script>
<template><div>
  <div class="controls">Span<c-radio-group v-model="span"><c-radio v-for="value in [4, 8, 12]" :key="value" :value="value">{{ value }}</c-radio></c-radio-group></div>
  <div class="controls">Offset<c-radio-group v-model="offset"><c-radio v-for="value in [0, 4, 8]" :key="value" :value="value">{{ value }}</c-radio></c-radio-group></div>
  <c-row :gutter="12"><c-col :span="span" :offset="offset"><div class="cell">{{ span }} / +{{ offset }}</div></c-col><c-col :span="4"><div class="cell soft">4</div></c-col></c-row>
</div></template>

<style scoped>
.controls { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; }
.cell { box-sizing: border-box; padding: 12px; min-width: 0; border-radius: 4px; background: var(--c-color-primary); color: var(--c-color-white); text-align: center; overflow-wrap: anywhere; }
.soft { opacity: .7; }
</style>
```

## 布局与排列

### 弹性比例与固定宽度

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `flex` | 弹性比例、固定长度或 CSS flex 值 | 弹性比例与固定宽度 |
| `xs` | 响应式栏数或包含 span、offset、order 的对象 | 响应式对象与隐藏恢复 |
| `sm` | 响应式栏数或包含 span、offset、order 的对象 | 响应式对象与隐藏恢复 |
| `md` | 响应式栏数或包含 span、offset、order 的对象 | 响应式对象与隐藏恢复 |
| `span` | 占用栏数；0 隐藏 | 响应式对象与隐藏恢复 |
<!-- demo-config-notes:end -->

Example source: src/col/__demos__/flex.vue

```vue
<template><div>
  <c-row :gutter="12"><c-col :flex="1"><div class="cell">1</div></c-col><c-col :flex="2"><div class="cell soft">2</div></c-col></c-row>
  <c-row :gutter="12" :wrap="false"><c-col flex="100px"><div class="cell">100px</div></c-col><c-col flex="auto"><div class="cell soft">auto</div></c-col></c-row>
</div></template>

<style scoped>
.controls { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; }
.cell { box-sizing: border-box; padding: 12px; min-width: 0; border-radius: 4px; background: var(--c-color-primary); color: var(--c-color-white); text-align: center; overflow-wrap: anywhere; }
.soft { opacity: .7; }
</style>
```

### 响应式对象与隐藏恢复

Example source: src/col/__demos__/responsive.vue

```vue
<template><div>
  <p>xs → sm (576px) → md (768px). Hidden columns return at larger breakpoints.</p>
  <c-row :gutter="[12, 12]"><c-col :xs="24" :sm="12" :md="8"><div class="cell">24 / 12 / 8</div></c-col><c-col :xs="0" :sm="12" :md="8"><div class="cell soft">Hidden / 12 / 8</div></c-col><c-col :span="8" :xs="{ span: 20, offset: 4, order: 2 }" :md="{ span: 8, offset: 0, order: 0 }"><div class="cell">Reset offset / order</div></c-col></c-row>
</div></template>

<style scoped>
.controls { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; }
.cell { box-sizing: border-box; padding: 12px; min-width: 0; border-radius: 4px; background: var(--c-color-primary); color: var(--c-color-white); text-align: center; overflow-wrap: anywhere; }
.soft { opacity: .7; }
</style>
```

## 内容与展示

### 排序与零值恢复

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `span` | 占用栏数；0 隐藏 | 排序与零值恢复 |
| `order` | 排序，0 可恢复 | 排序与零值恢复 |
<!-- demo-config-notes:end -->

Example source: src/col/__demos__/order.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const reverse = ref(false)
</script>
<template><div><div class="controls"><c-switch v-model="reverse" aria-label="Reverse order" />Reverse order</div><c-row :gutter="12"><c-col v-for="i in 3" :key="i" :span="8" :order="reverse ? 3 - i : 0"><div class="cell">{{ i }}</div></c-col></c-row></div></template>

<style scoped>
.controls { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; }
.cell { box-sizing: border-box; padding: 12px; min-width: 0; border-radius: 4px; background: var(--c-color-primary); color: var(--c-color-white); text-align: center; overflow-wrap: anywhere; }
.soft { opacity: .7; }
</style>
```

## API

<!-- same-source-api:start -->
### Props

| 属性 | 说明 | Type | Default |
| --- | --- | --- | --- |
| span | 占用栏数；0 隐藏 | `number` | `24` |
| offset | 左侧偏移，0 可恢复 | `number` | `undefined` |
| order | 排序，0 可恢复 | `number` | `undefined` |
| xs | 响应式栏数或包含 span、offset、order 的对象 | `number / ColSizeDescriptor` | `undefined` |
| sm | 响应式栏数或包含 span、offset、order 的对象 | `number / ColSizeDescriptor` | `undefined` |
| md | 响应式栏数或包含 span、offset、order 的对象 | `number / ColSizeDescriptor` | `undefined` |
| lg | 响应式栏数或包含 span、offset、order 的对象 | `number / ColSizeDescriptor` | `undefined` |
| xl | 响应式栏数或包含 span、offset、order 的对象 | `number / ColSizeDescriptor` | `undefined` |
| xxl | 响应式栏数或包含 span、offset、order 的对象 | `number / ColSizeDescriptor` | `undefined` |
| flex | 弹性比例、固定长度或 CSS flex 值 | `number / string` | `undefined` |

### Events

| Event | Description |
| --- | --- |
| click | 原生 MouseEvent，每次点击一次 |

### Slots

| Slot | Description |
| --- | --- |
| default | 布局内容 |

### Methods

| Method | Description |
| --- | --- |
<!-- same-source-api:end -->

排序示例关闭倒序后，各列恢复 `order: 0`。响应式断点依据浏览器视口，而非 Demo 卡片宽度；仅加宽卡片不会触发断点。`span: 0` 隐藏列，匹配更大断点后可恢复。

## 响应式与可访问性

断点基于浏览器视口：xs 为基础值，sm ≥576、md ≥768、lg ≥992、xl ≥1200、xxl ≥1600px；从最大匹配断点向下取已配置值。SSR 首屏使用 xs，挂载后响应视口；Grid 折叠和动态排序在挂载后计算。组件为布局容器，不增加键盘快捷键；内容语义及可聚焦元素由调用者提供。没有公开方法和专用主题 Token。

## 导入

Grid 仅包含 Grid.Item；Row、Col 是独立组件，拥有独立源码、样式、菜单、文档和 Demo。已移除 Grid.Row/Grid.Col、Grid 入口的 Row/Col 转导出以及 GridRowInstance/GridColInstance。请从库根入口或独立 row/col 入口导入；安装 Grid 不再自动注册 Row/Col。

---

Document: llms/zh-CN/components/collapse.md

<!-- Source: src/collapse/README.md; locale: zh-CN; page: /components/collapse/ -->

# Collapse

可以折叠 / 展开的内容区域。

## 基础示例

### 基础用法

用于将复杂的内容区域分组和隐藏，可折叠或展开。默认可以展开多个面板。

Example source: src/collapse/__demos__/basic.vue

```vue
<template>
  <c-collapse :default-value="['1', 2]">
    <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="1">
      <div>Beijing Toutiao Technology Co., Ltd.</div>
    </c-collapse-item>
    <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." :name="2">
      <div>Beijing Toutiao Technology Co., Ltd.</div>
    </c-collapse-item>
    <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="3">
      <div>Beijing Toutiao Technology Co., Ltd.</div>
    </c-collapse-item>
  </c-collapse>
</template>
<script lang="ts" setup>
</script>
```

## 外观与状态

### 禁用

通过 `disabled` 禁用面板。

Example source: src/collapse/__demos__/disabled.vue

```vue
<template>
  <c-space direction="column" :style="{ width: '100%' }">
    <c-button @click="disabled = !disabled">
      {{ disabled ? 'Enable' : 'Disable' }}
    </c-button>
    <c-collapse :default-value="[1]">
      <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." :name="1" :disabled="disabled">
        <div>Beijing Toutiao Technology Co., Ltd.</div>
      </c-collapse-item>
      <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." :name="2" :disabled="disabled">
        <div>Beijing Toutiao Technology Co., Ltd.</div>
      </c-collapse-item>
    </c-collapse>
  </c-space>
</template>
<script lang="ts" setup>
import { ref } from 'vue'

const disabled = ref(false)
</script>
```

## 布局与排列

### 嵌套面板

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `default-value` | 非受控初始展开面板 | 嵌套面板、展开图标位置 |
| `destroy-on-hide` | 是否在隐藏时销毁内容 | 嵌套面板 |
| `offset` | 展开面板是否显示间距 | 展开间距 |
| `expand-icon-position` | 展开图标在标题区域的 left 或 right 位置，默认 left；不控制内容展开方向 | 展开图标位置 |
| `show-expand-icon` | 是否显示展开图标；未设置时由子项决定 | 展开图标位置 |
<!-- demo-config-notes:end -->

面板多层嵌套。

Example source: src/collapse/__demos__/nested.vue

```vue
<template>
  <c-collapse :default-value="['1', 2]" destroy-on-hide>
    <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="1">
      <c-collapse :default-value="['1.1']" destroy-on-hide>
        <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="1.1">
          <div>Beijing Toutiao Technology Co., Ltd.</div>
        </c-collapse-item>
        <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="1.2">
          <div>Beijing Toutiao Technology Co., Ltd.</div>
        </c-collapse-item>
      </c-collapse>
    </c-collapse-item>
    <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." :name="2">
      <div>Beijing Toutiao Technology Co., Ltd.</div>
    </c-collapse-item>
    <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="3">
      <div>Beijing Toutiao Technology Co., Ltd.</div>
    </c-collapse-item>
  </c-collapse>
</template>
<script lang="ts" setup>
</script>
```

### 展开间距

通过 `offset` 控制展开面板之间的间距。

Example source: src/collapse/__demos__/offset.vue

```vue
<template>
  <c-space direction="column" :style="{ width: '100%' }">
    <c-button @click="offset = !offset">
      {{ offset ? 'Hide offset' : 'Show offset' }}
    </c-button>
    <c-collapse v-model="activeNames" :offset="offset">
      <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="1">
        <div>Beijing Toutiao Technology Co., Ltd.</div>
      </c-collapse-item>
      <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="2">
        <div>Beijing Toutiao Technology Co., Ltd.</div>
      </c-collapse-item>
      <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="3">
        <div>Beijing Toutiao Technology Co., Ltd.</div>
      </c-collapse-item>
    </c-collapse>
  </c-space>
</template>
<script lang="ts" setup>
import { ref } from 'vue'

const offset = ref(true)
const activeNames = ref<(string | number)[]>(['1', '2'])
</script>
```

### 展开图标位置

通过 `expand-icon-position` 属性设置展开图标的位置。

Example source: src/collapse/__demos__/icon-position.vue

```vue
<template>
  <c-space direction="column" :style="{ width: '100%' }">
    <c-space>
      <c-button @click="position = position === 'right' ? 'left' : 'right'">
        {{ position === 'right' ? 'Icon left' : 'Icon right' }}
      </c-button>
      <c-button @click="hideIcon = !hideIcon">
        {{ hideIcon ? 'Show icon' : 'Hide icon' }}
      </c-button>
    </c-space>
    <c-collapse :default-value="['1']" :expand-icon-position="position" :show-expand-icon="!hideIcon">
      <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="1">
        <template #extra>
          <c-tag size="sm">city</c-tag>
        </template>
        <div>Beijing Toutiao Technology Co., Ltd.</div>
      </c-collapse-item>
      <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="2" disabled>
        <div>Beijing Toutiao Technology Co., Ltd.</div>
      </c-collapse-item>
      <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="3">
        <div>Beijing Toutiao Technology Co., Ltd.</div>
      </c-collapse-item>
    </c-collapse>
  </c-space>
</template>
<script lang="ts" setup>
import { ref } from 'vue'

const position = ref<'left' | 'right'>('left')
const hideIcon = ref(false)
</script>
```

## 内容与展示

### 手风琴模式

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `default-value` | 非受控初始展开面板 | 手风琴模式、边框与分隔线、展开图标 |
| `accordion` | 手风琴模式，同时最多展开一项 | 手风琴模式 |
| `bordered` | 是否显示边框 | 边框与分隔线 |
| `divider` | 是否显示面板分割线 | 边框与分隔线 |
| `destroy-on-hide` | 是否在隐藏时销毁内容 | 隐藏时销毁 |
<!-- demo-config-notes:end -->

通过 `accordion` 开启手风琴模式，同时只能打开一个面板。手风琴模式下 `modelValue` 仍为数组，最多包含一项。

Example source: src/collapse/__demos__/accordion.vue

```vue
<template>
  <c-collapse :default-value="[1]" accordion>
    <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="1">
      <div>Beijing Toutiao Technology Co., Ltd.</div>
    </c-collapse-item>
    <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="2">
      <div>Beijing Toutiao Technology Co., Ltd.</div>
    </c-collapse-item>
    <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="3">
      <div>Beijing Toutiao Technology Co., Ltd.</div>
    </c-collapse-item>
  </c-collapse>
</template>
<script lang="ts" setup>
</script>
```

### 边框与分隔线

比较外边框和面板间分隔线，分别展开面板观察两种装饰的边界。

<details>
<summary>配置说明与使用限制</summary>

#### 无边框模式

通过设置 `bordered="false"` 隐藏边框。

#### 分割线

通过 `divider` 控制面板之间的分割线。

</details>

Example source: src/collapse/__demos__/border-comparison.vue

```vue
<script setup lang="ts">
import { ref } from "vue"
import { proxyRefs as demoProxyRefs } from 'vue'

const scene2 = demoProxyRefs((() => {


const divider = ref(true)
return { divider }
})())
</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="border-less">
    <h4><span lang="zh-CN">无边框模式</span><span lang="en-US">border less</span></h4>
    <c-collapse :default-value="['1']" :bordered="false">
        <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="1">
          <div>Beijing Toutiao Technology Co., Ltd.</div>
        </c-collapse-item>
        <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="2" disabled>
          <div>Beijing Toutiao Technology Co., Ltd.</div>
        </c-collapse-item>
        <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="3">
          <div>Beijing Toutiao Technology Co., Ltd.</div>
        </c-collapse-item>
      </c-collapse>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="divider">
    <h4><span lang="zh-CN">分割线</span><span lang="en-US">divider</span></h4>
    <c-space direction="column" :style="{
      width: '100%'
    }">
        <c-button @click="scene2.divider = !scene2.divider">
          {{ scene2.divider ? 'Hide divider' : 'Show divider' }}
        </c-button>
        <c-collapse :default-value="[]" :divider="scene2.divider">
          <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="1">
            <div>Beijing Toutiao Technology Co., Ltd.</div>
          </c-collapse-item>
          <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="2">
            <div>Beijing Toutiao Technology Co., Ltd.</div>
          </c-collapse-item>
          <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="3">
            <div>Beijing Toutiao Technology Co., Ltd.</div>
          </c-collapse-item>
        </c-collapse>
      </c-space>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

### 额外节点

通过 `extra` 可以设置额外节点。点击 `extra` 区域不会触发展开。

Example source: src/collapse/__demos__/extra.vue

```vue
<template>
  <c-collapse>
    <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="1">
      <template #extra>Extra</template>
      <div>Beijing Toutiao Technology Co., Ltd.</div>
    </c-collapse-item>
    <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." :name="2">
      <template #extra>
        <c-button status="primary" size="sm">Action</c-button>
      </template>
      <div>Beijing Toutiao Technology Co., Ltd.</div>
    </c-collapse-item>
    <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="3">
      <template #extra>
        <c-tag size="sm">city</c-tag>
      </template>
      <div>Beijing Toutiao Technology Co., Ltd.</div>
    </c-collapse-item>
  </c-collapse>
</template>
<script lang="ts" setup>
</script>
```

### 展开图标

为展开项自定义展开图标。父级 `expand-icon` 插槽会下发给未自定义图标的子项。

Example source: src/collapse/__demos__/expand-icon.vue

```vue
<template>
  <c-collapse :default-value="['1', 2]">
    <template #expand-icon="{ expanded }">
      <span>{{ expanded ? '▼' : '▶' }}</span>
    </template>
    <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="1">
      <template #expand-icon="{ expanded }">
        <span>{{ expanded ? '^^' : 'vv' }}</span>
      </template>
      <div>Beijing Toutiao Technology Co., Ltd.</div>
    </c-collapse-item>
    <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." :name="2">
      <div>Beijing Toutiao Technology Co., Ltd.</div>
    </c-collapse-item>
    <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="3">
      <div>Beijing Toutiao Technology Co., Ltd.</div>
    </c-collapse-item>
  </c-collapse>
</template>
<script lang="ts" setup>
</script>
```

### 隐藏时销毁

通过设置 `destroy-on-hide` 可以让面板内容在隐藏时销毁。

Example source: src/collapse/__demos__/destroy.vue

```vue
<template>
  <c-collapse :default-value="['1', 2]" destroy-on-hide>
    <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="1">
      <div>Beijing Toutiao Technology Co., Ltd.</div>
    </c-collapse-item>
    <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." :name="2">
      <div>Beijing Toutiao Technology Co., Ltd.</div>
    </c-collapse-item>
    <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="3" :show-expand-icon="false">
      <div>Beijing Toutiao Technology Co., Ltd.</div>
    </c-collapse-item>
  </c-collapse>
</template>
<script lang="ts" setup>
</script>
```

## 自定义与插槽

### 自定义样式

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `default-value` | 非受控初始展开面板 | 自定义样式 |
| `bordered` | 是否显示边框 | 自定义样式 |
<!-- demo-config-notes:end -->

自定义面板样式。

Example source: src/collapse/__demos__/custom.vue

```vue
<template>
  <c-collapse :default-value="['1', 2]" :bordered="false">
    <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." :style="customStyle" name="1">
      <div>Beijing Toutiao Technology Co., Ltd.</div>
    </c-collapse-item>
    <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." :style="customStyle" :name="2">
      <div>Beijing Toutiao Technology Co., Ltd.</div>
    </c-collapse-item>
    <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." :style="customStyle" name="3">
      <div>Beijing Toutiao Technology Co., Ltd.</div>
    </c-collapse-item>
  </c-collapse>
</template>
<script lang="ts" setup>
const customStyle = {
  borderRadius: '6px',
  marginBottom: '12px',
  overflow: 'hidden',
}
</script>
```

## 交互与控制

### 切换全部

通过 `toggleAll` 批量展开 / 收起面板。手风琴模式下不可用。

Example source: src/collapse/__demos__/toggle-all.vue

```vue
<template>
  <c-space direction="column" :style="{ width: '100%' }">
    <c-space wrap>
      <c-button @click="toggleAll({ expand: 'inverse' })">Toggle all</c-button>
      <c-button @click="toggleAll({ expand: 'inverse', skipDisabled: true })">Toggle all (skip disabled)</c-button>
      <c-button @click="toggleAll({ expand: true })">Expand all</c-button>
      <c-button @click="toggleAll({ expand: true, skipDisabled: true })">Expand all (skip disabled)</c-button>
      <c-button @click="toggleAll({ expand: false })">Collapse all</c-button>
      <c-button @click="toggleAll({ expand: false, skipDisabled: true })">Collapse all (skip disabled)</c-button>
    </c-space>
    <c-collapse ref="collapseRef" v-model="activeNames">
      <c-collapse-item title="Panel 1" name="1">
        <div>Content 1</div>
      </c-collapse-item>
      <c-collapse-item title="Panel 2" name="2">
        <div>Content 2</div>
      </c-collapse-item>
      <c-collapse-item title="Panel 3" name="3" disabled>
        <div>Content 3</div>
      </c-collapse-item>
      <c-collapse-item title="Panel 4" name="4" disabled>
        <div>Content 4</div>
      </c-collapse-item>
    </c-collapse>
  </c-space>
</template>
<script lang="ts" setup>
import { ref } from 'vue'

const collapseRef = ref<{
  toggleAll: (options: { expand: boolean | 'inverse'; skipDisabled?: boolean }) => void
}>()
const activeNames = ref<(string | number)[]>(['2', '4'])

const toggleAll = (options: { expand: boolean | 'inverse'; skipDisabled?: boolean }) => {
  collapseRef.value?.toggleAll(options)
}
</script>
```

## 阅读方向

继承最近的 `dir="ltr|rtl"`，支持运行时切换与局部覆盖。标题文字与扩展内容继承阅读方向，展开状态不因切换方向改变。expand-icon-position 的 left/right 始终表示物理侧，不改为逻辑起止；自定义展开图形不额外镜像。

## API

主值使用普通 `v-model`：`modelValue` 表示展开面板的 name 数组，手风琴模式也使用数组。`defaultValue` 仅在创建时初始化非受控状态，之后修改不会重置当前值；初始化不触发 `update:modelValue`。提供 `modelValue` 时由父级控制，以受控值为准。

<!-- same-source-api:start -->
### Props

| 属性 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| model-value | 当前展开面板的 name，支持 v-model | `(string \| number)[]` | `—` |
| default-value | 非受控初始展开面板 | `(string \| number)[]` | `[]` |
| accordion | 手风琴模式，同时最多展开一项 | `boolean` | `false` |
| show-expand-icon | 是否显示展开图标；未设置时由子项决定 | `boolean` | `—` |
| expand-icon-position | 展开图标在标题区域的 left 或 right 位置，默认 left；不控制内容展开方向 | `'left' \| 'right'` | `'left'` |
| bordered | 是否显示边框 | `boolean` | `true` |
| divider | 是否显示面板分割线 | `boolean` | `true` |
| offset | 展开面板是否显示间距 | `boolean` | `false` |
| destroy-on-hide | 是否在隐藏时销毁内容 | `boolean` | `false` |

### Events

| Event | Description | Arguments |
| --- | --- | --- |
| update:model-value | 请求更新展开面板 | `(string \| number)[]` |
| change | 展开面板变化时触发 | `(string \| number)[]`, `Event` |

### Slots

| Slot | Description | Scope |
| --- | --- | --- |
| default | 面板列表 | `—` |

### Methods

| Method | Description |
| --- | --- |
| toggleAll | 开启或关闭所有面板（手风琴模式下无效） |

<!-- same-source-api:end -->

父级可通过 `expand-icon` 插槽下发默认展开图标，作用域为 `expanded`、`disabled`、`position`。该插槽由子项读取，不在根节点渲染。

#### CollapseToggleAllOptions

| 参数 | 描述 | 类型 | 默认值 |
| --- | --- | --- | --- |
| expand | `'inverse'` 切换全部；`boolean` 控制全部展开或收起 | `'inverse' \| boolean` | `—` |
| skipDisabled | 是否跳过禁用面板 | `boolean` | `false` |

### `<collapse-item>` Props

| 参数名 | 描述 | 类型 | 默认值 |
| --- | --- | --- | --- |
| name **(必填)** | 面板唯一标识，对应 `modelValue` 中的值 | `string \| number` | `—` |
| title | 面板的标题 | `string` | `—` |
| disabled | 是否禁用 | `boolean` | `false` |
| show-expand-icon | 是否显示展开图标 | `boolean` | `true` |
| destroy-on-hide | 是否在隐藏时销毁内容 | `boolean` | `false` |

### `<collapse-item>` Slots

| 插槽名 | 描述 | 参数 |
| --- | --- | --- |
| title | 面板的标题 | `—` |
| extra | 额外内容 | `—` |
| expand-icon | 展开图标 | expanded: `boolean`<br>disabled: `boolean`<br>position: `'left' \| 'right'` |
| default | 面板内容 | `—` |

### 类型定义

组件导出以下类型定义。`Collapse.Item` 与 `CollapseItem` 为同一组件。

```ts
import type { CollapseInstance, CollapseToggleAllOptions, ExpandIconPosition } from '@cedar-design/ui'
```

## 颜色变量

Collapse 的公开颜色变量使用 system 语义作为默认值，Cedar 与 Maple 保持一致：

| 变量 | 默认语义 |
| --- | --- |
| `--c-collapse-border-color` | `--c-sys-color-border-default` |
| `--c-collapse-title-bg` | `--c-sys-color-surface-default` |
| `--c-collapse-title-bg-active` | `--c-sys-color-surface-default` |
| `--c-collapse-title-bg-disabled` | `--c-sys-color-surface-default` |
| `--c-collapse-title-text-color` | `--c-sys-color-content-primary` |
| `--c-collapse-title-text-color-disabled` | `--c-sys-color-content-disabled` |
| `--c-collapse-content-text-color` | `--c-sys-color-content-primary` |
| `--c-collapse-content-text-color-disabled` | `--c-sys-color-content-disabled` |
| `--c-collapse-content-bg` | `--c-sys-color-surface-muted` |
| `--c-collapse-expand-icon` | `var(--c-sys-color-content-secondary)` |
| `--c-collapse-item-border-color` | `--c-sys-color-border-default` |

### 减少动态效果

内置 CSS 过渡遵循 `prefers-reduced-motion: reduce`。关闭过渡不改变最终显隐、选中／展开状态及事件语义；插槽内自定义动画由应用自行控制。

---

Document: llms/zh-CN/components/color-picker.md

<!-- Source: src/color-picker/README.md; locale: zh-CN; page: /components/color-picker/ -->

# ColorPicker

颜色选择**面板**（默认无触发器）。

表单字段请使用 [`Color`](llms/zh-CN/components/color.md)。

## 基础示例

### 基本用法

默认只渲染面板。

Example source: src/color-picker/__demos__/basic.vue

```vue
<template>
  <c-color-picker default-value="#00BEBE" />
</template>
```

## 外观与状态

### 禁用

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `default-value` | 默认值 | 禁用 |
| `disabled` | 禁用 | 禁用 |
| `hide-trigger` | 无触发器，仅面板 | 禁用 |
| `show-text` | 显示颜色值 | 禁用 |
<!-- demo-config-notes:end -->

Example source: src/color-picker/__demos__/disabled.vue

```vue
<template>
  <c-space>
    <c-color-picker defaultValue="#00BEBE" disabled :hide-trigger="false" />
    <c-color-picker defaultValue="#00BEBE" showText disabled :hide-trigger="false" />
  </c-space>
</template>
```

## 内容与展示

### 预设颜色和历史颜色

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `default-value` | 默认值 | 预设颜色和历史颜色 |
| `history-colors` | 历史颜色 | 预设颜色和历史颜色 |
| `show-history` | 显示历史颜色 | 预设颜色和历史颜色 |
| `show-preset` | 显示预设颜色 | 预设颜色和历史颜色 |
<!-- demo-config-notes:end -->

通过 `showPreset` 和 `showHistory` 开启预设颜色和历史颜色区域。

Example source: src/color-picker/__demos__/colors.vue

```vue
<template>
  <c-color-picker
    defaultValue="#00BEBE"
    :historyColors="history"
    showHistory
    showPreset
    @open-change="addHistory" />
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const history = ref(['#00BEBE'])
const addHistory = (visible, color) => {
  if (!visible) {
    const index = history.value.indexOf(color)
    if (index !== -1) {
      history.value.splice(index, 1)
    }
    history.value.unshift(color)
  }
}
</script>
```

## 数据与选项

### 颜色格式

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `default-value` | 默认值 | 颜色格式 |
| `format` | 颜色值格式 | 颜色格式 |
| `show-text` | 显示颜色值 | 颜色格式 |
| `hide-trigger` | 无触发器，仅面板 | 颜色格式 |
<!-- demo-config-notes:end -->

通过 `format` 设置颜色值的格式，支持 `hex` 和 `rgb`。

Example source: src/color-picker/__demos__/format.vue

```vue
<template>
  <c-space direction="column">
    <c-radio-group type="button" v-model="format">
      <c-radio v-for="item in formatList" :value="item">{{ item }}</c-radio>
    </c-radio-group>
    <c-color-picker defaultValue="#00BEBE" :format="format" showText :hide-trigger="false" />
  </c-space>
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const format = ref('hex')
const formatList = ['hex', 'rgb']
</script>
```

## API

### `<ColorPicker>` Props

| 参数名 | 描述 | 类型 | 默认值 |
| --- | --- | --- | --- |
| model-value **(v-model)** | 绑定值 | `string` | `-` |
| default-value | 默认值 | `string` | `-` |
| format | 颜色值格式 | `'hex' \| 'rgb'` | `-` |
| size | 尺寸 | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` |
| show-text | 显示颜色值 | `boolean` | `false` |
| show-history | 显示历史颜色 | `boolean` | `false` |
| show-preset | 显示预设颜色 | `boolean` | `false` |
| disabled | 禁用 | `boolean` | `false` |
| disabled-alpha | 禁用透明通道 | `boolean` | `false` |
| hide-trigger | 无触发器，仅面板 | `boolean` | `true` |
| history-colors | 历史颜色 | `string[]` | `-` |
| preset-colors | 预设颜色 | `string[]` | `-` |


### 透传配置的现有优先级（F07）

现有 triggerProps 在部分内部 Trigger 配置之后展开，嵌套 disabled 等字段目前可以覆盖内部传值。F07 兼容阶段保留该顺序和类型，不套用 AutoComplete 的托管字段规则；不新增安全子集承诺，也不自动禁止这些旧能力。

拖动监听绑定控件所属视图。KeepAlive 停用或卸载会结束当前手势并释放监听；重新激活后需重新开始手势，旧手势回调不能继续改值。

---

Document: llms/zh-CN/components/color.md

<!-- Source: src/color/README.md; locale: zh-CN; page: /components/color/ -->

# Color

表单颜色字段（带触发器）。内部使用 `ColorPicker`。

纯面板请使用 [`ColorPicker`](llms/zh-CN/components/color-picker.md)（默认无触发器）。设计 Token 色板见 [颜色 Color](llms/zh-CN/components/style/color.md)。

## 基础示例

### 基本用法

Example source: src/color/__demos__/basic.vue

```vue
<template>
  <c-color v-model="value" show-text />
</template>

<script setup>
import { ref } from 'vue'

const value = ref('#00BEBE')
</script>
```

## 外观与状态

### 尺寸

<!-- demo-config-notes:start -->

#### 本组配置对照

| 配置        | 作用       | 相关示例 |
| ----------- | ---------- | -------- |
| `size`      | 尺寸       | 尺寸     |
| `show-text` | 显示颜色值 | 尺寸     |

<!-- demo-config-notes:end -->

Example source: src/color/__demos__/size.vue

```vue
<template>
  <c-space>
    <c-color v-model="value" size="xs" />
    <c-color v-model="value" size="sm" />
    <c-color v-model="value" size="md" show-text />
    <c-color v-model="value" size="lg" show-text />
  </c-space>
</template>

<script setup>
import { ref } from 'vue'

const value = ref('#165DFF')
</script>
```

## API

### 空值识别与阅读空文案

`empty-values` 用于空值识别，`empty-value` 保留原清空输出；`empty-text` 仅在 `read-pretty` 空内容下展示，默认 `'-'`，字段 > FormItem > Form，自定义 read 插槽优先。显式配置 empty-values 后，内置 required 接入该策略，自定义校验仍收到原值。详见[统一说明](llms/zh-CN/guide/empty-values.md)。

| 参数         | 类型               | 缺省与范围                                            |
| ------------ | ------------------ | ----------------------------------------------------- |
| empty-values | readonly unknown[] | 字段 > FormItem > Form > 组件族默认；完整覆盖，不合并 |
| empty-text   | string             | 字段 > FormItem > Form > '-'；显式 '' 有效            |

以上是字段展示层 API；纯面板不因此新增阅读模式。Form 与 FormItem 提供继承配置。empty-value 的现有类型与默认输出仍按该组件原 API 执行。

### Props

| 参数                 | 说明               | 类型                         | 默认值  |
| -------------------- | ------------------ | ---------------------------- | ------- |
| `model-value`        | 绑定值             | `string`                     | `-`     |
| `format`             | 颜色格式           | `hex \| rgb`                 | `-`     |
| `size`               | 尺寸               | `xs \| sm \| md \| lg \| xl` | `md`    |
| `show-text`          | 显示颜色值         | `boolean`                    | `false` |
| `show-history`       | 显示历史颜色       | `boolean`                    | `false` |
| `show-preset`        | 显示预设颜色       | `boolean`                    | `false` |
| `disabled`           | 禁用               | `boolean`                    | `false` |
| `disabled-alpha`     | 禁用透明通道       | `boolean`                    | `false` |
| `color-picker-props` | 透传给 ColorPicker | `object`                     | `{}`    |

### Form 字段展示与确认

本组件支持 `edit-mode`，字段 > FormItem > Form 逐层继承；未指定时为 `direct`，保留原有交互。支持值：`direct / click / dblclick`。非 direct 编辑模式通过字段值入口打开编辑面板，并维护单份草稿；确认后才更新 v-model，取消、重置或启用 readPretty 时丢弃草稿。

Cedar 使用 edit-mode="click" / "dblclick" 在字段附近打开编辑浮层，Enter/F2 也可进入；取消/Escape 丢弃草稿，确认后提交。readPretty 为独立阅读属性，与 readonly、disabled 分开。

`before-commit(value, { previousValue, signal })` 可拦截弹层保存；FormItem 先校验候选值，失败保持编辑。`open / default-open / update:open` 控制编辑层。`#read="{ value, text }"` 可自定义阅读内容。集中示例见 Form 的“各类字段统一展示”。

`read-pretty` 为独立布尔属性，与 `readonly`、`disabled` 同级；字段 > FormItem > Form 继承，显式 `false` 覆盖父级。默认 `false`。纯阅读不显示编辑器。

拖动监听绑定控件所属视图。KeepAlive 停用或卸载会结束当前手势并释放监听；重新激活后需重新开始手势，旧手势回调不能继续改值。

---

Document: llms/zh-CN/components/config-provider.md

<!-- Source: src/config-provider/README.md; locale: zh-CN; page: /components/config-provider/ -->

# ConfigProvider

在应用的最外层进行配置，一次设置，全局生效。一般用于设置国际化语言等功能。

## 基础示例

### 基础用法

通过 Provider 为子组件设置统一尺寸，点击按钮在 sm / lg 之间切换；内部 Input 和 Button 无需重复声明 size。

Example source: src/config-provider/__demos__/basic.vue

```vue
<template>
  <c-space direction="column">
    <c-button @click="large = !large">切换尺寸</c-button>
    <c-config-provider :size="large ? 'lg' : 'sm'">
      <c-space>
        <c-input placeholder="继承全局尺寸" />
        <c-button>继承尺寸</c-button>
      </c-space>
    </c-config-provider>
    <p role="status">当前尺寸：{{ large ? 'lg' : 'sm' }}</p>
  </c-space>
</template>
<script lang="ts" setup>
import { ref } from 'vue'
const large = ref(false)
</script>
```

## API

### ConfigProvider Props

| 属性 | 说明     | 类型   | 默认值 |
| ---- | -------- | ------ | ------ |
| dir | 阅读方向；省略时继承来源作用域。物理 left/right 方位保持原意。 | `ReadingDirection` (`ltr` / `rtl`) | — |
| type | 参数类型 | string | -      |

### ConfigProvider Events

| 事件名 | 说明           | 参数                          |
| ------ | -------------- | ----------------------------- |
| click  | 点击触发的事件 | `(event: MouseEvent) => void` |

### ConfigProvider Slots

| 插槽名  | 说明           |
| ------- | -------------- |
| default | 自定义默认内容 |

## 类型定义

组件导出以下类型定义

```ts
import type { ConfigProviderProps } from '@cedar-design/ui'
```


## 阅读方向

使用 `<c-config-provider dir="rtl">` 设置局部 RTL；省略 dir 时继承父级，可嵌套 `dir="ltr"` 切回 LTR。普通原生 DOM dir 容器同样有效。Provider 使用 display: contents 的 div 承载方向，不增加布局盒子；请放在允许 div 的 HTML 上下文中。它不会修改整个 document。发布前将原 rtl 布尔配置统一收敛为 dir；明确表示物理左右的方位 API 保持原意。

---

Document: llms/zh-CN/components/count-to.md

<!-- Source: src/count-to/README.md; locale: zh-CN; page: /components/count-to/ -->

# CountTo 数字动画

展示起始数值到目标数值的数字动画。

## 基础示例

### 基础用法

通过 `from` 和 `to` 指定起始值与目标值。

Example source: src/count-to/__demos__/basic.vue

```vue
<template>
  <c-count-to :to="123456" />
</template>
```

## 内容与展示

### 精度、时长与动画曲线

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `to` | 目标值 | 精度、时长与动画曲线 |
| `precision` | 小数精度 | 精度、时长与动画曲线 |
| `duration` | 动画持续时间（毫秒） | 精度、时长与动画曲线 |
| `timing-function` | 动画缓动函数 | 精度、时长与动画曲线 |
<!-- demo-config-notes:end -->

比较小数精度对最终文本的影响，以及时长和缓动曲线对数字变化过程的影响；手动启动、暂停另行展示。

<details>
<summary>配置说明与使用限制</summary>

#### 精度

通过 `precision` 控制小数位数。

#### 自定义时长

通过 `duration` 指定动画时长（毫秒）。

#### 自定义动画曲线

通过 `timing-function` 指定缓动函数。

</details>

Example source: src/count-to/__demos__/number-format-comparison.vue

```vue
<script setup lang="ts">
import { proxyRefs as demoProxyRefs } from 'vue'

const scene3 = demoProxyRefs((() => {

const easeOutCubic = (v: number) => 1 - Math.pow(1 - v, 3)
return { easeOutCubic }
})())
</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="precision">
    <h4><span lang="zh-CN">精度</span><span lang="en-US">precision</span></h4>
    <c-count-to :to="123456" :precision="2" />
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="duration">
    <h4><span lang="zh-CN">自定义时长</span><span lang="en-US">duration</span></h4>
    <c-count-to :to="123456" :duration="10000" />
  </section>

  <section class="demo-comparison-case demo-comparison-case--3" data-comparison-scene="timing-function">
    <h4><span lang="zh-CN">自定义动画曲线</span><span lang="en-US">timing function</span></h4>
    <c-count-to :to="123456" :timing-function="scene3.easeOutCubic" />
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

## 自定义与插槽

### 自定义样式

通过默认插槽自定义展示内容，插槽参数为当前数值。

Example source: src/count-to/__demos__/custom.vue

```vue
<template>
  <c-count-to :to="123456">
    <template #default="{ value }">
      {{ value.toLocaleString() }}
    </template>
  </c-count-to>
</template>
```

## 交互与控制

### 手动控制

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `to` | 目标值 | 手动控制 |
| `auto-start` | 是否自动开始播放动画 | 手动控制 |
<!-- demo-config-notes:end -->

设置 `auto-start` 为 `false`，通过 `start`、`pause`、`reset` 手动控制动画。

Example source: src/count-to/__demos__/manual.vue

```vue
<template>
  <c-space direction="column">
    <c-count-to ref="countToRef" :to="123456" :auto-start="false" />
    <c-space>
      <c-button status="primary" @click="countToRef?.start()">开始</c-button>
      <c-button @click="countToRef?.pause()">暂停</c-button>
      <c-button @click="countToRef?.reset()">重置</c-button>
    </c-space>
  </c-space>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import type { CountToInstance } from '../index'

const countToRef = ref<CountToInstance>()
</script>
```

## API

### CountTo Props

| 属性              | 说明                     | 类型                     | 默认值   |
| ----------------- | ------------------------ | ------------------------ | -------- |
| from              | 起始值                   | _number \| string_       | `0`      |
| to                | 目标值                   | _number \| string_       | `0`      |
| duration          | 动画持续时间（毫秒）     | _number \| string_       | `2000`   |
| precision         | 小数精度                 | _number \| string_       | `0`      |
| auto-start        | 是否自动开始播放动画     | _boolean_                | `true`   |
| timing-function   | 动画缓动函数             | _(v: number) => number_  | `-`      |

### CountTo Events

| 事件名 | 说明           | 回调参数 |
| ------ | -------------- | -------- |
| end    | 动画结束时触发 | `-`      |

### CountTo Slots

| 插槽名  | 说明       | 参数              |
| ------- | ---------- | ----------------- |
| default | 自定义内容 | `value: number`   |

### CountTo Methods

| 方法名 | 说明                                                             | 参数 | 返回值 |
| ------ | ---------------------------------------------------------------- | ---- | ------ |
| start  | 开始动画                                                         | `-`  | `-`    |
| pause  | 暂停动画                                                         | `-`  | `-`    |
| reset  | 重置动画；若 `auto-start` 为 `true`，重置后会自动开始播放        | `-`  | `-`    |

## 类型定义

组件导出以下类型定义

```ts
import type { CountToProps, CountToInstance } from '@cedar-design/ui'
```

### 样式变量

| 变量名                        | 默认值                     |
| ----------------------------- | -------------------------- |
| `--c-count-to-text-color`     | `var(--c-sys-color-content-primary)` |
| `--c-count-to-text-font-size` | `var(--c-font-size-lg)`    |

## 同源实现与平台边界

两端各自保存完整源码，不引用公共核心，不共享组件实例或响应式状态；修改时同步维护两份实现。主体、Props、关键样式及配对测试纳入只读源码一致性检查，主题 token 和安装入口各自维护。

动画在卸载及 KeepAlive 停用时暂停，重新激活后恢复；各实例的数值和动画状态独立。

---

Document: llms/zh-CN/components/countdown.md

<!-- Source: src/countdown/README.md; locale: zh-CN; page: /components/countdown/ -->

# Countdown 倒计时

### Countdown 业务时钟与停用边界

Countdown 的 RAF 刷新业务剩余时间，不是视觉插值；CSS duration／减少动效不能改变业务计时。暂停与 KeepAlive 停用冻结剩余时间，重新激活按冻结值续跑，不把停用期间计入消耗。停用时更新 time／reset 可更新剩余数据及 change 通知，但不申请 RAF；auto-start 的启动延后到激活，手动 pause 取消待恢复。停用期间直接 start 被忽略，卸载后的 start／reset 不再通知或调度。

实时展示剩余时长，支持暂停、重置与毫秒精度。

`time` 为剩余时长（毫秒）。若要对准某个时刻，传入 `deadline - Date.now()`。

## 基础示例

### 基础用法

Example source: src/countdown/__demos__/basic.vue

```vue
<template>
  <c-countdown :time="2 * 60 * 60 * 1000" />
</template>
```

## 内容与展示

### 时间格式与自定义内容

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `time` | 倒计时时长（毫秒） | 时间格式与自定义内容、嵌入 Statistic |
| `format` | 展示格式 | 时间格式与自定义内容、嵌入 Statistic |
<!-- demo-config-notes:end -->

比较单位格式、毫秒显示和自定义时间片段。使用各示例中的时间字段检查最终文本，而非把精度与启动控制混在一起。

<details>
<summary>配置说明与使用限制</summary>

#### 显示毫秒

通过 `S` / `SS` / `SSS` 展示毫秒。

#### 自定义格式

`format` 占位符为 `DD` / `HH` / `mm` / `ss` / `S`（`SS` / `SSS`）。未出现的高位会累加到下一级。

#### 自定义样式

默认插槽参数为 `timeData`，可按天、时、分、秒分别渲染。

</details>

Example source: src/countdown/__demos__/format-comparison.vue

```vue
<script setup lang="ts">


</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="format">
    <h4><span lang="zh-CN">自定义格式</span><span lang="en-US">format</span></h4>
    <c-countdown :time="4 * 24 * 60 * 60 * 1000" format="DD 天 HH 时 mm 分 ss 秒" />
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="millisecond">
    <h4><span lang="zh-CN">显示毫秒</span><span lang="en-US">millisecond</span></h4>
    <c-countdown :time="2 * 60 * 60 * 1000" format="HH:mm:ss.SSS" />
  </section>

  <section class="demo-comparison-case demo-comparison-case--3" data-comparison-scene="custom">
    <h4><span lang="zh-CN">自定义样式</span><span lang="en-US">custom</span></h4>
    <c-countdown :time="108000000">
        <template #default="{ hours, minutes, seconds }">
          <span class="countdown-block">{{ hours }}</span>
          <span class="countdown-colon">:</span>
          <span class="countdown-block">{{ minutes }}</span>
          <span class="countdown-colon">:</span>
          <span class="countdown-block">{{ seconds }}</span>
        </template>
      </c-countdown>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }
.demo-comparison-case--3 {

.countdown-block {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  width: 36px;
  height: 36px;
  color: var(--c-color-white);
  background: var(--c-color-primary-6);
  border-radius: 8px;
}

.countdown-colon {
  margin: 0 6px;
  font-weight: 500;
}

}
</style>
```

### 嵌入 Statistic

未传入 `value` 时，Statistic 可用默认插槽嵌入 Countdown。

Example source: src/countdown/__demos__/statistic.vue

```vue
<template>
  <c-space size="xl" wrap>
    <c-statistic title="Countdown">
      <c-countdown :time="2 * 60 * 60 * 1000" />
    </c-statistic>
    <c-statistic title="Campaign">
      <c-countdown :time="4 * 24 * 60 * 60 * 1000" format="DD 天 HH 时 mm 分 ss 秒" />
    </c-statistic>
  </c-space>
</template>
```

## 交互与控制

### 手动控制

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `time` | 倒计时时长（毫秒） | 手动控制 |
| `auto-start` | 是否自动开始倒计时 | 手动控制 |
| `format` | 展示格式 | 手动控制 |
<!-- demo-config-notes:end -->

设置 `auto-start` 为 `false`，通过 `start`、`pause`、`reset` 控制。倒计时结束时触发 `end`。

Example source: src/countdown/__demos__/manual.vue

```vue
<template>
  <c-space direction="column" align="flex-start">
    <c-countdown
      ref="countdownRef"
      :time="5000"
      :auto-start="false"
      format="ss.SSS"
      @end="handleEnd"
    />
    <c-space>
      <c-button status="primary" @click="countdownRef?.start()">开始</c-button>
      <c-button @click="countdownRef?.pause()">暂停</c-button>
      <c-button @click="countdownRef?.reset()">重置</c-button>
    </c-space>
  </c-space>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import { Message } from '@cedar-design/ui'
import type { CountdownInstance } from '../index'

const countdownRef = ref<CountdownInstance>()

const handleEnd = () => {
  Message.info('end!')
}
</script>
```

## API

### Countdown Props

| 属性          | 说明                                       | 类型                 | 默认值       |
| ------------- | ------------------------------------------ | -------------------- | ------------ |
| `time`        | 倒计时时长（毫秒）                         | `number \| string`   | `0`          |
| `format`      | 展示格式                                   | `string`             | `'HH:mm:ss'` |
| `auto-start`  | 是否自动开始倒计时                         | `boolean`            | `true`       |

### format 占位符

| 格式  | 说明          |
| ----- | ------------- |
| `DD`  | 天数          |
| `HH`  | 小时          |
| `mm`  | 分钟          |
| `ss`  | 秒            |
| `S`   | 毫秒（1 位）  |
| `SS`  | 毫秒（2 位）  |
| `SSS` | 毫秒（3 位）  |

### Countdown Events

| 事件名   | 说明             | 参数                  |
| -------- | ---------------- | --------------------- |
| `change` | 倒计时变化时触发 | `timeData: TimeData`  |
| `end`    | 倒计时结束时触发 | `-`                   |

### Countdown Slots

| 插槽名    | 说明       | 参数                  |
| --------- | ---------- | --------------------- |
| `default` | 自定义内容 | `timeData: TimeData`  |

### TimeData

| 名称           | 说明     | 类型     |
| -------------- | -------- | -------- |
| `days`         | 剩余天数 | `number` |
| `hours`        | 剩余小时 | `number` |
| `minutes`      | 剩余分钟 | `number` |
| `seconds`      | 剩余秒   | `number` |
| `milliseconds` | 剩余毫秒 | `number` |

### Countdown Methods

| 方法名  | 说明                                                              | 参数 | 返回值 |
| ------- | ----------------------------------------------------------------- | ---- | ------ |
| `start` | 开始倒计时                                                        | `-`  | `-`    |
| `pause` | 暂停倒计时                                                        | `-`  | `-`    |
| `reset` | 重置倒计时；若 `auto-start` 为 `true`，重置后会自动开始           | `-`  | `-`    |

## 类型定义

组件导出以下类型定义

```ts
import type { CountdownProps, CountdownInstance, TimeData } from '@cedar-design/ui'
```

### 样式变量

| 变量名                          | 默认值                     |
| ------------------------------- | -------------------------- |
| `--c-countdown-text-color`      | `var(--c-sys-color-content-primary)` |
| `--c-countdown-text-font-size`  | `var(--c-font-size-lg)`    |

## 同源实现与平台边界

两端各自保存完整源码，不引用公共核心，不共享组件实例或响应式状态；修改时同步维护两份实现。主体、Props、关键样式及配对测试纳入只读源码一致性检查，主题 token 和安装入口各自维护。

SSR 输出初始格式化时间。暂停时修改 format 会更新显示；结束事件每轮只触发一次，reset 后可开始新一轮；卸载清理动画帧。

---

Document: llms/zh-CN/components/date-picker.md

<!-- Source: src/date/picker/README.md; locale: zh-CN; page: /components/date-picker/ -->

# DatePicker

日期选择**面板**（默认无触发器）。通过 `type` 切换年/月/周/日/季度。

### 单值快捷预览等待（2026-10-16）

离开快捷项后的100ms为悬停交互宽限，不是CSS动画完成时长；不提交模型。新预览、关闭、禁用、只读、关闭快捷预览、模型替换、停用／卸载使旧等待失效；已取消／已消费回调不能清掉新预览。重新激活只接受新hover，不恢复旧等待。保留100ms默认值与公开API，无新CSS Token。

表单字段请使用 [`Date`](llms/zh-CN/components/date.md)；日期范围字段请使用 [`DateRange`](llms/zh-CN/components/date-range.md)；范围面板请使用 [`DateRangePicker`](components/date-range-picker)。

根入口和 date 子路径均导出 DatePicker、DatePickerProps、DatePickerInstance、DatePickerType、DatePickerOptions、DatePickerEmits。面板可以单独 app.use 安装，也可使用 Date.Picker。Options 只允许展示配置，不含模型、格式、边界和禁用规则。没有独立的 date-picker/date-range-picker npm 子路径。

两端共同支持 abbreviation；日期语言使用全局 Locale。移动端 presentation、multiple/range、触摸手势及面板外观为真实展示差异，不把差集机械补成空 API。

## 基础示例

### 基本用法

默认只渲染面板。

Example source: src/date/picker/__demos__/basic.vue

```vue
<template>
  <c-date-picker default-value="2019-06-03" />
</template>
```

## 日期视图与展示

### 选择类型

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `type` | 面板类型 | 选择类型、月份标签、日期语言的实例隔离 |
| `disable-confirm` | 选择后立即提交 | 月份标签、窄屏与组合面板 |
| `day-start-of-week` | 每周第一天（仅日历），整数 0～6 | 日期语言的实例隔离 |
| `show-time` | 选择时间 | 窄屏与组合面板 |
<!-- demo-config-notes:end -->

通过 `type` 切换面板类型。

Example source: src/date/picker/__demos__/mode.vue

```vue
<template>
  <c-space direction="column" fill>
    <c-date-picker type="week" />
    <c-date-picker type="month" />
    <c-date-picker type="year" />
    <c-date-picker type="quarter" />
  </c-space>
</template>
```

### 月份标签

`abbreviation`（boolean，默认 `true`）控制日历月份网格的缩写；`false` 使用当前 Locale 的完整月份名。运行时修改立即生效，不改变值，也不触发选择事件。此开关不影响星期标签、标题、滚轮列或值格式。范围日历以顶层选项为准，嵌套日历参数不能覆盖。

Example source: src/date/picker/__demos__/month-labels.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const abbreviation = ref(true)
</script>

<template>
  <c-checkbox v-model="abbreviation">月份缩写</c-checkbox>
  <c-date-picker type="month" picker-value="2025-01" :abbreviation="abbreviation" :disable-confirm="false" />
  <c-date-range-picker type="month" :abbreviation="abbreviation" />
</template>
```

### 语言与嵌套日历参数

日期标签、标题和动作接入各库的全局 Locale 与既有 Provider。Cedar 删除日期组件级 `locale`，不保留覆盖字典或兼容别名。切换语言不会选择或提交日期。

### 日期语言的实例隔离

日期所有者读取本库全局 Locale/Provider，周起始日由各实例 `day-start-of-week` 管理。不切换宿主 Dayjs 默认语言，也不覆盖宿主基础语言配置；只在各库命名空间下注册日期语言元数据，组件实例与源码不跨库共享。

`value-format` 是稳定英文日期协议（包括月份名称 token），`format` 的显示及手输文本使用界面语言。切换语言不会改写模型，也不会令英文月份名称模型失效。默认数字协议、Date 对象、时间戳不变。中文核心语言与 Maple 内置语言数据已接入；其他日期格式优先使用已注册 Dayjs 语言数据，未加载的语言安全回退英文。

周号和周比较不再依赖全局周起始设置，跨年同周号不能被误判成同一周。两个不同周起始实例的挂载、更新和卸载互不影响。

Example source: src/date/picker/__demos__/locale-isolation.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const first = ref('2021-01-03')
const second = ref('2021-01-03')
const monday = ref(true)
const monthModel = ref('2025 January 15')
</script>

<template>
  <p>两个实例独立管理周起始日。可切换顶部语言，模型不随展示语言改变。</p>
  <c-date v-model="first" type="week" :date-picker-props="{ dayStartOfWeek: 0 }" />
  <c-date v-model="second" type="week" :date-picker-props="{ dayStartOfWeek: monday ? 1 : 2 }" />
  <c-checkbox v-model="monday">第二个实例周一起始（关闭为周二）</c-checkbox>
  <c-date-picker type="week" v-model="first" picker-value="2021-01-01" :day-start-of-week="0" />
  <c-date-picker type="week" v-model="second" picker-value="2021-01-01" :day-start-of-week="monday ? 1 : 2" />
  <c-date v-model="monthModel" value-format="YYYY MMMM DD" format="YYYY MMMM DD" />
  <p>月份名称模型（稳定英文协议）：{{ monthModel }}</p>
</template>
```

### 编辑容器与面板复用

DatePicker / DateRangePicker 独立使用时自带表面背景和操作区；actions 插槽替换整个默认操作区。嵌入 Form 的弹层时，统一外壳负责标题、关闭与底部确认，日期面板只贡献此刻等辅助操作，避免重复确认。关闭放弃草稿，确认失败仍保留草稿。

### 窄屏与组合面板

独立面板随容器宽度收缩；范围日历在空间不足时上下排列。可切换快捷项位置，检查时间、导航与确认操作。

Example source: src/date/picker/__demos__/responsive-panels.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
const selected = ref("2026-10-20 09:30:00");
const selectedRange = ref(["2026-10-20 09:30:00", "2026-10-22 18:00:00"]);
const position = ref<"left" | "right" | "bottom">("left");
const positions = ["left", "right", "bottom"].map((value) => ({
  label: value,
  value,
}));
const types = ["date", "month", "year"] as const;
const shortcuts = [{ label: "本月工作日范围", value: "2026-10-20 09:30:00" }];
const rangeShortcuts = [
  {
    label: "本月工作日范围",
    value: ["2026-10-20 09:30:00", "2026-10-22 18:00:00"],
  },
];
</script>
<template>
  <div>
    <c-form-item layout="vertical" size="sm" label="独立面板快捷位置">
      <c-radio-group
        v-model="position"
        aria-label="独立面板快捷位置"
        :options="positions"
        variant="button"
        size="sm"
      />
    </c-form-item>

    <section
      v-for="type in types"
      :key="type"
      :aria-label="'独立 ' + type + ' 面板'"
    >
      <h4>{{ type }} · DatePicker / DateRangePicker</h4>
      <c-date-picker :type="type" :disable-confirm="false" />
      <c-date-range-picker :type="type" :disable-confirm="false" />
    </section>
    <section aria-label="独立日期时间面板">
      <h4>DatePicker · 时间与快捷项</h4>
      <c-date-picker
        v-model="selected"
        show-time
        :shortcuts="shortcuts"
        :shortcuts-position="position"
        :disable-confirm="false"
      />
    </section>
    <p role="status" aria-label="独立日期时间已提交">{{ selected }}</p>
    <section aria-label="独立日期时间范围面板">
      <h4>DateRangePicker · 时间与快捷项</h4>
      <c-date-range-picker
        v-model="selectedRange"
        show-time
        :shortcuts="rangeShortcuts"
        :shortcuts-position="position"
        :disable-confirm="false"
      />
    </section>
    <p role="status" aria-label="独立日期时间范围已提交">{{ selectedRange }}</p>
  </div>
</template>
```

## 时间与选择规则

### 带时间

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `show-time` | 选择时间 | 带时间、禁用部分日期、内嵌时间与滚轮展示 |
| `format` | 展示格式 | 带时间、内嵌时间与滚轮展示 |
| `value-format` | 模型与事件的格式，可为自定义日期格式、Date 或 timestamp | 当前日期与范围策略、内嵌时间与滚轮展示 |
| `default-value` | 非受控初始值，仅初始化读取 | 带时间 |
| `disabled-date` | 禁用日期 | 禁用部分日期 |
| `disabled-time` | 当前日期、端点的时间禁用列表 | 禁用部分日期 |
<!-- demo-config-notes:end -->

Example source: src/date/picker/__demos__/show-time.vue

```vue
<template>
  <c-date-picker
    show-time
    default-value="2025-01-15 09:09:06"
    format="YYYY-MM-DD HH:mm:ss"
  />
</template>
```

### 禁用部分日期

Example source: src/date/picker/__demos__/disabled-parts.vue

```vue
<template>
  <c-date-picker style="margin: 0 24px 24px 0"
    :disabled-date="(current: any) => dayjs(current).isBefore(dayjs())"
  />
  <c-date-picker style="margin-right: 24px; margin-bottom: 24px"
    show-time
    :disabled-date="(current: any) => dayjs(current).isBefore(dayjs())"
    :disabled-time="getDisabledTime"
  />
</template>

<script lang="ts">
import { defineComponent } from 'vue'
import dayjs from 'dayjs'

export default defineComponent({
  setup() {
    function range(start: any, end: any) {
      const result = []
      for (let i = start; i < end; i++) {
        result.push(i)
      }
      return result
    }

    function getDisabledTime(date: any) {
      return {
        disabledHours: () => range(6, 24),
        disabledMinutes: () => range(30, 60),
        disabledSeconds: () => range(30, 60),
      }
    }
    return {
      dayjs,
      getDisabledTime,
    }
  },
})
</script>
```

### 当前日期与范围策略

Example source: src/date/picker/__demos__/current-range.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'

const yesterday = new Date()
yesterday.setDate(yesterday.getDate() - 1)
const selected = ref(yesterday)
const showCurrent = ref(true)
const showNowButton = ref(true)
const exchangeTime = ref(true)
const range = ref(['2025-01-05 09:00', '2025-01-10 18:00'])
</script>
<template>
  <div>
    <p>今日高亮和选择当前是两个独立功能。</p>
    <c-checkbox v-model="showCurrent"> 今日高亮</c-checkbox>
    <c-checkbox v-model="showNowButton"> 选择当前按钮</c-checkbox>
    <c-date-picker
      v-model="selected"
      value-format="Date"
      :default-picker-value="new Date()"
      :show-current="showCurrent"
      :show-now-button="showNowButton"
      :disable-confirm="false"
    />
    <p>确认后选中：{{ selected }}</p>
    <c-checkbox v-model="exchangeTime"> 日期反序时连同时间交换</c-checkbox>
    <p>先选较晚日期，再选较早日期，对比起止时间。</p>
    <c-date-range-picker
      v-model="range"
      show-time
      format="YYYY-MM-DD HH:mm"
      value-format="YYYY-MM-DD HH:mm"
      :exchange-time="exchangeTime"
      :disable-confirm="false"
    />
    <p>确认后范围：{{ range }}</p>
  </div>
</template>
```

| 属性              | 说明                                               | 默认值 |
| ----------------- | -------------------------------------------------- | ------ |
| `show-current`    | 日历中高亮当前日/月/年，不产生选择或提交           | true   |
| `show-now-button` | DatePicker 单选面板的选择当前按钮，多选/范围不显示 | true   |

选择当前按面板 type、时间精度与 value-format 生成候选，遵守 disabled/readonly、min/max、日期和时间禁用规则及 disable-confirm。disable-confirm=false 时只选择草稿，确认才提交；挂载或改变高亮均不写模型。字段通过 date-picker-props 配置。旧 showNowBtn 名称已删除，不保留别名。

actions 插槽提供 `{ confirm, disabled, selectNow, nowDisabled }`。自定义按钮应调用这两个受保护动作，不应直接写模型。

DateRangePicker 的 `exchange-time` 默认 true。反序交互日期在 true 时交换整个日期时间端点；false 时只交换日期、保留起止位置的时分秒。结果仍须通过端点规则和锁定端点校验。外部模型、手输值和快捷项不静默重排；保留时间位置后同日时间仍逆序的候选不能提交。Cedar 原 ConfigProvider.exchangeTime 全局覆盖已移除。

### 内嵌时间与滚轮展示

`time-picker-props` 使用 `DateTimePickerOptions`：`use12Hours`、`step`、`hideDisabledOptions`、`class`、`style`。仅配置时间展示；日期值、格式/秒精度、约束和确认仍由日期所有者管理。`step` 负责展示采样，不静默修正外部值。未知参数及监听函数不转发。

Example source: src/date/picker/__demos__/time-presentation.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'

const use12Hours = ref(true)
const timeOptions = { step: { minute: 15 }, hideDisabledOptions: true }
</script>

<template>
  <c-checkbox v-model="use12Hours">十二小时展示</c-checkbox>

  <c-date-picker
    model-value="2025-01-05 13:30"
    show-time
    format="YYYY-MM-DD HH:mm"
    value-format="YYYY-MM-DD HH:mm"
    :time-picker-props="{ ...timeOptions, use12Hours }"
  />
</template>
```

## 快捷工具与定制

### 预设快捷选择

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `disable-confirm` | 选择后立即提交 | 快捷选项与日历视口、字段与嵌入式面板 |
| `show-time` | 选择时间 | 预设快捷选择 |
| `day-start-of-week` | 每周第一天（仅日历），整数 0～6 | 字段与嵌入式面板 |
<!-- demo-config-notes:end -->

Example source: src/date/picker/__demos__/short-cuts.vue

```vue
<template>
  <c-date-picker style="margin: 0 24px 24px 0"
    :shortcuts="[
      {
        label: '2 hours later',
        value: () => dayjs().add(2, 'hour'),
      },
      {
        label: 'a week later',
        value: () => dayjs().add(1, 'week'),
      },
      {
        label: 'a month later',
        value: () => dayjs().add(1, 'month'),
      },
    ]"
    show-time
  />
</template>

<script lang="ts">
import { defineComponent } from 'vue'
import dayjs from 'dayjs'

export default defineComponent({
  setup() {
    return {
      dayjs,
    }
  },
})
</script>
```

### 额外页脚

Example source: src/date/picker/__demos__/footer.vue

```vue
<template>
  <c-date-picker style="margin-bottom: 20px">
    <template #extra>Extra footer</template>
  </c-date-picker>
  <br />
  <c-date-range-picker showTime>
    <template #extra>Extra footer</template>
  </c-date-range-picker>
</template>

<script lang="ts">
import { defineComponent } from 'vue'
export default defineComponent({
  })
</script>
```

### 快捷选项与日历视口

Example source: src/date/picker/__demos__/panel-tools.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
const selected = ref("2025-01-15");
const viewport = ref("2025-01-01");
const acceptNavigation = ref(true);
const shortcuts = [
  { label: "月初", value: "2025-01-01" },
  { label: "下个月", value: () => "2025-02-01" },
  { label: "不可选", value: "2025-03-01", disabled: true },
];
function navigate(value: unknown) {
  if (acceptNavigation.value && typeof value === "string")
    viewport.value = value;
}
</script>
<template>
  <div>
    <p>选择值：{{ selected }}；视口：{{ viewport }}</p>
    <c-checkbox v-model="acceptNavigation"> 接受视口导航</c-checkbox>
    <c-date-picker
      v-model="selected"
      :picker-value="viewport"
      :shortcuts="shortcuts"
      :disable-confirm="false"
      @update:picker-value="navigate"
    />
    <p>范围快捷项走同一套确认与校验。</p>
    <c-date-range-picker
      :default-value="['2025-01-10', '2025-01-15']"
      :shortcuts="[{ label: '第一周', value: ['2025-01-01', '2025-01-07'] }]"
      :disable-confirm="false"
    />
  </div>
</template>
```

两端均导出 `DateShortcut`、`DateShortcutsPosition`。快捷项包含 `label`、`value`（值或按需执行的函数）、可选 `format`（快捷值的输入格式）与 `disabled`；输出使用面板的 `value-format`。悬停或聚焦只预览，不提交；点击走普通日期选择的校验与确认流程。设置 `preview-shortcut=false` 仅关闭预览。`shortcuts-position` 支持 left/bottom/right，移动端建议 bottom。

`picker-value` 管理日历视口，不是选中值；`default-picker-value` 仅初始化读取。范围视口为两个日期。导航发出 `update:picker-value` 和 `picker-value-change(value, dates, texts)`，不触发 `change` 或 `select`；受控更新不被接纳时保留原视口。`select-shortcut(shortcut)` 仅在快捷项通过校验并被接受后触发。移动端滚轮/时钟展示不提供日历月份导航。字段通过 `date-picker-props` 配置这些选项，转发上述三个事件。

### 字段与嵌入式面板

字段管理输入与浮层，纯面板直接嵌入页面。日历周起点统一为 day-start-of-week（数字 0～6，0 为周日），动态修改立即生效。

本例纯面板显式设置 `:disable-confirm="false"`：点击日期只修改草稿，“已提交”在确认后更新。切换周起点或移除边界不提交新值；恢复边界不会清除已有模型，超出新边界的草稿不能确认，请重新选择合法日期。

面板箭头提供可访问名称，并跟随组件语言系统切换；日面板为上一月/下一月，月份面板为上一年/下一年，年份列表为上一组/下一组年份。月份预览变化不等于提交日期。

Example source: src/date/picker/__demos__/entry-boundary.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import type { DateSelection } from "@cedar-design/ui";
const limited = ref(true);
const fieldValue = ref<DateSelection>("2025-02-12");
const panelValue = ref<DateSelection>("2025-02-12");
const week = ref<0 | 1 | 6>(1);
</script>

<template>
  <div class="entry-demo">
    <p>仅允许选择 2025 年 2 月；移除限制不会改变已有选中值。</p>
    <c-button @click="limited = !limited">{{
      limited ? "移除日期限制" : "恢复日期限制"
    }}</c-button>
    <c-space wrap>
      <c-button @click="week = 0">周日起始</c-button>
      <c-button @click="week = 1">周一起始</c-button>
      <c-button @click="week = 6">周六起始</c-button>
    </c-space>
    <div>
      <p>字段：管理输入与浮层；面板参数放在 date-picker-props。</p>
      <c-date
        :min="limited ? '2025-02-01' : undefined"
        :max="limited ? '2025-02-28' : undefined"
        v-model="fieldValue"
        :date-picker-props="{ dayStartOfWeek: week }"
        placeholder="选择日期"
      />
    </div>
    <div>
      <p>纯面板：直接嵌入页面，不使用 open / popup-container。</p>
      <c-date-picker
        :min="limited ? '2025-02-01' : undefined"
        :max="limited ? '2025-02-28' : undefined"
        v-model="panelValue"
        :day-start-of-week="week"
        :disable-confirm="false"
      />
      <p>已提交：{{ panelValue }}</p>
    </div>
  </div>
</template>

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

## 阅读方向

组件继承最近的 `dir="ltr|rtl"`，支持运行时切换与局部方向覆盖。日历日期、月份、年份按阅读顺序排列，前后翻页图形随方向调整，日期值与起止顺序保持原义。分页网格中左右键按视觉方向移动焦点，上下键移动一行，Home/End 移至当前行首尾并跳过禁用项；焦点移动不提交，Enter/Space 沿用选值行为，边界停留在当前显示网格。快捷区 `shortcuts-position="left|right"` 保持物理侧，底部使用 `bottom`。弹层继承字段来源方向。

## API

### Props

纯面板不接收 open/default-open、popup-container、placement、trigger-props、placeholder、variant、clearable 等字段/浮层属性。浮层配置请使用 Date/DateRange 的 popup-props；输入可编辑性使用字段 input-editable。确认区只由 disable-confirm 控制，不再使用 show-confirm-btn。

| 参数                | 说明                            | 类型                                       | 默认值  |
| ------------------- | ------------------------------- | ------------------------------------------ | ------- |
| `model-value`       | 绑定值                          | `Date \| string \| number`                 | `-`     |
| `type`              | 面板类型                        | `date \| week \| month \| year \| quarter` | `date`  |
| `format`            | 展示格式                        | `string \| Function`                       | `-`     |
| `day-start-of-week` | 每周第一天（仅日历），整数 0～6 | `DateWeekStart`                            | `0`     |
| `readonly`          | 只读，不更改选择                | `boolean`                                  | `false` |
| `time-picker-props` | 本库时间面板展示选项            | `Partial<TimePickerProps>`                 | `-`     |
| `show-time`         | 选择时间                        | `boolean`                                  | `false` |
| `disabled`          | 禁用                            | `boolean`                                  | `false` |
| `disabled-date`     | 禁用日期                        | `Function`                                 | `-`     |

桌面日历展示能力（快捷选择、页脚和单元格插槽）保留在独立的 presentation 实现中。

### 日期族统一契约

| 参数              | 说明                                                    | 类型                                             | 默认值  |
| ----------------- | ------------------------------------------------------- | ------------------------------------------------ | ------- |
| `default-value`   | 非受控初始值，仅初始化读取                              | DateValue / DateValue[]                          | —       |
| `value-format`    | 模型与事件的格式，可为自定义日期格式、Date 或 timestamp | string                                           | 随 type |
| `min` / `max`     | 包含端点的边界；字符串按 value-format 解析              | DateValue                                        | —       |
| `disabled-time`   | 当前日期、端点的时间禁用列表                            | (date: Date, side: DateSide) => DateDisabledTime | —       |
| `disable-confirm` | 选择后立即提交                                          | boolean                                          | true    |

`DateValue = Date | string | number`。单值清除为 undefined，范围清除为 []。
`disabledDate(date, side)` 和 `disabledTime(date, side)` 的 date 始终为 Date，side 为 start/end。
时间回调返回 `disabledHours()`、`disabledMinutes(hour)`、`disabledSeconds(hour, minute)` 数字列表。
非法日期、不完整或逆序范围不能提交；确认时重新验证动态禁用规则。范围锁定端点不能被清除或改动。
嵌套面板 props 只配置展示，不得覆盖顶层 model-value、格式、边界、禁用规则或控制事件。

### Events

| 事件                 | 说明                    | 参数                              |
| -------------------- | ----------------------- | --------------------------------- |
| `update:model-value` | 写入模型                | value                             |
| `select`             | 选择草稿，不等于提交    | value, date(s), formatted text(s) |
| `change`             | 有效值正式变化          | value, date(s), formatted text(s) |
| `confirm`            | 确认有效选择，不使用 ok | value, date(s), formatted text(s) |

设置 `:disable-confirm="false"` 显示确认区；`actions` 插槽提供 `{ confirm, disabled }`，自定义操作仍须调用 confirm 完成校验。

---

Document: llms/zh-CN/components/date-range.md

<!-- Source: src/date-range/README.md; locale: zh-CN; page: /components/date-range/ -->

# DateRange

表单日期范围字段（带触发器）。内部使用 `DateRangePicker`。

纯面板请使用 [`DateRangePicker`](components/date-range-picker)（默认无触发器）。

字段通过 `date-picker-props`（Date）或 `date-range-picker-props`（DateRange）配置面板的该选项。

`abbreviation`（boolean，默认 `true`）控制日历月份网格的缩写；`false` 使用当前 Locale 的完整月份名。运行时修改立即生效，不改变值，也不触发选择事件。此开关不影响星期标签、标题、滚轮列或值格式。范围日历以顶层选项为准，嵌套日历参数不能覆盖。

## 基础示例

### 基本用法

Example source: src/date-range/__demos__/basic.vue

```vue
<template>
  <c-date-range v-model="range" style="width: 300px" clearable />
</template>

<script setup>
import { ref } from 'vue'

const range = ref()
</script>
```

## 外观与日期展示

### 外观配置对比

<!-- demo-config-notes:start -->

#### 本组配置对照

| 配置           | 作用                                                    | 相关示例                     |
| -------------- | ------------------------------------------------------- | ---------------------------- |
| `clearable`    | 可清除                                                  | 选择类型、自定义分隔符与占位 |
| `value-format` | 模型与事件的格式，可为自定义日期格式、Date 或 timestamp | 外观配置对比                 |
| `type`         | 选择类型                                                | 选择类型                     |
| `separator`    | 分隔符                                                  | 自定义分隔符与占位           |
| `placeholder`  | 占位                                                    | 自定义分隔符与占位           |

<!-- demo-config-notes:end -->

选择一个对比维度后，同屏展示它的全部可选值；其余配置和内容保持一致。可切换其他配置检查组合效果；输入类预览共享一个值。

<details>
<summary>配置说明与使用限制</summary>

#### 外观组合

适用于预订或查询的起止日期。调整变体、尺寸，用相同数据观察变化。内容保持一致，便于比较不同设置的实际效果。

</details>

Example source: src/date-range/__demos__/appearance-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref(["2026-10-23", "2026-10-25"]);
const __demoAppearance = __demoReactive({ variant: "filled", size: "md" });

import { computed as demoComputed, ref as demoRef } from 'vue'
const demoCompareFields = [{"name":"variant","values":["filled","outline","standard"]},{"name":"size","values":["xs","sm","md","lg","xl"]}]
const demoCompareAxis = demoRef("variant")
const demoComparedOptions = demoComputed(() => demoCompareFields.find(field => field.name === demoCompareAxis.value)?.values ?? [])
</script>
<template>
  <c-space direction="column" :size="16">
    <c-form layout="vertical">
      <c-form-item layout="vertical" size="sm" label="variant">
        <c-radio-group
          v-model="__demoAppearance['variant']"
          aria-label="variant"
          :options="[
            { label: 'filled', value: 'filled' },
            { label: 'outline', value: 'outline' },
            { label: 'standard', value: 'standard' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
      <c-form-item layout="vertical" size="sm" label="size">
        <c-radio-group
          v-model="__demoAppearance['size']"
          aria-label="size"
          :options="[
            { label: 'xs', value: 'xs' },
            { label: 'sm', value: 'sm' },
            { label: 'md', value: 'md' },
            { label: 'lg', value: 'lg' },
            { label: 'xl', value: 'xl' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
    </c-form>
    <p class="demo-config-comparison-hint"><span lang="zh-CN">选择一个对比维度；其他配置和内容保持一致。输入类示例共享同一个值，便于比较外观。</span><span lang="en-US">Compare one dimension while keeping the other settings and content identical. Input specimens share the same value.</span></p>
<c-radio-group v-model="demoCompareAxis" aria-label="Compare configuration" :options="demoCompareFields.map(field => ({ label: field.name, value: field.name }))" />
<div class="demo-config-comparison">
<section v-for="sample in demoComparedOptions" :key="String(sample)">
<p><code>{{ demoCompareAxis }}={{ sample }}</code></p>
<c-date-range
      v-model="value"
      value-format="YYYY-MM-DD"
      v-bind="{ ...__demoAppearance, [demoCompareAxis]: sample }"
    ></c-date-range>
</section>
</div>
  </c-space>
</template>

<style scoped>
.demo-config-comparison { display: grid; grid-template-columns: repeat(auto-fit, minmax(min(100%, 220px), 1fr)); gap: 20px; min-width: 0; max-width: 100%; }
.demo-config-comparison > section { min-width: 0; }
.demo-config-comparison p { margin: 0 0 8px; }
html:not([lang='en-US']) .demo-config-comparison-hint > [lang='en-US'],
html[lang='en-US'] .demo-config-comparison-hint > [lang='zh-CN'] { display: none; }
</style>
```

### 选择类型

通过 `type` 切换日 / 周 / 月 / 年 / 季度范围。

Example source: src/date-range/__demos__/mode.vue

```vue
<template>
  <c-space direction="column" fill>
    <c-date-range v-model="dateRange" style="width: 300px" clearable />
    <c-date-range v-model="weekRange" type="week" style="width: 300px" clearable />
    <c-date-range v-model="monthRange" type="month" style="width: 300px" clearable />
    <c-date-range v-model="yearRange" type="year" style="width: 300px" clearable />
    <c-date-range v-model="quarterRange" type="quarter" style="width: 300px" clearable />
  </c-space>
</template>

<script setup>
import { ref } from 'vue'

const dateRange = ref()
const weekRange = ref()
const monthRange = ref()
const yearRange = ref()
const quarterRange = ref()
</script>
```

### 自定义分隔符与占位

Example source: src/date-range/__demos__/separator.vue

```vue
<template>
  <c-date-range
    v-model="range"
    style="width: 300px"
    separator=" 至 "
    :placeholder="['开始日期', '结束日期']"
    clearable
  />
</template>

<script setup>
import { ref } from 'vue'

const range = ref()
</script>
```

## 时间与范围规则

### 带时间

<!-- demo-config-notes:start -->

#### 本组配置对照

| 配置            | 作用                                                    | 相关示例               |
| --------------- | ------------------------------------------------------- | ---------------------- |
| `format`        | 展示格式                                                | 带时间、边界和端点禁用 |
| `show-time`     | 选择时间                                                | 带时间                 |
| `clearable`     | 可清除                                                  | 带时间                 |
| `value-format`  | 模型与事件的格式，可为自定义日期格式、Date 或 timestamp | 边界和端点禁用         |
| `disabled-date` | 禁用日期                                                | 边界和端点禁用         |

<!-- demo-config-notes:end -->

Example source: src/date-range/__demos__/show-time.vue

```vue
<template>
  <c-date-range
    v-model="range"
    style="width: 380px"
    show-time
    format="YYYY-MM-DD HH:mm:ss"
    clearable
  />
  <p role="status" aria-label="Date-time range model">{{ JSON.stringify(range) ?? 'undefined' }}</p>
</template>

<script setup>
import { ref } from 'vue'

const range = ref()
</script>
```

### 边界和端点禁用

桌面日历需要选齐起点和终点后才能确认；点击结束输入可先选终点、再选起点。Escape 关闭时丢弃未确认的范围。

Example source: src/date-range/__demos__/boundaries.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const value = ref(['2026/09/10', '2026/09/15'])
const disabledDate = (date: Date, side: 'start' | 'end') => side === 'end' && date.getDay() === 0
</script>
<template>
  <div class="date-contract-demo">
    <c-date-range v-model="value" value-format="YYYY/MM/DD" format="DD-MM-YYYY"
      min="2026/09/01" max="2026/09/30" :disabled-date="disabledDate" />
    <p>仅可选九月，结束日期不能是周日。请选齐两个端点；确认提交，Escape 取消草稿。</p>
    <output>{{ value }}</output>
  </div>
</template>
<style scoped>
.date-contract-demo { display: flex; flex-direction: column; gap: 12px; }
.date-contract-demo p { margin: 0; }
</style>
```

### 语言与嵌套日历参数

日期标签、标题和动作接入各库的全局 Locale 与既有 Provider。Cedar 删除日期组件级 `locale`，不保留覆盖字典或兼容别名。切换语言不会选择或提交日期。

### 内嵌时间与滚轮展示

日期范围的内嵌时间选择也属于外层草稿：修改起点或终点时间不会提前写回，显式确认后才提交；取消保留原模型。日期时间手输的反序范围不会自动交换端点。

Embedded time edits update the outer range draft, not the committed model. Confirm explicitly to submit; cancel preserves the previous value. Reversed date-time text input is rejected rather than reordered.

`time-picker-props` 使用 `DateTimePickerOptions`：`use12Hours`、`step`、`hideDisabledOptions`、`class`、`style`。仅配置时间展示；日期值、格式/秒精度、约束和确认仍由日期所有者管理。`step` 负责展示采样，不静默修正外部值。未知参数及监听函数不转发。

### 真实端侧能力

Cedar 不公开 `Date.pickerProps`、`DateRange.pickerProps` 或 `DateRange.datePickerProps`：PC 字段不渲染移动滚轮或范围内部的移动日历插件，原无效参数已删除且无兼容别名。Maple 保留这些真实扩展，使用 DateWheelOptions 与 DateRangeCalendarOptions。两端通过 `Date.datePickerProps` / `DateRange.dateRangePickerProps` 配置完整面板，`timePickerProps` 配置内嵌时间展示。初始日期时间放在顶层 `defaultValue`，不要放在 `timePickerProps.defaultValue` 中。

### 日期语言的实例隔离

日期所有者读取本库全局 Locale/Provider，周起始日由各实例 `day-start-of-week` 管理。不切换宿主 Dayjs 默认语言，也不覆盖宿主基础语言配置；只在各库命名空间下注册日期语言元数据，组件实例与源码不跨库共享。

`value-format` 是稳定英文日期协议（包括月份名称 token），`format` 的显示及手输文本使用界面语言。切换语言不会改写模型，也不会令英文月份名称模型失效。默认数字协议、Date 对象、时间戳不变。中文核心语言与 Maple 内置语言数据已接入；其他日期格式优先使用已注册 Dayjs 语言数据，未加载的语言安全回退英文。

周号和周比较不再依赖全局周起始设置，跨年同周号不能被误判成同一周。两个不同周起始实例的挂载、更新和卸载互不影响。

### 周与季度手输

默认周展示 `gggg-wo` 按当前界面语言与实例周起始解析为该周的第一天，模型仍为 `YYYY-MM-DD`。中文周一起始的 `2020-53周` 提交 `2020-12-28`；不存在的周、错误序数后缀不提交。默认季度 `YYYY-[Q]Q`（如 `2025-Q2`）严格解析为首月，模型 `YYYY-MM`（`2025-04`）。手输继续遵守禁用、边界和范围顺序，不自动交换端点。

自定义周/季度展示可以使用 Dayjs 支持的普通日期 token；任意自定义周序数格式没有逆解析协议。`format` 为函数时请设置 `input-editable=false`，通过面板选择。

日期字段的可编辑条件由公共所有者统一管理：`input-editable` 默认 true，函数 `format` 不可反解析，因此输入只读。两端单值/范围的 Enter、失焦、组合输入、受控拒绝回写、禁用与范围顺序通过同一组原生输入测试；Maple 多选拼接文本保持只读，由面板选择。

## 值模型与输入

### 字符串模型：年月日、年月与月日范围

<!-- demo-config-notes:start -->

#### 本组配置对照

| 配置           | 作用                                                    | 相关示例                                           |
| -------------- | ------------------------------------------------------- | -------------------------------------------------- |
| `format`       | 展示格式                                                | 字符串模型：年月日、年月与月日范围、手输与面板选择 |
| `value-format` | 模型与事件的格式，可为自定义日期格式、Date 或 timestamp | 字符串模型：年月日、年月与月日范围                 |
| `disabled`     | 禁用                                                    | 手输与面板选择                                     |

<!-- demo-config-notes:end -->

`format` 决定显示，`value-format` 决定提交值。下面直接得到 `"2026-09-10"`、`"2026-09"` 或 `["09-10", "10-10"]`，无需将 Date 再转换。日期范围使用数组。`MM-DD` 没有年份，解析时使用当前年，不能表示跨年先后或某个明确年份的 2 月 29 日；有跨年、时区或闰年要求时保留 `YYYY-MM-DD`，在业务提交时单独映射月日。默认仍是 page，未指定 timeZone 使用浏览器本地时区。

Example source: src/date-range/__demos__/string-values.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
const date = ref("2026-09-10");
const month = ref("2026-09");
const range = ref(["09-10", "10-10"]);
</script>
<template>
  <c-space direction="column">
    <c-date v-model="date" format="YYYY-MM-DD" value-format="YYYY-MM-DD" />
    <p>String: {{ JSON.stringify(date) }}</p>
    <c-date
      v-model="month"
      type="month"
      format="YYYY-MM"
      value-format="YYYY-MM"
    />
    <p>Month string: {{ JSON.stringify(month) }}</p>
    <c-date-range v-model="range" format="MM-DD" value-format="MM-DD" />
    <p>Month/day array: {{ JSON.stringify(range) }}</p>
  </c-space>
</template>
```

### 手输与面板选择

Example source: src/date/picker/__demos__/text-entry.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'

const value = ref('2025-01-15')
const range = ref(['2025-01-15', '2025-01-20'])
const panelOnly = ref(false)
</script>

<template>
  <p>输入 DD/MM/YYYY，Enter 或失焦提交；非法日期和范围外输入恢复模型显示。</p>
  <c-date v-model="value" format="DD/MM/YYYY" min="2025-01-10" max="2025-01-25" :input-editable="!panelOnly" />
  <p>模型：{{ value }}</p>
  <c-switch v-model="panelOnly" />
  <p>仅面板选择：{{ panelOnly }}</p>
  <c-date-range v-model="range" format="DD/MM/YYYY" :disabled="[true, false]" :input-editable="!panelOnly" />
  <p>起点锁定，终点不能早于起点：{{ range }}</p>
</template>
```

## 交互与字段配置

### 交互状态对比

<!-- demo-config-notes:start -->

#### 本组配置对照

| 配置                      | 作用                                                    | 相关示例                             |
| ------------------------- | ------------------------------------------------------- | ------------------------------------ |
| `open`                    | 弹层显隐                                                | 受控关闭被拒绝、透传配置边界与优先级 |
| `date-range-picker-props` | 面板展示选项                                            | 字段视口与快捷项事件、字段与面板边界 |
| `value-format`            | 模型与事件的格式，可为自定义日期格式、Date 或 timestamp | 交互状态对比                         |
| `readonly`                | 只读                                                    | 交互状态对比                         |
| `format`                  | 展示格式                                                | 字段视口与快捷项事件                 |
| `popup-props`             | Trigger 展示配置；不允许覆盖展开状态及规则              | 透传配置边界与优先级                 |

<!-- demo-config-notes:end -->

在同一实例上切换禁用、只读和错误状态后再操作控件，比较可编辑性和交互反馈。恢复开关位于目标控件外；错误外观本身不会执行校验。

<details>
<summary>配置说明与使用限制</summary>

#### 交互状态切换

适用于预订或查询的起止日期。调整只读、错误反馈，用相同数据观察变化。控制区始终可用，可以随时恢复编辑；错误外观本身不会触发表单校验。

</details>

Example source: src/date-range/__demos__/state-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref(["2026-10-23", "2026-10-25"]);
const __demoState = __demoReactive({ readonly: false, error: false });
</script>
<template>
  <c-space direction="column" :size="16">
    <c-space wrap>
      <c-checkbox v-model="__demoState['readonly']">readonly</c-checkbox>
      <c-checkbox v-model="__demoState['error']">error</c-checkbox>
    </c-space>
    <c-date-range
      v-model="value"
      value-format="YYYY-MM-DD"
      v-bind="__demoState"
    ></c-date-range>
  </c-space>
</template>
```

### 受控关闭被拒绝

父级拒绝关闭时，范围面板会保留展开；同一选择的重复确认不会再次提交或请求关闭，修改起止日期后则可以开启新的确认事务。

Example source: src/date-range/__demos__/rejected-close.vue

```vue
<script setup>
import { ref } from "vue";

const value = ref(["2026-09-22", "2026-09-24"]);
const open = ref(false);
const closeRequests = ref(0);
const commits = ref(0);

function requestOpen(next) {
  if (next) open.value = true;
  else closeRequests.value++;
}
</script>

<template>
  <c-space direction="column" size="12px">
    <p>
      关闭请求会被父级拒绝；修改起止日期后可再次确认，重复确认不应重复提交。
    </p>
    <c-date-range
      v-model="value"
      :open="open"
      @update:open="requestOpen"
      @change="commits++"
    >
      <template #actions="{ confirm, disabled }">
        <c-button :disabled="disabled" @click="confirm()">确认</c-button>
        <c-button @click="open = false">允许关闭</c-button>
      </template>
    </c-date-range>
    <span data-test="date-range-transaction-state"
      >值：{{ value.join(" ~ ") }}；提交：{{ commits }}；拒绝关闭：{{
        closeRequests
      }}</span
    >
  </c-space>
</template>
```

### 字段视口与快捷项事件

字段通过嵌套 `date-range-picker-props` 配置 `pickerValue`、`defaultPickerValue` 和快捷项，不新增第二套顶层视口 Prop。嵌套配置里的监听器不会透传；在字段组件上监听以下事件并回写嵌套 `pickerValue`。

| 事件                  | 说明                             | 参数                              |
| --------------------- | -------------------------------- | --------------------------------- |
| `update:picker-value` | 请求日历视口更新，不改变选择模型 | value: DateSelection              |
| `picker-value-change` | 已请求的视口及展示通知           | value, date(s), formatted text(s) |
| `select-shortcut`     | 接受的快捷项，仍遵守字段确认策略 | shortcut: DateShortcut            |

受控视口拒绝更新时保持原月份，后续回写才更新；快捷项选择先进入字段草稿，默认确认后提交。滚轮/时钟没有日历月份导航能力。

Example source: src/date-range/__demos__/field-panel-tools.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import type { DateShortcut } from "@cedar-design/ui";

const selected = ref(["2025-01-15", "2025-01-20"]);
const viewport = ref(["2025-01-01", "2025-02-01"]);
const acceptNavigation = ref(true);
const notice = ref("");
const shortcutNotice = ref("");
const shortcuts: DateShortcut[] = [
  { label: "下个月", value: ["2025-02-15", "2025-02-20"] },
  { label: "不可选", value: ["2025-03-01", "2025-03-05"], disabled: true },
];
function navigate(value: unknown) {
  if (
    acceptNavigation.value &&
    Array.isArray(value) &&
    value.length === 2 &&
    value.every((part) => typeof part === "string")
  )
    viewport.value = value;
}
function observe(_value: unknown, _dates: unknown, texts: unknown) {
  notice.value = String(texts);
}
function choose(shortcut: DateShortcut) {
  shortcutNotice.value = String(shortcut.label);
}
</script>

<template>
  <c-checkbox v-model="acceptNavigation"> 接受视口请求</c-checkbox>
  <c-date-range
    v-model="selected"
    :input-editable="false"
    format="DD/MM/YYYY"
    :date-range-picker-props="{ pickerValue: viewport, shortcuts }"
    @update:picker-value="navigate"
    @picker-value-change="observe"
    @select-shortcut="choose"
  />
  <p>选择模型：{{ selected }}；受控视口：{{ viewport }}</p>
  <p>视口通知：{{ notice }}；快捷项通知：{{ shortcutNotice }}</p>
  <p>
    导航不改变选择模型；拒绝视口请求后，日历仍显示原月份。快捷项先选择草稿，确认后提交。
  </p>
</template>
```

### 展示模式的所有权

Cedar 只实现桌面日历，不公开移动 `edit-mode`。Maple 在字段/纯面板根选择真实展示模式；字段嵌套 `DatePickerOptions` / `DateRangePickerOptions` 不包含 presentation，两库复制的过滤器均拒绝嵌套选择器，不通过隐式覆盖保留无效 API。

### 周起始日的响应式展示

`dayStartOfWeek` 更新时，日历表头与日期列位置同步更新，不改变选中值或提交草稿。纯面板使用根属性，字段通过 `datePickerProps` / `dateRangePickerProps` 配置；滚轮视图不使用星期列。

### 动态日期限制

更新或移除 `min` / `max` 会重新计算可选日期，不自动修改已有模型或草稿。面板导航与候选日期校验是不同职责，已有值超出新限制时也不会被静默重写；用户重新选择或确认时按当前限制校验。

### Form 字段展示与确认

本组件支持 `edit-mode`，字段 > FormItem > Form 逐层继承；未指定时为 `direct`，保留原有交互。支持值：`direct / click / dblclick`。非 direct 编辑模式通过字段值入口打开编辑面板，并维护单份草稿；确认后才更新 v-model，取消、重置或启用 readPretty 时丢弃草稿。

Cedar 使用 edit-mode="click" / "dblclick" 在字段附近打开编辑浮层，Enter/F2 也可进入；取消/Escape 丢弃草稿，确认后提交。readPretty 为独立阅读属性，与 readonly、disabled 分开。

`before-commit(value, { previousValue, signal })` 可拦截弹层保存；FormItem 先校验候选值，失败保持编辑。`open / default-open / update:open` 控制编辑层。`#read="{ value, text }"` 可自定义阅读内容。集中示例见 Form 的“各类字段统一展示”。

日期／时间字段在 inline 下沿用原确认策略；在 click/dblclick 编辑展示中，内部纯面板隐藏确认工具栏，由编辑层提供唯一一组确认／取消。独立 DatePicker、DateRangePicker、TimePicker、TimeRangePicker 保留原有面板 API 和确认行为，不继承 Form 的字段展示。

### 范围日历的视口与选择

默认双日历从起始日期所在月开始显示连续两个月；两侧外部箭头联动翻月，跨年连续。月份／年份标题选择同步调整相邻面板，视口导航只发 picker-value 事件，不修改选中范围。显式 picker-value / default-picker-value 可以指定独立视口；同月或逆序视口只在显示层纠正，不回写受控值。

已有范围时重新点选第一个日期会进入未完成草稿，确认暂时禁用；第二个端点合法后才可确认。反向点选按日期排序，取消恢复先前已提交值。禁用端点和日期／时间限制仍在选择及确认时校验。

独立 DatePicker / DateRangePicker 与 inline 共用日历基准宽度（每个 265px）。单日期带时间时，宽屏下日历与时间列左右排列；范围在宽屏保留两个并排日历。面板会按窄容器换行，侧边快捷项另占一列，不压缩日历；确认与 actions 插槽保持由面板自身管理。

`read-pretty` 为独立布尔属性，与 `readonly`、`disabled` 同级；字段 > FormItem > Form 继承，显式 `false` 覆盖父级。默认 `false`。纯阅读不显示编辑器。

### 字段与面板边界

字段保留输入和浮层状态；嵌套面板参数只接受展示选项，不能覆盖顶层模型、格式或校验规则。

Example source: src/date-range/__demos__/entry-boundary.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import type { DateValue } from "@cedar-design/ui";
const limited = ref(true);
const blockEnd20 = ref(false);
const disabledEnd = (date: Date, side: "start" | "end") =>
  side === "end" && blockEnd20.value && date.getDate() === 20;
const fieldValue = ref<DateValue[]>(["2025-02-12", "2025-02-14"]);
const panelValue = ref<DateValue[]>(["2025-02-12", "2025-02-14"]);
</script>

<template>
  <div class="entry-demo">
    <p>仅允许选择 2025 年 2 月；移除限制不会改变已有选中值。</p>
    <c-button @click="limited = !limited">{{
      limited ? "移除日期限制" : "恢复日期限制"
    }}</c-button>
    <div>
      <p>范围字段：管理输入、浮层和确认流程。</p>
      <c-date-range
        :min="limited ? '2025-02-01' : undefined"
        :max="limited ? '2025-02-28' : undefined"
        v-model="fieldValue"
        :date-range-picker-props="{ dayStartOfWeek: 1 }"
      />
    </div>
    <div>
      <p>范围面板：日历从周一开始，点击确认后才提交。</p>
      <c-checkbox v-model="blockEnd20">
        禁用20日结束（不改已提交值）</c-checkbox
      >
      <c-date-range-picker
        :min="limited ? '2025-02-01' : undefined"
        :max="limited ? '2025-02-28' : undefined"
        v-model="panelValue"
        :day-start-of-week="1"
        :disable-confirm="false"
        :disabled-date="disabledEnd"
      >
        <template #actions="{ confirm, disabled }">
          <c-button :disabled="disabled" @click="confirm"
            >提交日期范围</c-button
          >
        </template>
      </c-date-range-picker>
      <p>已提交：{{ panelValue.join(" ~ ") }}</p>
    </div>
  </div>
</template>

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

### 日期值格式

两端使用独立复制的日期值、约束、面板和字段主体。年/月/日模型格式为 `YYYY` / `YYYY-MM` / `YYYY-MM-DD`，日期时间默认含秒；`format="YYYY-MM-DD HH:mm"` 与 `value-format="YYYY-MM-DD HH:mm"` 使用分钟字符串。`format` 只控制显示，`value-format` 控制模型和事件，支持自定义格式、`Date` 与 `timestamp`。Cedar 另提供周/季度面板；Maple 另提供移动端滚轮和时钟展示。

起止输入使用同一字段焦点：Tab 在两端间切换时保留草稿，不触发 blur 校验或提交；Enter 或离开整个字段才提交，Escape 丢弃草稿。点击结束输入会让范围面板从结束端开始选择。

字段使用 PickerField → FieldDecorator；面板只负责选择，不注入表单。有效文本在回车或失焦时提交，Escape 或外部关闭丢弃未确认草稿，清除立即提交空值。四类字段的统一示例见 [Date](llms/zh-CN/components/date.md#统一字段与提交)。

### 透传配置边界与优先级

建议使用 `DateRangePopupOptions` 声明 popup-props，边界与 DatePopupOptions 一致。仅用于 inline 锚定弹层；范围值、规则、open/defaultOpen、禁用及通知归 DateRange 管理。popup-container 顶层优先、嵌套回退，popupClass 合并内部类；trigger、closeOnClickReference、preventFocus、popupOffset 由展示层固定，Maple 还固定 unmountOnClose=true。新类型不开放这些固定项，附加平移使用 popupTranslate。已有运行时字段/监听过滤和旧配置可用能力保持。

本次仅新增可主动选用的专用类型，不收窄已发布的宽属性类型，不增加运行时过滤、不改变覆盖顺序；旧业务写法继续可编译。若直接使用旧宽属性，内部托管字段仍可能通过类型检查，但不代表能控制内部状态。

```ts
import type { DateRangePopupOptions } from "@cedar-design/ui";
```

Example source: src/date-range/__demos__/passthrough-options.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import type { DateRangePopupOptions } from "@cedar-design/ui";
const open = ref(false);
const popupOptions: DateRangePopupOptions = {
  placement: "top-start",
  popupTranslate: [0, -8],
  popupContainer: false,
};
</script>
<template>
  <c-space direction="column" fill>
    <c-button @click="open = !open">{{
      open ? "关闭面板" : "打开面板"
    }}</c-button>
    <c-date-range
      edit-mode="direct"
      v-model:open="open"
      :popup-props="popupOptions"
      aria-label="透传配置示例"
    />
    <p role="status">顶层 open：{{ open }}；嵌套配置：向上展开并调整偏移。</p>
  </c-space>
</template>
```

### 复制与编辑

open-trigger-target="icon" 时，输入区可以编辑或复制，只有右侧选择按钮响应点击打开。关闭手输或搜索后，已有文本仍可复制。

Example source: src/date-range/__demos__/open-trigger-target.vue

```vue
<template>
  <c-space direction="column">
    <c-radio-group
      v-model="target"
      :options="[
        { label: '整个字段', value: 'field' },
        { label: '仅右侧图标', value: 'icon' },
      ]"
    />
    <label><c-switch v-model="editable" /> 允许编辑 / 搜索</label>
    <c-date-range
      v-model="value"
      edit-mode="direct"
      :open-trigger-target="target"
      :input-editable="editable"
    />
    <p>关闭编辑后，可以复制已有文本；仅图标模式下编辑不会展开。</p>
  </c-space>
</template>
<script setup lang="ts">
import { ref } from "vue";
const target = ref<"field" | "icon">("icon");
const editable = ref(true);
const value = ref(["2026-10-27", "2026-10-28"]);
</script>
```

### 共享字段加载

`loading` 控制共享字段加载状态；`loading-mode` 为 `default`（指示器）或 `line`（底部不定进度线），默认 `default`。渲染统一由 FieldDecorator 负责，不隐式改变 disabled/readonly；需要禁止编辑时单独设置。

## 阅读方向

范围值始终保持 `[开始, 结束]`，切换阅读方向不会交换端点或提交草稿。日历范围连接线与边界圆角跟随阅读方向；分页网格的左右键按视觉方向移动焦点，上下键保持日期行序。Maple 的端点编辑和连续范围高亮是不同展示路径。显式 `shortcuts-position="left|right"` 保持物理侧；弹层继承字段来源方向。

## API

### 空值识别与阅读空文案

`empty-values` 用于空值识别，`empty-value` 保留原清空输出；`empty-text` 仅在 `read-pretty` 空内容下展示，默认 `'-'`，字段 > FormItem > Form，自定义 read 插槽优先。显式配置 empty-values 后，内置 required 接入该策略，自定义校验仍收到原值。详见[统一说明](llms/zh-CN/guide/empty-values.md)。

| 参数         | 类型               | 缺省与范围                                            |
| ------------ | ------------------ | ----------------------------------------------------- |
| empty-values | readonly unknown[] | 字段 > FormItem > Form > 组件族默认；完整覆盖，不合并 |
| empty-text   | string             | 字段 > FormItem > Form > '-'；显式 '' 有效            |

以上是字段展示层 API；纯面板不因此新增阅读模式。Form 与 FormItem 提供继承配置。empty-value 的现有类型与默认输出仍按该组件原 API 执行。

### Props

| 参数                      | 说明                                                                                   | 类型                                       | 默认值    |
| ------------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------ | --------- |
| `open-trigger-target`     | 打开面板的点击区域；field 为整个字段，icon 仅右侧选择按钮。不影响键盘展开及受控 open。 | `'field' \| 'icon'`                        | `'field'` |
| `model-value`             | 绑定值                                                                                 | `(Date \| string \| number)[]`             | `-`       |
| `type`                    | 选择类型                                                                               | `date \| week \| month \| year \| quarter` | `date`    |
| `open`                    | 弹层显隐                                                                               | `boolean`                                  | `-`       |
| `clearable`               | 可清除                                                                                 | `boolean`                                  | `true`    |
| `disabled`                | 禁用                                                                                   | `boolean \| boolean[]`                     | `-`       |
| `readonly`                | 只读                                                                                   | `boolean`                                  | `false`   |
| `size`                    | 尺寸                                                                                   | `xs \| sm \| md \| lg \| xl`               | `-`       |
| `variant`                 | 输入框变体                                                                             | `filled \| outline \| standard`            | `filled`  |
| `separator`               | 分隔符                                                                                 | `string`                                   | `-`       |
| `placeholder`             | 占位                                                                                   | `string[]`                                 | `-`       |
| `disabled-date`           | 禁用日期                                                                               | `Function`                                 | `-`       |
| `format`                  | 展示格式                                                                               | `string`                                   | `-`       |
| `show-time`               | 选择时间                                                                               | `boolean`                                  | `false`   |
| `date-range-picker-props` | 面板展示选项                                                                           | `DateRangePickerOptions`                   | `{}`      |

### 日期族统一契约

| 参数              | 说明                                                    | 类型                                               | 默认值  |
| ----------------- | ------------------------------------------------------- | -------------------------------------------------- | ------- |
| `default-value`   | 非受控初始值，仅初始化读取                              | DateValue / DateValue[]                            | —       |
| `value-format`    | 模型与事件的格式，可为自定义日期格式、Date 或 timestamp | string                                             | 随 type |
| `min` / `max`     | 包含端点的边界；字符串按 value-format 解析              | DateValue                                          | —       |
| `disabled-time`   | 当前日期、端点的时间禁用列表                            | (date: Date, side: DateSide) => DateDisabledTime   | —       |
| `disable-confirm` | 选择后立即提交                                          | boolean                                            | false   |
| `default-open`    | 非受控初始展开                                          | boolean                                            | false   |
| `popup-props`     | Trigger 展示配置；不允许覆盖展开状态及规则              | object                                             | {}      |
| `popup-container` | 挂载目标；顶层优先，支持 false 原地渲染                 | string / HTMLElement / (() => HTMLElement) / false | —       |

`DateValue = Date | string | number`。单值清除为 undefined，范围清除为 []。
`disabledDate(date, side)` 和 `disabledTime(date, side)` 的 date 始终为 Date，side 为 start/end。

`disabled-date` 限制起止端点，范围可以跨过中间的禁用项；不会逐项扫描或自动截断范围。日期、月份、年份均采用此规则。中间禁用项保持灰色，翻页保留已选起点并清除悬浮预览；反向点选按时间先后排序。
时间回调返回 `disabledHours()`、`disabledMinutes(hour)`、`disabledSeconds(hour, minute)` 数字列表。
非法日期、不完整或逆序范围不能提交；确认时重新验证动态禁用规则。范围锁定端点不能被清除或改动。
嵌套面板 props 只配置展示，不得覆盖顶层 model-value、格式、边界、禁用规则或控制事件。

### Events

| 事件                          | 说明                 | 参数                              |
| ----------------------------- | -------------------- | --------------------------------- |
| `update:model-value`          | 写入模型             | value                             |
| `select`                      | 选择草稿，不等于提交 | value, date(s), formatted text(s) |
| `change`                      | 有效值正式变化       | value, date(s), formatted text(s) |
| `update:open` / `open-change` | 展开状态变化         | open: boolean                     |
| `clear`                       | 清除                 | 无                                |
| `focus` / `blur`              | 整个字段的焦点边界   | 无                                |
| `click`                       | 点击字段             | event                             |

桌面支持键盘编辑。默认面板先编辑草稿再确认；设置 disable-confirm 可直接提交。Escape 或关闭会丢弃草稿。focus(index = 0) 定位起止输入，blur() 关闭浮层。

## 配置清空后的值

`empty-value` 指定当前组件已有清空动作的输出；省略时采用该组件默认返回。具体类型以组件 API 为准。它不改变 empty-values 的识别规则，也不改变 Form reset 的初始值。

`empty-value` 可显式设为 `null`（或 `() => null`），清空时原样提交 null；省略时保留组件原默认值。界面把 null 显示为空，不会把普通输入的空字符串自动转成 null。支持弹出编辑的字段中，清空先修改草稿，确认后提交，取消则保留原值。

---

Document: llms/zh-CN/components/date.md

<!-- Source: src/date/README.md; locale: zh-CN; page: /components/date/ -->

# Date

浮动日期面板按可视视口限制高度，正常高度完整展示日历；只有窗口放不下时才滚动，确认操作保持可见。可通过 `--c-date-picker-popover-max-height` 调整最大高度（默认 `100dvh - 32px`）。

展开时，原生 combobox 通过 `aria-controls` 关联当前实例的命名弹层；关闭后同步更新状态并移除关联。`aria-label`、`aria-describedby` 可传递给原生控件。自定义 selected/触发插槽需自行保留可访问名称、键盘操作和状态关联。

表单日期字段（带触发器）。内部使用 `DatePicker`。

纯面板请使用 [`DatePicker`](llms/zh-CN/components/date-picker.md)（默认无触发器）。日期范围字段请使用 [`DateRange`](llms/zh-CN/components/date-range.md)。

## 基础示例

### 基本用法

Example source: src/date/__demos__/basic.vue

```vue
<template>
  <c-date v-model="value" style="width: 200px" clearable />
</template>

<script setup>
import { ref } from 'vue'

const value = ref()
</script>
```

## 外观与日期展示

### 外观配置对比

<!-- demo-config-notes:start -->

#### 本组配置对照

| 配置           | 作用                                                    | 相关示例                         |
| -------------- | ------------------------------------------------------- | -------------------------------- |
| `value-format` | 模型与事件的格式，可为自定义日期格式、Date 或 timestamp | 外观配置对比、日期语言的实例隔离 |
| `type`         | 选择类型                                                | 选择类型、日期语言的实例隔离     |
| `size`         | 尺寸                                                    | 表单控件尺寸对照                 |
| `variant`      | 输入框变体                                              | 表单控件尺寸对照                 |
| `placeholder`  | 占位                                                    | 表单控件尺寸对照                 |
| `clearable`    | 可清除                                                  | 选择类型                         |

<!-- demo-config-notes:end -->

选择一个对比维度后，同屏展示它的全部可选值；其余配置和内容保持一致。可切换其他配置检查组合效果；输入类预览共享一个值。

<details>
<summary>配置说明与使用限制</summary>

#### 外观组合

适用于选择单个日期。调整变体、尺寸，用相同数据观察变化。内容保持一致，便于比较不同设置的实际效果。

</details>

Example source: src/date/__demos__/appearance-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref("2026-10-23");
const __demoAppearance = __demoReactive({ variant: "filled", size: "md" });

import { computed as demoComputed, ref as demoRef } from 'vue'
const demoCompareFields = [{"name":"variant","values":["filled","outline","standard"]},{"name":"size","values":["xs","sm","md","lg","xl"]}]
const demoCompareAxis = demoRef("variant")
const demoComparedOptions = demoComputed(() => demoCompareFields.find(field => field.name === demoCompareAxis.value)?.values ?? [])
</script>
<template>
  <c-space direction="column" :size="16">
    <c-form layout="vertical">
      <c-form-item layout="vertical" size="sm" label="variant">
        <c-radio-group
          v-model="__demoAppearance['variant']"
          aria-label="variant"
          :options="[
            { label: 'filled', value: 'filled' },
            { label: 'outline', value: 'outline' },
            { label: 'standard', value: 'standard' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
      <c-form-item layout="vertical" size="sm" label="size">
        <c-radio-group
          v-model="__demoAppearance['size']"
          aria-label="size"
          :options="[
            { label: 'xs', value: 'xs' },
            { label: 'sm', value: 'sm' },
            { label: 'md', value: 'md' },
            { label: 'lg', value: 'lg' },
            { label: 'xl', value: 'xl' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
    </c-form>
    <p class="demo-config-comparison-hint"><span lang="zh-CN">选择一个对比维度；其他配置和内容保持一致。输入类示例共享同一个值，便于比较外观。</span><span lang="en-US">Compare one dimension while keeping the other settings and content identical. Input specimens share the same value.</span></p>
<c-radio-group v-model="demoCompareAxis" aria-label="Compare configuration" :options="demoCompareFields.map(field => ({ label: field.name, value: field.name }))" />
<div class="demo-config-comparison">
<section v-for="sample in demoComparedOptions" :key="String(sample)">
<p><code>{{ demoCompareAxis }}={{ sample }}</code></p>
<c-date
      v-model="value"
      value-format="YYYY-MM-DD"
      v-bind="{ ...__demoAppearance, [demoCompareAxis]: sample }"
    ></c-date>
</section>
</div>
  </c-space>
</template>

<style scoped>
.demo-config-comparison { display: grid; grid-template-columns: repeat(auto-fit, minmax(min(100%, 220px), 1fr)); gap: 20px; min-width: 0; max-width: 100%; }
.demo-config-comparison > section { min-width: 0; }
.demo-config-comparison p { margin: 0 0 8px; }
html:not([lang='en-US']) .demo-config-comparison-hint > [lang='en-US'],
html[lang='en-US'] .demo-config-comparison-hint > [lang='zh-CN'] { display: none; }
</style>
```

### 表单控件尺寸对照

切换五档 size 和三种字段变体，比较 Input、Button、Select、日期时间及其他单行表单控件的高度。Button 在这里固定使用 outline。DatePicker/TimePicker 是面板，此处使用带输入框的 Date/Time 字段。示例同时展示有值、可清空、标签删除与长标签多选；Select/Cascader 设置 tag-nowrap 时保持同档高度，长标签文字省略、删除图标保留；标签行可横向滚动，清空按钮和箭头固定在外侧。被省略的标签正文支持悬停、键盘聚焦或点按查看完整文字，点外部或按 Esc 关闭，不改变选中值。可清空后恢复选中值重复比较。多行文本和允许换行的多选内容按内容撑高。

Example source: src/field-decorator/__demos__/control-sizes.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
const sizes = ["xs", "sm", "md", "lg", "xl"] as const;
const variants = ["outline", "filled", "standard"] as const;
const size = ref<(typeof sizes)[number]>("md");
const variant = ref<(typeof variants)[number]>("outline");
const options = [
  { value: "beijing", label: "Beijing" },
  { value: "shanghai", label: "Shanghai" },
];
const cascaderOptions = [{ value: "china", label: "China", children: options }];

const inputValue = ref("Beijing");
const selectValue = ref("beijing");
const cascaderValue = ref("beijing");
const selectMultiple = ref(["beijing", "shanghai"]);
const cascaderMultiple = ref(["beijing", "shanghai"]);
const selectOverflow = ref(["long", "beijing", "shanghai"]);
const cascaderOverflow = ref(["long", "beijing", "shanghai"]);
const selectedOptions = [
  ...options,
  {
    value: "long",
    label:
      "A very long selected option label for overflow comparison — full text preview keeps the selected value unchanged.",
  },
];
const selectedCascaderOptions = [
  { value: "china", label: "China", children: selectedOptions },
];
function resetSelections() {
  inputValue.value = "Beijing";
  selectValue.value = "beijing";
  cascaderValue.value = "beijing";
  selectMultiple.value = ["beijing", "shanghai"];
  cascaderMultiple.value = ["beijing", "shanghai"];
  selectOverflow.value = ["long", "beijing", "shanghai"];
  cascaderOverflow.value = ["long", "beijing", "shanghai"];
}
</script>
<template>
  <section
    aria-label="Form control size comparison"
    class="control-size-comparison"
  >
    <c-space wrap :size="12">
      <c-radio-group v-model="size" aria-label="Comparison size">
        <c-radio v-for="item in sizes" :key="item" :value="item">{{
          item
        }}</c-radio>
      </c-radio-group>
      <c-radio-group v-model="variant" aria-label="Comparison variant">
        <c-radio v-for="item in variants" :key="item" :value="item">{{
          item
        }}</c-radio>
      </c-radio-group>
    </c-space>
    <div class="control-size-comparison__grid">
      <div data-control="Input">
        <p>Input</p>
        <c-input :size="size" :variant="variant" placeholder="Input" />
      </div>
      <div data-control="Button">
        <p>Button</p>
        <c-button :size="size" variant="outline">Button</c-button>
      </div>
      <div data-control="Select">
        <p>Select</p>
        <c-select
          :size="size"
          :variant="variant"
          :options="options"
          placeholder="Select"
        />
      </div>
      <div data-control="Date">
        <p>Date</p>
        <c-date :size="size" :variant="variant" placeholder="Date" />
      </div>
      <div data-control="Time">
        <p>Time</p>
        <c-time :size="size" :variant="variant" placeholder="Time" />
      </div>
      <div data-control="InputNumber">
        <p>InputNumber</p>
        <c-input-number :size="size" :variant="variant" placeholder="Number" />
      </div>
      <div data-control="AutoComplete">
        <p>AutoComplete</p>
        <c-auto-complete
          :size="size"
          :variant="variant"
          :options="options"
          placeholder="AutoComplete"
        />
      </div>
      <div data-control="Cascader">
        <p>Cascader</p>
        <c-cascader
          :size="size"
          :variant="variant"
          :options="cascaderOptions"
          placeholder="Cascader"
        />
      </div>
      <div data-control="DateRange">
        <p>DateRange</p>
        <c-date-range
          :size="size"
          :variant="variant"
          :placeholder="['Start', 'End']"
        />
      </div>
      <div data-control="TimeRange">
        <p>TimeRange</p>
        <c-time-range
          :size="size"
          :variant="variant"
          :placeholder="['Start', 'End']"
        />
      </div>
    </div>

    <section
      aria-label="Selected control size comparison"
      class="control-size-comparison__states"
    >
      <c-space wrap align="center" :size="12">
        <span>Selected / Clearable / Multiple — 有值、可清空与多选不换行</span>
        <span
          >Hover or focus truncated text; tap on touch screens /
          悬停或聚焦省略正文查看全文；触屏点按查看，点外部关闭</span
        >
        <c-button size="sm" variant="outline" @click="resetSelections"
          >Reset / 恢复选中值</c-button
        >
      </c-space>
      <div class="control-size-comparison__grid">
        <div data-control="InputValue">
          <p>Input · clearable</p>
          <c-input
            v-model="inputValue"
            :size="size"
            :variant="variant"
            clearable
            placeholder="Input value"
          />
        </div>
        <div data-control="ButtonReference">
          <p>Button · reference</p>
          <c-button :size="size" variant="outline">Button</c-button>
        </div>
        <div data-control="SelectValue">
          <p>Select · clearable</p>
          <c-select
            v-model="selectValue"
            :size="size"
            :variant="variant"
            :options="selectedOptions"
            clearable
            placeholder="Select value"
          />
        </div>
        <div data-control="CascaderValue">
          <p>Cascader · clearable</p>
          <c-cascader
            v-model="cascaderValue"
            :size="size"
            :variant="variant"
            :options="selectedCascaderOptions"
            clearable
            placeholder="Cascader value"
          />
        </div>
        <div data-control="SelectMultiple">
          <p>Select · multiple / nowrap</p>
          <c-select
            v-model="selectMultiple"
            :size="size"
            :variant="variant"
            :options="selectedOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Select multiple"
          />
        </div>
        <div data-control="CascaderMultiple">
          <p>Cascader · multiple / nowrap</p>
          <c-cascader
            v-model="cascaderMultiple"
            :size="size"
            :variant="variant"
            :options="selectedCascaderOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Cascader multiple"
          />
        </div>
        <div data-control="SelectOverflow">
          <p>Select · long values / nowrap</p>
          <c-select
            v-model="selectOverflow"
            edit-mode="direct"
            :size="size"
            :variant="variant"
            :options="selectedOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Select long values"
          />
        </div>
        <div data-control="CascaderOverflow">
          <p>Cascader · long values / nowrap</p>
          <c-cascader
            v-model="cascaderOverflow"
            edit-mode="direct"
            :size="size"
            :variant="variant"
            :options="selectedCascaderOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Cascader long values"
          />
        </div>
      </div>
    </section>
  </section>
</template>
<style scoped>
.control-size-comparison,
.control-size-comparison__states {
  display: grid;
  gap: 24px;
}
.control-size-comparison__grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
  align-items: start;
  gap: 24px 16px;
}
.control-size-comparison__grid > div {
  min-width: 0;
}
.control-size-comparison__grid p {
  margin: 0 0 12px;
  font-size: 14px;
  line-height: 20px;
}
.control-size-comparison__grid :deep(.c-input-number),
.control-size-comparison__grid :deep(.c-auto-complete) {
  width: 100%;
}
</style>
```

### 选择类型

通过 `type` 切换日 / 周 / 月 / 年 / 季度。

Example source: src/date/__demos__/type.vue

```vue
<template>
  <c-space direction="column" fill>
    <c-date v-model="date" style="width: 200px" clearable />
    <c-date v-model="week" type="week" style="width: 200px" clearable />
    <c-date v-model="month" type="month" style="width: 200px" clearable />
    <c-date v-model="year" type="year" style="width: 200px" clearable />
    <c-date v-model="quarter" type="quarter" style="width: 200px" clearable />
  </c-space>
</template>

<script setup>
import { ref } from 'vue'

const date = ref()
const week = ref()
const month = ref()
const year = ref()
const quarter = ref()
</script>
```

### 月份标签

字段通过 `date-picker-props`（Date）或 `date-range-picker-props`（DateRange）配置面板的该选项。

`abbreviation`（boolean，默认 `true`）控制日历月份网格的缩写；`false` 使用当前 Locale 的完整月份名。运行时修改立即生效，不改变值，也不触发选择事件。此开关不影响星期标签、标题、滚轮列或值格式。范围日历以顶层选项为准，嵌套日历参数不能覆盖。

Example source: src/date/picker/__demos__/month-labels.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const abbreviation = ref(true)
</script>

<template>
  <c-checkbox v-model="abbreviation">月份缩写</c-checkbox>
  <c-date-picker type="month" picker-value="2025-01" :abbreviation="abbreviation" :disable-confirm="false" />
  <c-date-range-picker type="month" :abbreviation="abbreviation" />
</template>
```

### 语言与嵌套日历参数

日期标签、标题和动作接入各库的全局 Locale 与既有 Provider。Cedar 删除日期组件级 `locale`，不保留覆盖字典或兼容别名。切换语言不会选择或提交日期。

### 日期语言的实例隔离

日期所有者读取本库全局 Locale/Provider，周起始日由各实例 `day-start-of-week` 管理。不切换宿主 Dayjs 默认语言，也不覆盖宿主基础语言配置；只在各库命名空间下注册日期语言元数据，组件实例与源码不跨库共享。

`value-format` 是稳定英文日期协议（包括月份名称 token），`format` 的显示及手输文本使用界面语言。切换语言不会改写模型，也不会令英文月份名称模型失效。默认数字协议、Date 对象、时间戳不变。中文核心语言与 Maple 内置语言数据已接入；其他日期格式优先使用已注册 Dayjs 语言数据，未加载的语言安全回退英文。

周号和周比较不再依赖全局周起始设置，跨年同周号不能被误判成同一周。两个不同周起始实例的挂载、更新和卸载互不影响。

Example source: src/date/picker/__demos__/locale-isolation.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const first = ref('2021-01-03')
const second = ref('2021-01-03')
const monday = ref(true)
const monthModel = ref('2025 January 15')
</script>

<template>
  <p>两个实例独立管理周起始日。可切换顶部语言，模型不随展示语言改变。</p>
  <c-date v-model="first" type="week" :date-picker-props="{ dayStartOfWeek: 0 }" />
  <c-date v-model="second" type="week" :date-picker-props="{ dayStartOfWeek: monday ? 1 : 2 }" />
  <c-checkbox v-model="monday">第二个实例周一起始（关闭为周二）</c-checkbox>
  <c-date-picker type="week" v-model="first" picker-value="2021-01-01" :day-start-of-week="0" />
  <c-date-picker type="week" v-model="second" picker-value="2021-01-01" :day-start-of-week="monday ? 1 : 2" />
  <c-date v-model="monthModel" value-format="YYYY MMMM DD" format="YYYY MMMM DD" />
  <p>月份名称模型（稳定英文协议）：{{ monthModel }}</p>
</template>
```

## 时间与选择规则

### 带时间

<!-- demo-config-notes:start -->

#### 本组配置对照

| 配置           | 作用                                                    | 相关示例 |
| -------------- | ------------------------------------------------------- | -------- |
| `show-time`    | 选择时间                                                | 带时间   |
| `format`       | 展示格式                                                | 带时间   |
| `value-format` | 模型与事件的格式，可为自定义日期格式、Date 或 timestamp | 带时间   |
| `clearable`    | 可清除                                                  | 带时间   |

<!-- demo-config-notes:end -->

Example source: src/date/__demos__/show-time.vue

```vue
<script setup>
import { ref } from 'vue'
const minute = ref()
const second = ref()
</script>

<template>
  <c-space direction="column" size="lg">
    <span>分钟精度：显式设置显示格式和模型格式</span>
    <c-date v-model="minute" show-time format="YYYY-MM-DD HH:mm" value-format="YYYY-MM-DD HH:mm" clearable />
    <span>已提交值：{{ minute || '未选择' }}</span>
    <span>秒精度：Cedar 的日期时间默认格式</span>
    <c-date v-model="second" show-time clearable />
    <span>已提交值：{{ second || '未选择' }}</span>
  </c-space>
</template>
```

### 内嵌时间与滚轮展示

`time-picker-props` 使用 `DateTimePickerOptions`：`use12Hours`、`step`、`hideDisabledOptions`、`class`、`style`。仅配置时间展示；日期值、格式/秒精度、约束和确认仍由日期所有者管理。`step` 负责展示采样，不静默修正外部值。未知参数及监听函数不转发。

Example source: src/date/picker/__demos__/time-presentation.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'

const use12Hours = ref(true)
const timeOptions = { step: { minute: 15 }, hideDisabledOptions: true }
</script>

<template>
  <c-checkbox v-model="use12Hours">十二小时展示</c-checkbox>

  <c-date-picker
    model-value="2025-01-05 13:30"
    show-time
    format="YYYY-MM-DD HH:mm"
    value-format="YYYY-MM-DD HH:mm"
    :time-picker-props="{ ...timeOptions, use12Hours }"
  />
</template>
```

### 真实端侧能力

Cedar 不公开 `Date.pickerProps`、`DateRange.pickerProps` 或 `DateRange.datePickerProps`：PC 字段不渲染移动滚轮或范围内部的移动日历插件，原无效参数已删除且无兼容别名。Maple 保留这些真实扩展，使用 DateWheelOptions 与 DateRangeCalendarOptions。两端通过 `Date.datePickerProps` / `DateRange.dateRangePickerProps` 配置完整面板，`timePickerProps` 配置内嵌时间展示。初始日期时间放在顶层 `defaultValue`，不要放在 `timePickerProps.defaultValue` 中。

## 值模型与输入

### 模型格式与显示格式

<!-- demo-config-notes:start -->

#### 本组配置对照

| 配置                | 作用                                                    | 相关示例                                                               |
| ------------------- | ------------------------------------------------------- | ---------------------------------------------------------------------- |
| `format`            | 展示格式                                                | 模型格式与显示格式、字符串模型：年月日、年月与月日范围、手输与面板选择 |
| `value-format`      | 模型与事件的格式，可为自定义日期格式、Date 或 timestamp | 模型格式与显示格式、字符串模型：年月日、年月与月日范围                 |
| `type`              | 选择类型                                                | 字符串模型：年月日、年月与月日范围、周与季度手输                       |
| `date-picker-props` | 面板展示选项                                            | 周与季度手输                                                           |

<!-- demo-config-notes:end -->

Example source: src/date/__demos__/value-formats.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const timestamp = ref(new Date(2026, 8, 15).getTime())
const objectValue = ref(new Date(2026, 8, 16))
</script>
<template>
  <div class="date-contract-demo">
    <c-date v-model="timestamp" value-format="timestamp" format="DD/MM/YYYY" />
    <p>时间戳模型：{{ timestamp }}</p>
    <c-date v-model="objectValue" value-format="Date" format="YYYY年MM月DD日" />
    <p>Date 对象模型：{{ objectValue }}</p>
  </div>
</template>
<style scoped>
.date-contract-demo { display: flex; flex-direction: column; gap: 12px; }
.date-contract-demo p { margin: 0; }
</style>
```

### 字符串模型：年月日、年月与月日范围

`format` 决定显示，`value-format` 决定提交值。下面直接得到 `"2026-09-10"`、`"2026-09"` 或 `["09-10", "10-10"]`，无需将 Date 再转换。日期范围使用数组。`MM-DD` 没有年份，解析时使用当前年，不能表示跨年先后或某个明确年份的 2 月 29 日；有跨年、时区或闰年要求时保留 `YYYY-MM-DD`，在业务提交时单独映射月日。默认仍是 page，未指定 timeZone 使用浏览器本地时区。

Example source: src/date/__demos__/string-values.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
const date = ref("2026-09-10");
const month = ref("2026-09");
const range = ref(["09-10", "10-10"]);
</script>
<template>
  <c-space direction="column">
    <c-date v-model="date" format="YYYY-MM-DD" value-format="YYYY-MM-DD" />
    <p>String: {{ JSON.stringify(date) }}</p>
    <c-date
      v-model="month"
      type="month"
      format="YYYY-MM"
      value-format="YYYY-MM"
    />
    <p>Month string: {{ JSON.stringify(month) }}</p>
    <c-date-range v-model="range" format="MM-DD" value-format="MM-DD" />
    <p>Month/day array: {{ JSON.stringify(range) }}</p>
  </c-space>
</template>
```

### 周与季度手输

默认周展示 `gggg-wo` 按当前界面语言与实例周起始解析为该周的第一天，模型仍为 `YYYY-MM-DD`。中文周一起始的 `2020-53周` 提交 `2020-12-28`；不存在的周、错误序数后缀不提交。默认季度 `YYYY-[Q]Q`（如 `2025-Q2`）严格解析为首月，模型 `YYYY-MM`（`2025-04`）。手输继续遵守禁用、边界和范围顺序，不自动交换端点。

自定义周/季度展示可以使用 Dayjs 支持的普通日期 token；任意自定义周序数格式没有逆解析协议。`format` 为函数时请设置 `input-editable=false`，通过面板选择。

Example source: src/date/picker/__demos__/period-text.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'

const week = ref('2020-12-28')
const quarter = ref('2025-04')
const range = ref(['2020-12-28', '2021-01-04'])
</script>

<template>
  <p>周一起始，中文可手输 2020-53周；切换英文后使用英文序数。提交为该周起始日。</p>
  <c-date v-model="week" type="week" :date-picker-props="{ dayStartOfWeek: 1 }" />
  <p>周模型：{{ week }}</p>
  <c-date v-model="quarter" type="quarter" />
  <p>季度输入 2025-Q2，模型为季度首月：{{ quarter }}</p>
  <c-date-range v-model="range" type="week" :date-range-picker-props="{ dayStartOfWeek: 1 }" />
  <p>周范围不自动交换手输端点：{{ range }}</p>
</template>
```

日期字段的可编辑条件由公共所有者统一管理：`input-editable` 默认 true，函数 `format` 不可反解析，因此输入只读。两端单值/范围的 Enter、失焦、组合输入、受控拒绝回写、禁用与范围顺序通过同一组原生输入测试；Maple 多选拼接文本保持只读，由面板选择。

### 手输与面板选择

Example source: src/date/picker/__demos__/text-entry.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'

const value = ref('2025-01-15')
const range = ref(['2025-01-15', '2025-01-20'])
const panelOnly = ref(false)
</script>

<template>
  <p>输入 DD/MM/YYYY，Enter 或失焦提交；非法日期和范围外输入恢复模型显示。</p>
  <c-date v-model="value" format="DD/MM/YYYY" min="2025-01-10" max="2025-01-25" :input-editable="!panelOnly" />
  <p>模型：{{ value }}</p>
  <c-switch v-model="panelOnly" />
  <p>仅面板选择：{{ panelOnly }}</p>
  <c-date-range v-model="range" format="DD/MM/YYYY" :disabled="[true, false]" :input-editable="!panelOnly" />
  <p>起点锁定，终点不能早于起点：{{ range }}</p>
</template>
```

## 交互与字段配置

### 交互状态对比

<!-- demo-config-notes:start -->

#### 本组配置对照

| 配置                | 作用                                                    | 相关示例                             |
| ------------------- | ------------------------------------------------------- | ------------------------------------ |
| `disabled`          | 禁用                                                    | 交互状态对比、统一字段与提交         |
| `open`              | 弹层显隐                                                | 受控关闭被拒绝、透传配置边界与优先级 |
| `date-picker-props` | 面板展示选项                                            | 字段视口与快捷项事件、字段与面板边界 |
| `placeholder`       | 占位                                                    | 统一字段与提交、字段与面板边界       |
| `value-format`      | 模型与事件的格式，可为自定义日期格式、Date 或 timestamp | 交互状态对比                         |
| `readonly`          | 只读                                                    | 交互状态对比                         |

<!-- demo-config-notes:end -->

在同一实例上切换禁用、只读和错误状态后再操作控件，比较可编辑性和交互反馈。恢复开关位于目标控件外；错误外观本身不会执行校验。

<details>
<summary>配置说明与使用限制</summary>

#### 交互状态切换

适用于选择单个日期。调整禁用、只读、错误反馈，用相同数据观察变化。控制区始终可用，可以随时恢复编辑；错误外观本身不会触发表单校验。

</details>

Example source: src/date/__demos__/state-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref("2026-10-23");
const __demoState = __demoReactive({
  disabled: false,
  readonly: false,
  error: false,
});
</script>
<template>
  <c-space direction="column" :size="16">
    <c-space wrap>
      <c-checkbox v-model="__demoState['disabled']">disabled</c-checkbox>
      <c-checkbox v-model="__demoState['readonly']">readonly</c-checkbox>
      <c-checkbox v-model="__demoState['error']">error</c-checkbox>
    </c-space>
    <c-date
      v-model="value"
      value-format="YYYY-MM-DD"
      v-bind="__demoState"
    ></c-date>
  </c-space>
</template>
```

### 受控关闭被拒绝

父级可以拒绝 `update:open(false)`，此时面板仍展开。一次选择只能提交并请求关闭一次；受控模型回写相同值不会重置已确认状态。在保持展开时选择新日期会开启新事务，可以再次确认。示例显示模型、提交次数与关闭请求次数。

Example source: src/date/__demos__/rejected-close.vue

```vue
<script setup>
import { ref } from "vue";

const value = ref("2026-09-22");
const open = ref(false);
const closeRequests = ref(0);
const commits = ref(0);

function requestOpen(next) {
  if (next) open.value = true;
  else closeRequests.value++;
}
</script>

<template>
  <c-space direction="column" size="12px">
    <p>关闭请求会被父级拒绝；选择新日期后可再次确认，重复确认不应重复提交。</p>
    <c-date
      v-model="value"
      :open="open"
      @update:open="requestOpen"
      @change="commits++"
    >
      <template #actions="{ confirm, disabled }">
        <c-button :disabled="disabled" @click="confirm()">确认</c-button>
        <c-button @click="open = false">允许关闭</c-button>
      </template>
    </c-date>
    <span data-test="date-transaction-state"
      >值：{{ value }}；提交：{{ commits }}；拒绝关闭：{{ closeRequests }}</span
    >
  </c-space>
</template>
```

### 字段视口与快捷项事件

字段通过嵌套 `date-picker-props` 配置 `pickerValue`、`defaultPickerValue` 和快捷项，不新增第二套顶层视口 Prop。嵌套配置里的监听器不会透传；在字段组件上监听以下事件并回写嵌套 `pickerValue`。

| 事件                  | 说明                             | 参数                              |
| --------------------- | -------------------------------- | --------------------------------- |
| `update:picker-value` | 请求日历视口更新，不改变选择模型 | value: DateSelection              |
| `picker-value-change` | 已请求的视口及展示通知           | value, date(s), formatted text(s) |
| `select-shortcut`     | 接受的快捷项，仍遵守字段确认策略 | shortcut: DateShortcut            |

受控视口拒绝更新时保持原月份，后续回写才更新；快捷项选择先进入字段草稿，默认确认后提交。滚轮/时钟没有日历月份导航能力。

Example source: src/date/picker/__demos__/field-panel-tools.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import type { DateShortcut } from "@cedar-design/ui";

const selected = ref("2025-01-15");
const viewport = ref("2025-01-01");
const acceptNavigation = ref(true);
const notice = ref("");
const shortcutNotice = ref("");
const shortcuts: DateShortcut[] = [
  { label: "下个月", value: "2025-02-15" },
  { label: "不可选", value: "2025-03-01", disabled: true },
];
function navigate(value: unknown) {
  if (acceptNavigation.value && typeof value === "string")
    viewport.value = value;
}
function observe(_value: unknown, _dates: unknown, texts: unknown) {
  notice.value = String(texts);
}
function choose(shortcut: DateShortcut) {
  shortcutNotice.value = String(shortcut.label);
}
</script>

<template>
  <c-checkbox v-model="acceptNavigation"> 接受视口请求</c-checkbox>
  <c-date
    v-model="selected"
    :input-editable="false"
    format="DD/MM/YYYY"
    :date-picker-props="{ pickerValue: viewport, shortcuts }"
    @update:picker-value="navigate"
    @picker-value-change="observe"
    @select-shortcut="choose"
  />
  <p>选择模型：{{ selected }}；受控视口：{{ viewport }}</p>
  <p>视口通知：{{ notice }}；快捷项通知：{{ shortcutNotice }}</p>
  <p>
    导航不改变选择模型；拒绝视口请求后，日历仍显示原月份。快捷项先选择草稿，确认后提交。
  </p>
</template>
```

### 展示模式的所有权

Cedar 只实现桌面日历，不公开移动 `edit-mode`。Maple 在字段/纯面板根选择真实展示模式；字段嵌套 `DatePickerOptions` / `DateRangePickerOptions` 不包含 presentation，两库复制的过滤器均拒绝嵌套选择器，不通过隐式覆盖保留无效 API。

### 周起始日的响应式展示

`dayStartOfWeek` 更新时，日历表头与日期列位置同步更新，不改变选中值或提交草稿。纯面板使用根属性，字段通过 `datePickerProps` / `dateRangePickerProps` 配置；滚轮视图不使用星期列。

### 动态日期限制

更新或移除 `min` / `max` 会重新计算可选日期，不自动修改已有模型或草稿。面板导航与候选日期校验是不同职责，已有值超出新限制时也不会被静默重写；用户重新选择或确认时按当前限制校验。

### Form 字段展示与确认

本组件支持 `edit-mode`，字段 > FormItem > Form 逐层继承；未指定时为 `direct`，保留原有交互。支持值：`direct / click / dblclick`。非 direct 编辑模式通过字段值入口打开编辑面板，并维护单份草稿；确认后才更新 v-model，取消、重置或启用 readPretty 时丢弃草稿。

Cedar 使用 edit-mode="click" / "dblclick" 在字段附近打开编辑浮层，Enter/F2 也可进入；取消/Escape 丢弃草稿，确认后提交。readPretty 为独立阅读属性，与 readonly、disabled 分开。

`before-commit(value, { previousValue, signal })` 可拦截弹层保存；FormItem 先校验候选值，失败保持编辑。`open / default-open / update:open` 控制编辑层。`#read="{ value, text }"` 可自定义阅读内容。集中示例见 Form 的“各类字段统一展示”。

日期／时间字段在 inline 下沿用原确认策略；在 click/dblclick 编辑展示中，内部纯面板隐藏确认工具栏，由编辑层提供唯一一组确认／取消。独立 DatePicker、DateRangePicker、TimePicker、TimeRangePicker 保留原有面板 API 和确认行为，不继承 Form 的字段展示。

独立 DatePicker / DateRangePicker 与 inline 共用日历基准宽度（每个 265px）。单日期带时间时，宽屏下日历与时间列左右排列；范围在宽屏保留两个并排日历。面板会按窄容器换行，侧边快捷项另占一列，不压缩日历；确认与 actions 插槽保持由面板自身管理。

`read-pretty` 为独立布尔属性，与 `readonly`、`disabled` 同级；字段 > FormItem > Form 继承，显式 `false` 覆盖父级。默认 `false`。纯阅读不显示编辑器。

### 统一字段与提交

Date / DateRange / Time / TimeRange 使用相同的 PickerField → FieldDecorator 字段链路。桌面支持键入有效值后回车或失焦提交；有确认按钮的面板只在确认时写回，Escape 或外部关闭丢弃草稿。清除立即提交空值。面板组件不再提供 `hideTrigger` 双模式，自定义触发器使用字段的默认插槽。

Example source: src/date/__demos__/field-protocol.vue

```vue
<script setup>
import { ref } from 'vue'
const disabled = ref(false)
const date = ref('2026-09-22')
const dateRange = ref(['2026-09-22', '2026-09-24'])
const time = ref('09:00:00')
const timeRange = ref(['23:00:00', '01:00:00'])
</script>

<template>
  <c-space direction="column">
    <p>范围字段：点击右侧输入可从结束端选择；Tab 切换两端不提交，回车或离开整个字段再提交。</p>
    <span>禁用字段</span>
    <c-switch v-model="disabled" aria-label="禁用字段" />
    <c-date v-model="date" :disabled="disabled" clearable placeholder="日期" />
    <c-date-range v-model="dateRange" :disabled="disabled" clearable :placeholder="['开始日期', '结束日期']" />
    <c-time v-model="time" :disabled="disabled" clearable placeholder="时间" />
    <c-time-range v-model="timeRange" :disabled="disabled" clearable show-next-day :placeholder="['开始时间', '结束时间']" />
    <p>日期：{{ date || '未选择' }}；日期范围：{{ dateRange }}</p>
    <p>时间：{{ time || '未选择' }}；时间范围：{{ timeRange }}</p>
  </c-space>
</template>
```

### 字段与面板边界

字段保留输入和浮层状态；嵌套面板参数只接受展示选项，不能覆盖顶层模型、格式或校验规则。

Example source: src/date/picker/__demos__/entry-boundary.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import type { DateSelection } from "@cedar-design/ui";
const limited = ref(true);
const fieldValue = ref<DateSelection>("2025-02-12");
const panelValue = ref<DateSelection>("2025-02-12");
const week = ref<0 | 1 | 6>(1);
</script>

<template>
  <div class="entry-demo">
    <p>仅允许选择 2025 年 2 月；移除限制不会改变已有选中值。</p>
    <c-button @click="limited = !limited">{{
      limited ? "移除日期限制" : "恢复日期限制"
    }}</c-button>
    <c-space wrap>
      <c-button @click="week = 0">周日起始</c-button>
      <c-button @click="week = 1">周一起始</c-button>
      <c-button @click="week = 6">周六起始</c-button>
    </c-space>
    <div>
      <p>字段：管理输入与浮层；面板参数放在 date-picker-props。</p>
      <c-date
        :min="limited ? '2025-02-01' : undefined"
        :max="limited ? '2025-02-28' : undefined"
        v-model="fieldValue"
        :date-picker-props="{ dayStartOfWeek: week }"
        placeholder="选择日期"
      />
    </div>
    <div>
      <p>纯面板：直接嵌入页面，不使用 open / popup-container。</p>
      <c-date-picker
        :min="limited ? '2025-02-01' : undefined"
        :max="limited ? '2025-02-28' : undefined"
        v-model="panelValue"
        :day-start-of-week="week"
        :disable-confirm="false"
      />
      <p>已提交：{{ panelValue }}</p>
    </div>
  </div>
</template>

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

### 日期值格式

两端使用独立复制的日期值、约束、面板和字段主体。年/月/日模型格式为 `YYYY` / `YYYY-MM` / `YYYY-MM-DD`，日期时间默认含秒；`format="YYYY-MM-DD HH:mm"` 与 `value-format="YYYY-MM-DD HH:mm"` 使用分钟字符串。`format` 只控制显示，`value-format` 控制模型和事件，支持自定义格式、`Date` 与 `timestamp`。Cedar 另提供周/季度面板；Maple 另提供移动端滚轮和时钟展示。

### 透传配置边界与优先级

建议使用 `DatePopupOptions` 声明 popup-props；仅用于 inline 锚定弹层的允许展示/定位配置。open/defaultOpen、disabled/readonly、modelValue、值格式、日期规则及通知监听由字段管理，已有 datePresentationOptions 会过滤托管字段和 onXxx 监听。popup-container 顶层明确传入时优先（包括 false），否则回退 popupProps.popupContainer；popupClass 与内部类合并。trigger、closeOnClickReference、preventFocus、popupOffset 由字段展示层固定（偏移当前为 4）；Maple 还固定 unmountOnClose=true。新类型为两端共同的安全子集，不能设置这些固定项；Cedar 旧配置可透传的 unmountOnClose 不受本次影响。可使用 popupTranslate 定制附加平移。其他有效展示字段保持原透传。

本次仅新增可主动选用的专用类型，不收窄已发布的宽属性类型，不增加运行时过滤、不改变覆盖顺序；旧业务写法继续可编译。若直接使用旧宽属性，内部托管字段仍可能通过类型检查，但不代表能控制内部状态。

```ts
import type { DatePopupOptions } from "@cedar-design/ui";
```

Example source: src/date/__demos__/passthrough-options.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import type { DatePopupOptions } from "@cedar-design/ui";
const open = ref(false);
const popupOptions: DatePopupOptions = {
  placement: "top-start",
  popupTranslate: [0, -8],
  popupContainer: false,
};
</script>
<template>
  <c-space direction="column" fill>
    <c-button @click="open = !open">{{
      open ? "关闭面板" : "打开面板"
    }}</c-button>
    <c-date
      edit-mode="direct"
      v-model:open="open"
      :popup-props="popupOptions"
      aria-label="透传配置示例"
    />
    <p role="status">顶层 open：{{ open }}；嵌套配置：向上展开并调整偏移。</p>
  </c-space>
</template>
```
日期范围还会保留未改动端点的原始 Date／时间戳及隐藏毫秒，避免重复小时中的第二次发生被错误转换成第一次。夏令时仅跳过半小时的地区仍可选择剩余有效分钟；交互范围排序比较真实时刻，交换日期但保留时间时会重新计算目标日期的时区偏移。

### 复制与编辑

open-trigger-target="icon" 时，输入区可以编辑或复制，只有右侧选择按钮响应点击打开。关闭手输或搜索后，已有文本仍可复制。

Example source: src/date/__demos__/open-trigger-target.vue

```vue
<template>
  <c-space direction="column">
    <c-radio-group
      v-model="target"
      :options="[
        { label: '整个字段', value: 'field' },
        { label: '仅右侧图标', value: 'icon' },
      ]"
    />
    <label><c-switch v-model="editable" /> 允许编辑 / 搜索</label>
    <c-date
      v-model="value"
      edit-mode="direct"
      :open-trigger-target="target"
      :input-editable="editable"
    />
    <p>关闭编辑后，可以复制已有文本；仅图标模式下编辑不会展开。</p>
  </c-space>
</template>
<script setup lang="ts">
import { ref } from "vue";
const target = ref<"field" | "icon">("icon");
const editable = ref(true);
const value = ref("2026-10-27");
</script>
```

### 共享字段加载

`loading` 控制共享字段加载状态；`loading-mode` 为 `default`（指示器）或 `line`（底部不定进度线），默认 `default`。渲染统一由 FieldDecorator 负责，不隐式改变 disabled/readonly；需要禁止编辑时单独设置。

## 阅读方向

组件继承最近的 `dir="ltr|rtl"`，支持运行时切换与局部方向覆盖。日历日期、月份、年份按阅读顺序排列，前后翻页图形随方向调整，日期值与起止顺序保持原义。分页网格中左右键按视觉方向移动焦点，上下键移动一行，Home/End 移至当前行首尾并跳过禁用项；焦点移动不提交，Enter/Space 沿用选值行为，边界停留在当前显示网格。快捷区 `shortcuts-position="left|right"` 保持物理侧，底部使用 `bottom`。弹层继承字段来源方向。

## API

### 空值识别与阅读空文案

`empty-values` 用于空值识别，`empty-value` 保留原清空输出；`empty-text` 仅在 `read-pretty` 空内容下展示，默认 `'-'`，字段 > FormItem > Form，自定义 read 插槽优先。显式配置 empty-values 后，内置 required 接入该策略，自定义校验仍收到原值。详见[统一说明](llms/zh-CN/guide/empty-values.md)。

| 参数         | 类型               | 缺省与范围                                            |
| ------------ | ------------------ | ----------------------------------------------------- |
| empty-values | readonly unknown[] | 字段 > FormItem > Form > 组件族默认；完整覆盖，不合并 |
| empty-text   | string             | 字段 > FormItem > Form > '-'；显式 '' 有效            |

以上是字段展示层 API；纯面板不因此新增阅读模式。Form 与 FormItem 提供继承配置。empty-value 的现有类型与默认输出仍按该组件原 API 执行。

### Props

| 参数                  | 说明                                                                                   | 类型                                       | 默认值    |
| --------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------ | --------- |
| `open-trigger-target` | 打开面板的点击区域；field 为整个字段，icon 仅右侧选择按钮。不影响键盘展开及受控 open。 | `'field' \| 'icon'`                        | `'field'` |
| `model-value`         | 绑定值                                                                                 | `Date \| string \| number`                 | `-`       |
| `type`                | 选择类型                                                                               | `date \| week \| month \| year \| quarter` | `date`    |
| `open`                | 弹层显隐                                                                               | `boolean`                                  | `-`       |
| `clearable`           | 可清除                                                                                 | `boolean`                                  | `true`    |
| `disabled`            | 禁用                                                                                   | `boolean`                                  | `false`   |
| `readonly`            | 只读                                                                                   | `boolean`                                  | `false`   |
| `size`                | 尺寸                                                                                   | `xs \| sm \| md \| lg \| xl`               | `-`       |
| `variant`             | 输入框变体                                                                             | `filled \| outline \| standard`            | `filled`  |
| `placeholder`         | 占位                                                                                   | `string`                                   | `-`       |
| `disabled-date`       | 禁用日期                                                                               | `Function`                                 | `-`       |
| `format`              | 展示格式                                                                               | `string \| Function`                       | 随 `type` |
| `show-time`           | 选择时间                                                                               | `boolean`                                  | `false`   |
| `date-picker-props`   | 面板展示选项                                                                           | `DatePickerOptions`                        | `{}`      |

### 日期族统一契约

| 参数              | 说明                                                                                                                                           | 类型                                               | 默认值  |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- | ------- |
| `default-value`   | 非受控初始值，仅初始化读取                                                                                                                     | DateValue / DateValue[]                            | —       |
| `value-format`    | 模型与事件的格式，可为自定义日期格式、Date 或 timestamp                                                                                        | string                                             | 随 type |
| `min` / `max`     | 包含端点的边界；字符串按 value-format 解析                                                                                                     | DateValue                                          | —       |
| `disabled-time`   | 当前日期、端点的时间禁用列表                                                                                                                   | (date: Date, side: DateSide) => DateDisabledTime   | —       |
| `disable-confirm` | 选择后立即提交                                                                                                                                 | boolean                                            | false   |
| `default-open`    | 非受控初始展开                                                                                                                                 | boolean                                            | false   |
| `popup-props`     | 可选的字段浮层展示配置，placement 默认 bottom-start；交给底层 Trigger 自动定位，可覆盖首选方位；不增加顶层 placement，不允许覆盖字段状态和规则 | object                                             | {}      |
| `popup-container` | 挂载目标；顶层优先，支持 false 原地渲染                                                                                                        | string / HTMLElement / (() => HTMLElement) / false | —       |

`DateValue = Date | string | number`。单值清除为 undefined，范围清除为 []。
`disabledDate(date, side)` 和 `disabledTime(date, side)` 的 date 始终为 Date，side 为 start/end。
时间回调返回 `disabledHours()`、`disabledMinutes(hour)`、`disabledSeconds(hour, minute)` 数字列表。
非法日期、不完整或逆序范围不能提交；确认时重新验证动态禁用规则。范围锁定端点不能被清除或改动。
嵌套面板 props 只配置展示，不得覆盖顶层 model-value、格式、边界、禁用规则或控制事件。

### Events

| 事件                          | 说明                 | 参数                              |
| ----------------------------- | -------------------- | --------------------------------- |
| `update:model-value`          | 写入模型             | value                             |
| `select`                      | 选择草稿，不等于提交 | value, date(s), formatted text(s) |
| `change`                      | 有效值正式变化       | value, date(s), formatted text(s) |
| `update:open` / `open-change` | 展开状态变化         | open: boolean                     |
| `clear`                       | 清除                 | 无                                |
| `focus` / `blur`              | 整个字段的焦点边界   | 无                                |
| `click`                       | 点击字段             | event                             |

桌面支持键盘编辑。默认面板先编辑草稿再确认；设置 disable-confirm 可直接提交。Escape 或关闭会丢弃草稿。focus(index = 0) 定位起止输入，blur() 关闭浮层。

## 显式时区

`timeZone` 接受 IANA 名称，例如 `Asia/Shanghai`。Date 与毫秒时间戳表示真实时刻，字符串表示目标时区的当地时间；展示、手输、min/max、快捷项和禁用规则遵守同一协议，事件 Date 保留真实时刻。未设置时保持本地时区行为。不存在的夏令时时间禁止提交，重复时间取第一次，非法时区禁止提交。Maple 的 scroll / line 属于移动日历呈现能力，桌面端继续使用现有面板。

## 配置清空后的值

`empty-value` 指定当前组件已有清空动作的输出；省略时采用该组件默认返回。具体类型以组件 API 为准。它不改变 empty-values 的识别规则，也不改变 Form reset 的初始值。

`empty-value` 可显式设为 `null`（或 `() => null`），清空时原样提交 null；省略时保留组件原默认值。界面把 null 显示为空，不会把普通输入的空字符串自动转成 null。支持弹出编辑的字段中，清空先修改草稿，确认后提交，取消则保留原值。

### 方位语义与配置入口

Date 字段默认从输入框下方 bottom-start 打开。需要时通过 popupProps.placement 覆盖首选方位，由底层 Trigger 定位；不是透传给 Popup 或 Popover。DatePicker 是独立日期面板，没有输入框锚点，不能把旧 date/picker 目录中的 placement 当成当前 DatePicker 的公开属性。

---

Document: llms/zh-CN/components/descriptions.md

<!-- Source: src/descriptions/README.md; locale: zh-CN; page: /components/descriptions/ -->

# Descriptions

一般用于详情页的信息展示。

## 基础示例

### 基础用法

简单地成组展示多个只读字段，一般用于详情页的信息。

Example source: src/descriptions/__demos__/basic.vue

```vue
<template>
  <c-space direction="column" fill size="lg">
    <c-descriptions :data="data" title="User Info" />
    <c-descriptions :column="{ xs: 1, md: 3, lg: 4 }" title="User Info">
      <c-descriptions-item v-for="item of data" :key="item.label" :label="item.label" :span="item.span ?? 1">
        <c-tag>{{ item.value }}</c-tag>
      </c-descriptions-item>
    </c-descriptions>
  </c-space>
</template>

<script lang="ts" setup>
const data = [
  {
    label: 'Name',
    value: 'Socrates',
  },
  {
    label: 'Mobile',
    value: '123-1234-1234',
  },
  {
    label: 'Residence',
    value: 'Beijing',
  },
  {
    label: 'Hometown',
    value: 'Beijing',
  },
  {
    label: 'Address',
    value: 'Yingdu Building, Zhichun Road, Beijing',
  },
]
</script>
```

## 布局与排列

### 标签文本对齐

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `data` | 描述列表的数据 | 标签文本对齐、布局模式 |
| `title` | 描述列表的标题 | 标签文本对齐、布局模式 |
| `layout` | 描述列表的排列方式 | 标签文本对齐、布局模式 |
| `align` | 文字的对齐位置 | 标签文本对齐 |
| `size` | 描述列表的大小 | 布局模式 |
| `bordered` | 是否显示边框 | 布局模式 |
<!-- demo-config-notes:end -->

标签文本可以设置左对齐右对齐，也可以设置垂直的排列方式。

Example source: src/descriptions/__demos__/label-text-alignment.vue

```vue
<template>
  <c-space direction="column" size="lg">
    <c-descriptions :data="data" align="right" title="User Info" />
    <c-descriptions :align="{ label: 'right' }" :data="data" title="User Info" />
    <c-descriptions :data="data" layout="inline-vertical" title="User Info" />
  </c-space>
</template>

<script lang="ts" setup>
const data = [
  {
    label: 'Name',
    value: 'Socrates',
  },
  {
    label: 'Mobile',
    value: '123-1234-1234',
  },
  {
    label: 'Residence',
    value: 'Beijing',
  },
  {
    label: 'Hometown',
    value: 'Beijing',
  },
  {
    label: 'Address',
    value: 'Yingdu Building, Zhichun Road, Beijing',
  },
]
</script>
```

### 布局模式

有水平排列、垂直排列、行内水平排列、行内垂直、行内自适应分隔排列五种布局模式。

Example source: src/descriptions/__demos__/layout-pattern.vue

```vue
<template>
  <c-radio-group v-model="size" variant="button">
    <c-radio value="xs">xs</c-radio>
    <c-radio value="sm">sm</c-radio>
    <c-radio value="md">md</c-radio>
    <c-radio value="lg">lg</c-radio>
    <c-radio value="xl">xl</c-radio>
  </c-radio-group>
  <div style="margin-top: 20px">
    <c-descriptions :data="data" :size="size" title="User Info (horizontal)" bordered />
    <c-descriptions :data="data" :size="size" title="User Info (inline-horizontal)" layout="inline-horizontal" bordered />
    <c-descriptions :data="data" :size="size" title="User Info (vertical)" layout="vertical" bordered />
    <c-descriptions :data="data" :size="size" title="User Info (inline-vertical)" layout="inline-vertical" bordered />
    <c-descriptions :data="inlineAutoData" :size="size" title="User Info (inline-auto)" layout="inline-auto" />
  </div>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
const size = ref('md')

const data = [
  {
    label: 'Name',
    value: 'Socrates',
  },
  {
    label: 'Mobile',
    value: '123-1234-1234',
  },
  {
    label: 'Residence',
    value: 'Beijing',
  },
  {
    label: 'Hometown',
    value: 'Beijing',
  },
  {
    label: 'Address',
    value: 'Yingdu Building, Zhichun Road, Beijing',
  },
]

const inlineAutoData = [
  {
    label: 'Name:',
    value: 'Socrates',
  },
  {
    label: 'Mobile:',
    value: '123-1234-1234',
  },
  {
    label: 'Residence:',
    value: 'Beijing',
  },
]
</script>
```

## 内容与展示

### 常用案例

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `data` | 描述列表的数据 | 常用案例、带边框样式 |
| `title` | 描述列表的标题 | 常用案例、带边框样式 |
| `column` | 每行放置的数据个数。2.20.0 版本支持响应式配置，配置可参考 Grid | 常用案例 |
| `size` | 描述列表的大小 | 常用案例 |
| `bordered` | 是否显示边框 | 带边框样式 |
<!-- demo-config-notes:end -->

单列的描述列表样式。

Example source: src/descriptions/__demos__/singel-column-style.vue

```vue
<template>
  <c-radio-group v-model="size" variant="button">
    <c-radio value="xs">xs</c-radio>
    <c-radio value="sm">sm</c-radio>
    <c-radio value="md">md</c-radio>
    <c-radio value="lg">lg</c-radio>
    <c-radio value="xl">xl</c-radio>
  </c-radio-group>
  <c-descriptions :column="1" :data="data" :size="size" style="margin-top: 20px" title="User Info" />
</template>

<script lang="ts" setup>
import { ref } from 'vue'
const size = ref('md')
const data = [
  {
    label: 'Name',
    value: 'Socrates',
  },
  {
    label: 'Mobile',
    value: '123-1234-1234',
  },
  {
    label: 'Residence',
    value: 'Beijing',
  },
  {
    label: 'Hometown',
    value: 'Beijing',
  },
  {
    label: 'Address',
    value: 'Yingdu Building, Zhichun Road, Beijing',
  },
]
</script>
```

### 带边框样式

带边框和背景颜色的列表。

Example source: src/descriptions/__demos__/border-background-list.vue

```vue
<template>
  <c-descriptions :data="data" title="User Info" bordered />
</template>

<script lang="ts" setup>
const data = [
  {
    label: 'Name',
    value: 'Socrates',
  },
  {
    label: 'Mobile',
    value: '123-1234-1234',
  },
  {
    label: 'Residence',
    value: 'Beijing',
  },
  {
    label: 'Hometown',
    value: 'Beijing',
  },
  {
    label: 'Address',
    value: 'Yingdu Building, Zhichun Road, Beijing',
  },
]
</script>
```

## 阅读方向

继承最近的 `dir="ltr|rtl"`，支持运行时切换与局部覆盖。标签和值按阅读顺序排列，边界和默认文本对齐使用逻辑起止位置；切换方向不反转记录、列定义或 span 的含义。

## API

### `<Descriptions>` Props

| 属性         | 说明                                                               |                                           类型                                            | 默认值         |
| ------------ | ------------------------------------------------------------------ | :---------------------------------------------------------------------------------------: | :------------- |
| data         | 描述列表的数据                                                     |                                       `DescData[]`                                        | `[]`           |
| column       | 每行放置的数据个数。2.20.0 版本支持响应式配置，配置可参考 Grid     |                                `number \| ResponsiveValue`                                | `3`            |
| title        | 描述列表的标题                                                     |                                         `string`                                          | `-`            |
| layout       | 描述列表的排列方式                                                 | `'horizontal' \| 'vertical' \| 'inline-horizontal' \| 'inline-vertical' \| 'inline-auto'` | `'horizontal'` |
| align        | 文字的对齐位置                                                     |                  `TextAlign \| { label?: TextAlign; value?: TextAlign }`                  | `'left'`       |
| size         | 描述列表的大小                                                     |                          `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'`                           | `-`            |
| bordered     | 是否显示边框                                                       |                                         `boolean`                                         | `false`        |
| label-style  | 数据标签的样式                                                     |                                      `CSSProperties`                                      | `-`            |
| value-style  | 数据内容的样式                                                     |                                      `CSSProperties`                                      | `-`            |
| table-layout | 描述中表格样式的 `layout-fixed`，当设置成 `fixed` 时，宽度会均分。 |                                    `'auto' \| 'fixed'`                                    | `'auto'`       |
| aria-label   | 描述列表的无障碍标签                                               |                                         `string`                                          | `-`            |

### `<Descriptions>` Slots

| 插槽名 |   说明   | 参数                                                   |
| ------ | :------: | ------------------------------------------------------ |
| value  | 数据内容 | value: `string`<br>index: `number`<br>data: `DescData` |
| label  | 数据标签 | label: `string`<br>index: `number`<br>data: `DescData` |
| title  |   标题   | -                                                      |

### `<DescriptionsItem>` Props

| 属性  | 说明     |   类型   | 默认值 |
| ----- | -------- | :------: | :----- |
| span  | 所占列数 | `number` | `1`    |
| label | 标签     | `string` | `-`    |

### `<DescriptionsItem>` Slots

| 插槽名  | 说明 | 参数 |
| ------- | :--: | ---- |
| default | 内容 | -    |
| label   | 标签 | -    |

### DescData

| 参数名 | 描述     | 类型                       | 默认值 |
| ------ | -------- | -------------------------- | :----: |
| label  | 标签     | `string \| RenderFunction` |  `-`   |
| value  | 数据     | `string \| RenderFunction` |  `-`   |
| span   | 所占列数 | `number`                   |  `-`   |

## 类型定义

组件导出以下类型定义

```ts
import type { DescriptionsProps } from "@cedar-design/ui";
```

---

Document: llms/zh-CN/components/dialog.md

<!-- Source: src/dialog/README.md; locale: zh-CN; page: /components/dialog/ -->

# Dialog

在当前页面打开一个浮层，承载相关操作。组件式与函数式 API 命名一致。

## 基础示例

### 基本用法

Example source: src/dialog/__demos__/basic.vue

```vue
<template>
  <c-button @click="open = true">Open Dialog</c-button>

  <c-dialog
    v-model:open="open"
    title="Dialog Title"
    message="This is a basic component dialog."
    @confirm="Message.success('Confirmed')"
    @cancel="Message.info('Cancelled')"
  />
</template>

<script setup lang="ts">
import { Message } from "@cedar-design/ui";
import { ref } from "vue";

const open = ref(false);
</script>
```

## 调用方式与内容

### 函数调用

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `title` | 标题 | 确认框、弹出层表单、简洁模式 |
| `type` | 类型图标：`info` `success` `warning` `error` | 确认框、简洁模式 |
| `message` | 内容（也可用 default 插槽） | 确认框、简洁模式 |
| `before-close` | 返回 boolean/Promise 或调用 done；首次完成生效 | 弹出层表单 |
| `simple` | 简洁布局（紧凑 padding、footer 居中） | 简洁模式 |
<!-- demo-config-notes:end -->

Example source: src/dialog/__demos__/global.vue

```vue
<template>
  <c-space>
    <c-button @click="openBasic">Basic</c-button>
    <c-button @click="openDialog">Open</c-button>
    <c-button @click="openAndUpdate">Open and Update</c-button>
    <c-button @click="awaitAction">Await Action</c-button>
    <c-button @click="hideButtons">Hide Footer Buttons</c-button>
  </c-space>
</template>

<script setup lang="ts">
import { Dialog, Message } from "@cedar-design/ui";

function openBasic() {
  Dialog.open("This dialog was opened from a string message.");
}

function openDialog() {
  Dialog.open({
    title: "Global Method",
    message: "This dialog was opened programmatically.",
  });
}

function openAndUpdate() {
  const instance = Dialog.open({
    title: "Submitting",
    message: "Processing the request…",
  });
  window.setTimeout(
    () =>
      instance.update({
        title: "Completed",
        message: "The request succeeded.",
      }),
    800,
  );
}

async function awaitAction() {
  const action = await Dialog.open("Choose an action to close this dialog.");
  if (action) Message.info(`Dialog action: ${action}`);
}

function hideButtons() {
  Dialog.open({
    title: "No Footer Buttons",
    message: "Click the overlay or press Esc to dismiss this dialog.",
    confirmButton: false,
    cancelButton: false,
  });
}
</script>
```

### Alert

Example source: src/dialog/__demos__/alert.vue

```vue
<template>
  <c-button @click="handleClick">Alert</c-button>
</template>

<script lang="ts">
import { Dialog } from '@cedar-design/ui'

export default {
  setup() {
    const handleClick = () => {
      Dialog.alert({
        title: 'Alert',
        message: 'This is an alert description.',
        type: 'info',
      })
    }

    return { handleClick }
  },
}
</script>
```

### 确认框

Example source: src/dialog/__demos__/confirm.vue

```vue
<template>
  <c-space>
    <c-button @click="openConfirm">Confirm</c-button>
    <c-button status="danger" @click="openDangerConfirm">Delete</c-button>
    <c-button @click="componentOpen = true">Component Confirm</c-button>
  </c-space>

  <c-dialog
    v-model:open="componentOpen"
    type="warning"
    title="Confirm Action"
    message="Are you sure you want to continue?"
  />
</template>

<script setup lang="ts">
import { ref } from "vue";
import { Dialog, Message } from "@cedar-design/ui";

const componentOpen = ref(false);

async function openConfirm() {
  const action = await Dialog.confirm({
    title: "Confirm Action",
    message: "Are you sure you want to continue?",
  });
  if (action) Message.info(`Dialog action: ${action}`);
}

async function openDangerConfirm() {
  const action = await Dialog.confirm({
    title: "Dangerous Action",
    message: "This action cannot be undone. Continue?",
    confirmButtonText: "Delete",
    confirmButtonProps: { variant: "default", status: "danger" },
  });
  if (action) Message.info(`Dialog action: ${action}`);
}
</script>
```

### 消息提示

设置 `type` 为 `info` / `success` / `warning` / `error` 显示对应图标。

Example source: src/dialog/__demos__/message.vue

```vue
<template>
  <c-space>
    <c-button @click="handleClickInfo">Info</c-button>
    <c-button status="success" @click="handleClickSuccess">Success</c-button>
    <c-button status="warning" @click="handleClickWarning">Warning</c-button>
    <c-button status="danger" @click="handleClickError">Error</c-button>
  </c-space>
</template>

<script lang="ts">
import { Dialog } from '@cedar-design/ui'

export default {
  setup() {
    const handleClickInfo = () => {
      Dialog.info({
        title: 'Info Notification',
        message: 'This is an info description which directly indicates a neutral informative change or action.',
      })
    }
    const handleClickSuccess = () => {
      Dialog.success({
        title: 'Success Notification',
        message: 'This is a success notification',
      })
    }
    const handleClickWarning = () => {
      Dialog.warning({
        title: 'Warning Notification',
        message: 'This is a warning description which directly indicates a warning that might need attention.',
      })
    }
    const handleClickError = () => {
      Dialog.error({
        title: 'Error Notification',
        message: 'This is an error description which directly indicates a dangerous or potentially negative action.',
      })
    }

    return {
      handleClickInfo,
      handleClickSuccess,
      handleClickWarning,
      handleClickError,
    }
  },
}
</script>
```

### 弹出层表单

Example source: src/dialog/__demos__/form.vue

```vue
<template>
  <c-button @click="handleClick">Open Form Dialog</c-button>
  <c-dialog v-model:open="visible" title="Dialog Form" @cancel="handleCancel" :before-close="handleBeforeClose">
    <c-form :model="form">
      <c-form-item field="name" label="Name">
        <c-input v-model="form.name" />
      </c-form-item>
      <c-form-item field="post" label="Post">
        <c-select v-model="form.post">
          <c-option value="post1">Post1</c-option>
          <c-option value="post2">Post2</c-option>
          <c-option value="post3">Post3</c-option>
          <c-option value="post4">Post4</c-option>
        </c-select>
      </c-form-item>
    </c-form>
  </c-dialog>
</template>

<script lang="ts">
import { defineComponent, reactive, ref } from 'vue'

export default defineComponent({
  setup() {
    const visible = ref(false)
    const form = reactive({
      name: '',
      post: '',
    })

    const handleClick = () => {
      visible.value = true
    }

    const handleBeforeClose = ({ action }, done) => {
      if (action !== 'confirm') {
        done()
        return
      }

      window.setTimeout(() => {
        done()
      }, 2000)
    }

    const handleCancel = () => {
      visible.value = false
    }

    return {
      visible,
      form,
      handleClick,
      handleBeforeClose,
      handleCancel,
    }
  },
})
</script>
```

### 简洁模式

`simple` 适合内容简短、操作聚焦的对话框。

Example source: src/dialog/__demos__/simple.vue

```vue
<template>
  <c-button @click="open = true">Open Simple Dialog</c-button>

  <c-dialog
    v-model:open="open"
    simple
    type="info"
    title="Simple Dialog"
    message="A compact dialog for short and focused information."
  />
</template>

<script setup lang="ts">
import { ref } from "vue";

const open = ref(false);
</script>
```

## 尺寸与布局

### 弹窗尺寸与长内容

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `title` | 标题 | 去除内容边距、最大高度 |
| `body-style` | 内容区 style | 去除内容边距、最大高度 |
| `width` | 宽度 | 弹窗尺寸与长内容 |
| `fullscreen` | 全屏 | 弹窗尺寸与长内容 |
<!-- demo-config-notes:end -->

分别打开弹窗，比较宽度、全屏或长内容的可视范围；关闭当前弹窗后再打开另一种布局。

<details>
<summary>配置说明与使用限制</summary>

#### 对话框宽度

通过 `width` 自定义宽度。

</details>

Example source: src/dialog/__demos__/size-comparison.vue

```vue
<script setup lang="ts">
import { ref } from "vue"
import { proxyRefs as demoProxyRefs } from 'vue'

const scene1 = demoProxyRefs((() => {


    const visibleSmall = ref(false)


    const visibleMedium = ref(false)


    const visibleLarge = ref(false)



    const handleClickSmall = () => {
      visibleSmall.value = true
    }


    const handleClickMedium = () => {
      visibleMedium.value = true
    }


    const handleClickLarge = () => {
      visibleLarge.value = true
    }


    const handleConfirm = () => {
      visibleSmall.value = false
      visibleMedium.value = false
      visibleLarge.value = false
    }


    const handleCancel = () => {
      visibleSmall.value = false
      visibleMedium.value = false
      visibleLarge.value = false
    }
return { visibleSmall, visibleMedium, visibleLarge, handleClickSmall, handleClickMedium, handleClickLarge, handleConfirm, handleCancel }
})())

const scene2 = demoProxyRefs((() => {


    const show = ref(false)



    const handleClick = () => {
      show.value = true
    }


    const handleConfirm = () => {
      show.value = false
    }


    const handleCancel = () => {
      show.value = false
    }
return { show, handleClick, handleConfirm, handleCancel }
})())
</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="width">
    <h4><span lang="zh-CN">对话框宽度</span><span lang="en-US">Width</span></h4>
    <c-space>
        <c-button @click="scene1.handleClickSmall">Small Dialog</c-button>
        <c-button @click="scene1.handleClickMedium">Medium Dialog</c-button>
        <c-button @click="scene1.handleClickLarge">Large Dialog</c-button>
      </c-space>
      <c-dialog :width="400" v-model:open="scene1.visibleSmall" @confirm="scene1.handleConfirm" @cancel="scene1.handleCancel">
        <template #title>Small Dialog</template>
        <div>
          You can customize modal body text by the current situation. This modal will be closed immediately once you press
          the OK button.
        </div>
      </c-dialog>
      <c-dialog v-model:open="scene1.visibleMedium" @confirm="scene1.handleConfirm" @cancel="scene1.handleCancel">
        <template #title>Medium Dialog</template>
        <div>
          You can customize modal body text by the current situation. This modal will be closed immediately once you press
          the OK button.
        </div>
      </c-dialog>
      <c-dialog :width="720" v-model:open="scene1.visibleLarge" @confirm="scene1.handleConfirm" @cancel="scene1.handleCancel">
        <template #title>Large Dialog</template>
        <div>
          You can customize modal body text by the current situation. This modal will be closed immediately once you press
          the OK button.
        </div>
      </c-dialog>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="fullscreen">
    <h4><span lang="zh-CN">全屏</span><span lang="en-US">Fullscreen</span></h4>
    <c-button @click="scene2.handleClick">Open Dialog</c-button>
      <c-dialog v-model:open="scene2.show" @confirm="scene2.handleConfirm" @cancel="scene2.handleCancel" fullscreen>
        <template #title>Title</template>
        <div>
          You can customize modal body text by the current situation. This modal will be closed immediately once you press
          the OK button.
        </div>
      </c-dialog>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

### 去除内容边距

通过 `body-class` / `body-style` 自定义内容区样式。

Example source: src/dialog/__demos__/no-padding.vue

```vue
<template>
  <c-space>
    <c-button @click="handleClick">Open Dialog</c-button>
  </c-space>

  <c-dialog
    v-model:open="show"
    title="no-padding"
    :body-style="{ padding: 0 }"
    @cancel="handleCancel"
    @confirm="handleConfirm"
  >
    <div class="p-24">
      You can customize modal body text by the current situation. This modal
      will be closed immediately once you press the OK button.
    </div>
  </c-dialog>
</template>

<script lang="ts">
import { defineComponent, ref } from "vue";
export default defineComponent({
  setup() {
    const show = ref(false);

    const handleClick = () => {
      show.value = true;
    };
    const handleConfirm = () => {
      show.value = false;
    };
    const handleCancel = () => {
      show.value = false;
    };

    return {
      show,
      handleClick,
      handleConfirm,
      handleCancel,
    };
  },
});
</script>
```

### 最大高度

Example source: src/dialog/__demos__/max-height.vue

```vue
<template>
  <c-button @click="open = true">Open Long Content Dialog</c-button>

  <c-dialog
    v-model:open="open"
    title="Long Content"
    :body-style="{ maxHeight: '50vh', overflowY: 'auto' }"
  >
    <p v-for="item in 12" :key="item">
      {{ item }}. Long dialog content remains scrollable while the title and
      actions stay visible.
    </p>
  </c-dialog>
</template>

<script setup lang="ts">
import { ref } from "vue";

const open = ref(false);
</script>
```

## 交互与定制

### 可拖动

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `unmount-on-close` | 关闭后卸载 | 定制按钮文字、高级属性 |
| `draggable` | 可拖动 | 可拖动 |
| `confirm-button-text` | 确认按钮文案 | 定制按钮文字 |
| `cancel-button-text` | 取消按钮文案 | 定制按钮文字 |
| `footer` | 是否展示 footer 区域 | 高级属性 |
| `type` | 类型图标：`info` `success` `warning` `error` | 高级属性 |
<!-- demo-config-notes:end -->

Example source: src/dialog/__demos__/draggable.vue

```vue
<template>
  <c-button @click="handleClick">Open Dialog</c-button>
  <c-dialog v-model:open="show" @confirm="handleConfirm" @cancel="handleCancel" draggable>
    <template #title>Title</template>
    <div>
      You can customize modal body text by the current situation. This modal will be closed immediately once you press
      the OK button.
    </div>
  </c-dialog>
</template>

<script lang="ts">
import { defineComponent, ref } from 'vue'
export default defineComponent({
  setup() {
    const show = ref(false)

    const handleClick = () => {
      show.value = true
    }
    const handleConfirm = () => {
      show.value = false
    }
    const handleCancel = () => {
      show.value = false
    }

    return {
      show,
      handleClick,
      handleConfirm,
      handleCancel,
    }
  },
})
</script>
```

### 自定义底部

`footer` 插槽会暴露 `confirm`、`cancel` 和 `close` 方法，便于组合自定义操作。

Example source: src/dialog/__demos__/custom-footer.vue

```vue
<template>
  <c-button @click="open = true">Open Custom Footer Dialog</c-button>

  <c-dialog v-model:open="open">
    <template #title>Custom Slots</template>
    Use the footer slot when the actions need different priorities or wording.
    <template #footer="{ close, cancel, confirm }">
      <c-space>
        <c-button variant="text" @click="close">Later</c-button>
        <c-button variant="outline" @click="cancel">Cancel</c-button>
        <c-button status="primary" @click="confirm">Continue</c-button>
      </c-space>
    </template>
  </c-dialog>
</template>

<script setup lang="ts">
import { ref } from "vue";

const open = ref(false);
</script>
```

### 定制按钮文字

Example source: src/dialog/__demos__/custom-text.vue

```vue
<template>
  <c-button @click="handleClick">Open Dialog</c-button>
  <c-dialog
    v-model:open="show"
    @confirm="handleConfirm"
    @cancel="handleCancel"
    confirmButtonText="Confirm"
    cancelButtonText="Exit"
    unmountOnClose
  >
    <template #title>Title</template>
    <div>
      You can customize modal body text by the current situation. This modal will be closed immediately once you press
      the OK button.
    </div>
  </c-dialog>
</template>

<script lang="ts">
import { defineComponent, ref } from 'vue'
export default defineComponent({
  setup() {
    const show = ref(false)

    const handleClick = () => {
      show.value = true
    }
    const handleConfirm = () => {
      show.value = false
    }
    const handleCancel = () => {
      show.value = false
    }

    return {
      show,
      handleClick,
      handleConfirm,
      handleCancel,
    }
  },
})
</script>
```

### 高级属性

组合 `footer`、`hide-title`、`body-class` / `body-style` 和 `unmount-on-close` 控制对话框的渲染行为。

Example source: src/dialog/__demos__/advanced.vue

```vue
<template>
  <c-space>
    <c-button @click="footerHiddenOpen = true">Hide Footer</c-button>
    <c-button @click="titleHiddenOpen = true">Hide Title</c-button>
    <c-button @click="customBodyOpen = true">Custom Body</c-button>
    <c-button @click="unmountOpen = true">Unmount on Close</c-button>
  </c-space>

  <c-dialog
    v-model:open="footerHiddenOpen"
    :footer="false"
    type="info"
    title="Read Only"
    message="This dialog intentionally has no footer actions."
  />
  <c-dialog
    v-model:open="titleHiddenOpen"
    hide-title
    aria-label="Dialog without a visible title"
    type="warning"
    message="Use aria-label when the visible title is hidden."
  />
  <c-dialog
    v-model:open="customBodyOpen"
    type="info"
    title="Custom Body"
    message="The body supports custom alignment, classes, and inline styles."
    message-align="center"
    body-class="dialog-demo__body--custom"
    :body-style="{
      padding: '16px 20px',
      background: 'rgba(22, 93, 255, 0.08)',
      borderRadius: '8px',
    }"
  />
  <c-dialog
    v-model:open="unmountOpen"
    unmount-on-close
    title="Unmount on Close"
  >
    This content is removed from the DOM after the close transition.
  </c-dialog>
</template>

<script setup lang="ts">
import { ref } from "vue";

const footerHiddenOpen = ref(false);
const titleHiddenOpen = ref(false);
const customBodyOpen = ref(false);
const unmountOpen = ref(false);
</script>

<style scoped>
:deep(.dialog-demo__body--custom) {
  font-weight: 500;
}
</style>
```

## 异步与关闭控制

### 异步关闭

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `before-close` | 返回 boolean/Promise 或调用 done；首次完成生效 | 异步关闭、before 钩子与 done 兼容 |
| `title` | 标题 | 异步关闭 |
| `message` | 内容（也可用 default 插槽） | 异步关闭 |
<!-- demo-config-notes:end -->

Example source: src/dialog/__demos__/async.vue

```vue
<template>
  <c-space>
    <c-button @click="asyncOpen = true">Async Close</c-button>
    <c-button @click="loadingOpen = true">Button Loading</c-button>
  </c-space>

  <c-dialog
    v-model:open="asyncOpen"
    title="Async Close"
    message="Every action waits for the asynchronous task to finish."
    :before-close="beforeClose"
  />
  <c-dialog
    v-model:open="loadingOpen"
    title="Button Loading"
    message="The confirm button displays loading while the task is running."
    :before-close="buttonLoadingClose"
  />
</template>

<script setup lang="ts">
import { ref } from "vue";
import type { DialogAction } from "../types";

const asyncOpen = ref(false);
const loadingOpen = ref(false);

function beforeClose({ action: _action }: { action: DialogAction }, done: () => void) {
  window.setTimeout(done, 1000);
}

function buttonLoadingClose(
  { action }: { action: DialogAction },
  done: () => void,

) {
  if (action !== "confirm") {
    done();
    return;
  }

  window.setTimeout(() => {
    done();
  }, 1000);
}
</script>
```

### before 钩子与 done 兼容

`beforeClose({ action }, done, context)` 为统一入口，不新增另一套命名。


只记录日志的同步钩子应显式 return true；同步 undefined 表示仍在等待回调。注意：以前返回 `Promise<void>` 却不调用 done 的异步钩子，现在会在 Promise 完成后放行。


Example source: src/dialog/__demos__/guard-protocol.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import type { DialogBeforeClose } from "@cedar-design/ui";
const open = ref(false);
const mode = ref("promise");
const allowed = ref(false);
const status = ref("");
const check: DialogBeforeClose = (payload, done, { signal }) => {
  status.value = `等待： ${payload.action}`;
  if (mode.value === "done") {
    setTimeout(() => {
      status.value = allowed.value ? "允许" : "阻止";
      done(!signal.aborted && allowed.value);
    }, 500);
    return;
  }
  return new Promise<boolean>((resolve) =>
    setTimeout(() => {
      status.value = allowed.value ? "允许" : "阻止";
      resolve(!signal.aborted && allowed.value);
    }, 500),
  );
};
</script>
<template>
  <c-space direction="column" align="stretch">
    <c-switch v-model="allowed" />
    <c-form-item layout="vertical" size="sm" label="mode">
      <c-radio-group
        aria-label="mode"
        v-model="mode"
        :options="[
          { value: 'promise', label: 'Promise' },
          { value: 'done', label: 'done 回调' },
        ]"
        variant="button"
        size="sm"
      />
    </c-form-item>
    <c-button @click="open = true">打开</c-button>
    <c-dialog
      v-model:open="open"
      :before-close="check"
      @guard-error="status = 'Error'"
    >
      <template #default
        ><c-button v-if="false" @click="open = true">Confirm action</c-button
        ><span v-else>通过 beforeClose 关闭</span></template
      >
    </c-dialog>
    <p role="status">{{ status }}</p>
  </c-space>
</template>
```


Promise 与 done 共用一次完成状态：`false` / `done(false)` 阻止，`true` / `done()` 允许；Promise&lt;void&gt; 正常完成允许。重复完成只生效一次，异常触发 guard-error，取消或卸载后迟到结果无效。此类关闭/确认回调同步返回 void 时保留原回调协议，等待 done。


守卫统一使用 `(payload, done, context)`：关闭 payload 为 `{ action }`，切换和提交为 `{ value, previousValue }`，Popup 为 `{ reason }`。context 提供 `signal` 和可选原始 `event`。返回 boolean/Promise，或调用 done()/done(false)；同步 void 等待 done，Promise&lt;void&gt; 放行。首次完成生效。等待期间自动管理 loading/disabled，取消后旧结果失效，不暴露内部按钮 refs。

## 阅读方向

继承最近的 `dir="ltr|rtl"`，支持运行时切换与局部覆盖。内容、标题与动作间距使用逻辑起止位置；外部弹层继承来源方向。关闭、确认、取消和未提交状态不因方向切换改变。

## API

### `<Dialog>` Props

| 参数名                    | 描述                                         | 类型                             | 默认值       |
| ------------------------- | -------------------------------------------- | -------------------------------- | ------------ |
| dir | 阅读方向；省略时继承来源作用域。物理 left/right 方位保持原意。 | `ReadingDirection` (`ltr` / `rtl`) | — |
| `open` **(v-model)**      | 是否显示                                     | `boolean`                        | `-`          |
| `default-open`            | 非受控默认显示                               | `boolean`                        | `false`      |
| `title`                   | 标题                                         | `string`                         | `-`          |
| `message`                 | 内容（也可用 default 插槽）                  | `string`                         | `-`          |
| `message-align`           | 内容对齐                                     | `'left' \| 'center' \| 'right'`  | `'left'`     |
| `type`                    | 类型图标：`info` `success` `warning` `error` | `string`                         | `-`          |
| `simple`                  | 简洁布局（紧凑 padding、footer 居中）        | `boolean`                        | `false`      |
| `width`                   | 宽度                                         | `number \| string`               | `-`          |
| `top`                     | 距顶部高度（`align-center` 时无效）          | `number \| string`               | `-`          |
| `title-align`             | 标题对齐                                     | `'start' \| 'center'`            | `'center'`   |
| `align-center`            | 垂直水平居中                                 | `boolean`                        | `true`       |
| `overlay`                    | 是否显示背景层                                 | `boolean`                        | `true`       |
| `overlay-class`              | 背景层 class                                   | `string`                         | `-`          |
| `overlay-style`              | 背景层 style                                   | `CSSProperties`                  | `-`          |
| `overlay-closable`           | 点击背景层关闭                                 | `boolean`                        | `true`       |
| `esc-to-close`            | ESC 关闭                                     | `boolean`                        | `true`       |
| `lock-scroll`             | 打开时锁定背景滚动                           | `boolean`                        | `true`       |
| `close-on-route-change`   | 浏览器历史或 hash 变化时关闭                 | `boolean`                        | `false`      |
| `popup-container`         | 挂载位置，`false` 禁用 teleport              | `string \| HTMLElement \| false` | `'body'`     |
| `confirm-button`          | 显示确认按钮                                 | `boolean`                        | `true`       |
| `cancel-button`           | 显示取消按钮                                 | `boolean`                        | `true`       |
| `closable`                | 显示右上角关闭按钮                           | `boolean`                        | `true`       |
| `confirm-button-text`     | 确认按钮文案                                 | `string`                         | `-`          |
| `cancel-button-text`      | 取消按钮文案                                 | `string`                         | `-`          |
| `confirm-button-loading`  | 确认按钮 loading                             | `boolean`                        | `false`      |
| `cancel-button-loading`   | 取消按钮 loading                             | `boolean`                        | `false`      |
| `confirm-button-disabled` | 确认按钮 disabled                            | `boolean`                        | `false`      |
| `cancel-button-disabled`  | 取消按钮 disabled                            | `boolean`                        | `false`      |
| `confirm-button-props`    | 确认按钮 props                               | `ButtonProps`                    | `-`          |
| `cancel-button-props`     | 取消按钮 props                               | `ButtonProps`                    | `-`          |
| `footer`                  | 是否展示 footer 区域                         | `boolean`                        | `true`       |
| `dialog-class`            | 对话框 class                                 | `string \| any[]`                | `-`          |
| `dialog-style`            | 对话框 style                                 | `CSSProperties`                  | `-`          |
| `body-class`              | 内容区 class                                 | `string \| any[]`                | `-`          |
| `body-style`              | 内容区 style                                 | `StyleValue`                     | `-`          |
| `hide-title`              | 隐藏标题                                     | `boolean`                        | `false`      |
| `unmount-on-close`        | 关闭后卸载                                   | `boolean`                        | `false`      |
| `draggable`               | 可拖动                                       | `boolean`                        | `false`      |
| `fullscreen`              | 全屏                                         | `boolean`                        | `false`      |
| `overlay-animation-name`     | 背景层动画                                     | `string`                         | `fade-modal` |
| `dialog-animation-name`   | 对话框动画                                   | `string`                         | `zoom-modal` |
| `z-index`                 | 层级                                         | `number`                         | `-`          |
| `before-close` | 返回 boolean/Promise 或调用 done；首次完成生效 | `DialogBeforeClose` | — |

### `<Dialog>` Events

| 事件名       | 描述          | 参数            |
| ------------ | ------------- | --------------- |
| `open`       | 打开时        | `-`             |
| `opened`     | 打开动画结束  | `-`             |
| `close`      | 关闭时        | `-`             |
| `closed`     | 关闭动画结束  | `-`             |
| `confirm`    | 点击确认      | `Event`         |
| `cancel`     | 点击取消/关闭 | `Event`         |
| `click-overlay` | 点击背景层      | `MouseEvent`    |
| `key-escape` | ESC           | `KeyboardEvent` |

关闭按钮、背景层、ESC 和 `close()` 使用 `close` 语义，不会额外触发 `cancel`。

### `<Dialog>` Slots

| 插槽名    | 描述 | 参数                         |
| --------- | ---- | ---------------------------- |
| `default` | 内容 | `-`                          |
| `title`   | 标题 | `-`                          |
| `footer`  | 底部 | `cancel`, `confirm`, `close` |

确认与取消按钮默认使用 Button 的 `default` 状态和 `text` 变体；可通过 `confirmButtonProps` / `cancelButtonProps` 覆盖。

### 全局方法

所有函数式 Dialog 默认使用简洁布局（`simple: true`）并隐藏右上角关闭按钮（`closable: false`），仍可通过传入参数或全局默认配置显式覆盖。

#### DialogConfig

与组件 props 一致（camelCase），另支持：

| 参数名        | 描述                               | 类型                       |
| ------------- | ---------------------------------- | -------------------------- |
| `content`     | 可渲染内容；设置时优先于 `message` | `RenderContent`            |
| `footer`      | 是否展示 footer 或自定义 footer    | `boolean \| RenderContent` |
| `onConfirm`   | 确认回调                           | `(e?: Event) => void`      |
| `onCancel`    | 取消回调                           | `(e?: Event) => void`      |
| `onClickOverlay` | 点击背景层回调                       | `() => void`               |
| `onKeyEscape` | ESC 回调                           | `() => void`               |

#### DialogMethod

| 方法                               | 描述                           | 返回值                                 |
| ---------------------------------- | ------------------------------ | -------------------------------------- |
| `Dialog.open(config)`              | 打开对话框                     | `Promise<DialogAction> & DialogReturn` |
| `Dialog.confirm(config)`           | 确认框（默认 `type: warning`） | 同上                                   |
| `Dialog.alert(config)`             | Alert（无取消按钮）            | 同上                                   |
| `Dialog.info(config)`              | 信息提示                       | 同上                                   |
| `Dialog.success(config)`           | 成功提示                       | 同上                                   |
| `Dialog.warning(config)`           | 警告提示                       | 同上                                   |
| `Dialog.error(config)`             | 错误提示                       | 同上                                   |
| `Dialog.close()`                   | 关闭最近打开的函数式对话框     | `void`                                 |
| `Dialog.setDefaultOptions(config)` | 设置函数式默认配置             | `void`                                 |
| `Dialog.resetDefaultOptions()`     | 重置函数式默认配置             | `void`                                 |

#### DialogReturn

| 属性             | 描述     |
| ---------------- | -------- |
| `close()`        | 关闭     |
| `update(config)` | 更新配置 |

安装后可通过 `app.config.globalProperties.$dialog` 调用。

### 类型定义

```ts
import type {
  DialogAction,
  DialogConfig,
  DialogMethod,
  DialogReturn,
  DialogService,
  DialogType,
} from "@cedar-design/ui";
```

### 样式变量

Dialog 的公开颜色变量与 Maple 同义：`--c-dialog-background` 表示浮层背景（`surface-raised`），`--c-dialog-overlay-background` 表示遮罩，`--c-dialog-title-text-color` 和 `--c-dialog-content-text-color` 表示主要内容，`--c-dialog-close-button-color` 表示次要操作；`--c-dialog-status-{info|success|warning|danger}-color` 对应可读状态内容色（content-info/success/warning/danger），不是状态填充色。业务主题优先覆盖这些组件变量，跨组件主题则覆盖相应的 system 变量。边框、宽度、间距和布局仍遵循桌面端规格。

#### 完整变量默认值

遮罩通过 Dialog 组件变量消费 `sys-color-scrim`；Maple 不再借用 Popup 的遮罩颜色。实例遮罩变量可放在 `overlay-style` 上；放在面板 `dialog-style` 上的变量不会继承给兄弟遮罩节点。显式 `overlay-style.backgroundColor` 优先。Teleport 场景需要在实际 DOM 祖先作用域设置变量。暗色主题继承同一套颜色语义；几何保留平台差异。状态图标改用可读的 content 状态色。

变量按用途分组：background／overlay-background 是面板与遮罩；border-* 是面板或分隔线边框；title-* 是标题排版；content-* 是正文排版；actions-* 是操作区；close-button-* 是关闭按钮；status-* 是语义图标；simple-*／fullscreen-* 是对应模式的尺寸；animation-* 是入退场动效。width／margin-top 控制常规面板布局。内部拖动与定位变量不构成公开定制入口。

| 变量 | 默认值 |
| --- | --- |
| `--c-dialog-background` | `var(--c-sys-color-surface-raised)` |
| `--c-dialog-overlay-background` | `var(--c-sys-color-scrim)` |
| `--c-dialog-border-color` | `var(--c-sys-color-border-default)` |
| `--c-dialog-border-width` | `1px` |
| `--c-dialog-border-radius` | `var(--c-sys-radius-md)` |
| `--c-dialog-width` | `520px` |
| `--c-dialog-margin-top` | `100px` |
| `--c-dialog-title-text-color` | `var(--c-sys-color-content-primary)` |
| `--c-dialog-title-font-size` | `var(--c-sys-font-size-lg)` |
| `--c-dialog-title-font-weight` | `var(--c-sys-font-weight-medium)` |
| `--c-dialog-title-padding` | `0 var(--c-sys-space-8)` |
| `--c-dialog-title-min-height` | `48px` |
| `--c-dialog-title-justify` | `center` |
| `--c-dialog-content-text-color` | `var(--c-sys-color-content-primary)` |
| `--c-dialog-content-font-size` | `var(--c-sys-font-size-md)` |
| `--c-dialog-content-line-height` | `var(--c-line-height)` |
| `--c-dialog-content-padding` | `28px var(--c-sys-space-8)` |
| `--c-dialog-actions-padding` | `var(--c-sys-space-7) var(--c-sys-space-8)` |
| `--c-dialog-actions-button-gap` | `var(--c-sys-space-6)` |
| `--c-dialog-close-button-size` | `32px` |
| `--c-dialog-close-button-color` | `var(--c-sys-color-content-secondary)` |
| `--c-dialog-close-button-font-size` | `var(--c-sys-font-size-lg)` |
| `--c-dialog-close-button-inset-inline-end` | `var(--c-sys-space-7)` |
| `--c-dialog-status-icon-size` | `18px` |
| `--c-dialog-status-icon-gap` | `var(--c-sys-space-5)` |
| `--c-dialog-status-info-color` | `var(--c-sys-color-content-info)` |
| `--c-dialog-status-success-color` | `var(--c-sys-color-content-success)` |
| `--c-dialog-status-warning-color` | `var(--c-sys-color-content-warning)` |
| `--c-dialog-status-danger-color` | `var(--c-sys-color-content-danger)` |
| `--c-dialog-simple-width` | `400px` |
| `--c-dialog-simple-border-radius` | `var(--c-sys-radius-md)` |
| `--c-dialog-simple-padding` | `28px 32px 32px` |
| `--c-dialog-simple-content-gap` | `28px` |
| `--c-dialog-simple-actions-gap` | `32px` |
| `--c-dialog-fullscreen-width` | `100vw` |
| `--c-dialog-fullscreen-height` | `100vh` |
| `--c-dialog-animation-duration` | `var(--c-sys-motion-duration-slow)` |
| `--c-dialog-animation-easing` | `var(--c-sys-motion-easing-standard)` |

### 守卫等待反馈

before-* 等待期间显示加载反馈并标记 aria-busy；拒绝或失败后恢复，重复提交不再启动同一操作。普通事件返回的 Promise 不参与加载。

函数调用的通知回调不控制任务完成。服务的选择或关闭结果独立于回调异常结算，关闭完成时仍会清理所属宿主。异常继续通过调用方或 Vue 错误通道传递；回调返回 Promise 不控制 loading 或关闭。

---

Document: llms/zh-CN/components/divider.md

<!-- Source: src/divider/README.md; locale: zh-CN; page: /components/divider/ -->

# Divider 分割线

用于分隔列表或布局中的内容区域。

## 基础示例

### 基础用法

用于分隔相邻的内容区域。

Example source: src/divider/__demos__/basic.vue

```vue
<template>
  <div>
    <p>内容上方 / Before</p>
    <c-divider />
    <p>内容下方 / After</p>
  </div>
</template>
```

## 布局与排列

### 垂直分割线

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `orientation` | 分割线自身的横纵朝向，默认 horizontal；不控制文字对齐 | 垂直分割线 |
| `type` | 线型 | 垂直分割线 |
| `text-align` | 文字沿分割线的位置；start/end 为逻辑起止位置 | 垂直分割线 |
| `description` | 文字描述；默认插槽优先 | 垂直分割线 |
<!-- demo-config-notes:end -->

设置 `orientation="vertical"`；父容器使用 flex 并提供可用高度。文字沿竖直方向排列。

Example source: src/divider/__demos__/vertical.vue

```vue
<template>
  <div>
    <div class="vertical-row">
      <span>Before</span>
      <c-divider orientation="vertical" />
      <span>Middle</span>
      <c-divider orientation="vertical" type="dashed" />
      <span>After</span>
    </div>
    <div class="vertical-labels">
      <c-divider orientation="vertical" text-align="start" description="Start" />
      <c-divider orientation="vertical" description="Center" />
      <c-divider orientation="vertical" text-align="end" description="End" />
    </div>
  </div>
</template>

<style scoped>
.vertical-row {
  display: flex;
  align-items: center;
  min-height: 40px;
}
.vertical-labels {
  display: flex;
  height: 160px;
}
</style>
```

## 内容与展示

### 线条尺寸、样式与颜色

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `inset` | 沿线两端缩进：水平时左右，竖直时上下 | 线条尺寸、样式与颜色 |
| `spacing` | 线条两侧外间距：水平时上下，竖直时左右 | 线条尺寸、样式与颜色 |
| `orientation` | 分割线自身的横纵朝向，默认 horizontal；不控制文字对齐 | 线条尺寸、样式与颜色 |
| `type` | 线型 | 线条尺寸、样式与颜色 |
| `thickness` | 有限线宽且至少 1，单位 px；未设置时使用主题默认 1px；hairline 优先 | 线条尺寸、样式与颜色 |
| `color` | 线条颜色；未设置时使用主题边框色 | 线条尺寸、样式与颜色 |
<!-- demo-config-notes:end -->

比较线宽/缩进、线型和颜色；带文字与自定义内容保持独立，避免把插槽行为混入线条装饰。

<details>
<summary>配置说明与使用限制</summary>

#### 间距与缩进

对比五档预设、数值、CSS 长度和非对称数组；竖直示例展示切换方向后的作用。

#### 线型

通过 `type` 对比实线、虚线、点线和双线；双线建议设置至少 3px 的 `thickness`。

#### 颜色、线宽与透明度

通过 `color`、`thickness`、`opacity` 定制线条。`opacity=0` 保留布局；`hairline` 优先于 `thickness`。

</details>

Example source: src/divider/__demos__/line-appearance-comparison.vue

```vue
<script setup lang="ts">
import { proxyRefs as demoProxyRefs } from 'vue'

const scene1 = demoProxyRefs((() => {

const presets = ['xs', 'sm', 'md', 'lg', 'xl']
return { presets }
})())
</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="size-inset">
    <h4><span lang="zh-CN">间距与缩进</span><span lang="en-US">Spacing &amp; Inset</span></h4>
    <div>
        <div v-for="size in scene1.presets" :key="size">
          <code>inset="{{ size }}" spacing="{{ size }}"</code>
          <c-divider :inset="size" :spacing="size" />
        </div>
        <p>数值 / Number · inset=24, spacing=16</p>
        <c-divider :inset="24" :spacing="16" />
        <p>CSS 长度 / CSS length · inset=2rem</p>
        <c-divider inset="2rem" />
        <p>非对称 / Asymmetric · inset=[8, 32], spacing=[12, 24]</p>
        <c-divider :inset="[8, 32]" :spacing="[12, 24]" />
        <p>竖直 / Vertical · inset=[8, 24], spacing=[12, 20]</p>
        <div class="vertical-preview">
          <span>Before</span>
          <c-divider orientation="vertical" :inset="[8, 24]" :spacing="[12, 20]" />
          <span>After</span>
        </div>
      </div>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="line-type">
    <h4><span lang="zh-CN">线型</span><span lang="en-US">Line Style</span></h4>
    <div>
        <p>实线 / solid</p>
        <c-divider />
        <p>虚线 / dashed</p>
        <c-divider type="dashed" />
        <p>点线 / dotted</p>
        <c-divider type="dotted" />
        <p>双线 / double · 3px</p>
        <c-divider type="double" :thickness="3" />
      </div>
  </section>

  <section class="demo-comparison-case demo-comparison-case--3" data-comparison-scene="opacity-color">
    <h4><span lang="zh-CN">颜色、线宽与透明度</span><span lang="en-US">Color, Thickness &amp; Opacity</span></h4>
    <div>
        <p>主题色 / Theme color</p>
        <c-divider color="var(--c-sys-color-action-primary)" />
        <p>线宽 / Thickness · 3px</p>
        <c-divider :thickness="3" />
        <p>半透明 / Half opacity · 0.5</p>
        <c-divider :thickness="3" :opacity="0.5" />
        <p>隐藏线条，保留间距 / Zero opacity preserves spacing</p>
        <c-divider :opacity="0" />
        <p>细线优先 / Hairline overrides thickness</p>
        <c-divider hairline :thickness="4" />
      </div>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }
.demo-comparison-case--1 {

.vertical-preview {
  display: flex;
  align-items: center;
  height: 96px;
}

}
</style>
```

### 带文字

通过 `description` 添加文字，`text-align` 控制起点、居中和终点位置。切换 RTL 可观察逻辑起止方向。

Example source: src/divider/__demos__/with-text.vue

```vue
<script setup>
import { ref } from 'vue'

const rtl = ref(false)
</script>

<template>
  <div>
    <c-checkbox v-model="rtl">RTL</c-checkbox>
    <div :dir="rtl ? 'rtl' : 'ltr'">
      <c-divider text-align="start" description="起点 / Start" />
      <c-divider description="居中 / Center" />
      <c-divider text-align="end" description="终点 / End" />
    </div>
  </div>
</template>
```

## 自定义与插槽

### 自定义内容

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `type` | 线型 | 自定义内容 |
| `description` | 文字描述；默认插槽优先 | 自定义内容 |
<!-- demo-config-notes:end -->

默认插槽优先于 `description`，自定义内容的留白由调用方设置。

Example source: src/divider/__demos__/custom.vue

```vue
<template>
  <c-divider type="dashed" description="默认插槽优先 / Slot takes priority">
    <span class="divider-label">★ 自定义内容 / Custom content</span>
  </c-divider>
</template>

<style scoped>
.divider-label {
  padding-inline: 8px;
}
</style>
```

## 交互与控制

### 动态属性

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `orientation` | 分割线自身的横纵朝向，默认 horizontal；不控制文字对齐 | 动态属性 |
| `opacity` | 整个分割线（含文字）的不透明度，范围 0–1；0 保留布局 | 动态属性 |
| `hairline` | 将主题线宽缩放为一半；默认主题下为 0.5px | 动态属性 |
| `thickness` | 有限线宽且至少 1，单位 px；未设置时使用主题默认 1px；hairline 优先 | 动态属性 |
| `inset` | 沿线两端缩进：水平时左右，竖直时上下 | 动态属性 |
| `spacing` | 线条两侧外间距：水平时上下，竖直时左右 | 动态属性 |
<!-- demo-config-notes:end -->

切换方向、默认插槽文字、透明度和细线，观察属性更新及恢复。

Example source: src/divider/__demos__/live-properties.vue

```vue
<script setup>
import { ref } from 'vue'

const vertical = ref(false)
const text = ref(false)
const invisible = ref(false)
const hairline = ref(false)
</script>

<template>
  <section class="divider-live-demo">
    <div class="controls">
      <c-checkbox v-model="vertical">Vertical divider</c-checkbox>
      <c-checkbox v-model="text">Divider text</c-checkbox>
      <c-checkbox v-model="invisible">Zero opacity</c-checkbox>
      <c-checkbox v-model="hairline">Hairline divider</c-checkbox>
    </div>
    <p role="status">Orientation: {{ vertical ? 'vertical' : 'horizontal' }}; opacity: {{ invisible ? 0 : 1 }}</p>
    <div class="preview" :class="{ vertical }">
      <span>Before</span>
      <c-divider
        data-testid="live-divider"
        :orientation="vertical ? 'vertical' : 'horizontal'"
        :opacity="invisible ? 0 : 1"
        :hairline="hairline"
        :thickness="4"
        :inset="[8, 16]"
        :spacing="[12, 20]"
        ><template v-if="text" #default>Section</template></c-divider
      >
      <span>After</span>
    </div>
  </section>
</template>

<style scoped>
.controls {
  display: flex;
  flex-wrap: wrap;
  gap: 12px;
}
.controls label {
  display: inline-flex;
  align-items: center;
  gap: 4px;
}
.preview {
  display: flex;
  flex-direction: column;
  min-height: 160px;
}
.preview.vertical {
  flex-direction: row;
  align-items: center;
}
</style>
```

## 阅读方向

继承最近的 `dir="ltr|rtl"`。水平文字 start/end 随阅读方向对齐，垂直文字 start/end 仍表示上/下。inset 表示沿线两端缩进，spacing 表示线外间距：水平线 inset 和垂直线 spacing 的成对数值按逻辑起止解释。竖线边框绘制在逻辑起点，hairline、线型与 aria-orientation 保持原义，方向切换不重建内容。

### 内容占位与最小线宽

主动设置 thickness 时，只接受至少为 1 的有限数。hairline 仍优先，使用主题线宽的一半。小于 1（包括 0 和负数）及非有限值不会写入样式，而是使用主题线宽，并在开发环境提示。

带文字、换行描述和默认插槽内容均正常占位，包括 spacing=0 时；后续正文不会被文字覆盖。

Example source: src/divider/__demos__/content-flow.vue

```vue
<template>
  <section class="divider-flow-demo">
    <h4>1px：最小显式线宽 / Minimum explicit width</h4>
    <div class="flow-sample">
      <c-divider
        data-min-line
        :thickness="1"
        :spacing="0"
        description="内容仍正常占位 / Content stays in normal flow"
      />
      <p>后续正文 / Following content</p>
    </div>
    <h4>4px：多行文字 / Multiline content</h4>
    <div class="flow-sample">
      <c-divider
        data-multiline
        :thickness="4"
        :spacing="0"
        description="分区标题支持换行，并为后续内容保留完整空间 / A wrapping section title reserves its full height"
      />
      <p>后续正文 / Following content</p>
    </div>
    <h4>默认插槽 / Custom content</h4>
    <div class="flow-sample">
      <c-divider data-custom-content :spacing="0"
        ><span class="flow-content"
          >第一行 / First line<br />第二行 / Second line</span
        ></c-divider
      >
      <p>后续正文 / Following content</p>
    </div>
    <p>
      thickness ≥ 1；hairline 优先，使用主题线宽的一半。hairline takes priority
      and halves the theme width.
    </p>
  </section>
</template>
<style scoped>
.flow-sample {
  max-width: 280px;
}
.flow-sample p {
  margin: 0;
}
.flow-content {
  padding: 12px 0;
}
</style>
```

## API

### 属性

| 属性 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| `orientation` | 分割线自身的横纵朝向，默认 horizontal；不控制文字对齐 | `horizontal` \| `vertical` | `horizontal` |
| `type` | 线型 | `solid` \| `dashed` \| `dotted` \| `double` | `solid` |
| `text-align` | 文字沿分割线的位置；start/end 为逻辑起止位置 | `start` \| `center` \| `end` | `center` |
| `description` | 文字描述；默认插槽优先 | `string` | — |
| `inset` | 沿线两端缩进：水平时左右，竖直时上下 | `DividerSize` | — |
| `spacing` | 线条两侧外间距：水平时上下，竖直时左右 | `DividerSize` | `md` |
| `thickness` | 有限线宽且至少 1，单位 px；未设置时使用主题默认 1px；hairline 优先 | `number` | — |
| `hairline` | 将主题线宽缩放为一半；默认主题下为 0.5px | `boolean` | `false` |
| `color` | 线条颜色；未设置时使用主题边框色 | `string` | — |
| `opacity` | 整个分割线（含文字）的不透明度，范围 0–1；0 保留布局 | `number` | — |

### 间距取值

`DividerSize = number | string | [number | string] | [number | string, number | string]`

`inset` 设置沿分割线方向的两端缩进，`spacing` 设置分割线与相邻内容的外间距。两者均支持预设 `xs`、`sm`、`md`、`lg`、`xl`、数值（单位 px）、CSS 长度或数组。单值或单元素数组对称应用；`[start, end]` 分别设置两端。数组元素为长度值，不使用预设名称。

| 方向 | inset 数组顺序 | spacing 数组顺序 |
| --- | --- | --- |
| horizontal | 行内起点/终点缩进（RTL 时为右/左） | 上/下外间距 |
| vertical | 上/下缩进 | 行内起点/终点外间距（RTL 时为右/左） |

`inset` 默认不缩进；`spacing` 默认使用当前平台的 `md` 间距。预设读取平台主题 token，具体像素值可不同。


开发环境会检查 orientation、text-align、type、间距结构、thickness 和 opacity。非法枚举使用默认值；非法 inset 不缩进，非法 spacing 回退 md，非法 opacity 不覆盖样式。opacity 必须为 0–1 的有限数。数组只允许一元或二元长度，数组项不使用预设名。仍支持有限负 margin 和 CSS var/calc 表达式，具体 CSS 语法由浏览器解析。

### 插槽

| 插槽名 | 说明 |
| --- | --- |
| `default` | 自定义分割线内容，优先于 description |

## 类型定义

```ts
import type { DividerProps, DividerInstance, DividerSize, DividerSizePreset, DividerOrientation, DividerTextAlign, DividerType } from '@cedar-design/ui'
```

### 样式变量

| 变量名 | 默认值 |
| --- | --- |
| `--c-divider-color` | `var(--c-sys-color-border-default)` |
| `--c-divider-text-color` | `var(--c-sys-color-content-secondary)` |
| `--c-divider-border-width` | `1px` |
| `--c-divider-text-padding` | `16px` |
| `--c-divider-text-align-inset` | `24px` |
| `--c-divider-orientation-vertical-inset-xs` | `2px` |
| `--c-divider-orientation-horizontal-inset-xs` | `12px` |
| `--c-divider-orientation-vertical-spacing-xs` | `4px` |
| `--c-divider-orientation-horizontal-spacing-xs` | `8px` |
| `--c-divider-orientation-vertical-inset-sm` | `4px` |
| `--c-divider-orientation-horizontal-inset-sm` | `16px` |
| `--c-divider-orientation-vertical-spacing-sm` | `8px` |
| `--c-divider-orientation-horizontal-spacing-sm` | `12px` |
| `--c-divider-orientation-vertical-inset-md` | `6px` |
| `--c-divider-orientation-horizontal-inset-md` | `24px` |
| `--c-divider-orientation-vertical-spacing-md` | `12px` |
| `--c-divider-orientation-horizontal-spacing-md` | `16px` |
| `--c-divider-orientation-vertical-inset-lg` | `8px` |
| `--c-divider-orientation-horizontal-inset-lg` | `32px` |
| `--c-divider-orientation-vertical-spacing-lg` | `16px` |
| `--c-divider-orientation-horizontal-spacing-lg` | `24px` |
| `--c-divider-orientation-vertical-inset-xl` | `12px` |
| `--c-divider-orientation-horizontal-inset-xl` | `40px` |
| `--c-divider-orientation-vertical-spacing-xl` | `24px` |
| `--c-divider-orientation-horizontal-spacing-xl` | `32px` |

预设值读取当前平台主题；文字留白在桌面端为 16px，移动端为 8px。

---

Document: llms/zh-CN/components/drawer.md

<!-- Source: src/drawer/README.md; locale: zh-CN; page: /components/drawer/ -->

# Drawer

从容器一侧进入的桌面抽屉。Drawer 与 Maple Popup 共用同一套模态表面控制逻辑；标题、页脚、操作按钮和宽高仍是 Drawer 的桌面端能力。

## 基础示例

### 基础用法

Example source: src/drawer/__demos__/basic.vue

```vue
<template>
  <c-button status="primary" @click="handleClick">Open Drawer</c-button>
  <c-drawer v-model:open="visible" :width="340" @confirm="handleConfirm" @cancel="handleCancel" unmount-on-close>
    <template #title>Title</template>
    <div>
      You can customize modal body text by the current situation. This modal will be closed immediately once you press
      the OK button.
    </div>
  </c-drawer>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
const visible = ref(false)

const handleClick = () => {
  visible.value = true
}
const handleConfirm = () => {
  visible.value = false
}
const handleCancel = () => {
  visible.value = false
}
</script>
```

## 尺寸与定位

### 抽屉尺寸与方向

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `unmount-on-close` | 关闭动画后是否卸载内容 | 抽屉尺寸与方向 |
| `placement` | 抽屉面板在容器中的出现侧，默认 right；不是相对按钮的定位，不执行浮层避让翻转 | 抽屉尺寸与方向 |
| `popup-container` | 挂载容器 | 挂载位置 |
<!-- demo-config-notes:end -->

依次打开不同抽屉，比较方向和占用空间；嵌套、挂载容器与关闭拦截另见后续案例。

<details>
<summary>配置说明与使用限制</summary>

#### 自定义宽度

Drawer 不提供离散 `size` 枚举；左右位置使用 `width`，上下位置使用 `height`，均支持 `number | string`。

</details>

Example source: src/drawer/__demos__/position-size-comparison.vue

```vue
<script setup lang="ts">
import { ref } from "vue"
import { proxyRefs as demoProxyRefs } from 'vue'

const scene1 = demoProxyRefs((() => {

const visibleSmall = ref(false)

const visibleMedium = ref(false)

const visibleLarge = ref(false)


const handleClickSmall = () => {
  visibleSmall.value = true
}

const handleClickMedium = () => {
  visibleMedium.value = true
}

const handleClickLarge = () => {
  visibleLarge.value = true
}

const handleConfirm = () => {
  visibleSmall.value = false
  visibleMedium.value = false
  visibleLarge.value = false
}

const handleCancel = () => {
  visibleSmall.value = false
  visibleMedium.value = false
  visibleLarge.value = false
}
return { visibleSmall, visibleMedium, visibleLarge, handleClickSmall, handleClickMedium, handleClickLarge, handleConfirm, handleCancel }
})())

const scene2 = demoProxyRefs((() => {

const visible = ref(false)

const position = ref('right')


const handleClick = () => {
  visible.value = true
}

const handleConfirm = () => {
  visible.value = false
}

const handleCancel = () => {
  visible.value = false
}
return { visible, position, handleClick, handleConfirm, handleCancel }
})())
</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="size">
    <h4><span lang="zh-CN">自定义宽度</span><span lang="en-US">Size</span></h4>
    <c-space>
        <c-button status="primary" @click="scene1.handleClickSmall">sm Drawer</c-button>
        <c-button status="primary" @click="scene1.handleClickMedium">md Drawer</c-button>
        <c-button status="primary" @click="scene1.handleClickLarge">lg Drawer</c-button>
      </c-space>
      <c-drawer v-model:open="scene1.visibleSmall" :width="280" @confirm="scene1.handleConfirm" @cancel="scene1.handleCancel" unmount-on-close>
        <template #title>Title</template>
        <div>
          You can customize modal body text by the current situation. This modal will be closed immediately once you press
          the OK button.
        </div>
      </c-drawer>
      <c-drawer v-model:open="scene1.visibleMedium" :width="420" @confirm="scene1.handleConfirm" @cancel="scene1.handleCancel" unmount-on-close>
        <template #title>Title</template>
        <div>
          You can customize modal body text by the current situation. This modal will be closed immediately once you press
          the OK button.
        </div>
      </c-drawer>
      <c-drawer v-model:open="scene1.visibleLarge" :width="640" @confirm="scene1.handleConfirm" @cancel="scene1.handleCancel" unmount-on-close>
        <template #title>Title</template>
        <div>
          You can customize modal body text by the current situation. This modal will be closed immediately once you press
          the OK button.
        </div>
      </c-drawer>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="location">
    <h4><span lang="zh-CN">抽屉位置</span><span lang="en-US">Location</span></h4>
    <c-radio-group v-model="scene2.position">
        <c-radio value="top">Top</c-radio>
        <c-radio value="right">Right</c-radio>
        <c-radio value="bottom">Bottom</c-radio>
        <c-radio value="left">Left</c-radio>
      </c-radio-group>
      <div :style="{
      marginTop: '20px'
    }">
        <c-button status="primary" @click="scene2.handleClick">Open Drawer</c-button>
      </div>
      <c-drawer
        :width="340"
        :height="340"
        v-model:open="scene2.visible"
        :placement="scene2.position"
        @confirm="scene2.handleConfirm"
        @cancel="scene2.handleCancel"
        unmountOnClose
      >
        <template #title> Title </template>
        <div>
          You can customize modal body text by the current situation. This modal will be closed immediately once you press
          the OK button.
        </div>
      </c-drawer>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

### 挂载位置

`popup-container` 支持选择器、HTMLElement 和 `false`；`false` 表示保留在当前组件树位置。

Example source: src/drawer/__demos__/popup-container.vue

```vue
<template>
  <div>
    <div
      id="parentNode"
      style="
        width: 100%;
        height: 300px;
        background-color: var(--c-color-bg-white);
        position: relative;
        overflow: hidden;
        line-height: 300px;
        text-align: center;
      "
    >
      <c-button status="primary" @click="handleClick">Open Drawer</c-button>
    </div>
  </div>
  <c-drawer v-model:open="visible" popup-container="#parentNode" @confirm="handleConfirm" @cancel="handleCancel">
    <template #title>Title</template>
    <div>
      You can customize modal body text by the current situation. This modal will be closed immediately once you press
      the OK button.
    </div>
  </c-drawer>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
const visible = ref(false)

const handleClick = () => {
  visible.value = true
}
const handleConfirm = () => {
  visible.value = false
}
const handleCancel = () => {
  visible.value = false
}
</script>
```

## 内容与嵌套

### 嵌套抽屉

Example source: src/drawer/__demos__/nest-drawer.vue

```vue
<template>
  <c-button status="primary" @click="handleClick">Open Drawer</c-button>
  <c-drawer v-model:open="visible" :width="500" @confirm="handleConfirm" @cancel="handleCancel" unmount-on-close>
    <template #title>Title</template>
    <div :style="{ marginBottom: '20px' }">
      You can customize modal body text by the current situation. This modal will be closed immediately once you press
      the OK button.
    </div>
    <c-button status="primary" @click="handleNestedClick">Open Nested Drawer</c-button>
  </c-drawer>
  <c-drawer v-model:open="nestedVisible" @confirm="handleNestedConfirm" @cancel="handleNestedCancel" unmount-on-close>
    <template #title>Title</template>
    <div>
      You can customize modal body text by the current situation. This modal will be closed immediately once you press
      the OK button.
    </div>
  </c-drawer>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
const visible = ref(false)
const nestedVisible = ref(false)

const handleClick = () => {
  visible.value = true
}
const handleConfirm = () => {
  visible.value = false
}
const handleCancel = () => {
  visible.value = false
}
const handleNestedClick = () => {
  nestedVisible.value = true
}
const handleNestedConfirm = () => {
  nestedVisible.value = false
}
const handleNestedCancel = () => {
  nestedVisible.value = false
}
</script>
```

### 自定义节点

Example source: src/drawer/__demos__/custom-node.vue

```vue
<template>
  <c-checkbox-group v-model="custom" :options="['hide header', 'hide footer', 'hide cancel']" />
  <div :style="{ marginTop: '20px' }">
    <c-button status="primary" @click="handleClick">Open Drawer</c-button>
  </div>
  <c-drawer
    :width="340"
    :header="!custom.includes('hide header')"
    :footer="!custom.includes('hide footer')"
    :cancel-button="!custom.includes('hide cancel')"
    v-model:open="visible"
    @confirm="handleConfirm"
    @cancel="handleCancel"
    unmountOnClose
  >
    <template #header>
      <span>Header and title</span>
    </template>
    <div>
      You can customize modal body text by the current situation. This modal will be closed immediately once you press
      the OK button.
    </div>
  </c-drawer>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
const visible = ref(false)
const custom = ref([])

const handleClick = () => {
  visible.value = true
}
const handleConfirm = () => {
  visible.value = false
}
const handleCancel = () => {
  visible.value = false
}
</script>
```

### 函数调用

Example source: src/drawer/__demos__/function-call.vue

```vue
<template>
  <c-button status="primary" @click="handleClick">Open Drawer</c-button>
</template>

<script lang="ts" setup>
import { Drawer } from '@cedar-design/ui'

const handleClick = () => {
  Drawer.open({
    title: 'Info Title',
    content: 'This is an info message',
    width: 340,
  })
}
</script>
```

## 关闭与异步控制

### before 钩子与 done 兼容

`beforeClose({ action }, done, context)` 为统一入口，不新增另一套命名。


只记录日志的同步钩子应显式 return true；同步 undefined 表示仍在等待回调。注意：以前返回 `Promise<void>` 却不调用 done 的异步钩子，现在会在 Promise 完成后放行。


Example source: src/drawer/__demos__/guard-protocol.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import type { DrawerBeforeClose } from "@cedar-design/ui";
const open = ref(false);
const mode = ref("promise");
const allowed = ref(true);
const status = ref("");
const check: DrawerBeforeClose = (payload, done, { signal }) => {
  status.value = `等待： ${payload.action}`;
  if (mode.value === "done") {
    setTimeout(() => {
      status.value = allowed.value ? "允许" : "阻止";
      done(!signal.aborted && allowed.value);
    }, 500);
    return;
  }
  return new Promise<boolean>((resolve) =>
    setTimeout(() => {
      status.value = allowed.value ? "允许" : "阻止";
      resolve(!signal.aborted && allowed.value);
    }, 500),
  );
};
</script>
<template>
  <c-space direction="column" align="stretch">
    <c-form-item layout="vertical" label="允许关闭"><c-switch v-model="allowed" aria-label="允许关闭" /></c-form-item>
    <c-form-item layout="vertical" size="sm" label="mode">
      <c-radio-group
        aria-label="mode"
        v-model="mode"
        :options="[
          { value: 'promise', label: 'Promise' },
          { value: 'done', label: 'done 回调' },
        ]"
        variant="button"
        size="sm"
      />
    </c-form-item>
    <c-button @click="open = true">打开</c-button>
    <c-drawer
      v-model:open="open"
      :before-close="check"
      @guard-error="status = 'Error'"
    >
      <p>关闭前等待片刻。可以关闭开关体验一次拦截，再在抽屉内重新允许关闭并重试。</p>
      <c-form-item layout="vertical" label="允许关闭"><c-switch v-model="allowed" aria-label="抽屉内允许关闭" /></c-form-item>
      <c-button @click="allowed = true; open = false">允许并关闭</c-button>
      <p role="status">{{ status }}</p>
    </c-drawer>
    <p role="status">{{ status }}</p>
  </c-space>
</template>
```


Promise 与 done 共用一次完成状态：`false` / `done(false)` 阻止，`true` / `done()` 允许；Promise&lt;void&gt; 正常完成允许。重复完成只生效一次，异常触发 guard-error，取消或卸载后迟到结果无效。此类关闭/确认回调同步返回 void 时保留原回调协议，等待 done。


守卫统一使用 `(payload, done, context)`：关闭 payload 为 `{ action }`，切换和提交为 `{ value, previousValue }`，Popup 为 `{ reason }`。context 提供 `signal` 和可选原始 `event`。返回 boolean/Promise，或调用 done()/done(false)；同步 void 等待 done，Promise&lt;void&gt; 放行。首次完成生效。等待期间自动管理 loading/disabled，取消后旧结果失效，不暴露内部按钮 refs。

## 阅读方向

继承最近的 `dir="ltr|rtl"`，支持运行时切换与局部覆盖。抽屉 placement 的 left/right 保持物理侧，进入/退出仍从对应屏幕边缘运动；标题、内容和底部动作继承阅读方向。方向切换不提交或清空内容。

## API

### Props

| 属性 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| dir | 阅读方向；省略时继承来源作用域。物理 left/right 方位保持原意。 | `ReadingDirection` (`ltr` / `rtl`) | — |
| open **(v-model)** | 是否可见 | `boolean` | - |
| default-open | 非受控模式下是否默认可见 | `boolean` | `false` |
| placement | 抽屉面板在容器中的出现侧，默认 right；不是相对按钮的定位，不执行浮层避让翻转 | `'top' \| 'right' \| 'bottom' \| 'left'` | `'right'` |
| title | 标题 | `string` | - |
| overlay | 是否显示遮罩 | `boolean` | `true` |
| overlay-class / overlay-style | 遮罩类名 / 样式 | `string / CSSProperties` | - |
| overlay-closable | 点击遮罩是否请求关闭 | `boolean` | `true` |
| closable | 是否显示关闭按钮 | `boolean` | `true` |
| confirm-button-text / cancel-button-text | 操作按钮文字 | `string` | - |
| confirm-button-loading / cancel-button-loading | 操作按钮加载状态 | `boolean` | `false` |
| confirm-button-disabled / cancel-button-disabled | 操作按钮禁用状态 | `boolean` | `false` |
| confirm-button-props / cancel-button-props | 操作按钮属性 | `ButtonProps` | - |
| unmount-on-close | 关闭动画后是否卸载内容 | `boolean` | `false` |
| width / height | 左右宽度 / 上下高度 | `number \| string` | `250` |
| popup-container | 挂载容器 | `string \| HTMLElement \| false` | `'body'` |
| drawer-class / drawer-style | 面板类名 / 样式 | `string \| any[] / CSSProperties` | - |
| body-class / body-style | 内容区类名 / 样式 | `string \| any[] / StyleValue` | - |
| `before-close` | 返回 boolean/Promise 或调用 done；首次完成生效 | `DrawerBeforeClose` | — |
| esc-to-close | ESC 是否请求关闭 | `boolean` | `true` |
| lock-scroll | 是否锁定挂载容器滚动 | `boolean` | `true` |
| close-on-route-change | 路由变化时是否请求关闭 | `boolean` | `false` |
| z-index | 自定义层级 | `number` | 自动分配 |
| header / footer / cancel-button | 是否显示对应区域 | `boolean` | `true` |


### Events

| 事件 | 说明 | 参数 |
| --- | --- | --- |
| update:open | 可见状态请求 | `boolean` |
| confirm / cancel | 点击对应操作按钮并获准关闭 | `Event` |
| open / close | 开始打开 / 开始关闭 | - |
| opened / closed | 打开 / 关闭动画结束 | - |
| click-overlay | 点击当前最上层遮罩 | `MouseEvent` |
| key-escape | 当前最上层抽屉收到 ESC | `KeyboardEvent` |

### Slots

`default`、`header`、`title`、`footer`。`footer` 获得 `confirm`、`cancel`、`close` 三个方法。

### 命令式调用

`Drawer.open(config)` 使用 camelCase 的同名配置，例如 `cancelButtonText`、`beforeClose`、`closeOnRouteChange`。通知事件使用 `onConfirm`、`onCancel`、`onOpen`、`onOpened`、`onClose`、`onClosed`、`onClickOverlay` 和 `onKeyEscape`。

```ts
import type { DrawerAction, DrawerConfig, DrawerProps } from '@cedar-design/ui'
```

## CSS 变量与颜色语义

内置 fade／四方向 slide 在 prefers-reduced-motion: reduce 下关闭过渡与起始位移，组件样式自身生效，不依赖全局动效兜底。默认时长不变；业务自定义动画另行适配。已有编译 CSS 检查不等于真实 OS 动态切换验收。

面板 bg 使用 surface-raised；overlay-bg 使用 sys-color-scrim；header-text-color／content-text-color 使用 content-primary，关闭按钮与标题共享 header-text-color；border-color 使用 border-default。几何、动效与层级保留 Drawer 既有默认值。Drawer 是 Cedar 平台组件，不在 Maple 创建空壳同名变量。

overlay-style 可设置实例遮罩变量，drawer-style 可设置面板内变量；两者是兄弟节点，变量不会互相继承。全局主题在实际共同祖先设置 system 变量。显式背景属性优先于变量消费。已移除从未被消费的 close-icon-right 变量；关闭按钮位置由标题布局和 close-btn-margin-left 控制，不提供无效兼容别名。

| 变量 | 默认值 |
| --- | --- |
| `--c-drawer-header-height` | `var(--c-size-12)` |
| `--c-drawer-footer-button-margin-left` | `var(--c-spacing-6)` |
| `--c-drawer-header-font-size` | `var(--c-font-size-title-1)` |
| `--c-drawer-padding-horizontal` | `var(--c-spacing-7)` |
| `--c-drawer-footer-padding-vertical` | `var(--c-spacing-7)` |
| `--c-drawer-content-padding-vertical` | `var(--c-spacing-6)` |
| `--c-drawer-header-font-weight` | `var(--c-font-weight-500)` |
| `--c-drawer-border-color` | `var(--c-sys-color-border-default)` |
| `--c-drawer-border-width` | `var(--c-border-width-1)` |
| `--c-drawer-header-text-color` | `var(--c-sys-color-content-primary)` |
| `--c-drawer-content-text-color` | `var(--c-sys-color-content-primary)` |
| `--c-drawer-bg` | `var(--c-sys-color-surface-raised)` |
| `--c-drawer-overlay-bg` | `var(--c-sys-color-scrim)` |
| `--c-drawer-line-height` | `var(--c-line-height)` |
| `--c-drawer-z-index` | `var(--c-z-index-drawer)` |
| `--c-drawer-close-icon-font-size` | `var(--c-size-3)` |
| `--c-drawer-close-btn-margin-left` | `var(--c-spacing-4)` |
| `--c-drawer-transition-duration` | `var(--c-transition-duration-3)` |
| `--c-drawer-transition-timing-function` | `var(--c-transition-timing-function-standard)` |

### 守卫等待反馈

before-* 等待期间显示加载反馈并标记 aria-busy；拒绝或失败后恢复，重复提交不再启动同一操作。普通事件返回的 Promise 不参与加载。

---

Document: llms/zh-CN/components/ellipsis.md

<!-- Source: src/ellipsis/README.md; locale: zh-CN; page: /components/ellipsis/ -->

# Ellipsis 文本省略

单行或多行文本省略，可选展开交互和 Tooltip。

## 基础示例

### 单行省略

Example source: src/ellipsis/__demos__/basic.vue

```vue
<template>
  <div class="ellipsis-demo">
    <c-ellipsis
      style="width: 240px; max-width: 100%"
    >
      这是一段较长的说明文字，用于展示有限宽度内的省略效果。点击或使用键盘可以展开查看完整内容，再次操作可以收起。容器宽度改变时，文本会根据新的空间重新排版。
    </c-ellipsis>
  </div>
</template>

<style scoped>
.ellipsis-demo { display: flex; flex-direction: column; align-items: flex-start; gap: 12px; }
.ellipsis-demo p { margin: 0; }
</style>
```

## 内容与展示

### 多行省略

Example source: src/ellipsis/__demos__/multiline.vue

```vue
<template>
  <div class="ellipsis-demo">
    <c-ellipsis
      style="width: 240px; max-width: 100%"
      :line-clamp="2"
    >
      这是一段较长的说明文字，用于展示有限宽度内的省略效果。点击或使用键盘可以展开查看完整内容，再次操作可以收起。容器宽度改变时，文本会根据新的空间重新排版。
    </c-ellipsis>
  </div>
</template>

<style scoped>
.ellipsis-demo { display: flex; flex-direction: column; align-items: flex-start; gap: 12px; }
.ellipsis-demo p { margin: 0; }
</style>
```

## 自定义与插槽

### 自定义提示

Example source: src/ellipsis/__demos__/custom-tooltip.vue

```vue
<template>
  <div class="ellipsis-demo">
    <c-ellipsis
      style="width: 240px; max-width: 100%"
      :tooltip="{ status: 'primary', trigger: ['hover', 'focus', 'click'], content: '独立的提示内容，不会重复拼接正文' }"
    >
      这是一段较长的说明文字，用于展示有限宽度内的省略效果。点击或使用键盘可以展开查看完整内容，再次操作可以收起。容器宽度改变时，文本会根据新的空间重新排版。
    </c-ellipsis>
  </div>
</template>

<style scoped>
.ellipsis-demo { display: flex; flex-direction: column; align-items: flex-start; gap: 12px; }
.ellipsis-demo p { margin: 0; }
</style>
```

## 交互与控制

### 交互展开

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `line-clamp` | 正数行数，向下取整；未传或无效为单行 | 交互展开、受控展开 |
| `expand-trigger` | 启用点击与 Enter / Space 展开 | 交互展开、受控展开 |
| `tooltip` | Tooltip 配置，false 禁用 | 交互展开、受控展开 |
| `expand` | 受控展开状态，配合 v-model:expand | 受控展开 |
<!-- demo-config-notes:end -->

Example source: src/ellipsis/__demos__/expand.vue

```vue
<template>
  <div class="ellipsis-demo">
    <c-ellipsis
      style="width: 240px; max-width: 100%"
      :line-clamp="2"
      expand-trigger="click"
      :tooltip="false"
    >
      这是一段较长的说明文字，用于展示有限宽度内的省略效果。点击或使用键盘可以展开查看完整内容，再次操作可以收起。容器宽度改变时，文本会根据新的空间重新排版。
    </c-ellipsis>
    <p>点击文本，或聚焦后按 Enter / Space 展开与收起。</p>
  </div>
</template>

<style scoped>
.ellipsis-demo { display: flex; flex-direction: column; align-items: flex-start; gap: 12px; }
.ellipsis-demo p { margin: 0; }
</style>
```

### 受控展开

Example source: src/ellipsis/__demos__/controlled.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const expanded = ref(false)
</script>

<template>
  <div class="ellipsis-demo">
    <c-button @click="expanded = !expanded">外部切换: {{ expanded }}</c-button>
    <c-ellipsis
      style="width: 240px; max-width: 100%"
      :line-clamp="2"
      expand-trigger="click"
      :tooltip="false"
      v-model:expand="expanded"
    >
      这是一段较长的说明文字，用于展示有限宽度内的省略效果。点击或使用键盘可以展开查看完整内容，再次操作可以收起。容器宽度改变时，文本会根据新的空间重新排版。
    </c-ellipsis>
  </div>
</template>

<style scoped>
.ellipsis-demo { display: flex; flex-direction: column; align-items: flex-start; gap: 12px; }
.ellipsis-demo p { margin: 0; }
</style>
```

## API

### Props

| 属性 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| `expand` | 受控展开状态，配合 v-model:expand | `boolean` | `undefined` |
| `default-expand` | 非受控初始展开状态 | `boolean` | `false` |
| `expand-trigger` | 启用点击与 Enter / Space 展开 | `'click'` | `—` |
| `line-clamp` | 正数行数，向下取整；未传或无效为单行 | `number \| string` | `—` |
| `tooltip` | Tooltip 配置，false 禁用 | `boolean \| TooltipProps` | `true` |

传入 `expand` 后只通知父级，不擅自修改受控值；省略时由内部状态管理，`default-expand` 仅用于初始化。Tooltip 遵循自身默认宽度及触发方式，不以实际测量是否溢出作为显示条件；触控场景可显式设置 `tooltip.trigger` 包含 `click`。外部 class/style/width 直接作用于文本节点。

### 事件与插槽

- `update:expand(expand: boolean)`：用户操作请求的新状态；外部更新不触发。
- `default`：正文。
- `tooltip-content`：提示内容；未提供时优先 tooltip.content，否则使用正文，不重复拼接。
- 键盘：可展开文本支持 Enter / Space；启用 Tooltip 的文本可通过 Tab 聚焦。无公开实例方法。

### 类型

```ts
import type { EllipsisProps, EllipsisInstance, EllipsisExpandTrigger } from '@cedar-design/ui'
```

### 样式变量

| Token | 默认值 |
| --- | --- |
| `--c-ellipsis-focus-color` | `var(--c-sys-color-content-brand)` |
| `--c-ellipsis-focus-width` | `2px` |
| `--c-ellipsis-focus-offset` | `2px` |

---

Document: llms/zh-CN/components/empty.md

<!-- Source: src/empty/README.md; locale: zh-CN; page: /components/empty/ -->

# Empty

指当前场景没有对应的数据内容，呈现出的一种状态。

## 基础示例

### 基础用法

空状态组件的基本用法。不传 `description` 时使用国际化文案。

Example source: src/empty/__demos__/basic.vue

```vue
<template>
  <c-empty description="暂无数据" />
</template>
```

## 外观与状态

### 图片尺寸

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `image-size` | 图片/图标尺寸 | 图片尺寸 |
| `description` | 描述内容，缺省时使用国际化文案 | 图片尺寸 |
<!-- demo-config-notes:end -->

通过 `image-size` 属性控制图标尺寸，可选值为 `xs` `sm` `md` `lg` `xl`，也可传入数值。

Example source: src/empty/__demos__/size.vue

```vue
<template>
  <c-space direction="column">
    <c-empty v-for="size in sizes" :key="size" :image-size="size" :description="`image-size: ${size}`" />
  </c-space>
</template>

<script lang="ts">
import { defineComponent } from 'vue'

export default defineComponent({
  setup() {
    const sizes = ['xs', 'sm', 'md', 'lg', 'xl']
    return { sizes }
  },
})
</script>
```

## 内容与展示

### 空态图形与补充操作

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `description` | 描述内容，缺省时使用国际化文案 | 空态图形与补充操作、显示与隐藏 |
| `image-url` | 自定义图片的地址 | 空态图形与补充操作 |
| `alt` | 图片替代文本 | 空态图形与补充操作 |
| `show-icon` | 是否显示图标 | 显示与隐藏 |
| `show-description` | 是否显示描述 | 显示与隐藏 |
<!-- demo-config-notes:end -->

对比自定义图形和补充操作，观察替换默认内容与保留业务操作入口的区别。

<details>
<summary>配置说明与使用限制</summary>

#### 操作按钮

Reload 只更新本地刷新次数和描述，不请求服务；真实业务请自行接入请求与结果状态。

通过 `extra` 插槽添加操作按钮。

#### 自定义图片和文案

通过 `image` 插槽自定义图标、图片，或通过默认插槽修改文案。

</details>

Example source: src/empty/__demos__/content-comparison.vue

```vue
<script setup lang="ts">
import { ref } from "vue"
import { proxyRefs as demoProxyRefs } from 'vue'

const scene1 = demoProxyRefs((() => {

const attempts = ref(0)
return { attempts }
})())
</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="extra">
    <h4><span lang="zh-CN">操作按钮</span><span lang="en-US">extra</span></h4>
    <c-empty :description="scene1.attempts ? 'No data. Local refresh completed.' : 'No data, please reload'">
        <template #extra>
          <c-button status="primary" @click="scene1.attempts++">Reload</c-button>
          <p aria-live="polite">Local refresh attempts: {{ scene1.attempts }}</p>
        </template>
      </c-empty>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="user-define">
    <h4><span lang="zh-CN">自定义图片和文案</span><span lang="en-US">user define</span></h4>
    <c-space direction="column">
        <c-empty>
          <template #image>
            <c-icon-exclamation-circle-fill />
          </template>
          No data, please reload!!
        </c-empty>
        <c-empty image-url="/cat.jpg" alt="空状态图片" description="自定义图片和文案" />
      </c-space>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

### 显示与隐藏

通过两个按钮分别隐藏和恢复图标、描述。两者同时隐藏不代表隐藏整个组件，也不影响 extra 插槽。

通过 `show-icon`、`show-description` 控制图标和描述是否显示。

Example source: src/empty/__demos__/show.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const showIcon = ref(true)
const showDescription = ref(true)
</script>

<template>
  <c-space direction="column" :size="16">
    <c-space wrap>
      <c-button @click="showIcon = !showIcon">Toggle icon</c-button>
      <c-button @click="showDescription = !showDescription">Toggle description</c-button>
    </c-space>
    <c-empty data-demo-empty description="Dynamic empty state" :show-icon="showIcon" :show-description="showDescription" />
  </c-space>
</template>
```

## API

### `<Empty>` Props

| 属性               | 说明                         | 类型                                                     | 默认值  |
| ------------------ | ---------------------------- | -------------------------------------------------------- | ------- |
| description      | 描述内容，缺省时使用国际化文案 | `string`                                                   | -      |
| image-url        | 自定义图片的地址               | `string`                                                   | -      |
| alt              | 图片替代文本                   | `string`                                                   | `''`   |
| image-size       | 图片/图标尺寸                  | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| number \| string` | `'md'` |
| show-icon        | 是否显示图标                   | `boolean`                                                  | `true` |
| show-description | 是否显示描述                   | `boolean`                                                  | `true` |

### `<Empty>` Events

| 事件名 | 说明     | 参数                  |
| ------ | -------- | --------------------- |
| click  | 点击回调 | `(ev: MouseEvent)`    |

### `<Empty>` Slots

| 插槽名  | 说明      | 参数 |
| ------- | --------- | ---- |
| image   | 图片/图标 | -    |
| default | 描述内容  | -    |
| extra   | 额外操作  | -    |

### 类型定义

组件导出以下类型定义

```ts
import type { EmptyImageSize, EmptyProps } from '@cedar-design/ui'
```

ConfigProvider 的 `empty` 插槽可以替换未自定义内容的 Empty，不作为 Empty 的公开 Prop。

### 样式变量

| 变量 | 默认值 | 用途 |
| --- | --- | --- |
| `--c-empty-description-color` | `var(--c-sys-color-content-tertiary)` | 低强调的空状态说明文字 |
| `--c-empty-icon-color` | `var(--c-sys-color-content-decorative)` | 非文字装饰图标；不用于需要阅读的文字 |
| `--c-empty-padding` | `var(--c-spacing-5) 0` | 容器留白 |
| `--c-empty-image-margin-bottom` | `var(--c-spacing-2)` | 图标与说明的间距 |
| `--c-empty-description-font-size` | `var(--c-font-size-body-3)` | 说明文字字号 |
| `--c-empty-description-line-height` | `var(--c-line-height)` | 说明文字行高 |
| `--c-empty-extra-margin-top` | `var(--c-spacing-5)` | 额外操作上方间距 |
| `--c-empty-size-xs/sm/md/lg/xl` | `var(--c-size-15/20/25/35/45)` | 默认图标／图片的尺寸档位 |

描述是文字，必须按文本对比度检查；装饰图标可以更弱。自定义图片或插槽可能有自己的颜色，不会被 `icon-color` 强制重染。尺寸与间距按桌面／移动布局分别维护，但同名变量职责一致。

---

Document: llms/zh-CN/components/field-decorator.md

<!-- Source: src/field-decorator/README.md; locale: zh-CN; page: /components/field-decorator/ -->

# FieldDecorator 字段装饰器

FieldDecorator 是 Input、Textarea、Select 与日期时间控件的展示外壳，负责边框、尺寸、浮动提示、前后缀和清除按钮；不管理输入值、表单校验或弹层开合。

Cedar 完成实现后独立复制到 Maple，替换命名空间与导入路径；两端不引用另一端的运行时代码。主体、几何测量、插槽、事件及样式规则一致。

- 三种变体：`outline`（默认）、`filled`、`standard`。消费者可以显式选择自己的默认变体。
- 五种尺寸：`xs / sm / md / lg / xl`，默认 `md`；具体高度使用各端 token。
- `hint` 默认 Cedar 为 `false`，Maple 为 `true`。其他行为一致；Input 在 FormItem 已有外部标签时关闭浮动提示。
- 有内容且可编辑时才渲染清除按钮；`0` 算非空，`[]` 算空。Cedar 在 hover/focus 时显示，Maple 常驻；触屏媒体条件下 Cedar 也常驻。
- 默认按钮通过各端全局语言系统读取无障碍文案，不维护组件私有词典。
- 内容列尺寸使用 ResizeObserver 观察，支持前缀变化及隐藏容器重新显示；卸载时清理监听。

输入控件聚焦时不额外绘制外圈 outline，沿用各变体已有的边框、底线或背景聚焦反馈；适用于 Input、Textarea、Date 和 Time 等消费者。

输入框、文本域和数字输入框的光标使用 `currentColor`，与当前输入文字颜色一致；错误态不单独覆盖光标颜色。

`--c-field-caret-color` 默认 `currentColor`，统一控制 Input、InputNumber 与 Textarea 的光标颜色；不改变文字色。

## 基础示例

### 表单控件尺寸对照

切换五档 size 和三种字段变体，比较 Input、Button、Select、日期时间及其他单行表单控件的高度。Button 在这里固定使用 outline。DatePicker/TimePicker 是面板，此处使用带输入框的 Date/Time 字段。示例同时展示有值、可清空、标签删除与长标签多选；Select/Cascader 设置 tag-nowrap 时保持同档高度，长标签文字省略、删除图标保留；标签行可横向滚动，清空按钮和箭头固定在外侧。被省略的标签正文支持悬停、键盘聚焦或点按查看完整文字，点外部或按 Esc 关闭，不改变选中值。可清空后恢复选中值重复比较。多行文本和允许换行的多选内容按内容撑高。

Example source: src/field-decorator/__demos__/control-sizes.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
const sizes = ["xs", "sm", "md", "lg", "xl"] as const;
const variants = ["outline", "filled", "standard"] as const;
const size = ref<(typeof sizes)[number]>("md");
const variant = ref<(typeof variants)[number]>("outline");
const options = [
  { value: "beijing", label: "Beijing" },
  { value: "shanghai", label: "Shanghai" },
];
const cascaderOptions = [{ value: "china", label: "China", children: options }];

const inputValue = ref("Beijing");
const selectValue = ref("beijing");
const cascaderValue = ref("beijing");
const selectMultiple = ref(["beijing", "shanghai"]);
const cascaderMultiple = ref(["beijing", "shanghai"]);
const selectOverflow = ref(["long", "beijing", "shanghai"]);
const cascaderOverflow = ref(["long", "beijing", "shanghai"]);
const selectedOptions = [
  ...options,
  {
    value: "long",
    label:
      "A very long selected option label for overflow comparison — full text preview keeps the selected value unchanged.",
  },
];
const selectedCascaderOptions = [
  { value: "china", label: "China", children: selectedOptions },
];
function resetSelections() {
  inputValue.value = "Beijing";
  selectValue.value = "beijing";
  cascaderValue.value = "beijing";
  selectMultiple.value = ["beijing", "shanghai"];
  cascaderMultiple.value = ["beijing", "shanghai"];
  selectOverflow.value = ["long", "beijing", "shanghai"];
  cascaderOverflow.value = ["long", "beijing", "shanghai"];
}
</script>
<template>
  <section
    aria-label="Form control size comparison"
    class="control-size-comparison"
  >
    <c-space wrap :size="12">
      <c-radio-group v-model="size" aria-label="Comparison size">
        <c-radio v-for="item in sizes" :key="item" :value="item">{{
          item
        }}</c-radio>
      </c-radio-group>
      <c-radio-group v-model="variant" aria-label="Comparison variant">
        <c-radio v-for="item in variants" :key="item" :value="item">{{
          item
        }}</c-radio>
      </c-radio-group>
    </c-space>
    <div class="control-size-comparison__grid">
      <div data-control="Input">
        <p>Input</p>
        <c-input :size="size" :variant="variant" placeholder="Input" />
      </div>
      <div data-control="Button">
        <p>Button</p>
        <c-button :size="size" variant="outline">Button</c-button>
      </div>
      <div data-control="Select">
        <p>Select</p>
        <c-select
          :size="size"
          :variant="variant"
          :options="options"
          placeholder="Select"
        />
      </div>
      <div data-control="Date">
        <p>Date</p>
        <c-date :size="size" :variant="variant" placeholder="Date" />
      </div>
      <div data-control="Time">
        <p>Time</p>
        <c-time :size="size" :variant="variant" placeholder="Time" />
      </div>
      <div data-control="InputNumber">
        <p>InputNumber</p>
        <c-input-number :size="size" :variant="variant" placeholder="Number" />
      </div>
      <div data-control="AutoComplete">
        <p>AutoComplete</p>
        <c-auto-complete
          :size="size"
          :variant="variant"
          :options="options"
          placeholder="AutoComplete"
        />
      </div>
      <div data-control="Cascader">
        <p>Cascader</p>
        <c-cascader
          :size="size"
          :variant="variant"
          :options="cascaderOptions"
          placeholder="Cascader"
        />
      </div>
      <div data-control="DateRange">
        <p>DateRange</p>
        <c-date-range
          :size="size"
          :variant="variant"
          :placeholder="['Start', 'End']"
        />
      </div>
      <div data-control="TimeRange">
        <p>TimeRange</p>
        <c-time-range
          :size="size"
          :variant="variant"
          :placeholder="['Start', 'End']"
        />
      </div>
    </div>

    <section
      aria-label="Selected control size comparison"
      class="control-size-comparison__states"
    >
      <c-space wrap align="center" :size="12">
        <span>Selected / Clearable / Multiple — 有值、可清空与多选不换行</span>
        <span
          >Hover or focus truncated text; tap on touch screens /
          悬停或聚焦省略正文查看全文；触屏点按查看，点外部关闭</span
        >
        <c-button size="sm" variant="outline" @click="resetSelections"
          >Reset / 恢复选中值</c-button
        >
      </c-space>
      <div class="control-size-comparison__grid">
        <div data-control="InputValue">
          <p>Input · clearable</p>
          <c-input
            v-model="inputValue"
            :size="size"
            :variant="variant"
            clearable
            placeholder="Input value"
          />
        </div>
        <div data-control="ButtonReference">
          <p>Button · reference</p>
          <c-button :size="size" variant="outline">Button</c-button>
        </div>
        <div data-control="SelectValue">
          <p>Select · clearable</p>
          <c-select
            v-model="selectValue"
            :size="size"
            :variant="variant"
            :options="selectedOptions"
            clearable
            placeholder="Select value"
          />
        </div>
        <div data-control="CascaderValue">
          <p>Cascader · clearable</p>
          <c-cascader
            v-model="cascaderValue"
            :size="size"
            :variant="variant"
            :options="selectedCascaderOptions"
            clearable
            placeholder="Cascader value"
          />
        </div>
        <div data-control="SelectMultiple">
          <p>Select · multiple / nowrap</p>
          <c-select
            v-model="selectMultiple"
            :size="size"
            :variant="variant"
            :options="selectedOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Select multiple"
          />
        </div>
        <div data-control="CascaderMultiple">
          <p>Cascader · multiple / nowrap</p>
          <c-cascader
            v-model="cascaderMultiple"
            :size="size"
            :variant="variant"
            :options="selectedCascaderOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Cascader multiple"
          />
        </div>
        <div data-control="SelectOverflow">
          <p>Select · long values / nowrap</p>
          <c-select
            v-model="selectOverflow"
            edit-mode="direct"
            :size="size"
            :variant="variant"
            :options="selectedOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Select long values"
          />
        </div>
        <div data-control="CascaderOverflow">
          <p>Cascader · long values / nowrap</p>
          <c-cascader
            v-model="cascaderOverflow"
            edit-mode="direct"
            :size="size"
            :variant="variant"
            :options="selectedCascaderOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Cascader long values"
          />
        </div>
      </div>
    </section>
  </section>
</template>
<style scoped>
.control-size-comparison,
.control-size-comparison__states {
  display: grid;
  gap: 24px;
}
.control-size-comparison__grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
  align-items: start;
  gap: 24px 16px;
}
.control-size-comparison__grid > div {
  min-width: 0;
}
.control-size-comparison__grid p {
  margin: 0 0 12px;
  font-size: 14px;
  line-height: 20px;
}
.control-size-comparison__grid :deep(.c-input-number),
.control-size-comparison__grid :deep(.c-auto-complete) {
  width: 100%;
}
</style>
```

## 加载与等待

### 共享字段加载

`loading` 控制共享字段加载状态；`loading-mode` 为 `default`（指示器）或 `line`（底部不定进度线），默认 `default`。渲染统一由 FieldDecorator 负责，不隐式改变 disabled/readonly；需要禁止编辑时单独设置。

 Example source: src/field-decorator/__demos__/loading.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const busy = ref(true)
const mode = ref<'default' | 'line'>('line')
const text = ref('加载时仍可编辑')
</script>
<template>
  <c-space direction="column" :size="16">
    <c-space><c-switch v-model="busy" />加载状态</c-space>
    <c-radio-group v-model="mode" :options="['default', 'line']" variant="button" aria-label="字段加载布局" />
    <c-form layout="vertical">
      <c-form-item label="文本"><c-input v-model="text" :loading="busy" :loading-mode="mode" /></c-form-item>
      <c-form-item label="多行文本"><c-textarea v-model="text" :loading="busy" :loading-mode="mode" /></c-form-item>
      <c-form-item label="选择"><c-select edit-mode="direct" :options="[{ label: '选项', value: 'a' }]" :loading="busy" :loading-mode="mode" /></c-form-item>
      <c-form-item label="日期"><c-date edit-mode="direct" :loading="busy" :loading-mode="mode" /></c-form-item>
    </c-form>
    <p>加载展示由同一个 FieldDecorator 实现，不隐式禁用输入；需要禁止操作时单独设置 disabled 或 readonly。</p>
  </c-space>
</template>
```

### Loading tokens

| Token | Default |
| --- | --- |
| `--c-field-loading-line-size` | `2px` |
| `--c-field-loading-duration` | `1s` |
| `--c-field-loading-color` | `var(--c-field-focus-color)` |

## Props

描边缺口通过 `fieldset / legend` 实现，不使用背景色遮罩。缺口起点与内容列对齐，左右各预留 `hint-space`；`padding-inline-start` 中的 CSS `max()/calc()` 必须使用 Less 原样输出，避免不同 Less 版本将其提前计算为 `0px`。`check:input` 同时检查源码一致性和两端 Less 编译产物。

| 属性 | 类型 | 默认值 / 含义 |
| --- | --- | --- |
| `tag` | `'div' \| 'span'` | `div`，外壳标签 |
| `value` | `unknown` | 仅判断内容是否为空 |
| `id` | `string` | 浮动标签关联的原生控件 id |
| `title` | `string` | 原生标题提示 |
| `size` | `ComponentSize` | `md`，实现全部五档尺寸 |
| `variant` | `'outline' \| 'filled' \| 'standard'` | `outline` |
| `placeholder` | `string` | 浮动标签文本 |
| `hint` | `boolean` | Cedar false / Maple true |
| `hint-center` | `boolean` | `true`；多行控件设为 false |
| `line` | `boolean` | `true`，是否显示边框或底线 |
| `focused` | `boolean` | 消费者传入焦点状态 |
| `composing` | `boolean` | 输入法组合期间保持标签浮起 |
| `disabled` / `readonly` / `error` | `boolean` | 消费者合并 Form / Group 后传入 |
| `clearable` | `boolean` | `false`，是否允许清除 |
| `text-color` / `focus-color` / `blur-color` | `string` | 自定义文字、焦点和非焦点颜色 |
| `cursor` | `string` | 自定义光标 |

## 插槽与事件

`default` 放原生输入框、标签或展示内容；`prefix` / `suffix` 放附加内容；`clear-icon` 接收 `clear(event?)`，自定义按钮应调用它，清除不会冒泡打开选择面板。

`clear(event)` 通知消费者更新值；`mousedown(event)` 供消费者管理焦点。外壳不自行修改模型。

样式语义统一使用 `--c-field-*` / `--mp-field-*`；声明集中在各自 `style/token.less`，实现不跨库共享。不要在消费者中重复绘制边框。

## 错误与禁用边框变量

以下后缀分别加上 `--c-field-` / `--mp-field-`：`variant-outline-border-color-error` 控制 outline 错误边框；`variant-standard-line-color-error` 控制 standard 错误底线；`variant-standard-line-color-disabled` 控制 standard 禁用底线，默认引用 system border-subtle。禁用优先于错误、hover 和 focus。三个入口均支持局部覆盖；错误提示文字仍由 `field-error-color` 管理。内部变量不是业务 API，已确认无消费的遗留内部声明直接删除，不提供别名。

动态更换 `tag` 后，尺寸观察会绑定当前根节点和内容节点。KeepAlive 停用释放观察和排队测量；旧激活代次的帧不会修改当前布局。

---

Document: llms/zh-CN/components/filter-form.md

<!-- Source: src/filter-form/README.md; locale: zh-CN; page: /components/filter-form/ -->

# FilterForm

列表页筛选项。FilterForm **不内置**输入组件，通过 `fields[].component` 直接传入组件（也可使用可选的 `field-map` 注册表），避免无用依赖进包。

持久化（记住筛选）由业务侧自行处理：组件只通过 `v-model` 同步值，不读写 storage。

## 基础示例

### 基础用法

在 `fields` 中直接传入组件并配置字段。宽屏会自动多列展示，超出时可展开/收起。

筛选容器使用主题表面色（亮色为白色、暗色随主题适配）、轻描边与20px内边距，不再使用输入控件的浅填充背景。操作区预留两列并与字段控件顶边对齐；单列时按可用列数收敛。单列/双列折叠默认保留一行字段和独立操作行，避免只剩按钮。展开/收起为原生按钮，支持Tab聚焦、Enter/空格操作并提供aria-expanded。行间距默认16px，可由grid-props.rowGap覆盖。

The filter uses the theme surface with a subtle border and 20px inset, rather than an input-fill background. Actions align with the fields and reserve two columns, clamped to the available column count. One- and two-column collapse retain a row of fields above the actions by default. Expand/collapse is a native keyboard-accessible button with aria-expanded. The default 16px row gap can be overridden through grid-props.rowGap.

Example source: src/filter-form/__demos__/basic.vue

```vue
<template>
  <c-filter-form
    v-model="filter"
    v-model:collapsed="collapsed"
    :fields="fields"
    :rules="rules"
  >
    <template #actions>
      <c-button variant="outline" :elevation="false" @click="reset">重置</c-button>
      <c-button status="primary" :elevation="false" @click="search">搜索</c-button>
    </template>
  </c-filter-form>
  <pre class="demo-filter-json">{{ filter }}</pre>
  <p role="status">{{ result }}</p>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import {
  Cascader,
  DateRange,
  Input,
  Select,
  type FilterFormField,
} from '@cedar-design/ui'

const collapsed = ref(true)
const result = ref('尚未搜索')
const filter = ref<Record<string, unknown>>({
  region: undefined,
  status: undefined,
  keyword: '',
  timeRange: undefined,
})

const options = {
  status: [
    { label: '待处理', value: 'pending' },
    { label: '进行中', value: 'doing' },
    { label: '已完成', value: 'done' },
  ],
  owner: [
    { label: '张三', value: 'zhang' },
    { label: '李四', value: 'li' },
  ],
}

const rules = {
  keyword: [{ maxLength: 50, message: '最多 50 个字符' }],
}

const fields: FilterFormField[] = [
  {
    component: Cascader,
    field: 'region',
    label: '地区',
    props: {
      clearable: true,
      placeholder: '请选择地区',
      pathMode: true,
      variant: 'outline',
      options: [
        {
          value: 'beijing',
          label: '北京',
          children: [
            { value: 'chaoyang', label: '朝阳' },
            { value: 'haidian', label: '海淀' },
          ],
        },
        {
          value: 'shanghai',
          label: '上海',
          children: [{ value: 'huangpu', label: '黄浦' }],
        },
      ],
    },
  },
  {
    component: Select,
    field: 'status',
    label: '状态',
    props: { variant: 'outline', clearable: true, placeholder: '全部', options: options.status },
  },
  {
    component: Select,
    field: 'owner',
    label: '负责人',
    props: { variant: 'outline', clearable: true, placeholder: '全部', options: options.owner },
  },
  {
    component: Input,
    field: 'keyword',
    label: '关键词',
    autoEmitChange: false,
    props: { variant: 'outline', clearable: true, placeholder: '回车或失焦触发' },
  },
  {
    component: DateRange,
    field: 'timeRange',
    label: '时间范围',
    gridItemProps: { span: 2 },
    props: { variant: 'outline', valueFormat: 'timestamp', clearable: true, showTime: true },
  },
]

function search() {
  result.value = `搜索条件：${JSON.stringify(filter.value)}`
}

function reset() {
  result.value = '已重置'
  filter.value = {
    region: undefined,
    status: undefined,
    keyword: '',
    timeRange: undefined,
  }
}
</script>

<style scoped>
.demo-filter-json {
  margin-top: 16px;
  padding: 12px 16px;
  border-radius: 4px;
  background: var(--c-sys-color-surface-muted);
  color: var(--c-sys-color-content-secondary);
  font-size: 12px;
  line-height: 1.5;
  white-space: pre-wrap;
  word-break: break-all;
}
</style>
```

```ts
import { Input, Select, type FilterFormField } from '@cedar-design/ui'

const fields: FilterFormField[] = [
  { field: 'keyword', label: '关键词', component: Input },
  {
    field: 'status',
    label: '状态',
    component: Select,
    props: { options: [{ label: '启用', value: 'enabled' }] },
  },
]
```

所有字段组件统一使用 `modelValue` / `update:modelValue` 同步值。自定义组件也应遵循该协议；其他协议可通过包装组件适配。值同步与 FilterForm 的防抖 `change` 通知独立，`autoEmitChange: false` 时值仍会即时同步。

## 内容与展示

### 可选组件注册表

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `fields` | 筛选项 schema | 可选组件注册表 |
| `field-map` | 可选字段组件注册表 | 可选组件注册表 |
| `collapsible` | 是否启用展开/收起 | 可选组件注册表 |
<!-- demo-config-notes:end -->

需要复用组件默认属性或使用后端 JSON schema 时，可通过 `fieldMap` 注册组件，字段的 `component` 填写注册表 key。注册表支持直接传组件或 `{ component, defaultProps }`，字段 `props` 覆盖注册表默认属性。未注册的字符串 key 不渲染。

Example source: src/filter-form/__demos__/registered-fields.vue

```vue
<template>
  <c-filter-form v-model="filter" :fields="fields" :field-map="fieldMap" :collapsible="false" />
  <pre>{{ filter }}</pre>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import { Input, Select, type FilterFormField, type FilterFormFieldMap } from '@cedar-design/ui'

const filter = ref<Record<string, unknown>>({ keyword: '', status: undefined })
const fieldMap: FilterFormFieldMap = {
  input: Input,
  select: { component: Select, defaultProps: { clearable: true, placeholder: '全部' } },
}
const fields: FilterFormField[] = [
  { field: 'keyword', label: '关键词', component: 'input', props: { clearable: true } },
  {
    field: 'status',
    label: '状态',
    component: 'select',
    props: { options: [{ label: '启用', value: 'enabled' }, { label: '停用', value: 'disabled' }] },
  },
]
</script>
```

## 异步与动态数据

### 异步 options

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `fields` | 筛选项 schema | 异步 options |
| `collapsible` | 是否启用展开/收起 | 异步 options |
<!-- demo-config-notes:end -->

选项统一通过字段 `props.options` 传入。使用 `computed` 根据响应式选项构造 `fields`，接口返回后即可更新选项。关闭折叠时适合筛选项较少的场景。

Example source: src/filter-form/__demos__/async-options.vue

```vue
<template>
  <c-space direction="column" style="width: 100%">
    <c-alert>
      异步加载选项后，通过 computed 更新字段的 props.options。
    </c-alert>
    <c-filter-form
      v-model="filter"
      :fields="fields"
      :collapsed="false"
      :collapsible="false"
    >
      <template #actions>
        <c-space>
          <c-button @click="reset">重置</c-button>
          <c-button status="primary" @click="search">搜索</c-button>
        </c-space>
      </template>
    </c-filter-form>
  </c-space>
  <p role="status">{{ result }}</p>
</template>

<script lang="ts" setup>
import { computed, onMounted, onUnmounted, ref } from 'vue'
import {
  Input,
  Select,
  type FilterFormField,
} from '@cedar-design/ui'

const filter = ref<Record<string, unknown>>({
  category: undefined,
  tag: undefined,
  name: '',
})

const options = ref<Record<string, unknown>>({
  category: [],
  tag: [],
})

const fields = computed<FilterFormField[]>(() => [
  {
    component: Select,
    field: 'category',
    label: '分类',
    props: { clearable: true, placeholder: '请选择', options: options.value.category },
  },
  {
    component: Select,
    field: 'tag',
    label: '标签',
    props: { clearable: true, multiple: true, placeholder: '请选择', options: options.value.tag },
  },
  {
    component: Input,
    field: 'name',
    label: '名称',
    props: { clearable: true },
  },
])

let timer: ReturnType<typeof setTimeout>
onUnmounted(() => clearTimeout(timer))

onMounted(() => {
  timer = setTimeout(() => {
    options.value = {
      category: [
        { label: '组件', value: 'component' },
        { label: '工具', value: 'tool' },
      ],
      tag: [
        { label: '推荐', value: 'hot' },
        { label: '新品', value: 'new' },
      ],
    }
  }, 800)
})

const result = ref('尚未搜索')
function search() {
  result.value = `搜索条件：${JSON.stringify(filter.value)}`
}

function reset() {
  filter.value = {
    category: undefined,
    tag: undefined,
    name: '',
  }
}
</script>
```

## API

### 主值与默认值

使用普通 `v-model`。`modelValue` 表示筛选字段对象；`defaultValue` 仅在创建时初始化非受控值，后续修改不会重置当前状态。显式绑定值优先，初始化不发出 `update:modelValue`。

### FilterForm Props

| 属性 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| model-value **(v-model)** | 表单值 | `Record<string, unknown>` | `{}` |
| fields | 筛选项 schema | `FilterFormField[]` | `[]` |
| field-map | 可选字段组件注册表 | `FilterFormFieldMap` | `{}` |
| rules | 透传 Form 校验规则 | object | - |
| collapsed **(v-model)** | 是否折叠多余项 | boolean | `true` |
| collapsible | 是否启用展开/收起 | boolean | `true` |
| cols | 响应式列数 | number \| object | `{ xs:1, sm:2, md:3, lg:3, xl:4, xxl:5 }` |
| grid-props | Grid 其余属性 | object | - |
| change-debounce | change 防抖毫秒 | number | `500` |

### FilterFormField

| 属性 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| component | Vue 组件，或 `fieldMap` 的 key | `string \| Component` | - |
| field | 表单字段路径 | string | - |
| label | 标签 | string | - |
| visible | 是否渲染 | boolean | `true` |
| autoEmitChange | 输入过程是否触发 change | boolean | `true` |
| props | 透传给字段组件 | object | - |
| gridItemProps | GridItem 属性 | object | - |
| formItemProps | FormItem 属性 | object | - |

### FilterFormFieldRegistration

| 属性 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| component | 字段组件 | Component | - |
| defaultProps | 默认 props | object | - |

### Events

| 事件名 | 说明 | 参数 |
| --- | --- | --- |
| update:model-value | v-model | `(value) => void` |
| update:collapsed | 折叠状态变化 | `(collapsed) => void` |
| change | 字段值变化（防抖） | `(value, field) => void` |

### Slots

| 插槽名 | 说明 |
| --- | --- |
| actions | 操作区（搜索 / 重置等），与展开收起同一行 |

### Methods

| 方法名 | 说明 |
| --- | --- |
| formRef | 内部 Form 实例 |

## 样式变量

| 变量名 | 默认值 |
| --- | --- |
| `--c-filter-form-border-radius` | `var(--c-border-radius-md)` |
| `--c-filter-form-background-color` | `var(--c-sys-color-surface-default)` |
| `--c-filter-form-padding` | `var(--c-sys-space-7)`（20px） |
| `--c-filter-form-border-color` | `var(--c-sys-color-border-subtle)` |
| `--c-filter-form-border-width` | `1px` |
| `--c-filter-form-action-offset` | `calc(1em * var(--c-form-line-height) + var(--c-form-vertical-label-margin-bottom))` |
| `--c-filter-form-item-margin-bottom` | `0px`（行距由Grid负责） |
| `--c-filter-form-actions-gap` | `var(--c-sys-space-5)`（12px） |
| `--c-filter-form-collapse-gap` | `4px` |
| `--c-filter-form-collapse-color` | `var(--c-color-text-2)` |
| `--c-filter-form-collapse-hover-color` | `var(--c-sys-color-content-brand)` |
| `--c-filter-form-focus-width` | `2px` |
| `--c-filter-form-focus-offset` | `3px` |

2026-10-16 消费核验：真实 Less 编译与挂载 DOM 确认上述 13 项分别进入容器、FormItem、操作区和折叠按钮规则；静态样式入口同时导入 Form 样式。多列操作项的 `padding-top` 消费 action-offset，单列 stacked 状态覆盖为 `0`。根级派生别名不会保证随局部 Form 依赖覆盖重新计算，需要调整操作区对齐时直接在实际 FilterForm 根覆盖 `--c-filter-form-action-offset`。

## 类型

```ts
import type {
  FilterFormProps,
  FilterFormField,
  FilterFormFieldMap,
  FilterFormFieldRegistration,
} from '@cedar-design/ui'
```

Grid 列间距通过 `grid-props.colGap`（数字 px）控制；没有同名 CSS 覆盖入口，以确保 Grid 的数值测量与实际间距一致。

changeDebounce 改变时按新延迟重排待发送快照，0为立即通知。回车先取消待发送任务再通知当前值；外部重置或不同模型替换会取消旧快照，但正常接受 update:modelValue 的相同值回传不会取消 change。KeepAlive 停用与卸载取消待发送任务；重新激活后接受新输入。

---

Document: llms/zh-CN/components/form.md

<!-- Source: src/form/README.md; locale: zh-CN; page: /components/form/ -->

# Form

具有数据收集、校验和提交功能的表单，包含复选框、单选框、输入框、下拉选择框等元素。

标签一律由 `FormItem` 的 `label`（或 label 插槽）负责渲染；控件本身只提供 `placeholder` 等占位文案，不承担字段标签。

## 阅读方向

Form 与 FormItem 的 content-align 支持 start、end、left、center、right，label-align 支持 start、end、left、right；默认内容 start、标签 end。默认 LTR 位置保持不变，RTL 按阅读方向排列；显式 left/right 均为物理对齐。字段覆盖优先于 Form，逐实例标签列样式保持最高优先级。切换方向不重置业务值、校验结果或只读/禁用状态。

## 基础示例

### 基础用法

Example source: src/form/__demos__/basic.vue

```vue
<template>
  <c-form ref="refForm" :model="form" @submit="handleSubmit">
    <c-form-item field="name" label="Username" required>
      <c-select v-model="form.name">
        <c-optgroup label="Group-1">
          <c-option>Beijing</c-option>
          <c-option>Shanghai</c-option>
        </c-optgroup>
        <c-option>Guangzhou</c-option>
        <c-option disabled>Disabled</c-option>
      </c-select>
    </c-form-item>
    <c-form-item>
      <c-button html-type="submit">Submit</c-button>
    </c-form-item>
  </c-form>
  {{ form.name }}
</template>
<script setup lang="ts">
import { reactive, ref } from "vue";
import type { FormInstance } from "../index";

const refForm = ref<FormInstance>();
const form = reactive({ name: "", post: "", isRead: false });
const handleSubmit = (data: any) => refForm.value?.resetFields(data);
</script>
```

## 表单外观与布局

### 全局禁用

<!-- demo-config-notes:start -->

#### 本组配置对照

| 配置               | 作用                                                      | 相关示例                                   |
| ------------------ | --------------------------------------------------------- | ------------------------------------------ |
| `layout`           | 表单的布局方式，包括水平、垂直、多列                      | 表单布局、标签与内容装饰、标签宽度方案对比 |
| `model`            | 表单数据对象                                              | 标签与内容装饰、标签宽度方案对比           |
| `disabled`         | 是否禁用表单                                              | 全局禁用                                   |
| `label-align`      | 标签的对齐方向                                            | 标签宽度方案对比                           |
| `auto-label-width` | 是否开启自动标签宽度，仅在 `layout="horizontal"` 下生效。 | 标签宽度方案对比                           |
| `label-col-flex`   | 标签列 flex；数字为伸缩比例，带单位字符串为宽度           | 标签宽度方案对比                           |

<!-- demo-config-notes:end -->

通过 disabled 属性可以禁用整个表单。

Example source: src/form/__demos__/disabled.vue

```vue
<template>
  <c-form :style="{ width: '600px' }" disabled>
    <c-form-item field="name" label="Username">
      <c-input placeholder="please enter your username..." />
    </c-form-item>
  </c-form>
</template>
<script lang="ts">
import { defineComponent } from 'vue'
export default defineComponent({
  })
</script>
```

### 表单布局

`edit-mode` 表示编辑模式：`direct` 始终显示控件；`click` / `dblclick` 保留当前在字段附近展开编辑浮层的行为。`readPretty` 是独立布尔属性。FormItem 和字段未设置时继承上层。字段旧 `presentation` 属性已移除，使用 `edit-mode` 配置编辑模式。`presentation="inline"` 迁移为 `edit-mode="direct"`，`layout="inline"` 不变。

表单支持三种布局方式： horizontal - 水平排列（默认，标签在左、控件在右）， vertical - 垂直排列（标签在上、控件在下）， inline - 行内排列。

组合切换 `layout`、`content-align` 与 `direct / click / dblclick` 编辑方式及独立的 `readPretty` 阅读开关，观察标签、字段值和长文字换行的对齐效果。备注项可单独覆盖布局，已有输入数据在切换时保留。`click` 单击进入弹层，`dblclick` 双击进入弹层，`readPretty` 只展示已保存的文字。

Example source: src/form/__demos__/layout.vue

```vue
<script setup lang="ts">
import { computed, reactive, ref } from "vue";
import type { FieldEditMode, FormContentAlign, FormLayout } from '@cedar-design/ui'

const props = defineProps<{ english?: boolean }>();
const layout = ref<FormLayout>("horizontal");
const itemLayout = ref<FormLayout | "inherit">("inherit");
const mode = ref<FieldEditMode>("direct");
const readPretty = ref(false);
const contentAlign = ref<FormContentAlign>("start");
const contentAlignOptions = ["start", "end", "left", "center", "right"].map((value) => ({
  label: value,
  value,
}));
const modeOptions = computed(() => (['direct', 'click', 'dblclick'] as const).map((value) => ({
  label: (props.english ? {"direct": "Direct", "click": "Single click", "dblclick": "Double click"} : {"direct": "直接编辑", "click": "单击编辑", "dblclick": "双击编辑"})[value], value,
})))
const model = reactive(
  props.english
    ? {
        name: "Alex",
        department: "Product design",
        notes: "Review progress every Wednesday and confirm the weekly plan.",
      }
    : {
        name: "林晓",
        department: "产品设计",
        notes: "每周三同步进度，确认后更新本周安排。",
      },
);
const layouts = ["vertical", "horizontal", "inline"] as const;
const layoutOptions = layouts.map((value) => ({ label: value, value }));
const copy = computed(() =>
  props.english
    ? {
        layout: "Form layout",
        itemLayout: "Notes layout",
        mode: "Edit mode",
        readPretty: "Read only display (readPretty)",
        contentAlign: "Content alignment",
        inherit: "Inherit",
        hint: "Switch between direct, click and dblclick editing and toggle readPretty independently. Switch content-align to compare value alignment; Notes can also override the form layout.",
        modeDescription: {
          direct: "Edit values directly in the form.",
          click: "Click a value to edit it in a popover; confirm to save.",
          dblclick:
            "Double-click a value to edit it in a popover; confirm to save.",
          readPretty:
            "Show saved values as text. Compare alignment and wrapping with the labels.",
        },
        description: {
          vertical:
            "Labels appear above controls, with each field on its own row.",
          horizontal:
            "Labels appear beside controls, with each field on its own row.",
          inline:
            "Fields flow alongside one another and wrap when space runs out.",
        },
        name: "Name",
        department: "Team",
        notes: "Notes",
        placeholder: "Enter a value",
        help: "Help stays below the control as the layout changes.",
        model: "Current values",
      }
    : {
        layout: "表单布局",
        itemLayout: "备注单项布局",
        mode: "编辑模式 edit-mode",
        readPretty: "纯阅读 readPretty",
        contentAlign: "内容对齐 content-align",
        inherit: "继承表单",
        hint: "组合切换表单布局与 direct / click / dblclick 编辑方式，并独立开关 readPretty；通过 content-align 切换内容左、中、右对齐；备注还可单独设置布局。",
        modeDescription: {
          direct: "直接在表单中编辑字段值。",
          click: "单击字段值进入编辑弹层，确认后保存。",
          dblclick: "双击字段值进入编辑弹层，确认后保存。",
          readPretty: "以纯文字展示已保存的值，观察与标签的对齐及长文字换行。",
        },
        description: {
          vertical: "标签在上、控件在下，每个字段单独一行。",
          horizontal: "标签在左、控件在右，每个字段单独一行。",
          inline: "字段依次横向排列，空间不足时换行。",
        },
        name: "姓名",
        department: "部门",
        notes: "备注",
        placeholder: "请输入",
        help: "切换布局后，帮助文字仍显示在控件下方。",
        model: "当前数据",
      },
);
const itemLayoutOptions = computed(() => [
  { label: copy.value.inherit, value: "inherit" },
  ...layoutOptions,
]);
</script>

<template>
  <c-space
    direction="column"
    align="stretch"
    :size="16"
    data-config-comparison="form-layout"
  >
    <c-form layout="vertical" edit-mode="direct">
      <c-form-item :label="copy.layout">
        <c-radio-group
          v-model="layout"
          :aria-label="copy.layout"
          :options="layoutOptions"
          variant="button"
          size="sm"
        />
      </c-form-item>
      <c-form-item :label="copy.itemLayout">
        <c-radio-group
          v-model="itemLayout"
          :aria-label="copy.itemLayout"
          :options="itemLayoutOptions"
          size="sm"
        />
      </c-form-item>
      <c-form-item :label="copy.mode">
        <c-radio-group
          v-model="mode"
          :aria-label="copy.mode"
          :options="modeOptions"
          variant="button"
          size="sm"
        />
      </c-form-item>
      <c-form-item :label="copy.contentAlign">
        <c-radio-group
          v-model="contentAlign"
          :aria-label="copy.contentAlign"
          :options="contentAlignOptions"
          variant="button"
          size="sm"
        />
      </c-form-item>
      <c-form-item :label="copy.readPretty">
        <c-checkbox v-model="readPretty" data-read-pretty-toggle
          >readPretty</c-checkbox
        >
      </c-form-item>
    </c-form>
    <p>
      {{ copy.hint }}<br />{{ copy.description[layout] }}<br />{{
        copy.modeDescription[readPretty ? "readPretty" : mode]
      }}
    </p>
    <c-form
      class="layout-comparison-form"
      :model="model"
      :layout="layout"
      :content-align="contentAlign"
      :edit-mode="mode"
      :read-pretty="readPretty"
      label-align="left"
      label-col-flex="6rem"
    >
      <c-form-item field="name" :label="copy.name" required>
        <c-input v-model="model.name" :placeholder="copy.placeholder" />
      </c-form-item>
      <c-form-item field="department" :label="copy.department">
        <c-input v-model="model.department" :placeholder="copy.placeholder" />
      </c-form-item>
      <c-form-item
        field="notes"
        :label="copy.notes"
        :layout="itemLayout === 'inherit' ? undefined : itemLayout"
        :help="copy.help"
      >
        <c-input v-model="model.notes" :placeholder="copy.placeholder" />
      </c-form-item>
    </c-form>
    <p role="status">{{ copy.model }}：{{ JSON.stringify(model) }}</p>
  </c-space>
</template>

<style scoped>
.layout-comparison-form :deep(.c-form-item-layout-inline) {
  width: min(100%, 22rem);
  margin-inline-end: 0;
}
p {
  margin: 0;
  overflow-wrap: anywhere;
}
</style>
```

### 标签与内容装饰

Example source: src/form/__demos__/decoration.vue

```vue
<script setup lang="ts">
import { reactive } from 'vue'
const model = reactive({ name: '', notes: '' })
</script>

<template>
  <c-form :model="model" layout="vertical">
    <c-form-item field="name" label="公开名称" required show-colon tooltip="名称将展示在个人主页。" :label-attrs="{ for: 'decorated-name' }">
      <c-input id="decorated-name" v-model="model.name" placeholder="输入公开名称" />
    </c-form-item>
    <c-form-item field="notes" label="备注" label-component="div" :content-flex="false" content-class="decoration-grid">
      <c-input v-model="model.notes" placeholder="支持自定义内容布局" />
      <small>content-flex=false 后由业务自行布局。</small>
    </c-form-item>
  </c-form>
</template>

<style scoped>
.decoration-grid { display: grid; gap: 8px; }
</style>
```

### 额外信息和帮助信息

可以使用 extra 添加额外信息。
如果需要在外部自定义校验信息，可以使用`help`属性或插槽。error 状态下校验信息优先；无错误展示时显示 help。

Example source: src/form/__demos__/extra.vue

```vue
<template>
  <c-form>
    <c-form-item field="name" label="Username" required>
      <c-input type="text" placeholder="请输入" />
      <template #extra>
        <div>UserName</div>
      </template>
    </c-form-item>
    <c-form-item field="post" label="Postname" required>
      <c-input type="text" placeholder="请输入" />
      <template #extra>
        <div>PostName</div>
      </template>
      <template #help>
        <div>Custom valitae message</div>
      </template>
    </c-form-item>
  </c-form>
</template>
<script lang="ts">
import { defineComponent } from 'vue'
export default defineComponent({
  setup() {
    return {}
  },
})
</script>
```

### 标签宽度方案对比

先输入数据，再切换自动测量、响应式栅格和固定宽度，三种方案使用同一份表单数据。修改最长标签或隐藏联系方式，观察自动测量更新。响应式方案在 576px 以下上下排列；固定宽度默认 6rem，联系方式单项覆盖为 8rem。

<details>
<summary>配置说明与使用限制</summary>

#### 自动标签宽度

设置 `auto-label-width` 开启自动标签宽度。仅在 `layout="horizontal"` 布局下生效。

自动宽度随标签修改、字段增删更新，各个表单独立计算。

#### 标签栅格与局部覆盖

两端默认横向比例为标签 5/24、内容 19/24；Cedar 默认 horizontal，Maple 默认 vertical。仅 horizontal 消费栅格比例与自动宽度；vertical/inline 不套用 Col 百分比。响应式 xs/sm 等按视口宽度生效。

#### 固定标签宽度

FormItem 显式配置优先于 Form。Col 参数与 style 对象整项覆盖，不做深层合并。label-col-flex 优先于 auto-label-width；带单位字符串指定宽度，数字沿用 Col 的伸缩比例（并非 px），内容列自动填满剩余空间。隐藏标签时内容占满。

自动宽度只测量未指定 label-col-flex 的横向标签；标签文字变化、动态增删会重新对齐。多个 Form 各自计算，标签为空或移除全部字段时不会产生 Infinity/NaN。使用很长的标签时建议在窄屏切换 vertical 或设置固定宽度。

</details>

Example source: src/form/__demos__/label-width-comparison.vue

```vue
<script setup lang="ts">
import { computed, reactive, ref } from 'vue'
const props = defineProps<{ english?: boolean }>()
const mode = ref<'auto' | 'columns' | 'fixed'>('auto')
const showExtra = ref(true)
const customLabel = ref('')
const model = reactive({ name: '', department: '', contact: '' })
const labels = computed(() => props.english
  ? { auto: 'Measured labels', columns: 'Responsive columns', fixed: 'Fixed width', name: 'Name', department: 'Department', contact: 'Contact details', extra: 'Show extra field', edit: 'Change the longest label', hint: 'Switch label sizing with the same model. Responsive columns stack below 576px; fixed labels use 6rem, with an 8rem override on the contact field.', model: 'Current model' }
  : { auto: '自动测量', columns: '响应式栅格', fixed: '固定宽度', name: '姓名', department: '部门', contact: '联系方式', extra: '显示额外字段', edit: '修改最长标签', hint: '切换标签宽度方案，输入数据保持不变。栅格在 576px 以下上下排列；固定标签为 6rem，联系方式一项覆盖为 8rem。', model: '当前数据' })
const choices = computed(() => (['auto', 'columns', 'fixed'] as const).map(value => ({ label: labels.value[value], value })))
</script>
<template>
  <div class="label-width-comparison" data-config-comparison="form-label-width">
    <c-radio-group v-model="mode" :options="choices" aria-label="Label width strategy" />
    <p>{{ labels.hint }}</p>
    <c-checkbox v-model="showExtra">{{ labels.extra }}</c-checkbox>
    <label>{{ labels.edit }}<c-input v-model="customLabel" :placeholder="labels.contact" /></label>
    <c-form :model="model" layout="horizontal" label-align="left"
      :auto-label-width="mode === 'auto'"
      :label-col-flex="mode === 'fixed' ? '6rem' : undefined"
      :label-col-props="mode === 'columns' ? { span: 6, xs: 24, sm: 6 } : undefined"
      :wrapper-col-props="mode === 'columns' ? { span: 18, xs: 24, sm: 18 } : undefined">
      <c-form-item field="name" :label="labels.name"><c-input v-model="model.name" /></c-form-item>
      <c-form-item field="department" :label="labels.department"><c-input v-model="model.department" /></c-form-item>
      <c-form-item v-if="showExtra" field="contact" :label="customLabel || labels.contact" :label-col-flex="mode === 'fixed' ? '8rem' : undefined"><c-input v-model="model.contact" /></c-form-item>
    </c-form>
    <p role="status">{{ labels.model }}: {{ JSON.stringify(model) }}</p>
  </div>
</template>
<style scoped>
.label-width-comparison { display: grid; gap: 12px; min-width: 0; max-width: 100%; }
p { margin: 0; overflow-wrap: anywhere; }
</style>
```

## 字段与数据模型

### 嵌套数据

展示了多种表单项嵌套的方式。
表单控件通过 FormItem 注入的上下文继承状态和事件，无需绑定到第一子组件。
如果使用 Grid 组件进行布局，请设置 :content-flex="false" 关闭表单项内容的 flex 布局。

Example source: src/form/__demos__/nested-data.vue

```vue
<template>
  <c-form :model="form" :style="{ width: '600px' }">
    <c-form-item
      label="Username"
      :content-flex="false"
      :merge-props="false"
      extra="Show error message together"
    >
      <c-row :gutter="8">
        <c-col :span="12">
          <c-form-item
            field="together.firstname"
            validate-trigger="input"
            :rules="[{ required: true, message: 'firstname is required' }]"
            no-style
          >
            <c-input
              v-model="form.together.firstname"
              placeholder="please enter your firstname..."
            />
          </c-form-item>
        </c-col>
        <c-col :span="12">
          <c-form-item
            field="together.lastname"
            validate-trigger="input"
            :rules="[{ required: true, message: 'lastname is required' }]"
            no-style
          >
            <c-input
              v-model="form.together.lastname"
              placeholder="please enter your lastname..."
            />
          </c-form-item>
        </c-col>
      </c-row>
    </c-form-item>
    <c-form-item label="Username" :content-flex="false" :merge-props="false">
      <c-row :gutter="8">
        <c-col :span="12">
          <c-form-item
            field="separate.firstname"
            validate-trigger="input"
            extra="Show error message separate"
            :rules="[{ required: true, message: 'firstname is required' }]"
            hide-label
          >
            <c-input
              v-model="form.separate.firstname"
              placeholder="please enter your firstname..."
            />
          </c-form-item>
        </c-col>
        <c-col :span="12">
          <c-form-item
            field="separate.lastname"
            validate-trigger="input"
            :rules="[{ required: true, message: 'lastname is required' }]"
            hide-label
          >
            <c-input
              v-model="form.separate.lastname"
              placeholder="please enter your lastname..."
            />
          </c-form-item>
        </c-col>
      </c-row>
    </c-form-item>
    <c-form-item label="Posts" :content-flex="false" :merge-props="false">
      <c-space direction="column" align="stretch">
        <c-form-item field="posts.post1" label="Post1">
          <c-input
            v-model="form.posts.post1"
            placeholder="please enter your post..."
          />
        </c-form-item>
        <c-form-item field="posts.post2" label="Post2">
          <c-input
            v-model="form.posts.post2"
            placeholder="please enter your post..."
          />
        </c-form-item>
      </c-space>
    </c-form-item>
    <c-form-item field="isRead">
      <c-checkbox v-model="form.isRead"> I have read the manual </c-checkbox>
    </c-form-item>
  </c-form>
  {{ form }}
</template>
<script lang="ts">
import { reactive, ref, defineComponent } from "vue";
export default defineComponent({
  setup() {
    const form = reactive({
      together: {
        firstname: "",
        lastname: "",
      },
      separate: {
        firstname: "",
        lastname: "",
      },
      posts: {
        post1: "",
        post2: "",
      },
      isRead: false,
    });

    return {
      form,
    };
  },
});
</script>
```

### 栅格布局

展示了使用栅格布局的方式。可以使用 `label-col-flex` 的带单位字符串指定标签宽度，数字表示 Col 伸缩比例。

### 文本与数值字段

Example source: src/form/__demos__/field-components.vue

```vue
<script setup>
import ModelOutput from "../__demo-utils__/ModelOutput.vue";
import { ref } from "vue";
const editMode = ref("direct");
const presentations = ["direct", "click", "dblclick"].map((value) => ({
  value,
  label: value,
}));
const model = ref({
  name: "表单输入示例",
  notes: "每个字段都继承上方的展示与触发方式",
  count: 3,
  code: "123456",
});
</script>

<template>
  <c-space direction="column" align="stretch" :size="16">
    <c-form-item layout="vertical" size="sm" label="字段展示方式">
      <c-radio-group
        v-model="editMode"
        aria-label="字段展示方式"
        :options="presentations"
        variant="button"
        size="sm"
      />
    </c-form-item>
    <c-form :model="model" :edit-mode="editMode">
      <c-form-item field="name" label="单行文本"
        ><c-input v-model="model.name"
      /></c-form-item>
      <c-form-item field="notes" label="多行文本"
        ><c-textarea v-model="model.notes"
      /></c-form-item>
      <c-form-item field="count" label="数量"
        ><c-input-number v-model="model.count" :min="0" :max="100"
      /></c-form-item>
      <c-form-item field="code" label="验证码"
        ><c-verification-code v-model="model.code" :length="6"
      /></c-form-item>
    </c-form>
    <ModelOutput aria-label="当前模型">{{
      JSON.stringify(model, null, 2)
    }}</ModelOutput>
  </c-space>
</template>
```

### 开关与勾选字段

Example source: src/form/__demos__/field-choice.vue

```vue
<script setup>
import ModelOutput from "../__demo-utils__/ModelOutput.vue";
import { ref } from "vue";
const editMode = ref("direct");
const presentations = ["direct", "click", "dblclick"].map((value) => ({
  value,
  label: value,
}));
const choices = [
  { label: "研发", value: "dev" },
  { label: "设计", value: "design" },
  { label: "运营", value: "ops" },
];
const model = ref({
  enabled: true,
  agreed: true,
  teams: ["dev", "design"],
  role: "dev",
});
</script>

<template>
  <c-space direction="column" align="stretch" :size="16">
    <c-form-item layout="vertical" size="sm" label="字段展示方式">
      <c-radio-group
        v-model="editMode"
        aria-label="字段展示方式"
        :options="presentations"
        variant="button"
        size="sm"
      />
    </c-form-item>
    <c-form :model="model" :edit-mode="editMode">
      <c-form-item field="enabled" label="启用"
        ><c-switch v-model="model.enabled"
      /></c-form-item>
      <c-form-item field="agreed" label="确认状态"
        ><c-checkbox v-model="model.agreed">已阅读说明</c-checkbox></c-form-item
      >
      <c-form-item field="teams" label="协作部门"
        ><c-checkbox-group v-model="model.teams" :options="choices"
      /></c-form-item>
      <c-form-item field="role" label="所属部门"
        ><c-radio-group v-model="model.role" :options="choices"
      /></c-form-item>
    </c-form>
    <ModelOutput aria-label="当前模型">{{
      JSON.stringify(model, null, 2)
    }}</ModelOutput>
  </c-space>
</template>
```

### 下拉选择字段

Example source: src/form/__demos__/field-selection.vue

```vue
<script setup>
import ModelOutput from "../__demo-utils__/ModelOutput.vue";
import { ref, watch } from "vue";
const editMode = ref("direct");
const presentations = ["direct", "click", "dblclick"].map((value) => ({
  value,
  label: value,
}));
const devices = [
  {
    isGroup: true,
    label: "常用设备",
    options: [
      { value: "laptop", label: "笔记本" },
      { value: "phone", label: "手机" },
      { value: "tablet", label: "平板" },
    ],
  },
  {
    isGroup: true,
    label: "其他设备",
    options: [
      { value: "desktop", label: "台式工作站" },
      { value: "watch", label: "智能手表（暂不可选）", disabled: true },
    ],
  },
];
const people = [
  { value: "lin", label: "林晓 · 研发" },
  { value: "chen", label: "陈晨 · 设计" },
  { value: "zhou", label: "周宁 · 运营" },
];
const suggestions = [
  {
    isGroup: true,
    label: "技术团队",
    options: [
      { value: "研发" },
      { value: "研发平台" },
      { value: "研发基础设施" },
    ],
  },
  {
    isGroup: true,
    label: "协作团队",
    options: [
      { value: "设计" },
      { value: "运营" },
      { value: "归档团队", disabled: true },
    ],
  },
];
const model = ref({
  device: "laptop",
  devices: ["laptop", "phone"],
  keyword: "研发",
  person: "lin",
});
</script>

<template>
  <c-space direction="column" align="stretch" :size="16">
    <c-form-item layout="vertical" size="sm" label="字段展示方式">
      <c-radio-group
        v-model="editMode"
        aria-label="字段展示方式"
        :options="presentations"
        variant="button"
        size="sm"
      />
    </c-form-item>
    <c-form :model="model" :edit-mode="editMode">
      <c-form-item field="device" label="单选设备"
        ><c-select v-model="model.device" :options="devices" filterable
      /></c-form-item>
      <c-form-item field="devices" label="多选设备"
        ><c-select
          v-model="model.devices"
          :options="devices"
          multiple
          filterable
          :limit="3"
      /></c-form-item>
      <c-form-item field="keyword" label="自动补全"
        ><c-auto-complete
          v-model="model.keyword"
          :options="suggestions"
          clearable
          placeholder="输入或选择团队"
      /></c-form-item>
      <c-form-item field="person" label="人员"
        ><c-people-select
          v-model="model.person"
          :label="people.find((item) => item.value === model.person)?.label"
          :options="people"
          clearable
          placeholder="搜索人员"
      /></c-form-item>
    </c-form>
    <ModelOutput aria-label="当前模型">{{
      JSON.stringify(model, null, 2)
    }}</ModelOutput>
  </c-space>
</template>
```

### 层级选择字段

Example source: src/form/__demos__/field-tree.vue

```vue
<script setup>
import ModelOutput from "../__demo-utils__/ModelOutput.vue";
import { ref } from "vue";
const editMode = ref("direct");
const presentations = ["direct", "click", "dblclick"].map((value) => ({
  value,
  label: value,
}));
const regions = [
  {
    label: "华东",
    value: "east",
    children: [
      { label: "上海", value: "shanghai" },
      {
        label: "浙江",
        value: "zhejiang",
        children: [
          { label: "杭州", value: "hangzhou" },
          { label: "宁波", value: "ningbo" },
        ],
      },
    ],
  },
  {
    label: "华北",
    value: "north",
    children: [
      { label: "北京", value: "beijing" },
      { label: "天津", value: "tianjin" },
    ],
  },
  { label: "华南（暂不可选）", value: "south", disabled: true },
];
const treeOptions = [
  {
    value: "east",
    label: "华东",
    children: [
      { value: "shanghai", label: "上海" },
      {
        value: "zhejiang",
        label: "浙江",
        children: [
          { value: "hangzhou", label: "杭州" },
          { value: "ningbo", label: "宁波" },
        ],
      },
    ],
  },
  {
    value: "north",
    label: "华北",
    children: [
      { value: "beijing", label: "北京" },
      { value: "tianjin", label: "天津", disabled: true },
    ],
  },
];
const model = ref({
  regions: ["shanghai", "hangzhou"],
  region: "shanghai",
  tree: "shanghai",
  trees: ["shanghai", "hangzhou"],
});
</script>

<template>
  <c-space direction="column" align="stretch" :size="16">
    <c-form-item layout="vertical" size="sm" label="字段展示方式">
      <c-radio-group
        v-model="editMode"
        aria-label="字段展示方式"
        :options="presentations"
        variant="button"
        size="sm"
      />
    </c-form-item>
    <c-form :model="model" :edit-mode="editMode">
      <c-form-item field="region" label="地区"
        ><c-cascader v-model="model.region" :options="regions" filterable
      /></c-form-item>
      <c-form-item field="regions" label="多选地区"
        ><c-cascader
          v-model="model.regions"
          :options="regions"
          multiple
          filterable
          show-path-label
      /></c-form-item>
      <c-form-item field="tree" label="树选择"
        ><c-tree-select
          v-model="model.tree"
          :data="treeOptions"
          :filter-tree-node="
            (query, node) => String(node.label).includes(query)
          "
          filterable
      /></c-form-item>
      <c-form-item field="trees" label="多选树节点"
        ><c-tree-select
          v-model="model.trees"
          :data="treeOptions"
          multiple
          tree-checkable
          :filter-tree-node="
            (query, node) => String(node.label).includes(query)
          "
          filterable
      /></c-form-item>
    </c-form>
    <ModelOutput aria-label="当前模型">{{
      JSON.stringify(model, null, 2)
    }}</ModelOutput>
  </c-space>
</template>
```

### 日期字段

Example source: src/form/__demos__/field-date.vue

```vue
<script setup>
import ModelOutput from "../__demo-utils__/ModelOutput.vue";
import { ref } from "vue";
const editMode = ref("direct");
const presentations = ["direct", "click", "dblclick"].map((value) => ({
  value,
  label: value,
}));
const model = ref({
  datetime: "2026-10-20 09:30:00",
  dateTimes: ["2026-10-20 09:30:00", "2026-10-22 18:00:00"],
  day: "2026-10-19",
  days: ["2026-10-19", "2026-10-22"],
});
</script>

<template>
  <c-space direction="column" align="stretch" :size="16">
    <c-form-item layout="vertical" size="sm" label="字段展示方式">
      <c-radio-group
        v-model="editMode"
        aria-label="字段展示方式"
        :options="presentations"
        variant="button"
        size="sm"
      />
    </c-form-item>
    <c-form :model="model" :edit-mode="editMode">
      <c-form-item field="day" label="日期"
        ><c-date v-model="model.day" value-format="YYYY-MM-DD"
      /></c-form-item>
      <c-form-item field="days" label="日期范围"
        ><c-date-range v-model="model.days" value-format="YYYY-MM-DD"
      /></c-form-item>
      <c-form-item field="datetime" label="日期时间"
        ><c-date v-model="model.datetime" show-time
      /></c-form-item>
      <c-form-item field="dateTimes" label="日期时间范围"
        ><c-date-range v-model="model.dateTimes" show-time
      /></c-form-item>
    </c-form>
    <ModelOutput aria-label="当前模型">{{
      JSON.stringify(model, null, 2)
    }}</ModelOutput>
  </c-space>
</template>
```

### 时间字段

Example source: src/form/__demos__/field-time.vue

```vue
<script setup>
import ModelOutput from "../__demo-utils__/ModelOutput.vue";
import { ref } from "vue";
const editMode = ref("direct");
const presentations = ["direct", "click", "dblclick"].map((value) => ({
  value,
  label: value,
}));
const model = ref({
  time: "09:30",
  times: ["09:30", "18:00"],
});
</script>

<template>
  <c-space direction="column" align="stretch" :size="16">
    <c-form-item layout="vertical" size="sm" label="字段展示方式">
      <c-radio-group
        v-model="editMode"
        aria-label="字段展示方式"
        :options="presentations"
        variant="button"
        size="sm"
      />
    </c-form-item>
    <c-form :model="model" :edit-mode="editMode">
      <c-form-item field="time" label="时间"
        ><c-time v-model="model.time" format="HH:mm"
      /></c-form-item>
      <c-form-item field="times" label="时间范围"
        ><c-time-range v-model="model.times" format="HH:mm"
      /></c-form-item>
    </c-form>
    <ModelOutput aria-label="当前模型">{{
      JSON.stringify(model, null, 2)
    }}</ModelOutput>
  </c-space>
</template>
```

### 进度与评分字段

Example source: src/form/__demos__/field-rating.vue

```vue
<script setup>
import ModelOutput from "../__demo-utils__/ModelOutput.vue";
import { ref } from "vue";
const editMode = ref("direct");
const presentations = ["direct", "click", "dblclick"].map((value) => ({
  value,
  label: value,
}));
const model = ref({
  progress: 40,
  score: 4,
});
</script>

<template>
  <c-space direction="column" align="stretch" :size="16">
    <c-form-item layout="vertical" size="sm" label="字段展示方式">
      <c-radio-group
        v-model="editMode"
        aria-label="字段展示方式"
        :options="presentations"
        variant="button"
        size="sm"
      />
    </c-form-item>
    <c-form :model="model" :edit-mode="editMode">
      <c-form-item field="progress" label="进度"
        ><c-slider v-model="model.progress"
      /></c-form-item>
      <c-form-item field="score" label="评分"
        ><c-rate v-model="model.score"
      /></c-form-item>
    </c-form>
    <ModelOutput aria-label="当前模型">{{
      JSON.stringify(model, null, 2)
    }}</ModelOutput>
  </c-space>
</template>
```

### 附件字段

Example source: src/form/__demos__/field-upload.vue

```vue
<script setup>
import ModelOutput from "../__demo-utils__/ModelOutput.vue";
import { ref } from "vue";
const editMode = ref("direct");
const presentations = ["direct", "click", "dblclick"].map((value) => ({
  value,
  label: value,
}));
const model = ref({
  attachments: [],
});
</script>

<template>
  <c-space direction="column" align="stretch" :size="16">
    <c-form-item layout="vertical" size="sm" label="字段展示方式">
      <c-radio-group
        v-model="editMode"
        aria-label="字段展示方式"
        :options="presentations"
        variant="button"
        size="sm"
      />
    </c-form-item>
    <c-form :model="model" :edit-mode="editMode">
      <c-form-item field="attachments" label="附件"
        ><c-upload v-model="model.attachments" :auto-upload="false"
      /></c-form-item>
    </c-form>
    <ModelOutput aria-label="当前模型">{{
      JSON.stringify(model, null, 2)
    }}</ModelOutput>
  </c-space>
</template>
```

### 专用字段

Example source: src/form/__demos__/field-specialized.vue

```vue
<script setup>
import ModelOutput from "../__demo-utils__/ModelOutput.vue";
import { ref } from "vue";
const editMode = ref("direct");
const presentations = ["direct", "click", "dblclick"].map((value) => ({
  value,
  label: value,
}));
const choices = [
  { label: "研发", value: "dev" },
  { label: "设计", value: "design" },
  { label: "运营", value: "ops" },
];
const model = ref({
  mention: "@设计 请确认",
  color: "#36b5ac",
  tags: ["Vue", "TypeScript"],
  transferred: [{ value: "dev", label: "研发" }],
});
</script>

<template>
  <c-space direction="column" align="stretch" :size="16">
    <c-form-item layout="vertical" size="sm" label="字段展示方式">
      <c-radio-group
        v-model="editMode"
        aria-label="字段展示方式"
        :options="presentations"
        variant="button"
        size="sm"
      />
    </c-form-item>
    <c-form :model="model" :edit-mode="editMode">
      <c-form-item field="mention" label="提及"
        ><c-mention v-model="model.mention" :options="['研发', '设计', '运营']"
      /></c-form-item>
      <c-form-item field="color" label="颜色"
        ><c-color v-model="model.color"
      /></c-form-item>
      <c-form-item field="tags" label="标签"
        ><c-input-tag v-model="model.tags"
      /></c-form-item>
      <c-form-item field="transferred" label="穿梭选择"
        ><c-transfer v-model="model.transferred" :data="choices"
      /></c-form-item>
    </c-form>
    <ModelOutput aria-label="当前模型">{{
      JSON.stringify(model, null, 2)
    }}</ModelOutput>
  </c-space>
</template>
```

## 校验与提交

### 验证表单

<!-- demo-config-notes:start -->

#### 本组配置对照

| 配置     | 作用                                 | 相关示例                                   |
| -------- | ------------------------------------ | ------------------------------------------ |
| `model`  | 表单数据对象                         | 验证表单、跨字段校验与原生提交、清空时校验 |
| `layout` | 表单的布局方式，包括水平、垂直、多列 | 清空时校验                                 |

<!-- demo-config-notes:end -->

展示了表单校验的使用方法。

Example source: src/form/__demos__/validate.vue

```vue
<template>
  <c-form ref="formRef" :model="form" :style="{ width: '600px' }" @submit="handleSubmit">
    <c-form-item
      field="name"
      label="Username"
      :rules="[
        { required: true, message: 'name is required' },
        { minLength: 5, message: 'must be greater than 5 characters' },
      ]"
      :validate-trigger="['change', 'input']"
    >
      <c-input v-model="form.name" placeholder="please enter your username..." />
    </c-form-item>
    <c-form-item
      field="age"
      label="Age"
      :rules="[
        { required: true, message: 'age is required' },
        { type: 'number', max: 200, message: 'age is max than 200' },
      ]"
    >
      <c-input v-model="form.age" placeholder="please enter your age..." />
    </c-form-item>
    <c-form-item field="date" label="date" :rules="[{ required: true, message: 'age is required' }]">
      <c-date-picker v-model="form.date" placeholder="please enter date..." />
    </c-form-item>
    <c-form-item field="section" label="Section" :rules="[{ match: /section one/, message: 'must select one' }]">
      <c-select v-model="form.section" placeholder="Please select ..." clearable>
        <c-option value="section one">Section One</c-option>
        <c-option value="section two">Section Two</c-option>
        <c-option value="section three">Section Three</c-option>
      </c-select>
    </c-form-item>
  </c-form>
</template>
<script lang="ts">
import { defineComponent, reactive } from 'vue'
export default defineComponent({
  setup() {
    const handleSubmit = (data: any) => {
      console.log(data)
    }

    const form = reactive({
      size: 'md',
      name: '',
      age: undefined,
      section: '',
      province: 'haidian',
      options: [],
      date: '',
      time: '',
      radio: 'radio one',
      slider: 5,
      score: 5,
      switch: false,
      multiSelect: ['section one'],
      treeSelect: '',
    })
    const options = [
      {
        value: 'beijing',
        label: 'Beijing',
        children: [
          {
            value: 'chaoyang',
            label: 'ChaoYang',
            children: [
              {
                value: 'datunli',
                label: 'Datunli',
              },
            ],
          },
          {
            value: 'haidian',
            label: 'Haidian',
          },
          {
            value: 'dongcheng',
            label: 'Dongcheng',
          },
          {
            value: 'xicheng',
            label: 'XiCheng',
          },
        ],
      },
      {
        value: 'shanghai',
        label: 'Shanghai',
        children: [
          {
            value: 'shanghaishi',
            label: 'Shanghai',
            children: [
              {
                value: 'huangpu',
                label: 'Huangpu',
              },
            ],
          },
        ],
      },
    ]

    return {
      form,
      options,
      handleSubmit,
    }
  },
})
</script>
```

### 跨字段校验与原生提交

Pause cross-field validation holds the local confirmation rule until Resolve cross-field result. Completion compares its confirmation value with the current source. Native reset settles pending tasks, clears the model and submitted snapshot, retains the history count and prevents late submission. This is not remote cancellation or exhaustive dependency-race coverage.

“暂停跨字段校验”将确认规则挂起到“返回跨字段结果”，返回时比较本次确认值与当前源代码（不是远端接口或提交开始时的源快照）。匹配值提交后等待中修改源代码，会返回依赖错误；修正确认值并Enter重试后通过。等待中原生重置会结清本地任务、清空模型与提交快照、保留历史计数，不产生迟到提交；停用/卸载也清理等待。不代表异步循环依赖或多请求顺序均已覆盖。

未暂停时确认规则立即比较当前源代码。先匹配通过，再修改源代码，主动只校验确认值或重新提交会显示依赖错误；改正确认值后可按 Enter 或提交按钮提交。原生重置清空模型、反馈和上次提交值，提交次数累计不清零。依赖由业务主动复验，单纯编辑不保证已有成功态仍有效；本地示例不等于任意异步提交竞争或外部持久化。

Example source: src/form/__demos__/cross-field.vue

```vue
<script setup>
import ModelOutput from "../__demo-utils__/ModelOutput.vue";

import {
  onBeforeUnmount,
  onDeactivated,
  reactive,
  ref,
  shallowRef,
  useId,
} from "vue";

const formRef = ref();
const id = useId();
const model = reactive({ source: "", confirmation: "" });
const result = ref("尚未提交");
const submissions = ref(0);
const snapshot = ref("");
const message = "两次代码须相同且不能为空";
const sourceRules = [{ required: true, message: "请输入源代码" }];
const paused = ref(false);
const pending = shallowRef([]);
let epoch = 0;
function complete() {
  const [resolve, ...rest] = pending.value;
  pending.value = rest;
  resolve?.();
}
function cleanup() {
  epoch++;
  const tasks = pending.value;
  pending.value = [];
  tasks.forEach((resolve) => resolve());
}
onBeforeUnmount(cleanup);
onDeactivated(cleanup);
const confirmationRules = [
  {
    validator: async (value, callback) => {
      if (paused.value)
        await new Promise((resolve) => {
          pending.value = [...pending.value, resolve];
        });
      if (!value || value !== model.source) callback(message);
    },
  },
];
function submitted({ errors, values }) {
  submissions.value++;
  result.value = errors ? "未通过" : "通过";
  snapshot.value = JSON.stringify(values);
}
async function validateConfirmation() {
  const current = ++epoch;
  const errors = await formRef.value?.validateField("confirmation");
  if (current === epoch) result.value = errors ? "确认值未通过" : "确认值通过";
}
function reset() {
  cleanup();
  result.value = "已重置";
  snapshot.value = "";
}
</script>

<template>
  <section class="cross-field-form-demo">
    <p>
      仅使用本地合成代码。校验时确认值比较当前源代码；修改源代码不自动复验依赖字段。
    </p>
    <c-form ref="formRef" :model="model" @submit="submitted" @reset="reset">
      <c-form-item
        field="source"
        label="源代码"
        :label-attrs="{ for: id + '-source' }"
        :rules="sourceRules"
        :validate-trigger="[]"
        feedback
      >
        <c-input :id="id + '-source'" v-model="model.source" />
      </c-form-item>
      <c-form-item
        field="confirmation"
        label="确认代码"
        :label-attrs="{ for: id + '-confirmation' }"
        :rules="confirmationRules"
        :validate-trigger="[]"
        feedback
      >
        <c-input :id="id + '-confirmation'" v-model="model.confirmation" />
      </c-form-item>
      <c-space wrap>
        <c-button html-type="submit">提交代码</c-button>
        <c-button @click="validateConfirmation">只校验确认值</c-button>
        <c-button html-type="reset">重置代码</c-button>
      </c-space>
    </c-form>
    <p role="status">结果：{{ result }}；提交次数：{{ submissions }}</p>
    <c-button
      html-type="button"
      :aria-pressed="paused"
      @click="paused = !paused"
      >暂停跨字段校验</c-button
    >
    <c-button html-type="button" :disabled="!pending.length" @click="complete"
      >返回跨字段结果</c-button
    >
    <p class="cross-field-pending">等待：{{ pending.length }}</p>
    <ModelOutput>模型：{{ model }}</ModelOutput>
    <ModelOutput>上次提交值：{{ snapshot || "-" }}</ModelOutput>
  </section>
</template>
```

### 清空时校验

`validate-trigger="clear"` 只在用户点击控件的清空按钮时校验；普通输入不会触发。本例清空后显示必填错误；重新输入不会自动清除该错误，可主动校验或重置表单。

Example source: src/form/__demos__/clear-trigger.vue

```vue
<script setup lang="ts">
import { reactive, ref } from 'vue'

const model = reactive({ keyword: 'Cedar' })
const formRef = ref()
</script>

<template>
  <c-form ref="formRef" :model="model" layout="vertical" style="max-width: 360px">
    <c-form-item field="keyword" label="关键词" :rules="[{ required: true, message: '请输入关键词' }]" validate-trigger="clear">
      <c-input v-model="model.keyword" clearable placeholder="清空后立即校验" />
    </c-form-item>
    <c-button @click="formRef?.resetFields()">重置</c-button>
  </c-form>
</template>
```

### 空值标记与必填校验

接口用 -1 表示未选择。点击“校验”会显示必填错误；选择部门后再次校验通过。点击清空返回 -1，再次校验失败。Form 统一提供识别列表，字段单独指定清空输出；自定义校验仍收到原值。

Example source: src/form/__demos__/empty-values-validation.vue

```vue
<script setup lang="ts">
import { reactive, ref } from "vue";
const model = reactive({ department: -1 as number | null | undefined });
const form = ref();
const result = ref("尚未校验");
const options = [
  { value: 1, label: "研发" },
  { value: 2, label: "产品" },
];
async function validate() {
  const errors = await form.value.validate();
  result.value = errors ? "存在必填错误" : "校验通过";
}
</script>
<template>
  <c-space direction="column">
    <p>先校验初始 -1，再选择部门并校验；点击清空后会回到 -1。</p>
    <c-form
      ref="form"
      :model="model"
      layout="vertical"
      :empty-values="[null, undefined, -1]"
    >
      <c-form-item field="department" label="部门" required>
        <c-select
          v-model="model.department"
          :options="options"
          edit-mode="direct"
          clearable
          :empty-value="-1"
        />
      </c-form-item>
    </c-form>
    <c-button @click="validate">校验</c-button>
    <p role="status">{{ result }}</p>
    <p>
      当前模型: <output>{{ String(model.department) }}</output>
    </p>
  </c-space>
</template>
```

### 自定义表单校验状态

开启 feedback 可以让部分输入组件展示当前状态信息

Example source: src/form/__demos__/feedback.vue

```vue
<template>
  <c-form :style="{ width: '600px' }">
    <c-form-item field="name" label="Username" validate-status="success" feedback>
      <c-input placeholder="please enter your username..." />
    </c-form-item>
  </c-form>
</template>
<script lang="ts">
import { defineComponent } from 'vue'
export default defineComponent({
  })
</script>
```

## 字段呈现与交互

### 交互状态切换

<!-- demo-config-notes:start -->

#### 本组配置对照

| 配置              | 作用                                                                                 | 相关示例                                                       |
| ----------------- | ------------------------------------------------------------------------------------ | -------------------------------------------------------------- |
| `layout`          | 表单的布局方式，包括水平、垂直、多列                                                 | 交互状态切换、校验展示状态、桌面与移动的同场景展示             |
| `model`           | 表单数据对象                                                                         | 字段展示与确认提交、桌面与移动的同场景展示、滚动到指定表单字段 |
| `disabled`        | 是否禁用表单                                                                         | 交互状态切换                                                   |
| `readonly`        | 是否将表单控件设为只读                                                               | 交互状态切换                                                   |
| `scroll-to-error` | 验证失败后滚动到页面顺序的第一个（start）或最后一个（end）错误字段；不是视口对齐方式 | 滚动到指定表单字段                                             |

<!-- demo-config-notes:end -->

适用于整张表单的状态继承。调整禁用、只读，用相同数据观察变化。控制区始终可用，可以随时恢复编辑；错误外观本身不会触发表单校验。

Example source: src/form/__demos__/state-lab.vue

```vue
<script setup lang="ts">
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
import type { FormItemValidateStatus } from "@cedar-design/ui";
const status = ref<FormItemValidateStatus>("warning");
const __demoState = __demoReactive({ disabled: false, readonly: false });
</script>
<template>
  <c-space direction="column" :size="16">
    <c-space wrap>
      <c-checkbox v-model="__demoState['disabled']">disabled</c-checkbox>
      <c-checkbox v-model="__demoState['readonly']">readonly</c-checkbox>
    </c-space>
    <c-form layout="vertical" v-bind="__demoState">
      <c-form-item
        label="展示状态"
        feedback
        :validate-status="status"
        help="显式状态只控制外观，不改变实际校验结果。"
      >
        <c-input placeholder="切换上方状态" />
      </c-form-item>
    </c-form>
  </c-space>
</template>
<style scoped>
.status-demo {
  display: flex;
  flex-direction: column;
  gap: 16px;
}
</style>
```

### 字段展示与确认提交

Form、FormItem、Input 和 Select 支持 edit-mode 继承，优先级为字段 > FormItem > Form。默认 direct；Cedar 支持 click/dblclick。普通 v-model 不变，弹层默认确认后提交。readPretty 不显示编辑器和搜索。direct 即时更新，弹层确认后更新；搜索框按展示位置自动排列。

Example source: src/form/__demos__/field-presentation.vue

```vue
<script setup>
import ModelOutput from "../__demo-utils__/ModelOutput.vue";

import { computed, ref } from "vue";

const editMode = ref("direct");
const readPretty = ref(false);

const options = ref([
  { value: 1, label: "研发设备" },
  { value: 2, label: "设计设备" },
  { value: 3, label: "运营设备" },
]);
const form = ref({
  name: "默认可直接编辑",
  deviceIds: [2],
  note: "此项始终直接编辑",
  summary: "只读展示",
});
const status = ref("");

const modeOptions = ["direct", "click", "dblclick"].map((value) => ({
  label: value,
  value,
}));
const committed = computed(() => JSON.stringify(form.value));
const presentationHint = computed(() =>
  readPretty.value
    ? "只展示已保存的值；下方“单项覆盖 direct”通过 readPretty=false 保持可编辑。"
    : editMode.value === "direct"
      ? "直接编辑，即时更新下方模型；选择设备无需额外确认。"
      : "按展示方式进入编辑；确认才更新下方模型，取消不保存本次修改。",
);
</script>
<template>
  <c-space direction="column" align="stretch" :size="16">
    <c-form-item layout="vertical" size="sm" label="Form 展示方式">
      <c-radio-group
        aria-label="Form 展示方式"
        v-model="editMode"
        :options="modeOptions"
        variant="button"
        size="sm"
      />
    </c-form-item>
    <c-space wrap>
      <c-checkbox v-model="readPretty">纯阅读 readPretty</c-checkbox>
    </c-space>
    <p>
      {{ presentationHint }}<br />设备 4 已停用，最多选择 3
      个设备；可切换本地搜索与模拟远程搜索。
    </p>
    <c-form
      :model="form"
      :edit-mode="editMode"
      :read-pretty="readPretty"
      @submit-success="status = '表单已提交'"
      @submit-failed="status = '请完成当前编辑或修正校验错误'"
    >
      <c-form-item
        field="name"
        label="名称"
        :rules="[{ required: true, message: '名称不能为空' }]"
      >
        <c-input v-model="form.name" placeholder="请输入名称" clearable />
      </c-form-item>
      <c-form-item
        field="deviceIds"
        label="设备"
        :rules="[{ type: 'array', required: true, message: '请选择设备' }]"
      >
        <c-select
          v-model="form.deviceIds"
          :options="options"
          multiple
          filterable
          :limit="3"
          placeholder="搜索设备"
        />
      </c-form-item>
      <c-form-item
        field="note"
        label="单项覆盖 direct"
        edit-mode="direct"
        :read-pretty="false"
      >
        <c-input v-model="form.note" />
      </c-form-item>
      <c-form-item field="summary" label="固定 readPretty" read-pretty>
        <c-input v-model="form.summary" />
      </c-form-item>
      <c-button html-type="submit">提交表单</c-button>
    </c-form>
    <ModelOutput role="status">当前模型：{{ committed }}</ModelOutput>
    <p v-if="status" role="status">{{ status }}</p>
  </c-space>
</template>
```

### 原位编辑的提交与切换

`click` / `dblclick` 共用事务逻辑：点击外部、Tab 离开或切换字段时先尝试保存，成功后关闭；校验失败或 `beforeCommit` 拒绝时保留草稿和错误，并阻止打开其他字段。同一文档同时只打开一个原位编辑器，包括不同 Form 和独立字段。字段自身传送到 body 的选项、日期和时间面板属于内部区域，选值不会触发外部保存。

内层面板打开时，Enter 优先选值，Esc 只关闭最上层面板并回到控件、保留字段草稿；面板关闭后，Enter 保存，Esc 取消并恢复原值。悬浮或键盘聚焦时显示编辑图标，并通过提示区分单击/双击；点击图标始终直接进入编辑。

多行文本保留 Enter 换行，Ctrl/Cmd+Enter 保存。输入法组词期间的 Enter 不提交。日期、时间面板内的单元格和列选项也只更新草稿，不误触外层保存。异步确认期间禁止重复确认、取消和切换；重置会终止保存及等待中的切换，迟到的结果不会写回。保存失败后可修改并重试。

### 阅读空文案与配置继承

初始为阅读模式，姓名继承 Form 的默认“-”，编号使用 FormItem 的“未分配”，昵称使用字段的“匿名”，数量 0 保持可见。切换空文案只影响继承的字段；切换阅读/编辑不改模型。优先级为字段 > FormItem > Form；自定义 read 插槽优先。

Example source: src/form/__demos__/empty-text.vue

```vue
<script setup lang="ts">
import { reactive, ref } from "vue";
const reading = ref(true);
const emptyText = ref("-");
const model = reactive({
  name: null as string | null,
  code: null as string | null,
  nickname: null as string | null,
  quantity: 0 as number | null | undefined,
});
</script>
<template>
  <c-space direction="column">
    <p>初始阅读模式：姓名显示“-”，编号和昵称使用各自覆盖；数量 0 仍显示 0。</p>
    <c-space wrap>
      <c-button @click="reading = !reading">切换阅读/编辑</c-button>
      <c-button @click="emptyText = '暂无'">使用“暂无”</c-button>
      <c-button @click="emptyText = '-'">使用默认“-”</c-button>
    </c-space>
    <c-form
      :model="model"
      layout="vertical"
      :read-pretty="reading"
      :empty-text="emptyText"
    >
      <c-form-item field="name" label="姓名：继承 Form"
        ><c-input v-model="model.name"
      /></c-form-item>
      <c-form-item field="code" label="编号：覆盖 FormItem" empty-text="未分配"
        ><c-input v-model="model.code"
      /></c-form-item>
      <c-form-item field="nickname" label="昵称：覆盖字段" empty-text="未分配"
        ><c-input v-model="model.nickname" empty-text="匿名"
      /></c-form-item>
      <c-form-item field="quantity" label="数量"
        ><c-input-number v-model="model.quantity"
      /></c-form-item>
    </c-form>
    <p>
      当前模型: <output>{{ JSON.stringify(model) }}</output>
    </p>
  </c-space>
</template>
```

### 校验展示状态

显式 validate-status 优先于自动状态；error 才显示错误信息，其他状态显示 help。它只控制展示，不改变 validate 的真实结果。自动校验经历 validating → success/error；clearValidate 恢复未校验状态。setFields 仅传 message 会设为 error；显式 status='' 和 message='' 可清空。

Example source: src/form/__demos__/presentation-status.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
import type { FormItemValidateStatus } from '@cedar-design/ui'
const status = ref<FormItemValidateStatus>('warning')
const statuses: FormItemValidateStatus[] = ['success', 'warning', 'error', 'validating']
</script>

<template>
  <div class="status-demo">
    <c-space wrap>
      <c-button v-for="item in statuses" :key="item" @click="status = item">{{ item }}</c-button>
    </c-space>
    <c-form layout="vertical">
      <c-form-item label="展示状态" feedback :validate-status="status" help="显式状态只控制外观，不改变实际校验结果。">
        <c-input placeholder="切换上方状态" />
      </c-form-item>
    </c-form>
  </div>
</template>

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

### 桌面与移动的同场景展示

桌面字段在当前位置展开面板；选择后观察已提交模型。

Example source: src/form/__demos__/platform-presentation.vue

```vue
<script setup>
import { computed, ref } from "vue";
const initialModel = () => ({
  title: "设备巡检",
  department: "design",
  date: undefined,
  time: undefined,
});
const model = ref(initialModel());
const departments = [
  { value: "dev", label: "研发部" },
  { value: "design", label: "设计部" },
  { value: "ops", label: "运营部" },
];
const committed = computed(() =>
  JSON.stringify({
    title: model.value.title,
    department: model.value.department,
    date: model.value.date ?? null,
    time: model.value.time ?? null,
  }),
);
function reset() {
  model.value = initialModel();
}
</script>
<template>
  <c-space direction="column" class="platform-presentation-demo">
    <p>桌面字段在当前位置展开面板；选择后观察已提交模型。</p>
    <c-form :model="model" layout="vertical">
      <c-form-item label="任务名称" field="title"
        ><c-input
          v-model="model.title"
          edit-mode="direct"
          placeholder="输入任务名称"
      /></c-form-item>
      <c-form-item label="负责部门" field="department"
        ><c-select
          v-model="model.department"
          :options="departments"
          edit-mode="direct"
          placeholder="选择部门"
      /></c-form-item>
      <c-form-item label="执行日期" field="date"
        ><c-date v-model="model.date" edit-mode="direct" placeholder="选择日期"
      /></c-form-item>
      <c-form-item label="执行时间" field="time"
        ><c-time v-model="model.time" edit-mode="direct" placeholder="选择时间"
      /></c-form-item>
    </c-form>
    <div class="platform-presentation-demo__model">
      <strong>已提交模型</strong
      ><output aria-label="已提交模型" role="status">{{ committed }}</output>
    </div>
    <c-button @click="reset">重置本例</c-button>
  </c-space>
</template>
<style scoped>
.platform-presentation-demo {
  width: 100%;
  min-width: 0;
}
.platform-presentation-demo__model {
  width: 100%;
  padding: 12px;
  border-radius: 8px;
  background: var(--c-color-fill-1);
  color: var(--c-color-text-1);
}
.platform-presentation-demo__model output {
  display: block;
  margin-top: 8px;
  overflow-wrap: anywhere;
  font-size: 12px;
}
</style>
```

### 独立面板操作区

Example source: src/form/__demos__/field-panel-actions.vue

```vue
<template>
  <c-space direction="column" :size="16">
    <c-date-picker
      default-value="2026-10-20 09:30:00"
      show-time
      :disable-confirm="false"
    />
    <c-date-picker
      default-value="2026-10-20 09:30:00"
      show-time
      :disable-confirm="false"
    >
      <template #actions="{ selectNow, nowDisabled, confirm, disabled }">
        <c-button variant="text" :disabled="nowDisabled" @click="selectNow"
          >此刻</c-button
        >
        <c-button :disabled="disabled" @click="confirm">完成</c-button>
      </template>
    </c-date-picker>
  </c-space>
</template>
```

### 滚动到指定表单字段

展示了提交失败自动滚动到第一个错误字段和手动滚动对应字段的使用方法。

Example source: src/form/__demos__/scroll-assign.vue

```vue
<template>
  <c-space>
    <c-button @click="formRef && formRef.validate()">Submit</c-button>
    <c-button @click="formRef && formRef.resetFields()">Reset</c-button>
    <c-button @click="formRef && formRef.scrollToField('name19')">Scroll to the last field</c-button>
  </c-space>
  <c-form
    ref="formRef"
    style="width: 500px; height: 300px; margin-top: 20px; padding-right: 16px; overflow: auto"
    :model="form"
    scroll-to-error="start"
  >
    <template v-for="(fieldName, index) in fieldNames" :key="index">
      <c-form-item :field="fieldName" :label="'user' + index" :rules="[{ required: true, message: 'Name is required' }]">
        <c-input v-model="form[fieldName]" />
      </c-form-item>
    </template>
  </c-form>
</template>
<script lang="ts">
import { reactive, ref, defineComponent } from 'vue'
export default defineComponent({
  setup() {
    const formRef = ref<FormInstance>()
    const fieldCount = 20
    const fieldNames = Array.from({ length: fieldCount }, (_, index) => `name${index}`)
    const form = reactive(
      Object.fromEntries(fieldNames.map((fieldName, index) => [fieldName, index === 7 ? '' : index.toString()])),
    )

    return {
      form,
      formRef,
      fieldCount,
      fieldNames,
    }
  },
})
</script>
```

## 动态与异步字段

### 动态表单

<!-- demo-config-notes:start -->

#### 本组配置对照

| 配置       | 作用                   | 相关示例                                 |
| ---------- | ---------------------- | ---------------------------------------- |
| `model`    | 表单数据对象           | 动态表单、表单异步校验、多字段异步聚合   |
| `disabled` | 是否禁用表单           | 禁用、只读与异步确认、异步校验的返回顺序 |
| `readonly` | 是否将表单控件设为只读 | 禁用、只读与异步确认、异步校验的返回顺序 |
| `rules`    | 表单项校验规则         | 禁用、只读与异步确认                     |

<!-- demo-config-notes:end -->

通过数据动态控制表单内容。

Example source: src/form/__demos__/dynamic-form.vue

```vue
<template>
  <c-form :model="form" :style="{ width: '600px' }">
    <c-form-item field="name" label="Username">
      <c-input v-model="form.name" placeholder="please enter your username..." />
    </c-form-item>
    <c-form-item
      v-for="(post, index) of form.posts"
      :field="`posts[${index}].value`"
      :label="`Post-${index}`"
      :key="index"
    >
      <c-input v-model="post.value" placeholder="please enter your post..." />
      <c-button @click="handleDelete(index)" :style="{ marginLeft: '10px' }">Delete</c-button>
    </c-form-item>
  </c-form>
  <div>
    <c-button @click="handleAdd">Add Post</c-button>
  </div>
  {{ form }}
</template>
<script lang="ts">
import { reactive, defineComponent } from 'vue'
export default defineComponent({
  setup() {
    const form = reactive({
      name: '',
      posts: [{ value: '' }],
    })
    const handleAdd = () => {
      form.posts.push({
        value: '',
      })
    }
    const handleDelete = (index) => {
      form.posts.splice(index, 1)
    }

    return {
      form,
      handleAdd,
      handleDelete,
    }
  },
})
</script>
```

### 表单异步校验

本地模拟异步校验，用户名输入 `admin` 后提交通过，其他值显示错误；不访问外部接口。原生提交/重置按钮使用 `html-type`。重置会取消本例的模拟校验并忽略旧提交结果，卸载或停用也会清理计时器。

外层标签通过 `label-attrs.for` 对应 Input 的 `id`；多个示例实例使用独立 ID，便于点击标签聚焦和辅助技术识别。

Example source: src/form/__demos__/async-validate-form.vue

```vue
<template>
  <section class="async-form-demo" @submit.capture="beginSubmit">
    <p>本地模拟异步校验：用户名只能是 admin，延迟 600ms，不访问外部接口。</p>
    <c-form
      ref="formRef"
      :model="form"
      @submit="handleSubmit"
      @reset="handleReset"
    >
      <c-form-item
        field="name"
        label="用户名"
        :label-attrs="{ for: `${demoId}-name` }"
        :rules="rules"
        feedback
      >
        <c-input
          :id="`${demoId}-name`"
          v-model="form.name"
          placeholder="请输入 admin"
        />
      </c-form-item>
      <c-form-item
        field="post"
        label="岗位"
        :label-attrs="{ for: `${demoId}-post` }"
      >
        <c-input
          :id="`${demoId}-post`"
          v-model="form.post"
          placeholder="请输入岗位"
        />
      </c-form-item>
      <c-form-item field="isRead">
        <c-checkbox v-model="form.isRead">已阅读说明</c-checkbox>
      </c-form-item>
      <c-form-item>
        <c-space>
          <c-button html-type="submit" status="primary" :loading="submitting"
            >提交</c-button
          >
          <c-button html-type="reset">重置</c-button>
          <c-button @click="setStatus">模拟服务端错误</c-button>
        </c-space>
      </c-form-item>
    </c-form>
    <p role="status">提交结果：{{ result }}；活动校验：{{ pendingCount }}</p>
    <ModelOutput>{{ form }}</ModelOutput>
  </section>
</template>

<script setup lang="ts">
import ModelOutput from '../__demo-utils__/ModelOutput.vue'

import { onBeforeUnmount, onDeactivated, reactive, ref, useId } from "vue";
import type { FormInstance, FieldRule } from "@cedar-design/ui";

const formRef = ref<FormInstance>();
const demoId = useId();
const form = reactive({ name: "", post: "", isRead: false });
const result = ref("尚未提交");
const submitting = ref(false);
const pendingCount = ref(0);
const pending = new Map<ReturnType<typeof setTimeout>, () => void>();
let generation = 0;
let submittedGeneration = -1;
const rules: FieldRule[] = [
  {
    validator: (value, callback) =>
      new Promise<void>((resolve) => {
        const current = generation;
        const timer = setTimeout(() => {
          pending.delete(timer);
          pendingCount.value = pending.size;
          if (current === generation && value !== "admin")
            callback("用户名必须是 admin");
          resolve();
        }, 600);
        pending.set(timer, resolve);
        pendingCount.value = pending.size;
      }),
  },
];

function beginSubmit() {
  submittedGeneration = generation;
  submitting.value = true;
  result.value = "校验中";
}
function cancelPending() {
  generation++;
  pending.forEach((resolve, timer) => {
    clearTimeout(timer);
    resolve();
  });
  pending.clear();
  pendingCount.value = 0;
  submitting.value = false;
}
function handleSubmit({ errors }: { errors?: unknown }) {
  if (submittedGeneration !== generation) return;
  submitting.value = false;
  result.value = errors ? "未通过" : "通过";
}
function handleReset() {
  cancelPending();
  result.value = "已重置";
}
function setStatus() {
  formRef.value?.setFields({
    name: { status: "error", message: "模拟服务端用户名错误" },
    post: { status: "error", message: "模拟服务端岗位错误" },
  });
  result.value = "服务端错误已展示";
}
onBeforeUnmount(cancelPending);
onDeactivated(cancelPending);
</script>
```

### 多字段异步聚合

State-command addendum: public `clearValidate()` and `setFields()` also invalidate a pending native submission, including field-scoped calls. Old completion cannot append submit events after a clear or explicit error; a fresh native submission still validates normally. The earlier exclusion below now applies only to editing without revalidation. The Demo keeps old tasks available for manual settlement; this does not cancel real requests.

显式调用validate()或validateField()会使等待中的旧原生submit失效：命令校验有自己的结果，不应让旧submit在完成后把旧错误或成功与当前模型混发。此后新的原生submit仍正常等待自己的字段校验并通知一次。该规则仅逻辑失效、不取消真实请求，不清空历史提交计数；既有方法签名不变，不保留旧的混发行为。仅编辑但未重新校验的快照协议仍未覆盖。

Explicit validate() or validateField() invalidates a pending older native submit. The imperative result is independent: an older submit must not later combine stale errors or success with the current model. A fresh native submit still waits for its own fields and notifies once. This is logical invalidation, not request cancellation, and retains submission history. Method signatures are unchanged; stale mixed notifications are not retained for compatibility. This does not define editing-only snapshot behavior.

“返回最新用户名结果 / 返回最新代码结果”优先结清对应字段最新任务，可让新submit先完成、旧结果最后返回。新成功后旧失败不追加提交或恢复错误；新失败后旧成功不追加提交或清除新错误。仍须等最新提交的两个字段都返回，单个字段返回不提交；默认“返回用户名/代码结果”继续返回最早任务。

原生submit采用最新提交生效：旧提交仍等待时再次提交，使旧提交的submit/submit-success/submit-failed续体失效。用guest/bad提交后改为admin/1234再提交；先返回旧两个结果，原生提交计数应仍0，新提交仍等自己的两个结果。反向旧成功/新失败同理，旧成功不能提前报通过。这个规则不取消真实请求，也不处理仅编辑但没有再次提交的业务快照。

原生submit等待中调用resetFields（含原生reset）会使该提交失效；旧Promise结清后不得再发submit、submit-success或submit-failed。停用/卸载同样使旧提交失效，后续新提交仍正常校验。此为逻辑失效，不是取消远端请求；并发submit和跨字段异步依赖不在这个重置协议内。

“原生异步提交”是表单内的原生submit按钮，也可聚焦后按Enter。独立“原生提交”计数须等两个本地异步字段都返回才增加：用户名失败先返回时暂不提交，代码返回后记录失败；修正为admin再提交，反序返回代码/用户名后记录成功并清错。下方“结果”仍只表示命令式校验，两个计数/结果互不冒充。完成后重置清空字段、保留历史提交计数。此顺序重试不代表并发submit或跨字段异步依赖已覆盖。

同一示例可连续点击两次“校验两个字段”：先输入旧值并发起，再改值发起新一轮。“返回用户名结果 / 返回代码结果”各返回该字段最早任务。旧整表先完成时，新一轮仍须等它自己的两个字段；旧成功或失败都不应覆盖最新字段反馈。结果文案由示例序号单独保护，不是 Form 自动取消旧请求，也不是原生提交并发协议。

两个字段分别返回独立本地 Promise。先返回任一字段可更新该字段反馈，但整表须等两个字段都完成。重置使旧反馈和示例结果失效，旧任务仍可手动返回以观察迟到结果。这里演示命令式 validate()，不是原生提交事件并发或跨字段依赖。

也可在用户名结果已返回、代码仍等待时重置，立即输入新值并再次校验。此时返回最早代码只会结清旧任务，不能恢复旧错误或提前完成新整表；必须返回新一轮自己的两个结果。分别用旧失败/新成功、旧成功/新失败核对字段反馈；结果文案仍由示例版本号单独保护，不等于取消真实请求。

Example source: src/form/__demos__/async-fields.vue

```vue
<script setup>
import ModelOutput from "../__demo-utils__/ModelOutput.vue";

import {
  onBeforeUnmount,
  onDeactivated,
  reactive,
  ref,
  shallowRef,
  useId,
} from "vue";
const formRef = ref();
const id = useId();
const model = reactive({ name: "", code: "" });
const pending = shallowRef([]);
const submissions = ref(0);
const submittedResult = ref("-");
function submitted({ errors }) {
  submissions.value++;
  submittedResult.value = errors ? "未通过" : "通过";
}
const result = ref("尚未校验");
let run = 0;
function request(field, value) {
  return new Promise((resolve) => {
    pending.value = [...pending.value, { field, value, resolve }];
  });
}
function rules(field) {
  return [
    {
      validator: async (value, callback) => {
        const answer = await request(field, value);
        if (answer !== true) callback(answer);
      },
    },
  ];
}
const nameRules = rules("name");
const codeRules = rules("code");
async function validate() {
  const current = ++run;
  result.value = "校验中";
  const errors = await formRef.value?.validate();
  if (current === run) result.value = errors ? "未通过" : "通过";
}
function complete(field, latest = false) {
  const tasks = pending.value.filter((item) => item.field === field);
  const task = latest ? tasks.at(-1) : tasks[0];
  if (!task) return;
  pending.value = pending.value.filter((item) => item !== task);
  task.resolve(
    task.value === (field === "name" ? "admin" : "1234")
      ? true
      : field === "name"
        ? "用户名必须是 admin"
        : "代码必须是 1234",
  );
}
function reset() {
  run++;
  formRef.value?.resetFields();
  result.value = "已重置";
}
function clear() {
  run++;
  formRef.value?.clearValidate();
  result.value = "已清空";
}
function serverError() {
  run++;
  formRef.value?.setFields({
    name: { status: "error", message: "模拟服务端拒绝" },
  });
  result.value = "服务端错误";
}
function cleanup() {
  run++;
  const tasks = pending.value;
  pending.value = [];
  tasks.forEach((task) => task.resolve(true));
}
onBeforeUnmount(cleanup);
onDeactivated(cleanup);
</script>
<template>
  <section class="async-fields-form-demo">
    <p>
      两个独立本地 Promise 规则分别接受 admin 和
      1234；手动返回各字段，不访问网络。
    </p>
    <c-form ref="formRef" :model="model" @submit="submitted">
      <c-form-item
        field="name"
        label="用户名"
        :label-attrs="{ for: id + '-name' }"
        :rules="nameRules"
        :validate-trigger="[]"
        feedback
      >
        <c-input :id="id + '-name'" v-model="model.name" />
      </c-form-item>
      <c-form-item
        field="code"
        label="代码"
        :label-attrs="{ for: id + '-code' }"
        :rules="codeRules"
        :validate-trigger="[]"
        feedback
      >
        <c-input :id="id + '-code'" v-model="model.code" />
      </c-form-item>
      <c-button html-type="submit">原生异步提交</c-button>
    </c-form>
    <c-button html-type="button" @click="clear">清空校验</c-button>
    <c-button html-type="button" @click="serverError">写入服务端错误</c-button>
    <p class="async-submit-status">
      原生提交：{{ submissions }}；结果：{{ submittedResult }}
    </p>
    <c-space wrap>
      <c-button @click="validate">校验两个字段</c-button>
      <c-button
        :disabled="!pending.some((item) => item.field === 'name')"
        @click="complete('name')"
        >返回用户名结果</c-button
      >
      <c-button
        :disabled="!pending.some((item) => item.field === 'code')"
        @click="complete('code')"
        >返回代码结果</c-button
      >
      <c-button
        :disabled="!pending.some((item) => item.field === 'name')"
        @click="complete('name', true)"
        >返回最新用户名结果</c-button
      >
      <c-button
        :disabled="!pending.some((item) => item.field === 'code')"
        @click="complete('code', true)"
        >返回最新代码结果</c-button
      >
      <c-button @click="reset">重置两个字段</c-button>
    </c-space>
    <p role="status">
      结果：{{ result }}；用户名等待：{{
        pending.filter((item) => item.field === "name").length
      }}；代码等待：{{ pending.filter((item) => item.field === "code").length }}
    </p>
    <ModelOutput>{{ model }}</ModelOutput>
  </section>
</template>
```

### 禁用、只读与异步确认

Example source: src/form/__demos__/presentation-state.vue

```vue
<script setup>
import ModelOutput from "../__demo-utils__/ModelOutput.vue";

import { computed, onBeforeUnmount, ref, shallowRef } from "vue";

const form = ref();
const editMode = ref("dblclick");
const disabled = ref(false);
const readonly = ref(false);
const model = ref({ title: "原名称", note: "原备注", department: "dev" });

const choices = [
  { value: "dev", label: "研发" },
  { value: "design", label: "设计" },
];

const check = (predicate) => [
  {
    validator: (value, callback) => {
      const result = predicate(value);
      callback(result === true ? undefined : result);
    },
  },
];
const rules = { title: check((value) => Boolean(value) || "名称必填") };

const scenario = ref("success");
const scenarios = [
  { value: "success", label: "保存成功" },
  { value: "failure", label: "保存失败，保留草稿" },
  { value: "reset", label: "等待期间重置表单" },
  { value: "disabled", label: "等待期间设为禁用" },
  { value: "readonly", label: "等待期间设为只读" },
];
const pending = shallowRef();
const result = ref("尚未保存");
const current = computed(() => JSON.stringify(model.value));
function save(value, { signal }) {
  return new Promise((resolve, reject) => {
    const timer = { id: undefined };
    let settled = false;
    const task = {
      value,
      finish(error, aborted = false) {
        if (settled) return;
        settled = true;
        clearTimeout(timer.id);
        signal.removeEventListener("abort", abort);
        if (pending.value === task) pending.value = undefined;
        result.value = aborted
          ? "保存已取消，旧结果不会提交"
          : error
            ? "保存失败，保留草稿"
            : "保存成功";
        if (error) reject(new Error("模拟保存失败，请重试"));
        else resolve(aborted ? false : undefined);
      },
    };
    const abort = () => task.finish(false, true);
    if (signal.aborted) {
      abort();
      return;
    }
    signal.addEventListener("abort", abort, { once: true });
    pending.value = task;
    result.value = "模拟保存中（1.2 秒）";
    timer.id = setTimeout(() => {
      if (scenario.value === "reset") form.value.resetFields();
      else if (scenario.value === "disabled") disabled.value = true;
      else if (scenario.value === "readonly") readonly.value = true;
      else task.finish(scenario.value === "failure");
    }, 1200);
  });
}
onBeforeUnmount(() => pending.value?.finish(false, true));
</script>
<template>
  <c-space direction="column" align="stretch" :size="16">
    <c-form-item layout="vertical" size="sm" label="异步保存场景">
      <c-radio-group
        v-model="scenario"
        aria-label="异步保存场景"
        :options="scenarios"
        variant="button"
        size="sm"
      />
    </c-form-item>
    <c-checkbox v-model="disabled">禁用状态示例</c-checkbox>
    <c-checkbox v-model="readonly">只读状态示例</c-checkbox>
    <p>
      编辑名称、备注或部门并保存，模拟等待 1.2
      秒。选择保存结果，或在等待时禁用、只读、重置，观察草稿是否提交。
    </p>
    <c-form
      ref="form"
      :model="model"
      :edit-mode="editMode"
      :disabled="disabled"
      :readonly="readonly"
      :rules="rules"
    >
      <c-form-item field="title" label="事务名称"
        ><c-input v-model="model.title" :before-commit="save"
      /></c-form-item>
      <c-form-item field="note" label="事务备注"
        ><c-textarea v-model="model.note" :before-commit="save"
      /></c-form-item>
      <c-form-item field="department" label="事务部门"
        ><c-select
          v-model="model.department"
          :options="choices"
          filterable
          :before-commit="save"
      /></c-form-item>
    </c-form>
    <c-space>
      <c-button @click="form.resetFields()">重置状态示例</c-button>
    </c-space>
    <p role="status" aria-label="事务保存状态">{{ result }}</p>
    <ModelOutput aria-label="事务当前模型">{{ current }}</ModelOutput>
  </c-space>
</template>
```

### 异步校验的返回顺序

主动调用 `validateField` 后可继续修改字段并发起新校验。示例关闭自动触发，只通过按钮发起，手动返回本地结果以比较新旧顺序。先校验 guest，再校验 admin，先返回最新结果再返回最早结果；旧错误不应覆盖最新字段状态。结果文案由示例的请求序号保护，“本次校验值”是校验快照，不是服务端提交。

清空校验或重置后，仍可返回等待中的旧结果，确认不会恢复旧错误；卸载和停用会结清本地等待。真实接口还应取消请求，并由业务保护提交快照和版本。

本例也可在等待中切换表单 disabled / readonly：它们限制控件交互，不自动取消已经发起的校验，也不清除已有错误。外部校验控制按钮不属于被禁用的 Form。需要使旧结果失效时主动清空校验或重置；解除限制后可再次输入并发起新校验。

关闭 Mount async field 会移除字段但保留业务模型和待返回任务。重新挂载后可发起新校验，再按新旧顺序返回结果，核对旧实例的错误不会污染新字段；这不是删除业务数据，也不是整表并发提交协议。

等待中可通过“写入服务端错误”调用 `setFields` 设置显式错误；之前的异步成功或失败不应覆盖它。示例仍保留旧任务供手动返回，结果文案单独做版本保护。清空校验可移除错误，重新发起校验后以新结果为准；不代表真实接口已取消。

“校验整表”调用 `validate()`，“校验字段”调用 `validateField('name')`。可交错发起并按不同顺序返回，分别观察字段反馈和示例最新结果；重置使旧结果失效，不等于取消真实服务。当前示例只有一个异步字段，不代表多字段聚合、跨字段依赖或原生 submit 事件并发均已覆盖。

Example source: src/form/__demos__/async-race.vue

```vue
<template>
  <section class="async-race-form-demo">
    <p>本地异步规则只接受 admin；手动返回最早或最新结果，不访问网络。</p>
    <c-form
      ref="formRef"
      :model="model"
      :disabled="disabled"
      :readonly="readonly"
    >
      <c-form-item
        v-if="mounted"
        field="name"
        label="用户名"
        :label-attrs="{ for: demoId }"
        :rules="rules"
        :validate-trigger="[]"
        feedback
      >
        <c-input :id="demoId" v-model="model.name" placeholder="请输入 admin" />
      </c-form-item>
    </c-form>
    <div class="async-race-controls">
      <c-checkbox v-model="disabled"> Disable async form</c-checkbox>
      <c-checkbox v-model="readonly"> Readonly async form</c-checkbox>
      <c-checkbox v-model="mounted"> Mount async field</c-checkbox>
    </div>
    <c-space wrap>
      <c-button :disabled="!mounted" @click="validate">校验字段</c-button>
      <c-button :disabled="!mounted" @click="validateAll">校验整表</c-button>
      <c-button :disabled="!pending.length" @click="complete(false)"
        >返回最早结果</c-button
      >
      <c-button :disabled="!pending.length" @click="complete(true)"
        >返回最新结果</c-button
      >
      <c-button :disabled="!mounted" @click="serverError"
        >写入服务端错误</c-button
      >
      <c-button @click="clear">清空校验</c-button>
      <c-button @click="reset">重置</c-button>
    </c-space>
    <p role="status">校验结果：{{ result }}；等待结果：{{ pending.length }}</p>
    <p>本次校验值：{{ checkedValue || "空" }}</p>
    <ModelOutput>{{ model }}</ModelOutput>
  </section>
</template>
<script setup lang="ts">
import ModelOutput from "../__demo-utils__/ModelOutput.vue";

import {
  onBeforeUnmount,
  onDeactivated,
  reactive,
  ref,
  shallowRef,
  useId,
} from "vue";
import type { FormInstance, FieldRule } from "@cedar-design/ui";

interface Pending {
  value: unknown;
  resolve: (result: true | string) => void;
}
const demoId = useId();
const disabled = ref(false);
const readonly = ref(false);
const mounted = ref(true);
const formRef = ref<FormInstance>();
const model = reactive({ name: "" });
const pending = shallowRef<Pending[]>([]);
const result = ref("尚未校验");
const checkedValue = ref("");
let run = 0;

function request(value: unknown) {
  return new Promise<true | string>((resolve) => {
    pending.value = [...pending.value, { value, resolve }];
  });
}
const rules: FieldRule[] = [
  {
    validator: async (value, callback) => {
      const answer = await request(value);
      if (answer !== true) callback(answer);
    },
  },
];

function validate() {
  return validateScope(false);
}
function validateAll() {
  return validateScope(true);
}
async function validateScope(all: boolean) {
  const current = ++run;
  checkedValue.value = model.name;
  result.value = "校验中";
  const errors = await (all
    ? formRef.value?.validate()
    : formRef.value?.validateField("name"));
  if (current === run) result.value = errors ? "未通过" : "通过";
}
function complete(latest: boolean) {
  const task = latest ? pending.value.at(-1) : pending.value[0];
  if (!task) return;
  pending.value = pending.value.filter((item) => item !== task);
  task.resolve(task.value === "admin" ? true : "用户名必须是 admin");
}
function clear() {
  run++;
  formRef.value?.clearValidate();
  result.value = "已清空";
}
function serverError() {
  run++;
  formRef.value?.setFields({
    name: { status: "error", message: "模拟服务端拒绝" },
  });
  result.value = "服务端错误";
}
function reset() {
  run++;
  formRef.value?.resetFields();
  checkedValue.value = "";
  result.value = "已重置";
}
function cleanup() {
  run++;
  result.value = "已取消";
  const tasks = pending.value;
  pending.value = [];
  tasks.forEach((task) => task.resolve(true));
}
onBeforeUnmount(cleanup);
onDeactivated(cleanup);
</script>

<style scoped>
.async-race-controls {
  display: flex;
  flex-wrap: wrap;
  gap: 12px;
}
.async-race-controls label {
  display: inline-flex;
  align-items: center;
  gap: 4px;
}
</style>
```

### 日期范围的跨页边界

比较日期、月份、年份范围：禁用 2027-01-01、2026-12、2100 年。禁用项不能作为端点，范围可以跨过它们；翻页后检查禁用项仍保持灰态。

Example source: src/form/__demos__/field-range-boundaries.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import ModelOutput from "../__demo-utils__/ModelOutput.vue";
const model = ref<{
  days: [string, string];
  months: [string, string];
  years: [string, string];
}>({
  days: ["2026-12-29", "2027-01-03"],
  months: ["2026-11", "2027-02"],
  years: ["2098", "2102"],
});
const disabledDay = (date: Date) =>
  date.getFullYear() === 2027 && date.getMonth() === 0 && date.getDate() === 1;
const disabledMonth = (date: Date) =>
  date.getFullYear() === 2026 && date.getMonth() === 11;
const disabledYear = (date: Date) => date.getFullYear() === 2100;
</script>
<template>
  <c-space direction="column" :size="16">
    <c-form :model="model">
      <c-form-item field="days" label="跨月日期"
        ><c-date-range
          v-model="model.days"
          value-format="YYYY-MM-DD"
          :disabled-date="disabledDay"
      /></c-form-item>
      <c-form-item field="months" label="跨年月份"
        ><c-date-range
          v-model="model.months"
          type="month"
          value-format="YYYY-MM"
          :disabled-date="disabledMonth"
      /></c-form-item>
      <c-form-item field="years" label="跨页年份"
        ><c-date-range
          v-model="model.years"
          type="year"
          value-format="YYYY"
          :disabled-date="disabledYear"
      /></c-form-item>
    </c-form>
    <ModelOutput>{{ JSON.stringify(model, null, 2) }}</ModelOutput>
  </c-space>
</template>
```

## 业务流程

### 巡检任务完整流程

<!-- demo-config-notes:start -->

#### 本组配置对照

| 配置     | 作用                                 | 相关示例         |
| -------- | ------------------------------------ | ---------------- |
| `model`  | 表单数据对象                         | 巡检任务完整流程 |
| `layout` | 表单的布局方式，包括水平、垂直、多列 | 巡检任务完整流程 |

<!-- demo-config-notes:end -->

填写、校验、确认、模拟失败与重试；返回修改不会覆盖已提交记录。

Example source: src/form/__demos__/task-workflow.vue

```vue
<script setup>
import { computed, onBeforeUnmount, onDeactivated, ref } from "vue";
const fresh = () => ({ title: "", department: "ops", priority: "normal" });
const draft = ref(fresh());
const saved = ref(null);
const stage = ref("edit");
const message = ref("填写任务后进入确认；也可以直接提交空表单查看校验。");
const busy = ref(false);
const failNext = ref(false);
const formRef = ref();
const rules = [{ required: true, whitespace: true, message: "请输入任务名称" }];
const departments = [
  { value: "ops", label: "运营部" },
  { value: "dev", label: "研发部" },
  { value: "design", label: "设计部" },
];
const priorities = [
  { value: "normal", label: "普通" },
  { value: "urgent", label: "紧急" },
];
const departmentLabel = computed(
  () =>
    departments.find((item) => item.value === draft.value.department)?.label,
);
let timer;
let epoch = 0;
function cancelPending() {
  epoch++;
  clearTimeout(timer);
  busy.value = false;
}
onBeforeUnmount(cancelPending);
onDeactivated(cancelPending);
function review({ errors }) {
  if (errors) {
    message.value = "请补全必填项，任务尚未提交。";
    return;
  }
  stage.value = "review";
  message.value = "核对信息后确认提交；返回修改不会改变上次提交记录。";
}
function submit() {
  if (busy.value) return;
  const current = ++epoch;
  const snapshot = { ...draft.value };
  const shouldFail = failNext.value;
  failNext.value = false;
  busy.value = true;
  message.value = "正在本地模拟保存…";
  timer = setTimeout(() => {
    if (current !== epoch) return;
    busy.value = false;
    if (shouldFail) {
      message.value = "保存失败：草稿已保留，请点击“重试提交”。";
      return;
    }
    saved.value = snapshot;
    stage.value = "done";
    message.value = "提交成功，已生成任务记录。";
  }, 500);
}
function reset() {
  cancelPending();
  draft.value = fresh();
  saved.value = null;
  stage.value = "edit";
  failNext.value = false;
  message.value = "已重置，可以重新演示。";
  formRef.value?.clearValidate();
}
function fill() {
  draft.value = {
    title: "展厅设备巡检",
    department: "ops",
    priority: "urgent",
  };
  formRef.value?.clearValidate();
}
</script>
<template>
  <section class="workflow-demo" aria-label="巡检任务完整流程">
    <ol class="workflow-demo__steps" aria-label="任务流程">
      <li :aria-current="stage === 'edit' ? 'step' : undefined">
        01 填写与校验
      </li>
      <li :aria-current="stage === 'review' ? 'step' : undefined">
        02 核对与提交
      </li>
      <li :aria-current="stage === 'done' ? 'step' : undefined">
        03 结果与记录
      </li>
    </ol>
    <c-form
      v-if="stage === 'edit'"
      ref="formRef"
      :model="draft"
      layout="vertical"
      @submit="review"
    >
      <c-form-item label="任务名称" field="title" :rules="rules" feedback
        ><c-input
          v-model="draft.title"
          edit-mode="direct"
          placeholder="例如：展厅设备巡检"
      /></c-form-item>
      <c-form-item label="执行部门" field="department"
        ><c-select
          v-model="draft.department"
          :options="departments"
          edit-mode="direct"
      /></c-form-item>
      <c-form-item label="任务优先级" field="priority"
        ><c-select
          v-model="draft.priority"
          :options="priorities"
          edit-mode="direct"
      /></c-form-item>
      <c-space wrap
        ><c-button html-type="submit" status="primary">校验并预览</c-button
        ><c-button @click="fill">填入演示数据</c-button></c-space
      >
    </c-form>
    <div v-else-if="stage === 'review'">
      <h4>确认巡检任务</h4>
      <dl>
        <dt>任务</dt>
        <dd>{{ draft.title }}</dd>
        <dt>部门</dt>
        <dd>{{ departmentLabel }}</dd>
        <dt>优先级</dt>
        <dd>{{ draft.priority === "urgent" ? "紧急" : "普通" }}</dd>
      </dl>
      <c-checkbox v-model="failNext" :disabled="busy"
        >模拟下一次保存失败（本地）</c-checkbox
      >
      <c-space wrap
        ><c-button
          status="primary"
          :loading="busy"
          :disabled="busy"
          @click="submit"
          >{{
            message.includes("保存失败") ? "重试提交" : "确认提交"
          }}</c-button
        ><c-button :disabled="busy" @click="stage = 'edit'"
          >返回修改</c-button
        ></c-space
      >
    </div>
    <div v-else>
      <h4>任务已创建</h4>
      <p>
        {{ saved.title }} ·
        {{ saved.priority === "urgent" ? "紧急处理" : "普通处理" }}
      </p>
      <c-button @click="stage = 'edit'">继续编辑</c-button>
    </div>
    <p role="status" aria-live="polite">{{ message }}</p>
    <c-collapse>
      <c-collapse-item title="查看已提交记录" name="saved">
        <pre>{{
          saved
            ? JSON.stringify(saved, null, 2)
            : "尚无记录；校验失败、返回修改或保存失败都不会创建记录。"
        }}</pre>
      </c-collapse-item>
    </c-collapse>
    <c-button @click="reset">重新演示</c-button>
    <small
      >本例使用本地模拟保存，不访问业务服务。校验、确认、保存与失败恢复由业务流程组合。</small
    >
  </section>
</template>
<style scoped>
.workflow-demo {
  width: 100%;
  min-width: 0;
}
.workflow-demo__steps {
  display: flex;
  flex-wrap: wrap;
  gap: 12px;
  list-style: none;
  padding: 0;
}
.workflow-demo__steps li {
  padding: 8px 12px;
  border-radius: 8px;
  background: var(--c-color-fill-1);
}
.workflow-demo__steps [aria-current] {
  color: var(--c-color-primary);
  font-weight: 700;
}
.workflow-demo dl {
  display: grid;
  grid-template-columns: 80px 1fr;
  gap: 8px;
}
.workflow-demo dd {
  margin: 0;
  overflow-wrap: anywhere;
}
.workflow-demo pre {
  white-space: pre-wrap;
  overflow-wrap: anywhere;
}
.workflow-demo small {
  display: block;
  margin-top: 12px;
  color: var(--c-color-text-2);
}
</style>
```

## API

### 空值识别与阅读空文案

Form / FormItem 通过 `empty-values` 提供空值识别策略；字段自己的 `empty-value` 决定清空输出。`empty-text` 仅在 `read-pretty` 空内容下展示，默认 `'-'`，字段 > FormItem > Form，自定义 read 插槽优先。显式配置 empty-values 后，内置 required 接入该策略，自定义校验仍收到原值。详见[统一说明](llms/zh-CN/guide/empty-values.md)。

| 参数         | 类型               | 缺省与范围                                            |
| ------------ | ------------------ | ----------------------------------------------------- |
| empty-values | readonly unknown[] | 字段 > FormItem > Form > 组件族默认；完整覆盖，不合并 |
| empty-text   | string             | 字段 > FormItem > Form > '-'；显式 '' 有效            |

以上是字段展示层 API；纯面板不因此新增阅读模式。Form 与 FormItem 提供继承配置。empty-value 的现有类型与默认输出仍按该组件原 API 执行。

### `<Form>` Props

| 参数名            | 描述                                                                                                    | 类型                                       |        默认值         |
| ----------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------ | :-------------------: |
| model             | 表单数据对象                                                                                            | `object`                                   |         `{}`          |
| layout            | 表单的布局方式，包括水平、垂直、多列                                                                    | `'horizontal' \| 'vertical' \| 'inline'`   |    `'horizontal'`     |
| size              | 表单控件的尺寸                                                                                          | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'`     |        `'md'`         |
| label-col-flex    | 标签列 flex；数字为伸缩比例，带单位字符串为宽度                                                         | `number \| string`                         |          `-`          |
| label-col-style   | 标签列逐实例样式                                                                                        | `CSSProperties`                            |          `-`          |
| wrapper-col-style | 内容列逐实例样式                                                                                        | `CSSProperties`                            |          `-`          |
| label-col-props   | 标签元素布局选项。参数同 `<col>` 组件一致                                                               | `object`                                   | `span: 5, offset: 0`  |
| wrapper-col-props | 表单控件布局选项。参数同 `<col>` 组件一致                                                               | `object`                                   | `span: 19, offset: 0` |
| label-align       | 标签的对齐方向                                                                                          | `'start' \| 'end' \| 'left' \| 'right'`                        |       `'end'`       |
| `content-align`   | 内容对齐，统一控制 direct 字段、弹出入口及 readPretty；与 label-align 独立                              | `'start' \| 'end' \| 'left' \| 'center' \| 'right'`            |       `'start'`        |
| `read-pretty`     | 独立的阅读开关；为 true 时展示已保存的值，关闭后恢复当前 edit-mode 的编辑方式；FormItem 未传时继承 Form | `boolean`                                  |          `-`          |
| `edit-mode`       | 表单内字段的统一编辑模式；未设置时保留各字段默认值                                                      | `'direct' \| 'click' \| 'dblclick'`        |          `-`          |
| disabled          | 是否禁用表单                                                                                            | `boolean`                                  |          `-`          |
| readonly          | 是否将表单控件设为只读                                                                                  | `boolean`                                  |          `-`          |
| rules             | 表单项校验规则                                                                                          | `Record<string, FieldRule \| FieldRule[]>` |          `-`          |
| auto-label-width  | 是否开启自动标签宽度，仅在 `layout="horizontal"` 下生效。                                               | `boolean`                                  |        `false`        |
| id                | 表单控件`id`的前缀                                                                                      | `string`                                   |          `-`          |
| scroll-to-error   | 验证失败后滚动到页面顺序的第一个（start）或最后一个（end）错误字段；不是视口对齐方式                    | `'start' \| 'end'`                         |        不滚动         |

### `<Form>` Events

| 事件名         | 描述                                   | 参数                                                                                                      |
| -------------- | -------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| submit         | 表单提交时触发                         | data: `{values: Record<string, any>; errors: Record<string, ValidatedError> \| undefined}`<br>ev: `Event` |
| submit-success | 验证成功时触发                         | values: `Record<string, any>`<br>ev: `Event`                                                              |
| submit-failed  | 验证失败时触发                         | data: `{values: Record<string, any>; errors: Record<string, ValidatedError>}`<br>ev: `Event`              |
| reset          | 原生重置时触发，并重置字段值与校验状态 | ev: `Event`                                                                                               |

### `<form>` Methods

| 方法名        | 描述                 | 参数                                                                                                     | 返回值                                               |
| ------------- | -------------------- | -------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| validate      | 校验全部表单数据     | callback: `(errors: undefined \| Record<string, ValidatedError>) => void`                                | Promise<undefined \| Record<string, ValidatedError>> |
| validateField | 校验部分表单数据     | field: `string \| string[]`<br>callback: `(errors: undefined \| Record<string, ValidatedError>) => void` | Promise<undefined \| Record<string, ValidatedError>> |
| resetFields   | 重置表单数据         | field: `string \| string[]`                                                                              | -                                                    |
| clearValidate | 清除校验状态         | field: `string \| string[]`                                                                              | -                                                    |
| setFields     | 设置表单项的值和状态 | data: `Record<string, FieldData>`                                                                        | -                                                    |
| scrollToField | 滚动到指定表单项     | `field: string`                                                                                          | `-`                                                  |

### `<FormItem>` Props

未传布局、标签/内容栅格、样式、对齐和 flex 时继承 Form；显式值覆盖。

| 参数名            | 描述                                                                                                    | 类型                                                  |      默认值      |
| ----------------- | ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | :--------------: |
| field             | 表单元素在数据对象中的path（数据项必填）                                                                | `string`                                              |       `''`       |
| label             | 标签的文本                                                                                              | `string`                                              |       `-`        |
| tooltip           | 提示内容                                                                                                | `string`                                              |       `-`        |
| show-colon        | 是否显示冒号                                                                                            | `boolean`                                             |     `false`      |
| no-style          | 是否去除样式                                                                                            | `boolean`                                             |     `false`      |
| disabled          | 是否禁用                                                                                                | `boolean`                                             |       `-`        |
| readonly          | 是否只读；未传时继承 Form                                                                               | `boolean`                                             |       `-`        |
| help              | 帮助文案                                                                                                | `string`                                              |       `-`        |
| extra             | 额外显示的文案                                                                                          | `string`                                              |       `-`        |
| required          | 是否必须填写                                                                                            | `boolean`                                             |     `false`      |
| asterisk-position | 必填星号在字段标签中的逻辑 start/end 位置，默认 start；不是表单或浮层位置                               | `'start' \| 'end'`                                    |    `'start'`     |
| rules             | 表单项校验规则（优先级高于 form 的 rules）                                                              | `FieldRule \| FieldRule[]`                            |       `-`        |
| validate-status   | 校验状态                                                                                                | `'success' \| 'warning' \| 'error' \| 'validating'`   |       `-`        |
| validate-trigger  | 触发校验的事件；`clear` 仅由控件清空动作触发，不等同于 `change`                                         | `'change' \| 'input' \| 'focus' \| 'blur' \| 'clear'` |    `'change'`    |
| size              | 控件尺寸，未传继承 Form；标签外观仍由 Form 布局控制                                                     | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'`                |       `-`        |
| layout            | 表单项布局；未传继承 Form                                                                               | `'horizontal' \| 'vertical' \| 'inline'`              |       `-`        |
| label-align       | 标签对齐；未传继承 Form                                                                                 | `'start' \| 'end' \| 'left' \| 'right'`                                   |       `-`        |
| `content-align`   | 内容对齐，统一控制 direct 字段、弹出入口及 readPretty；与 label-align 独立                              | `'start' \| 'end' \| 'left' \| 'center' \| 'right'`                       | `-`（继承 Form） |
| `read-pretty`     | 独立的阅读开关；为 true 时展示已保存的值，关闭后恢复当前 edit-mode 的编辑方式；FormItem 未传时继承 Form | `boolean`                                             |       `-`        |
| `edit-mode`       | 编辑模式；未设置时继承 Form，字段可单独覆盖                                                             | `'direct' \| 'click' \| 'dblclick'`                   |       `-`        |
| label-col-props   | 标签元素布局选项。参数同 `<col>` 组件一致                                                               | `object`                                              |       `-`        |
| wrapper-col-props | 表单控件布局选项。参数同 `<col>` 组件一致                                                               | `object`                                              |       `-`        |
| hide-label        | 是否隐藏标签                                                                                            | `boolean`                                             |     `false`      |
| hide-asterisk     | 是否隐藏星号                                                                                            | `boolean`                                             |     `false`      |
| label-col-style   | 标签元素布局组件的 style                                                                                | `object`                                              |       `-`        |
| wrapper-col-style | 表单控件布局组件的 style                                                                                | `object`                                              |       `-`        |
| row-props         | 表单项布局选项。参数同 `<row>` 组件一致                                                                 | `object`                                              |       `-`        |
| row-class         | 表单项布局组件的 class                                                                                  | `string\|array\|object`                               |       `-`        |
| content-class     | 表单控件包裹层的 class                                                                                  | `string\|array\|object`                               |       `-`        |
| content-flex      | 内容层是否开启 flex 布局                                                                                | `boolean`                                             |      `true`      |
| label-col-flex    | 设置标签 `Col` 组件的 flex 属性。设置时表单 `Col` 组件的 flex 属性会被设置为 `auto`。                   | `number\|string`                                      |       `-`        |
| feedback          | 是否显示表单控件的反馈图标                                                                              | `boolean`                                             |     `false`      |
| label-component   | 表单项标签渲染的元素                                                                                    | `string`                                              |    `'label'`     |
| label-attrs       | 标签原生属性；for 指向控件真实 id                                                                       | `object`                                              |       `-`        |

### `<FormItem>` Slots

| 插槽名 |   描述   | 参数 |
| ------ | :------: | ---- |
| label  |   标签   | -    |
| help   | 帮助信息 | -    |
| extra  | 额外内容 | -    |

## Type

### FieldRule

| 参数名    | 描述                              | 类型                                                                                                        | 默认值  |
| --------- | --------------------------------- | ----------------------------------------------------------------------------------------------------------- | :-----: |
| type      | 校验的值的类型，默认为 `'string'` | `'string'    \| 'number'    \| 'boolean'    \| 'array'    \| 'object'    \| 'email'    \| 'url'    \| 'ip'` |   `-`   |
| required  | 是否必填                          | `boolean`                                                                                                   | `false` |
| message   | 校验失败时展示的信息              | `string`                                                                                                    |   `-`   |
| length    | 校验长度（string, array）         | `number`                                                                                                    |   `-`   |
| maxLength | 最大长度（string）                | `number`                                                                                                    |   `-`   |
| minLength | 最小长度（string）                | `number`                                                                                                    |   `-`   |
| match     | 匹配校验（string）                | `RegExp`                                                                                                    |   `-`   |
| uppercase | 大写（string）                    | `boolean`                                                                                                   | `false` |
| lowercase | 小写（string）                    | `boolean`                                                                                                   | `false` |
| min       | 最小值（number）                  | `number`                                                                                                    |   `-`   |
| max       | 最大值（number）                  | `number`                                                                                                    |   `-`   |
| equal     | 校验数值（number）                | `number`                                                                                                    |   `-`   |
| positive  | 正数（number）                    | `boolean`                                                                                                   | `false` |
| negative  | 负数（number）                    | `boolean`                                                                                                   | `false` |
| true      | 是否为 `true`（boolean）          | `boolean`                                                                                                   | `false` |
| false     | 是否为 `false`（boolean）         | `boolean`                                                                                                   | `false` |
| includes  | 数组中是否包含给定值（array）     | `any[]`                                                                                                     |   `-`   |
| deepEqual | 数组元素是否相等（array）         | `any`                                                                                                       |   `-`   |
| empty     | 是否为空（object）                | `boolean`                                                                                                   | `false` |
| hasKeys   | 对象是否包含给定属性（object）    | `string[]`                                                                                                  |   `-`   |
| validator | 自定义校验规则                    | `(    value: FieldValue \| undefined,    callback: (error?: string) => void  ) => void`                     |   `-`   |

### FieldData

| 参数名  | 描述           | 类型             | 默认值 |
| ------- | -------------- | ---------------- | :----: |
| value   | 字段的值       | `any`            |  `-`   |
| status  | 字段的状态     | `ValidateStatus` |  `-`   |
| message | 字段的错误信息 | `string`         |  `-`   |

### ValidatedError

| 参数名          | 描述                   | 类型      | 默认值  |
| --------------- | ---------------------- | --------- | :-----: |
| label           | 标签的文本             | `string`  |   `-`   |
| field           | 字段名                 | `string`  |   `-`   |
| value           | 字段值                 | `any`     |   `-`   |
| type            | 字段类型               | `string`  |   `-`   |
| isRequiredError | 是否为 `required` 错误 | `boolean` | `false` |
| message         | 错误信息               | `string`  |   `-`   |

### FormItemEventHandler

| 参数名   | 描述     | 类型                   | 默认值 |
| -------- | -------- | ---------------------- | :----: |
| onChange | onChange | `(ev?: Event) => void` |  `-`   |
| onInput  | onInput  | `(ev?: Event) => void` |  `-`   |
| onFocus  | onFocus  | `(ev?: Event) => void` |  `-`   |
| onBlur   | onBlur   | `(ev?: Event) => void` |  `-`   |

### useFormItem

```ts
const useFormItem = (data: {
  size?: Ref<Size | undefined>;
  disabled?: Ref<boolean>;
  error?: Ref<boolean>;
}) => {
  mergedSize: Ref<Size>;
  mergedDisabled: Ref<boolean>;
  mergedError: Ref<boolean>;
  feedback: Ref<string>;
  eventHandlers: Ref<FormItemEventHandler>;
};
```

## 类型定义

组件导出以下类型定义

```ts
import type { FormProps } from "@cedar-design/ui";
```

### 五档密度与项目间距

xs/sm/md/lg/xl 均通过 size 类选择对应几何。项目下间距和验证文案预留高度共同使用 size-*-item-margin-bottom；inline 使用独立 inline-item-margin-bottom，error/help 不重复添加项目下间距。

| 变量                                  | 默认值                      |
| ------------------------------------- | --------------------------- |
| `--c-form-size-xl-height`             | `var(--c-size-xl)`          |
| `--c-form-size-xl-label-font-size`    | `var(--c-sys-font-size-lg)` |
| `--c-form-size-xl-item-margin-bottom` | `var(--c-spacing-8)`        |

### edit-mode 继承规则

Form 支持 `direct / click / dblclick`；未设置时保留字段各自的默认值，FormItem 和字段继承上层显式设置的值，字段显式值优先。readPretty 是阅读属性，与 readonly/disabled 分开。确认编辑未结束时整表提交会失败并保留草稿；reset 取消编辑。原有默认插槽与 v-model 保持不变，不需要 editor 插槽。

`read-pretty` 为独立布尔属性，与 `readonly`、`disabled` 同级；字段 > FormItem > Form 继承，显式 `false` 覆盖父级。默认 `false`。纯阅读不显示编辑器。

---

Document: llms/zh-CN/components/grid.md

<!-- Source: src/grid/README.md; locale: zh-CN; page: /components/grid/ -->

# Grid

CSS Grid 布局：列数、跨列、间距、折叠与后缀。24 栏 Flex 布局使用 Row / Col。

> **布局怎么选**
>
> - Grid + GridItem：适合表单分栏、卡片网格，需要统一列宽、跨列、响应式列数或折叠行与后缀时使用。
> - Row + Col：适合 24 栏 Flex 布局，需要水平/垂直对齐、控制换行、固定宽度与自适应宽度组合，或响应式排序时使用。Row 控制整行，Col 控制列宽、偏移和排序。
> - Space：适合按钮、标签、文字等简单排列，只需要间距、方向和对齐时使用；更自由的宽度分配可使用原生 Flex。

## 基础示例

### 列数、跨列与偏移

Example source: src/grid/__demos__/basic.vue

```vue
<template><div>
  <c-grid :cols="4" :col-gap="12" :row-gap="12"><c-grid-item v-for="i in 8" :key="i" class="cell">{{ i }}</c-grid-item></c-grid>
  <c-grid :cols="4" :col-gap="12" :row-gap="12"><c-grid-item :span="2" class="cell">span 2</c-grid-item><c-grid-item :offset="1" class="cell soft">offset 1</c-grid-item><c-grid-item :span="4" class="cell">span 4</c-grid-item></c-grid>
</div></template>

<style scoped>
.controls { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; }
.cell { box-sizing: border-box; padding: 12px; min-width: 0; border-radius: 4px; background: var(--c-color-primary); color: var(--c-color-white); text-align: center; overflow-wrap: anywhere; }
.soft { opacity: .7; }
</style>
```

## 布局与排列

### 响应式列数、间距与跨列

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `cols` | 每行列数，最少为 1 | 响应式列数、间距与跨列 |
| `col-gap` | 列间距（px） | 响应式列数、间距与跨列 |
| `row-gap` | 行间距（px） | 响应式列数、间距与跨列 |
<!-- demo-config-notes:end -->

Example source: src/grid/__demos__/responsive.vue

```vue
<template><div>
  <p>xs: 1 column · sm: 2 columns · md: 4 columns</p>
  <c-grid :cols="{ xs: 1, sm: 2, md: 4 }" :col-gap="{ xs: 8, md: 16 }" :row-gap="{ xs: 8, md: 16 }">
    <c-grid-item :span="{ xs: 1, md: 2 }" class="cell">Responsive span</c-grid-item><c-grid-item v-for="i in 6" :key="i" class="cell soft">{{ i }}</c-grid-item>
  </c-grid>
</div></template>

<style scoped>
.controls { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; }
.cell { box-sizing: border-box; padding: 12px; min-width: 0; border-radius: 4px; background: var(--c-color-primary); color: var(--c-color-white); text-align: center; overflow-wrap: anywhere; }
.soft { opacity: .7; }
</style>
```

## 自定义与插槽

### 折叠行数与后缀插槽

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `cols` | 每行列数，最少为 1 | 折叠行数与后缀插槽 |
| `col-gap` | 列间距（px） | 折叠行数与后缀插槽 |
| `row-gap` | 行间距（px） | 折叠行数与后缀插槽 |
| `collapsed` | 折叠超出的行 | 折叠行数与后缀插槽 |
| `collapsed-rows` | 折叠时保留行数，最少为 1 | 折叠行数与后缀插槽 |
<!-- demo-config-notes:end -->

示例由父级保存 `collapsed` 和行数；More/Less 与开关修改同一状态。4列折叠1行时展示3项及后缀，2行时展示7项及后缀；展开后展示全部9项及后缀。后缀占一个网格位置，不是浮在内容之上的额外按钮。

Example source: src/grid/__demos__/collapse.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const collapsed = ref(true)
const rows = ref(1)
</script>
<template><div>
  <div class="controls"><c-switch v-model="collapsed" aria-label="Collapsed" />Collapsed<c-radio-group v-model="rows"><c-radio :value="1">1 row</c-radio><c-radio :value="2">2 rows</c-radio></c-radio-group></div>
  <c-grid :cols="4" :col-gap="12" :row-gap="12" :collapsed="collapsed" :collapsed-rows="rows">
    <c-grid-item v-for="i in 9" :key="i" class="cell">{{ i }}</c-grid-item>
    <c-grid-item suffix v-slot="{ overflow }"><c-button block variant="outline" @click="collapsed = !collapsed">{{ overflow ? 'More' : 'Less' }}</c-button></c-grid-item>
  </c-grid>
</div></template>

<style scoped>
.controls { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; }
.cell { box-sizing: border-box; padding: 12px; min-width: 0; border-radius: 4px; background: var(--c-color-primary); color: var(--c-color-white); text-align: center; overflow-wrap: anywhere; }
.soft { opacity: .7; }
</style>
```

## 交互与控制

### 动态插入、删除与排序

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `cols` | 每行列数，最少为 1 | 动态插入、删除与排序 |
| `col-gap` | 列间距（px） | 动态插入、删除与排序 |
| `row-gap` | 行间距（px） | 动态插入、删除与排序 |
| `collapsed` | 折叠超出的行 | 动态插入、删除与排序 |
<!-- demo-config-notes:end -->

按钮只修改本例的数据数组；删除至空时禁用 Remove first，后缀显示 End。重新插入后恢复布局与删除能力。Grid 本身不提供新增/删除业务事件。

Example source: src/grid/__demos__/dynamic.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const items = ref([1, 2, 3, 4, 5])
let next = 6
</script>
<template><div>
  <div class="controls"><c-button @click="items.unshift(next++)">Insert first</c-button><c-button :disabled="!items.length" @click="items.shift()">Remove first</c-button><c-button @click="items.reverse()">Reverse</c-button></div>
  <c-grid :cols="3" :col-gap="12" :row-gap="12" collapsed><c-grid-item v-for="i in items" :key="i" class="cell">{{ i }}</c-grid-item><c-grid-item suffix v-slot="{ overflow }" class="cell soft">{{ overflow ? '…' : 'End' }}</c-grid-item></c-grid>
</div></template>

<style scoped>
.controls { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; }
.cell { box-sizing: border-box; padding: 12px; min-width: 0; border-radius: 4px; background: var(--c-color-primary); color: var(--c-color-white); text-align: center; overflow-wrap: anywhere; }
.soft { opacity: .7; }
</style>
```

## API

<!-- same-source-api:start -->
### Props

| 属性 | 说明 | Type | Default |
| --- | --- | --- | --- |
| cols | 每行列数，最少为 1 | `number / ResponsiveValue` | `24` |
| row-gap | 行间距（px） | `number / ResponsiveValue` | `0` |
| col-gap | 列间距（px） | `number / ResponsiveValue` | `0` |
| collapsed | 折叠超出的行 | `boolean` | `false` |
| collapsed-rows | 折叠时保留行数，最少为 1 | `number` | `1` |

### Events

| Event | Description |
| --- | --- |

### Slots

| Slot | Description |
| --- | --- |
| default | 布局内容 |

### Methods

| Method | Description |
| --- | --- |
<!-- same-source-api:end -->

## 响应式与可访问性

断点基于浏览器视口：xs 为基础值，sm ≥576、md ≥768、lg ≥992、xl ≥1200、xxl ≥1600px；从最大匹配断点向下取已配置值。SSR 首屏使用 xs，挂载后响应视口；Grid 折叠和动态排序在挂载后计算。组件为布局容器，不增加键盘快捷键；内容语义及可聚焦元素由调用者提供。没有公开方法和专用主题 Token。

## GridItem

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| span | 跨越格数 | number / ResponsiveValue | 1 |
| offset | 左侧留空格数 | number / ResponsiveValue | 0 |
| suffix | 行末后缀 | boolean | false |

默认插槽参数 `{ overflow: boolean }` 表示折叠是否隐藏了内容；没有自定义事件或公开方法。

## 导入

Grid 仅包含 Grid.Item；Row、Col 是独立组件，拥有独立源码、样式、菜单、文档和 Demo。已移除 Grid.Row/Grid.Col、Grid 入口的 Row/Col 转导出以及 GridRowInstance/GridColInstance。请从库根入口或独立 row/col 入口导入；安装 Grid 不再自动注册 Row/Col。

---

Document: llms/zh-CN/components/hover.md

<!-- Source: src/hover/README.md; locale: zh-CN; page: /components/hover/ -->

# Hover 悬停反馈

`v-hover` 通过鼠标进入和离开更新样式或通知回调；`HoverOverlay` 根据显式的悬停与聚焦状态绘制装饰遮层。两者可独立组合，遮层不接管点击和键盘语义。

## 基础示例

### 悬停与焦点

将鼠标移入按钮，观察悬停状态；再通过 Tab 聚焦，观察焦点状态。示例使用原生按钮语义，悬停指令自身只处理 mouseenter / mouseleave，键盘焦点由宿主事件传入。

Example source: src/hover/__demos__/basic.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { Hover, useHoverOverlay } from '@cedar-design/ui'
import '@cedar-design/ui/hover/style'

const vHover = Hover
const { hovering, handleHovering } = useHoverOverlay()
const focusing = ref(false)
</script>

<template>
  <c-space direction="column">
    <c-button v-hover="handleHovering" class="hover-example-target" @focus="focusing = true" @blur="focusing = false">
      将鼠标移入，或用 Tab 聚焦
      <c-hover-overlay :hovering="hovering" :focusing="focusing" />
    </c-button>
    <span role="status">悬停：{{ hovering ? '是' : '否' }}；焦点：{{ focusing ? '是' : '否' }}</span>
  </c-space>
</template>

<style scoped>
.hover-example-target { position: relative; }
</style>
```

## API

### 指令

| 用法 | 说明 |
| --- | --- |
| `v-hover="callback"` | 鼠标进入和离开时通知 `(hovering: boolean) => void` |
| `v-hover="styleObject"` | 鼠标进入时应用样式，离开时恢复 |
| `v-hover:desktop` / `v-hover:mobile` | 按指令的端侧判断启用，不代表支持真实触屏悬停 |

### HoverOverlay Props

| 属性 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| hovering | boolean | false | 悬停装饰状态 |
| focusing | boolean | false | 焦点装饰状态 |

`useHoverOverlay()` 返回 `hovering` 与 `handleHovering`，可连接指令回调。遮层使用绝对定位，宿主需提供定位上下文；独立使用时引入 `@cedar-design/ui/hover/style`。

---

Document: llms/zh-CN/components/icon.md

<!-- Source: src/icon/README.md; locale: zh-CN; page: /components/icon/ -->

# Icon

图标以独立 SVG Vue 组件提供。推荐通过 Resolver 自动按需导入；需要统一尺寸、颜色或旋转时，使用 Icon 容器包裹图标。

## 基础示例

### 基础用法

Example source: src/icon/__demos__/basic-usage.vue

```vue
<script setup lang="ts">
import { IconCheckCircleFill } from "@cedar-design/icons-vue";
</script>
<template>
  <div class="icon-demo-row">
    <div>
      <p>Resolver 自动按需导入</p>
      <c-icon size="40" color="red"><c-icon-check-circle-fill /></c-icon>
    </div>
    <div>
      <p>手动按需导入</p>
      <c-icon size="40" color="red"><IconCheckCircleFill /></c-icon>
    </div>
  </div>
</template>
<style scoped>
.icon-demo-row {
  display: flex;
  flex-wrap: wrap;
  align-items: center;
  gap: 32px;
}
p {
  margin: 0 0 12px;
  font-size: 14px;
}
</style>
```

## 外观与状态

### 图标尺寸与颜色

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `size` | `inherit` | 图标尺寸与颜色 |
| `color` | 图标颜色 | 图标尺寸与颜色 |
<!-- demo-config-notes:end -->

比较相同图标的尺寸和颜色，旋转/动画与点击行为另行展示。

Example source: src/icon/__demos__/appearance-comparison.vue

```vue
<script setup lang="ts">


</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="size">
    <h4><span lang="zh-CN">图标尺寸</span><span lang="en-US">size</span></h4>
    <c-space wrap align="center" :size="24">
        <c-icon size="20"><c-icon-check-circle /></c-icon>
        <c-icon size="28"><c-icon-check-circle /></c-icon>
        <c-icon size="36"><c-icon-check-circle /></c-icon>
      </c-space>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="color">
    <h4><span lang="zh-CN">图标颜色</span><span lang="en-US">color</span></h4>
    <c-space wrap :size="24">
        <c-icon size="28" color="rgb(var(--c-primary-6))"
          ><c-icon-check-circle
        /></c-icon>
        <c-icon size="28" color="rgb(var(--c-success-6))"
          ><c-icon-check-circle
        /></c-icon>
      </c-space>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

## 内容与展示

### 旋转与持续旋转

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `size` | `inherit` | 旋转与持续旋转 |
| `rotate` | 旋转角度 | 旋转与持续旋转 |
| `spin` | 是否持续旋转 | 旋转与持续旋转 |
<!-- demo-config-notes:end -->

`rotate` 设置静态角度，`spin` 开启持续旋转动画，两者可以组合使用。

Example source: src/icon/__demos__/rotate-spin.vue

```vue
<template>
  <c-space wrap align="center" :size="32">
    <div class="demo-item">
      <c-icon size="32" :rotate="90"><c-icon-arrow-right /></c-icon>
      <span>rotate="90"</span>
    </div>
    <div class="demo-item">
      <c-icon size="32" spin><c-icon-refresh /></c-icon>
      <span>spin</span>
    </div>
    <div class="demo-item">
      <c-icon-refresh :size="32" :rotate="45" spin />
      <span>独立 SVG：rotate + spin</span>
    </div>
  </c-space>
</template>
<style scoped>
.demo-item {
  display: inline-flex;
  align-items: center;
  gap: 8px;
}
</style>
```

### 全部图标

两端使用同一套规范名称。搜索忽略首尾空格和大小写，清空后恢复全部图标。卡片放大展示图标，完整名称可换行；点击或按 Enter / Space 复制对应标签。复制使用浏览器 Clipboard API，需要安全上下文及剪贴板权限；失败时显示错误反馈。

Example source: src/icon/__demos__/catalog.vue

```vue
<script setup lang="ts">
import { computed, ref } from "vue";
import { iconNames } from "@cedar-design/icons-vue";
import * as CedarIcons from "@cedar-design/icons-vue";
import { Message } from "../../message";

const keyword = ref("");
const filteredIcons = computed(() =>
  keyword.value
    ? iconNames.filter((name) =>
        name.includes(keyword.value.trim().toLowerCase()),
      )
    : iconNames,
);

const groupRules = [
  [
    "方向",
    /(^|-)(arrow|caret|chevron|left|right|up|down|expand|shrink|swap|rotate|fullscreen|backward|forward)(-|$)/,
  ],
  [
    "状态与反馈",
    /(^|-)(alert|check|close|error|exclamation|info|question|success|warning|empty|stop)(-|$)/,
  ],
  [
    "编辑",
    /(^|-)(align|attachment|bold|brush|copy|delete|edit|eraser|filter|font|formula|italic|link|list|paste|quote|redo|scissor|sort|underline|undo|zoom)(-|$)/,
  ],
  ["文件", /(^|-)(archive|book|bookmark|drive|file|folder|save|storage)(-|$)/],
  [
    "媒体",
    /(^|-)(camera|image|live|music|mute|pause|play|record|skip|sound|video|voice)(-|$)/,
  ],
  [
    "通信与用户",
    /(^|-)(email|message|notification|phone|send|share|subscribe|user|robot)(-|$)/,
  ],
  [
    "品牌",
    /(alipay|bytedance|codepen|facebook|github|gitlab|google|lark|qq|tiktok|twitter|wechat|weibo|xigua)/,
  ],
  ["天气", /(^|-)weather-|(^|-)sun(-|$)|(^|-)moon(-|$)/],
  ["商业", /(^|-)(barcode|cart|gift|shopping|tag)(-|$)/],
] as const;

const iconGroups = computed(() => {
  const groups = new Map<string, string[]>();
  for (const name of filteredIcons.value) {
    const label = groupRules.find(([, rule]) => rule.test(name))?.[0] ?? "通用";
    if (!groups.has(label)) groups.set(label, []);
    groups.get(label)?.push(name);
  }
  return [...groupRules.map(([label]) => label), "通用"].flatMap((label) => {
    const names = groups.get(label);
    return names?.length ? [[label, names.sort()] as const] : [];
  });
});

function pascalCase(name: string) {
  return name
    .split("-")
    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
    .join("");
}

function resolveIcon(name: string) {
  return CedarIcons[`Icon${pascalCase(name)}` as keyof typeof CedarIcons];
}

async function copyIcon(name: string) {
  const markup = `<c-icon-${name} />`;
  try {
    await navigator.clipboard.writeText(markup);
    Message.success(`已复制 ${markup}`);
  } catch {
    Message.error("复制失败，请检查浏览器剪贴板权限");
  }
}
</script>

<template>
  <c-input v-model="keyword" clearable placeholder="搜索图标名称">
    <template #prefix><c-icon-search /></template>
  </c-input>
  <section v-for="[group, names] in iconGroups" :key="group" class="icon-group">
    <h3>
      {{ group }} <small>{{ names.length }}</small>
    </h3>
    <div class="icon-catalog">
      <c-button
        v-for="name in names"
        :key="name"
        class="icon-card"
        variant="outline"
        @click="copyIcon(name)"
      >
        <span class="icon-card-content">
          <component :is="resolveIcon(name)" :size="40" />
          <span class="icon-name">{{ name }}</span>
        </span>
      </c-button>
    </div>
  </section>
</template>

<style scoped>
.icon-catalog {
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(min(100%, 168px), 1fr));
  gap: 16px;
  margin-top: 12px;
}

.icon-group {
  margin-top: 24px;
}
.icon-group h3 {
  margin: 0;
  font-size: 16px;
}
.icon-group small {
  margin-left: 6px;
  color: var(--color-text-3);
  font-weight: normal;
}

.icon-card {
  min-height: 132px;
  height: auto;
  justify-content: center;
  font: inherit;
  line-height: 1.5;
  display: flex;
  min-width: 0;
  flex-direction: column;
  align-items: center;
  gap: 12px;
  padding: 20px 14px;
  color: var(--color-text-1);
  background: var(--color-bg-2);
  border: 1px solid var(--color-border-2);
  border-radius: 8px;
  cursor: pointer;
}

.icon-card:hover {
  color: rgb(var(--c-primary-6));
  border-color: rgb(var(--c-primary-6));
}
.icon-card-content {
  display: flex;
  flex-direction: column;
  align-items: center;
  gap: 12px;
}
.icon-name {
  width: 100%;
  text-align: center;
  font-size: 13px;
  overflow-wrap: anywhere;
  white-space: normal;
}
</style>
```

## 自定义与插槽

### 自定义图标

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `size` | `inherit` | 自定义图标 |
| `color` | 图标颜色 | 自定义图标 |
<!-- demo-config-notes:end -->

在默认插槽内放入自定义 SVG，尺寸和颜色由 Icon 容器统一控制。

Example source: src/icon/__demos__/custom.vue

```vue
<template>
  <c-icon size="40" color="currentColor">
    <svg
      viewBox="0 0 24 24"
      fill="none"
      stroke="currentColor"
      stroke-width="2"
      role="img"
      aria-label="自定义菱形图标"
    >
      <path d="M12 2 22 12 12 22 2 12Z" />
      <path d="M8 12h8M12 8v8" />
    </svg>
  </c-icon>
</template>
```

### 接入 IconPark 自定义项目

IconPark 自定义项目提供的 **SVG Symbol JS** 和 **Web Component JS** 都可以直接接入，不需要逐个导出 SVG，也不需要为每个图标生成 Vue 组件。它们是 SVG 资源方案，与通过 `@font-face` 加载文字字体不同。

`@icon-park/vue-next` 提供的公共图标组件与自定义项目 JS 是不同的资源入口；安装公共图标包不会自动包含团队上传或维护的自定义图标。

| 方式 | 图标资源来源 | 使用方式 | 加载粒度 |
| --- | --- | --- | --- |
| SVG Symbol JS | 自定义项目生成的 JS | 默认插槽放入 `svg` / `use` | 该 JS 包含的图标集合 |
| Web Component JS | 自定义项目生成的 JS | 默认插槽放入自定义元素 | 以生成产物的实现为准，不能假定逐图标加载 |
| 独立 SVG Vue 组件 | 本地图标文件或组件包 | 默认插槽放入 Vue 图标组件 | 按模块导入，具体取决于打包配置 |

建议先使用 SVG Symbol：它可以复用 Icon 容器，并且不需要配置 Vue 自定义元素识别。

**当前 API 边界：** `CIcon` 没有 `symbol` 属性，也不会自动下载、注册或注入 IconPark 资源。本文通过现有默认插槽接入；`name` 只解析当前 Vue 应用已注册的图标组件，不能用于查找 Symbol ID 或 Web Component 图标名称。默认插槽优先于 `name`。

#### SVG Symbol：加载项目 JS

从 IconPark 自定义项目复制 **SVG Symbol** 类型的 JS 地址，在业务应用的 HTML 入口加载一次。例如 Vite 应用的 `index.html`：

```html
<!-- 示例路径：替换为自定义项目生成的 JS 地址，或部署到此路径的本地副本 -->
<script src="/icons/project-symbol.js" defer></script>
```

脚本执行后，应在页面中注入带有 `symbol` 节点的 SVG 集合。组件库不内置业务项目地址；由应用决定使用远程地址还是随应用部署的静态文件。Web Component 和 Symbol 两种 JS 按选定方式加载即可，不需要为了同一个图标集合同时引入两份。

#### SVG Symbol：引用图标

假设脚本注入了 `<symbol id="project-home" viewBox="0 0 48 48">`，可以这样使用。以下路径和 ID 均为示例，以实际生成产物为准。

```vue
<script setup lang="ts">
import { Icon as CIcon } from '@cedar-design/ui'
import '@cedar-design/ui/icon/style'
</script>

<template>
  <c-icon :size="24" color="#1677ff">
    <svg width="1em" height="1em" aria-hidden="true">
      <use href="#project-home" />
    </svg>
  </c-icon>
</template>
```

`href` 指向页面中的完整 Symbol ID，包含 `#`。显示名称、组件库的 `name`、项目中的图标名称不一定等于 Symbol ID；不要自行添加或移除前缀。可在开发者工具中检查 `symbol[id]`。这里使用的是 JS 注入的页面内资源，不能写成 `href="项目.js#project-home"`。

`size` 控制外层字号，内部 SVG 使用 `1em` 跟随尺寸；`rotate`、`spin` 作用于整个容器。没有显式 `size` 时沿用 Icon 的尺寸继承规则。Symbol 应保留生成产物中的 `viewBox`，避免图形裁剪或缩放异常。

#### 在业务层封装简写

如果需要按 ID 传参，可以增加一个业务组件 `ProjectIcon.vue`，无需修改组件库或生成每个图标的 Vue 文件：

```vue
<script setup lang="ts">
import { Icon as CIcon } from '@cedar-design/ui'
import '@cedar-design/ui/icon/style'

defineProps<{ symbol: string }>()
</script>

<template>
  <c-icon>
    <svg width="1em" height="1em" aria-hidden="true">
      <use :href="`#${symbol}`" />
    </svg>
  </c-icon>
</template>
```

业务调用：

```vue
<script setup lang="ts">
import ProjectIcon from './ProjectIcon.vue'
</script>

<template>
  <ProjectIcon symbol="project-home" :size="24" color="#1677ff" />
</template>
```

这里的 `symbol` 属于业务组件 `ProjectIcon`，传值不包含 `#`；`size`、`color`、`rotate`、`spin` 等未声明属性通过 Vue 的单根属性透传交给 `CIcon`。若封装组件增加多个根节点或关闭 `inheritAttrs`，需要显式转发 `$attrs`。`transition` 目前只控制 `CIcon` 的 `name` 切换，不会为插槽内的 Symbol 引用切换提供动画。

#### Web Component：加载与编译配置

也可以加载自定义项目提供的 **Web Component JS**，然后在插槽中使用其注册的元素。以下假设生成产物使用 `iconpark-icon` 标签和 `name` 属性，实际名称、属性及可配置主题以项目生成的使用说明为准。

```html
<!-- 放在业务应用的 HTML 入口；这是 Web Component 版本的 JS -->
<script src="/icons/project-web-component.js" defer></script>
```

在使用该标签的 Vue SFC 的构建配置中，将它识别为自定义元素。Vite 示例：

```ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [
    vue({
      template: {
        compilerOptions: {
          isCustomElement: (tag) => tag === 'iconpark-icon',
        },
      },
    }),
  ],
})
```

把配置合并到现有的 Vue 插件配置中，不要重复添加插件。`isCustomElement` 是编译时选项；使用构建工具时，仅设置 `app.config.compilerOptions` 不能替代上面的配置。如果组件库内部封装了该标签，应在组件库编译时配置；业务源码直接使用时，应在业务构建中配置。

```vue
<template>
  <c-icon :size="24" color="#1677ff">
    <iconpark-icon name="project-home" size="1em"></iconpark-icon>
  </c-icon>
</template>
```

示例沿用项目已有的 `c-icon` 导入或注册配置。外层 `CIcon` 不会自动把主题、线宽等属性传给插槽中的元素；请按生成产物支持的 API 直接设置。若元素使用 Shadow DOM，外部 `.c-icon svg` 样式不能直接设置内部 SVG；尺寸和颜色应通过该元素支持的属性、继承样式或 CSS 变量设置。

#### 尺寸、颜色与多色图标

| 配置 | 实际效果与限制 |
| --- | --- |
| `size` | Symbol 示例通过 `1em` 继承容器尺寸；Web Component 需要确认自身尺寸 API |
| `color` | 只有图形使用 `currentColor` 或支持相应继承机制时才生效 |
| 固定 `fill` / `stroke` | 图形内部写死的颜色不会被外层 `color` 自动覆盖 |
| 多色图标 | 保留原有颜色，不建议对所有路径统一强制覆盖 `fill` 或 `stroke` |
| 主题与线宽 | 取决于生成产物能力，不能把公共 Vue 图标包的属性直接套用到项目 JS |

#### 按需加载与体积

组件的按需引入与图标资源的加载是两件事。使用插槽不会让 `CIcon` 自动依赖整个 IconPark 包，现有 Resolver 的按需导入方式仍然适用；Resolver 也不会根据 `use` 的 ID 自动加载图标资源。

对于一次性注入集合的 Symbol JS，加载单位是整个文件。例如项目文件包含 200 个图标，即使页面只引用 3 个，也会下载并注入该文件中的 200 个图标。`href="#project-home"` 只选择要显示的图形，不会触发单个图标的网络请求。静态脚本不进入业务模块的 tree-shaking 分析，字符串 ID 也不会让未使用的 Symbol 被自动裁剪。

| 目标 | 做法 |
| --- | --- |
| 集合较小、多个页面频繁复用 | 应用入口加载一次，按文件版本复用浏览器缓存 |
| 集合较大、模块之间差异明显 | 在资源侧拆分公共集合和业务集合，在对应路由或模块需要时加载 |
| 希望先渲染页面，再加载图标 | 业务维护加载完成、失败和占位状态，资源可用后显示图标 |
| 必须逐个图标参与打包裁剪 | 使用独立 SVG 模块或 Vue 组件，并验证组件包导出和构建工具的裁剪结果 |

远程 JS 不会进入组件库 npm 包，但仍计入应用实际下载体积。新增或删除图标后需要更新项目产物并处理缓存版本；不要只依据组件库的构建体积判断页面成本。

#### 加载时机、SSR 与可访问性

- 静态脚本应在需要使用图标时可用；动态加载应等待脚本成功执行。Web Component 还可通过 `customElements.whenDefined('iconpark-icon')` 等待元素注册，该方法不负责下载脚本，也不表示资源加载失败会自动结束等待。
- 一个应用统一加载相同资源一次，避免组件每次挂载都创建脚本。多个集合中的 Symbol ID 应保持唯一，避免同名图形互相覆盖或引用错误。
- SSR 环境中，不要在服务端执行依赖 `window`、`document`、`customElements` 的项目脚本。通过 HTML 脚本或客户端生命周期加载；需要条件渲染时，让服务端和客户端首次渲染的占位内容一致。图形资源尚未注入时不会显示，严格要求首屏图标的场景需另行准备服务端内联 Symbol 或独立 SVG。
- 装饰性 SVG 使用 `aria-hidden="true"`。独立传递信息的 SVG 应设置 `role="img"` 和可访问名称；只有图标的按钮应给按钮设置 `aria-label`，不能仅靠图标表达操作。

#### 常见问题

| 问题 | 检查项 |
| --- | --- |
| 图标空白 | 脚本是否成功执行、是否选对 JS 类型、完整 ID 是否存在、容器尺寸是否为零 |
| `Failed to resolve component: iconpark-icon` | 使用标签的源码是否在编译时配置了 `isCustomElement` |
| 图标颜色不变 | 图形是否使用固定颜色，或 Web Component 是否提供了颜色设置接口 |
| 尺寸不跟随 `CIcon` | 内部 SVG / 自定义元素是否使用 `1em`，是否存在固定像素尺寸 |
| 更新项目后仍显示旧图标 | 页面是否加载了新版本 JS，浏览器或 CDN 缓存是否已更新 |
| 本地正常，部署后空白 | 检查静态资源基础路径、网络请求、CSP 的 `script-src` 及脚本执行错误 |
| 多项目图标显示错误 | 检查 Symbol ID 冲突和重复加载，使用资源产物实际提供的唯一 ID |

参考：[Vue 与 Web Components](https://cn.vuejs.org/guide/extras/web-components)、[SVG use 元素](https://developer.mozilla.org/zh-CN/docs/Web/SVG/Reference/Element/use)。

## 交互与控制

### 点击事件

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `size` | `inherit` | 点击事件、动态名称 |
| `color` | 图标颜色 | 点击事件 |
| `name` | 已显式注册的图标名称 | 动态名称 |
| `transition` | 名称切换动画时长（ms） | 动态名称 |
<!-- demo-config-notes:end -->

Example source: src/icon/__demos__/click.vue

```vue
<script setup lang="ts">
import { Message } from "@cedar-design/ui";
</script>
<template>
  <c-button
    variant="text"
    round
    aria-label="确认操作"
    @click="Message.success('点击成功')"
  >
    <template #icon><c-icon-check-circle /></template>
  </c-button>
</template>
```

### 动态名称

`name` 使用短横线名称（例如 `arrow-left`），只查找当前 Vue 应用已注册的图标，不会自动加载图标全集。点击“切换图标”查看名称与图形同步变化。设置默认插槽时，优先显示插槽内容，`name` 不再决定图形。

Example source: src/icon/__demos__/dynamic-name.vue

```vue
<script setup lang="ts">
import { getCurrentInstance, ref } from "vue";
import {
  IconArrowLeft,
  IconArrowRight,
  IconCheckCircle,
  IconInfoCircle,
  IconRefresh,
  IconSearch,
} from "@cedar-design/icons-vue";
const iconName = ref("arrow-left");
const app = getCurrentInstance()?.appContext.app;
const icons = {
  IconArrowLeft,
  IconArrowRight,
  IconCheckCircle,
  IconInfoCircle,
  IconRefresh,
  IconSearch,
};
for (const [name, component] of Object.entries(icons)) {
  if (app && !app.component(name)) {
    app.component(name, component);
  }
}
function toggle() {
  iconName.value =
    iconName.value === "arrow-left" ? "arrow-right" : "arrow-left";
}
</script>
<template>
  <p>
    name 是已注册图标的名称。本例提供
    arrow-left、arrow-right、check-circle、info-circle、refresh、search；默认插槽存在时优先显示插槽内容。
  </p>
  <div class="icon-name-demo">
    <c-space wrap align="center" :size="24">
      <c-button @click="toggle">切换图标</c-button>
      <c-icon :name="iconName" :size="32" :transition="300" />
    </c-space>
  </div>
</template>
```

## 生命周期与边界

### 名称切换与生命周期

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `name` | 已显式注册的图标名称 | 名称切换与生命周期 |
| `transition` | 名称切换动画时长（ms） | 名称切换与生命周期 |
| `size` | `inherit` | 名称切换与生命周期 |
<!-- demo-config-notes:end -->

Example source: src/icon/__demos__/lifecycle.vue

```vue
<script setup lang="ts">
import { computed, getCurrentInstance, KeepAlive, ref } from "vue";
import { IconArrowLeft, IconArrowRight } from "@cedar-design/icons-vue";

const language = ref("zh-CN");
const english = computed(() => language.value === "en-US");

const active = ref(true),
  iconName = ref("arrow-left"),
  duration = ref(300);
const app = getCurrentInstance()?.appContext.app;
if (app && !app.component("IconArrowLeft")) {
  app.component("IconArrowLeft", IconArrowLeft);
}
if (app && !app.component("IconArrowRight")) {
  app.component("IconArrowRight", IconArrowRight);
}
function toggleName() {
  iconName.value =
    iconName.value === "arrow-left" ? "arrow-right" : "arrow-left";
}
</script>
<template>
  <c-space wrap>
    <c-button @click="toggleName">{{
      english ? "Switch name" : "切换名称"
    }}</c-button>
    <c-button @click="active = !active">{{
      english ? "Toggle active" : "切换激活"
    }}</c-button>
    <c-button @click="duration = duration ? 0 : 300"
      >{{ english ? "Toggle duration" : "切换时长" }} {{ duration }}ms</c-button
    >
    <KeepAlive
      ><c-icon v-if="active" :name="iconName" :transition="duration" :size="32"
    /></KeepAlive>
  </c-space>
  <p>
    {{
      english
        ? "Inactive changes commit on activation without replay. Duration changes cancel the old phase; zero shows the latest name immediately."
        : "停用后切换名称，激活直接显示最新图标，不重放旧动画；时长变更取消旧阶段，0立即显示最新名称。"
    }}
  </p>
</template>
```

## API

### 独立图标样式与使用边界

Resolver 自动导入独立图标时会一并引入轻量旋转样式；`importStyle: false` 时由业务自行引入。UI Icon 的样式入口也包含这份样式，不需要加载全部图标。

手动导入独立 SVG 组件时，若使用 `spin`，请在应用入口引入一次：

```ts
import '@cedar-design/icons-vue/style.css'
```

`rotate` 与 `spin` 可以组合；内置旋转遵循减少动态效果设置。`transition` 只控制注册名称的切换，以毫秒数值或数字字符串传入（如 `200` / `"200"`），不解析 `"200ms"` / `"1s"`。默认插槽接管内容后不执行名称切换动画，移除插槽时立即显示最新名称。自定义 `animation-class` 应避免覆盖持续旋转使用的 `transform`，并自行适配减少动态效果设置。

`name` 只查找当前应用在渲染前显式注册的图标，不自动下载资源；挂载后补注册不会自动刷新。容器的原生 `title` 不会传给内部 SVG，需要图像名称时在独立图标上设置 `title`；作为操作入口时使用带可访问名称的 Button。`click` 是普通通知事件，支持 Vue 的 `.once`，不会根据监听器返回的 Promise 管理等待状态。`stroke-*` 只作用于描边，填充或固定多色资源不保证随这些属性变化。


### Icon Props

| 属性            | 说明                   | 类型             | 默认值 |
| --------------- | ---------------------- | ---------------- | ------ |
| name            | 已显式注册的图标名称   | string           | -      |
| size            | `inherit` | number \| string | -      |
| color           | 图标颜色               | string           | -      |
| rotate          | 旋转角度               | number           | -      |
| spin            | 是否持续旋转           | boolean          | false  |
| transition      | 名称切换动画时长（ms） | number \| string | 0      |
| animation-class | 自定义切换动画类名     | string           | -      |

### Icon-xxx Props

| 属性            | 说明       | 类型                                       | 默认值  |
| --------------- | ---------- | ------------------------------------------ | ------- |
| size            | `inherit` | number \| string                            | -       |
| color           | 图标颜色   | string                                     | -       |
| rotate          | 旋转角度   | number                                     | -       |
| spin            | 是否旋转   | boolean                                    | false   |
| title           | 无障碍标题 | string                                     | -       |
| stroke-width    | 线宽       | number                                     | 4       |
| stroke-linecap  | 端点类型   | 'butt' \| 'round' \| 'square'              | 'butt'  |
| stroke-linejoin | 拐角类型   | 'bevel' \| 'inherit' \| 'miter' \| 'round' | 'miter' |

### Icon Events

| 事件名 | 说明           | 参数                        |
| ------ | -------------- | --------------------------- |
| click  | 点击触发的事件 | (event: MouseEvent) => void |

### Icon Slots

| 插槽名  | 说明           |
| ------- | -------------- |
| default | 自定义默认内容 |

### 类型定义

组件导出以下类型定义

```ts
import type { IconProps, IconInstance } from "@cedar-design/ui";
```

## 同源实现与平台边界

两端各自保存完整源码，不引用公共核心，不共享组件实例或响应式状态；修改时同步维护两份实现。主体、Props、关键样式及配对测试纳入只读源码一致性检查，主题 token 和安装入口各自维护。

只解析本应用已注册的图标；连续切换 name 会取消过期定时器，卸载后不再执行切换。各库注册前缀和历史 spin 类由本地适配保留，图标资源不跨库引用。

两端 Icon 默认继承宿主字号。需要固定 20px 的场景请显式设置 size="20" 或 icon-size 变量；size 属性优先于变量，颜色默认继承宿主。

### 动效变量

| Token | Default |
| --- | --- |
| `--c-icon-spin-duration` | `1s` |

内置动效遵循 prefers-reduced-motion: reduce：保留内容与状态反馈，关闭装饰性旋转、扫光和波纹。Icon 名称切换直接显示最新值并取消未结束阶段，CSS与JS时长保持一致；自定义动画类由调用方负责适配。Ripple的时长与清理策略以Ripple组件文档为准，不将其历史250ms规则当作Icon的时长上限。

---

Document: llms/zh-CN/components/image.md

<!-- Source: src/image/README.md; locale: zh-CN; page: /components/image/ -->

# Image

## 基础示例

### 基础用法

设置 `src` 即可获得带预览能力的图片组件。

Example source: src/image/__demos__/basic.vue

```vue
<template>
  <c-image width="200" src="/cat.jpg" />
</template>
```

## 图片展示与状态

### 填充模式

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `width` | 图片显示宽度 | 填充模式、图片说明与附加内容、错误状态 |
| `src` | 图片获取地址 | 填充模式、图片说明与附加内容、错误状态 |
| `height` | 图片显示高度 | 填充模式、错误状态、加载状态 |
| `preview-disabled` | 是否禁用点击预览 | 填充模式、加载状态、懒加载与回退 |
| `object-fit` | 确定图片如何适应容器框 | 填充模式、懒加载与回退 |
| `title` | 标题 | 图片说明与附加内容 |
<!-- demo-config-notes:end -->

通过 `object-fit` 控制图片如何适应容器。

Example source: src/image/__demos__/fit-mode.vue

```vue
<script setup lang="ts">
const fits = ['fill', 'contain', 'cover', 'none', 'scale-down'] as const
</script>

<template>
  <c-space :size="16" wrap>
    <c-space v-for="fit in fits" :key="fit" direction="column" align="center" :size="8">
      <c-image width="120" height="120" :object-fit="fit" preview-disabled src="/cat.jpg" />
      <span class="label">{{ fit }}</span>
    </c-space>
  </c-space>
</template>

<style scoped>
.label {
  color: var(--c-color-text-3);
  font-size: 12px;
}
</style>
```

### 图片说明与附加内容

比较图片说明和附加插槽的位置；预览入口、加载和错误回退保持独立。

<details>
<summary>配置说明与使用限制</summary>

#### 标题与描述

通过 `title`、`description` 和 `footer-position` 控制说明文案的展示位置。

#### 底部额外内容

通过 `extra` 插槽在页脚定制额外内容。

</details>

Example source: src/image/__demos__/content-comparison.vue

```vue
<script setup lang="ts">


</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="caption">
    <h4><span lang="zh-CN">标题与描述</span><span lang="en-US">caption</span></h4>
    <c-space :size="24" wrap>
        <c-image width="200" src="/cat.jpg" title="一只猫" description="页脚在图片内侧" />
        <c-image width="200" src="/cat2.jpg" title="一只猫" description="页脚在图片外侧" footer-position="outer" />
      </c-space>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="extra">
    <h4><span lang="zh-CN">底部额外内容</span><span lang="en-US">extra</span></h4>
    <c-space :size="24" wrap>
        <c-image width="200" src="/cat.jpg" title="一只猫" description="内侧额外内容">
          <template #extra>
            <span class="extra">Extra</span>
          </template>
        </c-image>
        <c-image width="200" src="/cat.jpg" title="一只猫" description="外侧额外内容" footer-position="outer">
          <template #extra>
            <span class="extra extra--outer">Extra</span>
          </template>
        </c-image>
      </c-space>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }
.demo-comparison-case--2 {

.extra {
  padding: 2px 8px;
  color: #fff;
  font-size: 12px;
  background: rgb(0 0 0 / 45%);
  border-radius: 10px;
}

.extra--outer {
  color: currentColor;
  background: var(--c-color-fill-2);
}

}
</style>
```

### 错误状态

图片加载失败时展示默认错误态，也可用 `error` 插槽自定义。示例使用损坏的内联图片数据触发解码失败，不发送无效网络请求。

Example source: src/image/__demos__/error.vue

```vue
<template>
  <c-space :size="16" wrap>
    <c-image width="160" height="120" src="data:image/png;base64,AA==" />
    <c-image width="160" height="120" src="data:image/png;base64,AA==" alt="自定义错误内容">
      <template #error>
        <div class="error-slot">加载失败</div>
      </template>
    </c-image>
  </c-space>
</template>

<style scoped>
.error-slot {
  display: flex;
  align-items: center;
  justify-content: center;
  width: 100%;
  height: 100%;
  color: var(--c-color-text-3);
  font-size: 12px;
}
</style>
```

### 加载状态

通过 `showLoader` 显示默认加载效果，或通过 `loader` 插槽自定义、模拟渐进加载。

Example source: src/image/__demos__/loader.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'

const timestamp = ref('')

function reload() {
  timestamp.value = String(Date.now())
}
</script>

<template>
  <c-space direction="column" :size="16">
    <c-button status="primary" size="sm" @click="reload">重新加载</c-button>
    <c-space :size="16" wrap>
      <c-image width="160" height="160" show-loader :src="`/cat.jpg?reload=${timestamp}`" preview-disabled />
      <c-image width="160" height="160" :src="`/cat.jpg?reload=${timestamp}`" preview-disabled>
        <template #loader>
          <div class="loader-animate" />
        </template>
      </c-image>
      <c-image width="160" height="160" :src="`/cat.jpg?reload=${timestamp}`" preview-disabled>
        <template #loader>
          <img class="progressive" src="/cat2.jpg" alt="" />
        </template>
      </c-image>
    </c-space>
  </c-space>
</template>

<style scoped>
.loader-animate {
  width: 100%;
  height: 100%;
  background: linear-gradient(
    -60deg,
    var(--c-color-fill-2) 25%,
    var(--c-color-fill-3) 40%,
    var(--c-color-fill-2) 55%
  );
  background-size: 400% 100%;
  animation: loop-circle 1.5s cubic-bezier(0.34, 0.69, 0.1, 1) infinite;
}

.progressive {
  width: 100%;
  height: 100%;
  object-fit: cover;
  filter: blur(5px);
}

@keyframes loop-circle {
  0% {
    background-position: 100% 50%;
  }

  100% {
    background-position: 0 50%;
  }
}
</style>
```

### 懒加载与回退

`lazy` 使用原生 `loading="lazy"`；失败时可用 `fallback-src` 回退。

Example source: src/image/__demos__/lazy.vue

```vue
<template>
  <c-space :size="16" wrap>
    <c-image width="160" height="120" object-fit="cover" lazy src="/cat.jpg" preview-disabled />
    <c-image width="160" height="120" object-fit="cover" src="data:image/png;base64,AA==" fallback-src="/cat2.jpg" preview-disabled />
  </c-space>
</template>
```

## 预览入口与分组

### 禁用预览

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `width` | 图片显示宽度 | 禁用预览、预览入口与受控、图片预览组 |
| `src` | 图片获取地址 | 禁用预览、预览入口与受控、图片预览组 |
| `height` | 图片显示高度 | 预览入口与受控、图片预览组 |
| `object-fit` | 确定图片如何适应容器框 | 预览入口与受控、图片预览组 |
| `preview-disabled` | 是否禁用点击预览 | 禁用预览 |
| `preview-props` | 预览的配置项 | 预览入口与受控 |
<!-- demo-config-notes:end -->

Example source: src/image/__demos__/disable-preview.vue

```vue
<template>
  <c-image preview-disabled width="200" src="/cat.jpg" />
</template>
```

### 预览入口与受控

通过 `preview-src`、`v-model:open` 和 `preview-props` 配置 Image 内嵌预览。

Example source: src/image/__demos__/preview-entry.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'

const previewOpen = ref(false)
</script>

<template>
  <c-space direction="column" :size="16">
    <c-image width="160" height="120" object-fit="cover" src="/cat.jpg" preview-src="/cat2.jpg" />
    <c-button status="primary" size="sm" @click="previewOpen = true">打开预览</c-button>
    <c-image
      v-model:open="previewOpen"
      width="160"
      height="120"
      object-fit="cover"
      src="/cat.jpg"
      :preview-props="{ scaleStep: 1 }"
    />
  </c-space>
</template>
```

### 单图 Preview

`ImagePreview` 只接收单个 `src`，负责缩放、旋转、拖拽和全屏等变换。

Example source: src/image/__demos__/component-preview.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'

const open = ref(false)
</script>

<template>
  <c-space direction="column" :size="16">
    <c-button status="primary" size="sm" @click="open = true">打开单图预览</c-button>
    <c-image-preview v-model:open="open" src="/cat.jpg" />
  </c-space>
</template>
```

### 命令式预览

命令式 API 对单图和多图返回同一套控制方法。

Example source: src/image/__demos__/imperative-preview.vue

```vue
<script setup lang="ts">
const images = ['/cat.jpg', '/cat2.jpg']
let handle: { next: () => void; close: () => void } | undefined

function previewSingle() {
  imagePreview(images[0])
}

function previewMultiple() {
  handle = imagePreview({ images, modelValue: 1 })
}

function next() {
  handle?.next()
}

function close() {
  handle?.close()
}
</script>

<template>
  <c-space :size="12" wrap>
    <c-button status="primary" size="sm" @click="previewSingle">预览单图</c-button>
    <c-button status="primary" size="sm" @click="previewMultiple">预览多图</c-button>
    <c-button size="sm" @click="next">下一张</c-button>
    <c-button size="sm" @click="close">关闭</c-button>
  </c-space>
</template>
```

### 图片预览组

`ImagePreviewGroup` 可以收集子 Image，集合状态只由 Group 管理。

Example source: src/image/__demos__/preview-group.vue

```vue
<template>
  <c-image-preview-group loop>
    <c-space :size="16" wrap>
      <c-image src="/cat.jpg" width="120" height="120" object-fit="cover" />
      <c-image src="/cat2.jpg" width="120" height="120" object-fit="cover" />
    </c-space>
  </c-image-preview-group>
</template>
```

### 数据驱动预览组

也可以直接传入 `images`，用按钮打开预览。

Example source: src/image/__demos__/component-preview-group.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'

const open = ref(false)
const current = ref(2)
const images = ['/cat.jpg', '/cat2.jpg']
</script>

<template>
  <c-space direction="column" :size="16">
    <p>默认在 body 全屏预览；切换缓存图片不重复等待加载。</p>
    <c-button status="primary" size="sm" @click="open = true">打开预览组</c-button>
    <c-image-preview-group v-model:open="open" v-model="current" :images="images" :loop="false" />
  </c-space>
</template>
```

## 预览定制与交互

### 水波与行内

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `width` | 图片显示宽度 | 水波与行内、点击背景层关闭、错误时仍显示 Footer |
| `src` | 图片获取地址 | 水波与行内、点击背景层关闭、错误时仍显示 Footer |
| `height` | 图片显示高度 | 水波与行内、点击背景层关闭、尺寸、圆角与位置 |
| `object-fit` | 确定图片如何适应容器框 | 水波与行内、点击背景层关闭、尺寸、圆角与位置 |
| `preview-disabled` | 是否禁用点击预览 | 水波与行内、错误时仍显示 Footer、尺寸、圆角与位置 |
| `preview-props` | 预览的配置项 | 点击背景层关闭、指定挂载容器 |
<!-- demo-config-notes:end -->

`ripple` 开启点击水波；`block` 设为 `false` 时作为行内元素排列。

Example source: src/image/__demos__/ripple.vue

```vue
<template>
  <c-space :size="16" wrap>
    <c-image width="120" height="120" object-fit="cover" ripple preview-disabled src="/cat.jpg" />
    <c-image :block="false" width="120" height="120" object-fit="cover" preview-disabled src="/cat.jpg" />
    <c-image :block="false" width="120" height="120" object-fit="cover" preview-disabled src="/cat2.jpg" />
  </c-space>
</template>
```

### 点击背景层关闭

通过 `preview-props.overlayClosable` 控制点击图片外的背景层是否关闭预览。左图开启，右图关闭；点击图片本身均不会关闭预览。

Example source: src/image/__demos__/overlay-closable.vue

```vue
<template>
  <c-space :size="16" wrap>
    <c-image
      width="120"
      height="120"
      object-fit="cover"
      src="/cat.jpg"
      :preview-props="{ overlayClosable: true }"
    />
    <c-image
      width="120"
      height="120"
      object-fit="cover"
      src="/cat2.jpg"
      :preview-props="{ overlayClosable: false }"
    />
  </c-space>
</template>
```

### 错误时仍显示 Footer

`hide-footer="never"` 可在加载失败时仍展示底部信息。

Example source: src/image/__demos__/hide-footer-never.vue

```vue
<template>
  <c-image
    width="200"
    src="data:image/png;base64,AA=="
    title="一只猫"
    description="错误时仍显示底部信息"
    hide-footer="never"
    preview-disabled
  />
</template>
```

### 自定义预览内容

关闭图标、指示器与操作区均可自定义。

Example source: src/image/__demos__/preview-features.vue

```vue
<script setup lang="ts">
import { ImagePreviewAction as CImagePreviewAction } from '../index'

import { ref } from 'vue'

const open = ref(false)
const current = ref(1)
const images = ['/cat.jpg', '/cat2.jpg']

function onAction() {
  current.value = current.value === 0 ? 1 : 0
}
</script>

<template>
  <c-space direction="column" :size="16">
    <c-button status="primary" size="sm" @click="open = true">打开自定义预览</c-button>
    <c-image-preview-group v-model:open="open" v-model="current" :images="images" :loop="false">
      <template #close-icon>
        <span class="close-icon">×</span>
      </template>
      <template #indicator="{ imageNumber, length }">
        <span class="indicator">{{ imageNumber }} / {{ length }}</span>
      </template>
      <template #actions>
        <c-image-preview-action name="切换" @click="onAction">+</c-image-preview-action>
      </template>
    </c-image-preview-group>
  </c-space>
</template>

<style scoped>
.close-icon {
  font-size: 24px;
  color: #fff;
}

.indicator {
  position: absolute;
  top: 16px;
  left: 50%;
  padding: 4px 12px;
  color: #fff;
  font-size: 12px;
  background: rgb(0 0 0 / 45%);
  border-radius: 12px;
  transform: translateX(-50%);
}
</style>
```

### 尺寸、圆角与位置

`width` / `height`、`radius` 和 `object-position` 控制几何与裁切位置。

Example source: src/image/__demos__/presentation.vue

```vue
<template>
  <c-space :size="16" wrap>
    <c-space direction="column" align="center" :size="8">
      <c-image width="160" height="100" object-fit="cover" object-position="left top" preview-disabled src="/cat.jpg" />
      <span class="label">160×100 · left top</span>
    </c-space>
    <c-space direction="column" align="center" :size="8">
      <c-image width="100" height="100" object-fit="cover" :radius="12" preview-disabled src="/cat.jpg" />
      <span class="label">radius 12</span>
    </c-space>
    <c-space direction="column" align="center" :size="8">
      <c-image width="100" height="100" object-fit="cover" radius="50%" preview-disabled src="/cat.jpg" />
      <span class="label">radius 50%</span>
    </c-space>
  </c-space>
</template>

<style scoped>
.label {
  color: var(--c-color-text-3);
  font-size: 12px;
}
</style>
```

### 指定挂载容器

Example source: src/image/__demos__/preview-popup-container.vue

```vue
<template>
  <div id="image-demo-preview-popup-container" class="popup-container">
    <c-image
      width="160"
      src="/cat.jpg"
      :preview-props="{
        popupContainer: '#image-demo-preview-popup-container',
        closable: false,
      }"
    />
  </div>
</template>

<style scoped>
.popup-container {
  position: relative;
  height: 220px;
  padding: 16px;
  overflow: hidden;
  background: var(--c-color-fill-2);
}
</style>
```

## 生命周期

### PreviewGroup track lifecycle / 轨道生命周期

Example source: src/image/__demos__/track-lifecycle.vue

```vue
<script setup lang="ts">
import { ImagePreviewAction as CImagePreviewAction } from '../index'

import { ref } from 'vue'
const active = ref(true)
const open = ref(false)
const current = ref(1)
const loop = ref(true)
const images = ref(['/cat.jpg', '/cat2.jpg'])
function replaceImages() { images.value = [...images.value].reverse() }
</script>
<template>
  <div>
    <c-button @click="open = true">Open / 打开</c-button>
    <c-button @click="active = !active">Activate / 停用与激活</c-button>
    <c-button @click="loop = !loop">Loop / 循环</c-button>
    <c-button @click="replaceImages">Replace images / 等长换图</c-button>
    <p>Current / 当前: {{ current }}. Navigate across the loop edge; deactivate, close or replace images. Old work must not replay.</p>
    <KeepAlive>
      <c-image-preview-group v-if="active" v-model:open="open" v-model="current" :images="images" :loop="loop">
        <template #actions>
          <c-image-preview-action name="Replace images / 换图" @click="replaceImages">换图</c-image-preview-action>
          <c-image-preview-action name="Deactivate / 停用" @click="active = false">停用</c-image-preview-action>
        </template>
      </c-image-preview-group>
    </KeepAlive>
  </div>
</template>
```

展示图片，支持说明、加载回退与预览。两端示例分组一致。

单图与预览组未设置 `popup-container` 时均挂载到 body 并覆盖视口；只有显式 `false` 才原地渲染，需要父容器提供定位和尺寸。预览组仅由当前图片的 load/error 结束加载提示，切回已加载的缓存图片不会残留加载图标。

### 预览交互生命周期

Example source: src/image/__demos__/controller-lifecycle.vue

```vue
<script setup lang="ts">
import { ImagePreviewAction as CImagePreviewAction } from '../index'

import { ref } from "vue";
const open = ref(false);
const active = ref(true);
const source = ref("/cat.jpg");
const presses = ref(0);
const switchSource = () => {
  source.value = source.value === "/cat.jpg" ? "/cat2.jpg" : "/cat.jpg";
};
</script>
<template>
  <div>
    <c-button @click="open = true">Open / 打开预览</c-button>
    <c-button @click="active = !active">Activate / 停用与激活</c-button>
    <p>
      Long presses / 长按通知: {{ presses }}. Cancel or deactivate; old input
      must not replay.
    </p>
    <KeepAlive>
      <c-image-preview
        v-if="active"
        v-model:open="open"
        :src="source"
        interaction="touch"
        :keyboard="true"
        @long-press="presses++"
      >
        <template #actions>
          <c-image-preview-action
            name="Switch source / 换图"
            @click="switchSource"
            >换图</c-image-preview-action
          >
          <c-image-preview-action
            name="Deactivate / 停用"
            @click="active = false"
            >停用</c-image-preview-action
          >
        </template>
      </c-image-preview>
    </KeepAlive>
  </div>
</template>
```

## 阅读方向

继承最近的 `dir="ltr|rtl"`，支持运行时切换与局部覆盖。预览集合的上一张/下一张、水平键与滑动沿阅读方向工作，值数组不反转。方向切换取消尚未完成的手势并保持当前图片、缩放与旋转；图片本身和放大后的拖拽坐标不自动镜像。图片序号保持 LTR 数值显示。

## API

图片预览组使用 `v-model` 绑定从 1 开始的图片序号，`defaultValue` 提供非受控初始图片序号；面板开关独立使用 `v-model:open` 与 `defaultOpen`。函数式预览配置同步使用 modelValue/defaultValue 和 onUpdate:modelValue。

### `<image>` Props

| 参数名                     | 描述                                                    | 类型                                                       |  默认值   | 版本   |
| -------------------------- | ------------------------------------------------------- | ---------------------------------------------------------- | :-------: | :----- |
| src                        | 图片获取地址                                            | `string`                                                   |    `-`    |        |
| width                      | 图片显示宽度                                            | `string \| number`                                         |    `-`    |        |
| height                     | 图片显示高度                                            | `string \| number`                                         |    `-`    |        |
| title                      | 标题                                                    | `string`                                                   |    `-`    |        |
| description                | 描述，将显示在底部，如果 alt 没有值，则会将其设置给 alt | `string`                                                   |    `-`    |        |
| object-fit                 | 确定图片如何适应容器框                                  | `'contain' \| 'cover' \| 'fill' \| 'none' \| 'scale-down'` |    `-`    |        |
| alt                        | 图片的文字描述                                          | `string`                                                   |    `-`    |        |
| hide-footer                | 是否隐藏 footer（支持 `'never'`，错误时仍显示底部）     | `boolean \| 'never'`                                       |  `false`  |        |
| footer-position            | 说明区位于图片内部 inner 或外部 outer，默认 inner；不是四边浮层方位 | `'inner' \| 'outer'`                                       | `'inner'` |        |
| show-loader                | 是否显示加载中效果                                      | `boolean`                                                  |  `false`  |        |
| preview-disabled           | 是否禁用点击预览                                        | `boolean`                                                  |  `false`  |        |
| open **(v-model)** | 控制预览的打开状态                                      | `boolean`                                                  |    `-`    |        |
| default-open       | 预览的默认打开状态                                      | `boolean`                                                  |  `false`  |        |
| preview-props              | 预览的配置项                                            | `ImagePreviewProps`                                        |    `-`    |        |
| footer-class               | 底部显示区域的类名                                      | `string\|array\|object`                                    |    `-`    | 2.23.0 |
| popup-container            | 预览挂载容器                                            | `string \| HTMLElement \| false`                           |    `-`    |        |

### `<image>` Events

| 事件名              | 描述                 | 参数            |
| ------------------- | -------------------- | --------------- |
| open-change | 预览的打开和关闭事件 | open: `boolean` |

### `<image>` Slots

| 插槽名          |         描述         | 参数 |
| --------------- | :------------------: | ---- |
| error           |  自定义错误状态内容  | -    |
| error-icon      | 自定义错误状态的图标 | -    |
| loader          |  自定义加载状态效果  | -    |
| extra           |     底部额外内容     | -    |
| preview-actions |   自定义预览工具栏   | -    |

### `<image-preview>` Props

| 参数名             | 描述                                                              | 类型                    |                                           默认值                                           |
| ------------------ | ----------------------------------------------------------------- | ----------------------- | :----------------------------------------------------------------------------------------: |
| src                | 图片获取地址                                                      | `string`                |                                            `-`                                             |
| open **(v-model)** | 是否打开                                                          | `boolean`               |                                            `-`                                             |
| default-open       | 默认是否打开，非受控                                              | `boolean`               |                                          `false`                                           |
| overlay-closable   | 点击图片外的 overlay 是否触发关闭，点击图片不会关闭               | `boolean`               |                                           `true`                                           |
| closable           | 是否显示关闭按钮                                                  | `boolean`               |                                           `true`                                           |
| actions-layout     | 操作项的布局                                                      | `string[]`              | `[  'fullScreen',  'rotateRight',  'rotateLeft',  'zoomIn',  'zoomOut',  'originalSize',]` |
| popup-container    | 设置弹出框的挂载点，同 `teleport` 的 `to`，缺省值是 document.body | `HTMLElement \| string \| false` |                                            `-`                                             |
| esc-to-close       | 是否支持 ESC 键关闭预览                                           | `boolean`               |                                           `true`                                           |
| wheel-zoom         | 是否开启滚轮缩放                                                  | `boolean`               |                                           `true`                                           |
| keyboard           | 是否开启键盘控制                                                  | `boolean`               |                                           `true`                                           |
| default-scale      | 默认缩放比                                                        | `number`                |                                            `1`                                             |
| scale-step         | 每次缩放的增量                                                    | `number`                |                                           `0.5`                                            |

### `<image-preview>` Events

| 事件名      | 描述         | 参数            |
| ----------- | ------------ | --------------- |
| close       | 关闭事件     | -               |
| open-change | 打开状态变更 | open: `boolean` |

### `<image-preview>` Slots

| 插槽名  |        描述        | 参数 | 版本   |
| ------- | :----------------: | ---- | :----- |
| actions | 自定义额外的操作项 | -    | 2.17.0 |

### `<image-preview-group>` Props

| 参数名                | 描述                                                              | 类型                    |                                           默认值                                           |
| --------------------- | ----------------------------------------------------------------- | ----------------------- | :----------------------------------------------------------------------------------------: |
| images                | 图片列表（设置了本属性之后，将不再收集子 Image 的图片信息）       | `string[]`              |                                            `-`                                             |
| model-value **(v-model)** | 当前展示的图片的序号（从 1 开始）                                              | `number`                |                                            `-`                                             |
| default-value       | 第一张展示的图片的序号（从 1 开始）                                            | `number`                |                                            `1`                                             |
| loop                  | 是否无限循环                                                      | `boolean`               |                                          `false`                                           |
| open **(v-model)**    | 是否打开，受控属性                                                | `boolean`               |                                            `-`                                             |
| default-open          | 默认是否打开，非受控                                              | `boolean`               |                                          `false`                                           |
| overlay-closable      | 点击图片外的 overlay 是否触发关闭，点击图片不会关闭               | `boolean`               |                                           `true`                                           |
| closable              | 是否显示关闭按钮                                                  | `boolean`               |                                           `true`                                           |
| actions-layout        | 控制条的布局                                                      | `string[]`              | `[  'fullScreen',  'rotateRight',  'rotateLeft',  'zoomIn',  'zoomOut',  'originalSize',]` |
| popup-container       | 设置弹出框的挂载点，同 `teleport` 的 `to`，缺省值是 document.body | `string \| HTMLElement \| false` |                                            `-`                                             |

### `<image-preview-group>` Events

| 事件名      | 描述             | 参数            |
| ----------- | ---------------- | --------------- |
| change      | 切换图片         | imageNumber: `number`，previousImageNumber: `number` |
| open-change | 预览的打开和关闭 | open: `boolean` |

### `<image-preview-group>` Slots

| 插槽名  |        描述        | 参数 | 版本   |
| ------- | :----------------: | ---- | :----- |
| actions | 自定义额外的操作项 | -    | 2.46.0 |

### `<image-preview-action>` Props (2.17.0)

| 参数名   | 描述     | 类型      | 默认值  |
| -------- | -------- | --------- | :-----: |
| name     | 名称     | `string`  |   `-`   |
| disabled | 是否禁用 | `boolean` | `false` |

### 类型定义

```ts
import type { ImageInstance } from "@cedar-design/ui";
import { imagePreview } from "@cedar-design/ui";
```

### `imagePreview` 方法

命令式预览被新的调用替换时，会清理旧实例并触发旧实例的 `onClosed`；与正常关闭一样，每个实例只通知一次，可用于释放 Object URL 等资源。旧句柄不会关闭后来打开的预览。若 `onClosed` 内同步打开新的预览，保留该新调用，外层调用返回 `undefined`。

| 方法名                             | 描述         | 参数                                  |
| ---------------------------------- | ------------ | ------------------------------------- |
| `imagePreview`                     | 打开图片预览 | `url \| url[] \| ImagePreviewOptions` |
| `imagePreview.close`               | 关闭预览     | `-`                                   |
| `imagePreview.setDefaultOptions`   | 设置默认配置 | `ImagePreviewOptions`                 |
| `imagePreview.resetDefaultOptions` | 重置默认配置 | `-`                                   |

## FAQ

### 关于 `image-preview` 的属性说明

1. 键盘快捷键 `keyboard` 设置此属性为 `true` 后，将根据 `actions-layout` 操作项来启用相应的快捷键操作。

- `esc`: 关闭预览
- `left`: 切换至上一张图片
- `right`: 切换至下一张图片
- `up`: 放大图片
- `down`: 缩小图片
- `space`: 还原至原始大小

2. 默认缩放比例 `defaultScale` 此属性定义了默认的图片缩放比例。例如，当设置为 1.5 时，图片将默认放大到原始大小的 1.5 倍。

3. `scaleStep` 控制滚轮、双击和工具栏每次放大或缩小的增量。

### 变量消费边界

预览组箭头字号由 `--c-image-preview-arrow-font-size` 控制。旧 actions-item、trigger、scale-value 尺寸以及 simple toolbar 变量对应的 DOM 已不存在，已删除这些无效入口；预览工具栏使用 preview-color-action-* 与 preview-padding-action-content，底栏使用现有 footer 变量。错误／加载层填满图片，不另加100px最小高度。缩放与轨道过渡消费 system motion，reduced-motion 时关闭。

### 图片预览组序号

`modelValue/defaultValue` 从 **1** 开始，`1` 表示第 1 张。`open(imageNumber = 1)`、`to(imageNumber)` 接收相同序号，无效或非整数序号会被忽略。`prev()/next()` 在循环边界也回传同一规则的序号。模型事件为 `update:modelValue(imageNumber)`，切换通知为 `change(imageNumber, previousImageNumber)`；外部赋值不补发切换通知。长按通知为 `long-press(imageNumber)`，指示器插槽参数为 `{ imageNumber, length }`。内部数组下标仍从 0 开始。

根节点 `class`、`style` 与 Image 容器样式合并；内部图片样式通过 `img-props.class/style` 设置。预览的 `open-change` 是 Vue 通知事件：每次状态切换只发送一次，`.once` 遵循 Vue 事件语义，返回 Promise 不控制 loading。类型中的 `onOpenChange` 监听器也走同一事件入口。

---

Document: llms/zh-CN/components/infinite-scroll.md

<!-- Source: src/infinite-scroll/README.md; locale: zh-CN; page: /components/infinite-scroll/ -->

# InfiniteScroll

InfiniteScroll 负责检测接近滚动底部并驱动分页状态，不负责请求、数据拼接或列表布局。通常与 `List` 组合使用。

## 基础示例

### 与列表组合

`status` 是唯一分页状态。组件触底时先同步更新为 `loading`，再触发 `load`；请求结束后由业务更新为 `idle`、`error` 或 `finished`。

Example source: src/infinite-scroll/__demos__/list.vue

```vue
<template>
  <div ref="scroller" class="infinite-scroll-demo">
    <c-infinite-scroll
      v-model:status="status"
      :target="scroller"
      :bottom-offset="32"
      @load="fetchData"
    >
      <c-list :data="data" :scrollbar="false">
        <template #header>Infinite list</template>
        <template #item="{ item }">
          <c-list-item>{{ item }}</c-list-item>
        </template>
      </c-list>
    </c-infinite-scroll>
  </div>
</template>

<script lang="ts" setup>
import { onBeforeUnmount, onDeactivated, ref } from "vue";
import type { InfiniteScrollStatus } from "@cedar-design/ui";

const scroller = ref<HTMLElement>();
const page = ref(0);
const data = ref<string[]>([]);
const status = ref<InfiniteScrollStatus>("idle");
let timer: ReturnType<typeof window.setTimeout> | undefined;

const fetchData = () => {
  window.clearTimeout(timer);
  timer = window.setTimeout(() => {
    timer = undefined;
    const start = data.value.length;
    data.value.push(
      ...Array.from(
        { length: 8 },
        (_, index) => `Cedar list item ${start + index + 1}`,
      ),
    );
    page.value += 1;
    status.value = page.value >= 5 ? "finished" : "idle";
  }, 600);
};
onBeforeUnmount(() => window.clearTimeout(timer));
onDeactivated(() => {
  window.clearTimeout(timer);
  timer = undefined;
  if (status.value === "loading") {
    status.value = "idle";
  }
});
</script>

<style scoped>
.infinite-scroll-demo {
  max-height: 320px;
  overflow-y: auto;
}
</style>
```

## 内容与展示

### 加载失败

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `status` | 分页状态，支持 `v-model:status` | 加载失败 |
| `target` | 滚动容器；未传时使用最近滚动父级 | 加载失败 |
<!-- demo-config-notes:end -->

请求失败时将 `status` 设置为 `error`。默认错误区域和 `error` 插槽都可以触发 `retry`，重试事件不会额外触发 `load`。

Example source: src/infinite-scroll/__demos__/error.vue

```vue
<template>
  <div ref="scroller" class="infinite-scroll-demo">
    <c-infinite-scroll
      v-model:status="status"
      :target="scroller"
      @load="fetchData"
      @retry="fetchData"
    >
      <c-list :data="data" :scrollbar="false">
        <template #item="{ item }">
          <c-list-item>{{ item }}</c-list-item>
        </template>
      </c-list>

      <template #error="{ retry }">
        加载失败，<c-button
          variant="text"
          size="sm"
          status="primary"
          @click="retry"
          >点击重试</c-button
        >
      </template>
    </c-infinite-scroll>
  </div>
</template>

<script lang="ts" setup>
import { onBeforeUnmount, onDeactivated, ref } from "vue";
import type { InfiniteScrollStatus } from "@cedar-design/ui";

const scroller = ref<HTMLElement>();
const data = ref<string[]>([]);
const status = ref<InfiniteScrollStatus>("idle");
let failedOnce = false;
let timer: ReturnType<typeof window.setTimeout> | undefined;

const fetchData = () => {
  window.clearTimeout(timer);
  timer = window.setTimeout(() => {
    timer = undefined;
    if (!failedOnce && data.value.length === 8) {
      failedOnce = true;
      status.value = "error";
      return;
    }

    const start = data.value.length;
    data.value.push(
      ...Array.from(
        { length: 8 },
        (_, index) => `Cedar list item ${start + index + 1}`,
      ),
    );
    status.value = data.value.length >= 32 ? "finished" : "idle";
  }, 600);
};
onBeforeUnmount(() => window.clearTimeout(timer));
onDeactivated(() => {
  window.clearTimeout(timer);
  timer = undefined;
  if (status.value === "loading") {
    status.value = "idle";
  }
});
</script>

<style scoped>
.infinite-scroll-demo {
  max-height: 320px;
  overflow-y: auto;
}
</style>
```

自定义重试操作请使用按钮，支持键盘 Enter/Space。示例中的模拟请求会在卸载或停用时清理计时器，避免离开页面后继续回写。

基础、自定义状态和错误重试示例均清理模拟请求；KeepAlive 恢复后可从 idle 状态重新加载，不复用取消前的计时器。

## 自定义与插槽

### 自定义状态

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `status` | 分页状态，支持 `v-model:status` | 自定义状态 |
| `target` | 滚动容器；未传时使用最近滚动父级 | 自定义状态 |
| `bottom-offset` | 距离底部的触发阈值，数字按 px，字符串按 CSS length | 自定义状态 |
<!-- demo-config-notes:end -->

通过 `loading`、`finished` 插槽自定义底部状态，同时可使用 CSS 长度设置 `bottom-offset`。

Example source: src/infinite-scroll/__demos__/custom-status.vue

```vue
<template>
  <div ref="scroller" class="infinite-scroll-demo">
    <c-infinite-scroll
      v-model:status="status"
      :target="scroller"
      bottom-offset="2rem"
      @load="fetchData"
    >
      <c-list :data="data" :scrollbar="false">
        <template #item="{ item }">
          <c-list-item>{{ item }}</c-list-item>
        </template>
      </c-list>

      <template #loading>
        <c-space align="center">
          <c-loading />
          正在加载下一页
        </c-space>
      </template>
      <template #finished>全部数据加载完成</template>
    </c-infinite-scroll>
  </div>
</template>

<script lang="ts" setup>
import { onBeforeUnmount, onDeactivated, ref } from "vue";
import type { InfiniteScrollStatus } from "@cedar-design/ui";

const scroller = ref<HTMLElement>();
const data = ref<string[]>([]);
const status = ref<InfiniteScrollStatus>("idle");
let timer: ReturnType<typeof window.setTimeout> | undefined;

const fetchData = () => {
  window.clearTimeout(timer);
  timer = window.setTimeout(() => {
    timer = undefined;
    const start = data.value.length;
    data.value.push(
      ...Array.from(
        { length: 8 },
        (_, index) => `Cedar list item ${start + index + 1}`,
      ),
    );
    status.value = data.value.length >= 32 ? "finished" : "idle";
  }, 600);
};
onBeforeUnmount(() => window.clearTimeout(timer));
onDeactivated(() => {
  window.clearTimeout(timer);
  timer = undefined;
  if (status.value === "loading") {
    status.value = "idle";
  }
});
</script>

<style scoped>
.infinite-scroll-demo {
  max-height: 320px;
  overflow-y: auto;
}
</style>
```

虚拟列表场景应将 `target` 指向实际虚拟滚动容器，并在追加数据后把 `status` 改回 `idle`；必要时调用 `check()`。

## 生命周期与边界

### 测量绑定生命周期

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `status` | 分页状态，支持 `v-model:status` | 测量绑定生命周期 |
| `target` | 滚动容器；未传时使用最近滚动父级 | 测量绑定生命周期 |
| `immediate` | 挂载并解析滚动容器后是否立即检查 | 测量绑定生命周期 |
<!-- demo-config-notes:end -->

Example source: src/infinite-scroll/__demos__/scheduler-lifecycle.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import type { InfiniteScrollStatus } from "@cedar-design/ui";
const first = ref<HTMLElement>();
const second = ref<HTMLElement>();
const alternate = ref(false);
const active = ref(true);
const status = ref<InfiniteScrollStatus>("idle");
const loads = ref(0);
const load = () => {
  loads.value++;
  status.value = "finished";
};
</script>
<template>
  <div>
    <c-button @click="alternate = !alternate"
      >Switch target / 切换目标</c-button
    >
    <c-button @click="active = !active">Activate / 停用与激活</c-button>
    <c-button @click="status = 'idle'">New status cycle / 新状态循环</c-button>
    <p>
      Loads / 加载次数: {{ loads }}. Old checks must not replay /
      旧检查不能重放。
    </p>
    <div ref="first" style="height: 100px; overflow: auto">
      <div style="height: 300px">Target A</div>
    </div>
    <div ref="second" style="height: 100px; overflow: auto">
      <div style="height: 300px">Target B</div>
    </div>
    <KeepAlive>
      <c-infinite-scroll
        v-if="active"
        v-model:status="status"
        :target="alternate ? second : first"
        :immediate="false"
        @load="load"
      >
        <div>Detector / 触底检测</div>
      </c-infinite-scroll>
    </KeepAlive>
  </div>
</template>
```

## API

### `<infinite-scroll>` Props

| 参数名        | 描述                                               | 类型                                           | 默认值   |
| ------------- | -------------------------------------------------- | ---------------------------------------------- | -------- |
| status        | 分页状态，支持 `v-model:status`                    | `'idle' \| 'loading' \| 'error' \| 'finished'` | `'idle'` |
| bottom-offset | 距离底部的触发阈值，数字按 px，字符串按 CSS length | `string \| number`                             | `0`      |
| immediate     | 挂载并解析滚动容器后是否立即检查                   | `boolean`                                      | `true`   |
| disabled      | 是否暂停加载和重试                                 | `boolean`                                      | `false`  |
| target        | 滚动容器；未传时使用最近滚动父级                   | `string \| HTMLElement`                        | `-`      |

### `<infinite-scroll>` Events

| 事件名        | 描述                       | 参数      |
| ------------- | -------------------------- | --------- |
| update:status | 请求分页状态改为 `loading` | `loading` |
| load          | 空闲状态下到达阈值时触发   | -         |
| retry         | 错误状态下调用重试时触发   | -         |

`retry` 不会同时触发 `load`。业务可让两个事件调用同一个请求函数。

### `<infinite-scroll>` Methods

| 方法名 | 描述                         |
| ------ | ---------------------------- |
| check  | 立即检查当前是否到达加载阈值 |
| retry  | 在 `error` 状态下发起重试    |

### `<infinite-scroll>` Slots

| 插槽名   | 描述             | 参数                |
| -------- | ---------------- | ------------------- |
| default  | 被监听的内容     | -                   |
| loading  | 分页加载状态     | -                   |
| error    | 分页失败状态     | `retry: () => void` |
| finished | 全部加载完成状态 | -                   |

默认错误区域可点击重试。`finished` 是终态，只有外部将 `status` 重置为 `idle` 后才会恢复检测。

### 类型定义

```ts
import type {
  InfiniteScrollInstance,
  InfiniteScrollMethods,
  InfiniteScrollProps,
  InfiniteScrollStatus,
} from "@cedar-design/ui";
```

### 样式变量

| 变量名                                          | 默认值                  |
| ----------------------------------------------- | ----------------------- |
| `--c-infinite-scroll-status-min-height`         | `50px`                  |
| `--c-infinite-scroll-status-padding`            | `12px 0`                |
| `--c-infinite-scroll-status-color`              | `var(--c-color-text-3)` |
| `--c-infinite-scroll-status-font-size`          | `var(--c-font-size-md)` |
| `--c-infinite-scroll-loading-gap`               | `8px`                   |
| `--c-infinite-scroll-error-color`               | `var(--c-color-danger)` |

---

Document: llms/zh-CN/components/input-number.md

<!-- Source: src/input-number/README.md; locale: zh-CN; page: /components/input-number/ -->

# InputNumber

InputNumber 用于编辑和提交业务数字。两端主体、数值控制器、样式及公开 API 按独立源码复制维护，不共享运行时实例。

- `model-value !== undefined` 表示受控；`default-value` 仅初始化非受控值。编辑草稿允许暂时不同于业务值；提交后若父组件拒绝更新，恢复到父组件值。外部回填不触发用户事件或校验。
- 默认在 Enter / 失焦时更新；`model-event="input"` 输入完整数字时更新，但 `change` 仍在提交时触发。Enter 后再失焦不会重复提交。
- 清空顺序为 **input → update:model-value → change → clear**，值为 `undefined`。这次改造移除了旧的“清空不触发 input/change”行为，不提供兼容分支。
- `-`、`.`、`1.` 等输入中间态暂时保留；提交 `1.` 得到数字 1，单独符号恢复之前的业务值。非法文本、NaN、Infinity 不会写入业务值。IME 组合输入结束后只处理一次。
- 范围优先于精度：舍入后仍限制在 min/max 内，非对齐边界保留实际值。两端采用独立配置的 Decimal 运算，不受应用修改 Decimal 全局配置影响；模型仍是 JavaScript number，不承诺任意精度的大数存储。
- 禁用/只读/尺寸从 InputGroup、FormItem、Form 继承，显式 false 可以覆盖；Cedar 的缺省尺寸再读取 ConfigProvider，Maple 使用现有默认系统。字段外观与 hint 可继承 InputGroup；外层已有 FormItem 标题时不重复显示浮动标签。
- 鼠标、触控都支持长按；释放、取消、移出、窗口失焦、组件停用/卸载或状态变化时停止。移动端建议用 button 布局增加触控面积；↑/↓ 步进，Enter 提交。

## 阅读方向

数字输入继承来源 `dir`，增减按钮随阅读顺序排列。数值、精度和上下键语义保持不变：ArrowUp 增加，ArrowDown 减少；不对数值或显示字符串做反转。

## 基础示例

### 基础与状态

Example source: src/input-number/__demos__/field-basic.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
const value = ref<number | undefined>(12);
const disabled = ref(false);
const readonly = ref(false);
const clearable = ref(true);
const hint = ref(false);
</script>
<template>
  <div class="number-demo">
    <div class="number-demo__options">
      <c-checkbox v-model="disabled" edit-mode="direct">禁用</c-checkbox>
      <c-checkbox v-model="readonly" edit-mode="direct">只读</c-checkbox>
      <c-checkbox v-model="clearable" edit-mode="direct">可清空</c-checkbox>
      <c-checkbox v-model="hint" edit-mode="direct">浮动提示</c-checkbox>
    </div>
    <c-input-number
      v-model="value"
      :disabled="disabled"
      :readonly="readonly"
      :clearable="clearable"
      :hint="hint"
      placeholder="数量"
    />
    <output>业务数值：{{ value ?? "空值" }}</output>
  </div>
</template>
<style scoped>
.number-demo {
  display: flex;
  flex-direction: column;
  gap: 12px;
}
.number-demo__options {
  display: flex;
  flex-wrap: wrap;
  gap: 12px;
}
</style>
```

## 外观与布局

### 外观组合

<!-- demo-config-notes:start -->

#### 本组配置对照

| 配置          | 作用                        | 相关示例                             |
| ------------- | --------------------------- | ------------------------------------ |
| `size`        | 五档均完整实现，可继承      | 表单控件尺寸对照、五档尺寸与字段外观 |
| `variant`     | 字段外观，可继承 InputGroup | 表单控件尺寸对照、五档尺寸与字段外观 |
| `placeholder` | 输入提示                    | 表单控件尺寸对照、五档尺寸与字段外观 |
| `min`         | 最小值                      | 外观组合                             |
| `max`         | 最大值                      | 外观组合                             |
| `mode`        | 步进按钮布局                | 三种布局                             |

<!-- demo-config-notes:end -->

适用于数量、配额等数值输入。调整变体、尺寸，用相同数据观察变化。内容保持一致，便于比较不同设置的实际效果。

Example source: src/input-number/__demos__/appearance-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref(3);
const __demoAppearance = __demoReactive({ variant: "filled", size: "md" });

import { computed as demoComputed, ref as demoRef } from 'vue'
const demoCompareFields = [{"name":"variant","values":["filled","outline","standard"]},{"name":"size","values":["xs","sm","md","lg","xl"]}]
const demoCompareAxis = demoRef("variant")
const demoComparedOptions = demoComputed(() => demoCompareFields.find(field => field.name === demoCompareAxis.value)?.values ?? [])
</script>
<template>
  <c-space direction="column" :size="16">
    <c-form layout="vertical">
      <c-form-item layout="vertical" size="sm" label="variant">
        <c-radio-group
          v-model="__demoAppearance['variant']"
          aria-label="variant"
          :options="[
            { label: 'filled', value: 'filled' },
            { label: 'outline', value: 'outline' },
            { label: 'standard', value: 'standard' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
      <c-form-item layout="vertical" size="sm" label="size">
        <c-radio-group
          v-model="__demoAppearance['size']"
          aria-label="size"
          :options="[
            { label: 'xs', value: 'xs' },
            { label: 'sm', value: 'sm' },
            { label: 'md', value: 'md' },
            { label: 'lg', value: 'lg' },
            { label: 'xl', value: 'xl' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
    </c-form>
    <p class="demo-config-comparison-hint"><span lang="zh-CN">选择一个对比维度；其他配置和内容保持一致。输入类示例共享同一个值，便于比较外观。</span><span lang="en-US">Compare one dimension while keeping the other settings and content identical. Input specimens share the same value.</span></p>
<c-radio-group v-model="demoCompareAxis" aria-label="Compare configuration" :options="demoCompareFields.map(field => ({ label: field.name, value: field.name }))" />
<div class="demo-config-comparison">
<section v-for="sample in demoComparedOptions" :key="String(sample)">
<p><code>{{ demoCompareAxis }}={{ sample }}</code></p>
<c-input-number
      v-model="value"
      :min="0"
      :max="10"
      v-bind="{ ...__demoAppearance, [demoCompareAxis]: sample }"
    ></c-input-number>
</section>
</div>
  </c-space>
</template>

<style scoped>
.demo-config-comparison { display: grid; grid-template-columns: repeat(auto-fit, minmax(min(100%, 220px), 1fr)); gap: 20px; min-width: 0; max-width: 100%; }
.demo-config-comparison > section { min-width: 0; }
.demo-config-comparison p { margin: 0 0 8px; }
html:not([lang='en-US']) .demo-config-comparison-hint > [lang='en-US'],
html[lang='en-US'] .demo-config-comparison-hint > [lang='zh-CN'] { display: none; }
</style>
```

### 表单控件尺寸对照

切换五档 size 和三种字段变体，比较 Input、Button、Select、日期时间及其他单行表单控件的高度。Button 在这里固定使用 outline。DatePicker/TimePicker 是面板，此处使用带输入框的 Date/Time 字段。示例同时展示有值、可清空、标签删除与长标签多选；Select/Cascader 设置 tag-nowrap 时保持同档高度，长标签文字省略、删除图标保留；标签行可横向滚动，清空按钮和箭头固定在外侧。被省略的标签正文支持悬停、键盘聚焦或点按查看完整文字，点外部或按 Esc 关闭，不改变选中值。可清空后恢复选中值重复比较。多行文本和允许换行的多选内容按内容撑高。

Example source: src/field-decorator/__demos__/control-sizes.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
const sizes = ["xs", "sm", "md", "lg", "xl"] as const;
const variants = ["outline", "filled", "standard"] as const;
const size = ref<(typeof sizes)[number]>("md");
const variant = ref<(typeof variants)[number]>("outline");
const options = [
  { value: "beijing", label: "Beijing" },
  { value: "shanghai", label: "Shanghai" },
];
const cascaderOptions = [{ value: "china", label: "China", children: options }];

const inputValue = ref("Beijing");
const selectValue = ref("beijing");
const cascaderValue = ref("beijing");
const selectMultiple = ref(["beijing", "shanghai"]);
const cascaderMultiple = ref(["beijing", "shanghai"]);
const selectOverflow = ref(["long", "beijing", "shanghai"]);
const cascaderOverflow = ref(["long", "beijing", "shanghai"]);
const selectedOptions = [
  ...options,
  {
    value: "long",
    label:
      "A very long selected option label for overflow comparison — full text preview keeps the selected value unchanged.",
  },
];
const selectedCascaderOptions = [
  { value: "china", label: "China", children: selectedOptions },
];
function resetSelections() {
  inputValue.value = "Beijing";
  selectValue.value = "beijing";
  cascaderValue.value = "beijing";
  selectMultiple.value = ["beijing", "shanghai"];
  cascaderMultiple.value = ["beijing", "shanghai"];
  selectOverflow.value = ["long", "beijing", "shanghai"];
  cascaderOverflow.value = ["long", "beijing", "shanghai"];
}
</script>
<template>
  <section
    aria-label="Form control size comparison"
    class="control-size-comparison"
  >
    <c-space wrap :size="12">
      <c-radio-group v-model="size" aria-label="Comparison size">
        <c-radio v-for="item in sizes" :key="item" :value="item">{{
          item
        }}</c-radio>
      </c-radio-group>
      <c-radio-group v-model="variant" aria-label="Comparison variant">
        <c-radio v-for="item in variants" :key="item" :value="item">{{
          item
        }}</c-radio>
      </c-radio-group>
    </c-space>
    <div class="control-size-comparison__grid">
      <div data-control="Input">
        <p>Input</p>
        <c-input :size="size" :variant="variant" placeholder="Input" />
      </div>
      <div data-control="Button">
        <p>Button</p>
        <c-button :size="size" variant="outline">Button</c-button>
      </div>
      <div data-control="Select">
        <p>Select</p>
        <c-select
          :size="size"
          :variant="variant"
          :options="options"
          placeholder="Select"
        />
      </div>
      <div data-control="Date">
        <p>Date</p>
        <c-date :size="size" :variant="variant" placeholder="Date" />
      </div>
      <div data-control="Time">
        <p>Time</p>
        <c-time :size="size" :variant="variant" placeholder="Time" />
      </div>
      <div data-control="InputNumber">
        <p>InputNumber</p>
        <c-input-number :size="size" :variant="variant" placeholder="Number" />
      </div>
      <div data-control="AutoComplete">
        <p>AutoComplete</p>
        <c-auto-complete
          :size="size"
          :variant="variant"
          :options="options"
          placeholder="AutoComplete"
        />
      </div>
      <div data-control="Cascader">
        <p>Cascader</p>
        <c-cascader
          :size="size"
          :variant="variant"
          :options="cascaderOptions"
          placeholder="Cascader"
        />
      </div>
      <div data-control="DateRange">
        <p>DateRange</p>
        <c-date-range
          :size="size"
          :variant="variant"
          :placeholder="['Start', 'End']"
        />
      </div>
      <div data-control="TimeRange">
        <p>TimeRange</p>
        <c-time-range
          :size="size"
          :variant="variant"
          :placeholder="['Start', 'End']"
        />
      </div>
    </div>

    <section
      aria-label="Selected control size comparison"
      class="control-size-comparison__states"
    >
      <c-space wrap align="center" :size="12">
        <span>Selected / Clearable / Multiple — 有值、可清空与多选不换行</span>
        <span
          >Hover or focus truncated text; tap on touch screens /
          悬停或聚焦省略正文查看全文；触屏点按查看，点外部关闭</span
        >
        <c-button size="sm" variant="outline" @click="resetSelections"
          >Reset / 恢复选中值</c-button
        >
      </c-space>
      <div class="control-size-comparison__grid">
        <div data-control="InputValue">
          <p>Input · clearable</p>
          <c-input
            v-model="inputValue"
            :size="size"
            :variant="variant"
            clearable
            placeholder="Input value"
          />
        </div>
        <div data-control="ButtonReference">
          <p>Button · reference</p>
          <c-button :size="size" variant="outline">Button</c-button>
        </div>
        <div data-control="SelectValue">
          <p>Select · clearable</p>
          <c-select
            v-model="selectValue"
            :size="size"
            :variant="variant"
            :options="selectedOptions"
            clearable
            placeholder="Select value"
          />
        </div>
        <div data-control="CascaderValue">
          <p>Cascader · clearable</p>
          <c-cascader
            v-model="cascaderValue"
            :size="size"
            :variant="variant"
            :options="selectedCascaderOptions"
            clearable
            placeholder="Cascader value"
          />
        </div>
        <div data-control="SelectMultiple">
          <p>Select · multiple / nowrap</p>
          <c-select
            v-model="selectMultiple"
            :size="size"
            :variant="variant"
            :options="selectedOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Select multiple"
          />
        </div>
        <div data-control="CascaderMultiple">
          <p>Cascader · multiple / nowrap</p>
          <c-cascader
            v-model="cascaderMultiple"
            :size="size"
            :variant="variant"
            :options="selectedCascaderOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Cascader multiple"
          />
        </div>
        <div data-control="SelectOverflow">
          <p>Select · long values / nowrap</p>
          <c-select
            v-model="selectOverflow"
            edit-mode="direct"
            :size="size"
            :variant="variant"
            :options="selectedOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Select long values"
          />
        </div>
        <div data-control="CascaderOverflow">
          <p>Cascader · long values / nowrap</p>
          <c-cascader
            v-model="cascaderOverflow"
            edit-mode="direct"
            :size="size"
            :variant="variant"
            :options="selectedCascaderOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Cascader long values"
          />
        </div>
      </div>
    </section>
  </section>
</template>
<style scoped>
.control-size-comparison,
.control-size-comparison__states {
  display: grid;
  gap: 24px;
}
.control-size-comparison__grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
  align-items: start;
  gap: 24px 16px;
}
.control-size-comparison__grid > div {
  min-width: 0;
}
.control-size-comparison__grid p {
  margin: 0 0 12px;
  font-size: 14px;
  line-height: 20px;
}
.control-size-comparison__grid :deep(.c-input-number),
.control-size-comparison__grid :deep(.c-auto-complete) {
  width: 100%;
}
</style>
```

### 三种布局

Example source: src/input-number/__demos__/field-modes.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const embed = ref(1)
const button = ref(1)
const input = ref(1)
</script>
<template>
  <div class="number-demo">
    <label>内嵌步进<c-input-number v-model="embed" mode="embed" /></label>
    <label>左右按钮（便于触控）<c-input-number v-model="button" mode="button" /></label>
    <label>纯输入<c-input-number v-model="input" mode="input" /></label>
    <p>按钮可长按；输入框内使用 ↑ / ↓ 步进，Enter 或失焦提交。</p>
  </div>
</template>
<style scoped>
.number-demo, .number-demo label { display: flex; flex-direction: column; gap: 12px; }
</style>
```

### 五档尺寸与字段外观

Example source: src/input-number/__demos__/field-options.vue

```vue
<script setup lang="ts">
const sizes = ['xs', 'sm', 'md', 'lg', 'xl'] as const
const variants = ['outline', 'filled', 'standard'] as const
</script>
<template>
  <div class="number-demo">
    <label v-for="size in sizes" :key="size">{{ size }}<c-input-number :size="size" :default-value="12" /></label>
    <label v-for="variant in variants" :key="variant">{{ variant }}<c-input-number :variant="variant" hint placeholder="金额" :default-value="12" /></label>
  </div>
</template>
<style scoped>
.number-demo, .number-demo label { display: flex; flex-direction: column; gap: 12px; }
</style>
```

## 数值输入与格式

### 数量控制与提交拦截

<!-- demo-config-notes:start -->

#### 本组配置对照

| 配置        | 作用                         | 相关示例                                           |
| ----------- | ---------------------------- | -------------------------------------------------- |
| `clearable` | 允许清空可编辑字段           | 数量控制与提交拦截、格式化与插槽、小步长与范围边界 |
| `mode`      | 步进按钮布局                 | 数量控制与提交拦截、格式化与插槽                   |
| `min`       | 最小值                       | 数量控制与提交拦截、小步长与范围边界               |
| `max`       | 最大值                       | 数量控制与提交拦截、小步长与范围边界               |
| `step`      | 正的有限步长，支持科学计数法 | 数量控制与提交拦截、小步长与范围边界               |
| `formatter` | 只格式化展示，不改变业务数字 | 格式化与插槽、小步长与范围边界                     |

<!-- demo-config-notes:end -->

`disable-input` 只禁止手输与清空，按钮和方向键仍可步进。`disable-increment` / `disable-decrement` 分别禁用方向；`increment-button` / `decrement-button` 控制显示，隐藏的方向同样不能通过键盘触发。`press=false` 关闭连续长按。

`before-commit(value, { previousValue, signal })` 复用字段提交协议，返回 `false` 拒绝，返回 `void` 允许；可返回 Promise。inline 的输入提交、步进与清空均经过拦截，`model-event="input"` 也需先审批后回填。等待期间公开 `aria-busy`、锁定操作，外部回填、禁用、只读、配置变化、停用或卸载会取消旧请求。不要把 signal 取消当作成功。抛错保留原值并触发 `commit-error(error)`。click / dblclick 编辑层在最终确认时拦截一次，内部草稿不重复审批；错误使用面板现有反馈。启用拦截时，长按不会连续发起审批。

`step(value, direction, event)` 只在已允许且实际改变的步进发生时触发，direction 为 `plus` 或 `minus`。外部回填、拒绝、边界、隐藏或禁用的方向均不触发。

Example source: src/input-number/__demos__/quantity-controls.vue

```vue
<script setup lang="ts">
import { onBeforeUnmount, ref, shallowRef } from "vue";

const props = defineProps<{ english?: boolean }>();
const value = ref<number | undefined>(2);
const disableInput = ref(true);
const disableIncrement = ref(false);
const disableDecrement = ref(false);
const incrementButton = ref(true);
const decrementButton = ref(true);
const press = ref(true);
const lastStep = ref("—");
const approved = ref<number | undefined>(2);
const blocked = ref(false);
const pending = ref(false);
const status = ref("—");
const decision = shallowRef<((allowed: boolean) => void) | undefined>();
const fail = shallowRef<(() => void) | undefined>();
function beforeCommit(
  { value: next }: { value: unknown },
  _done: (allow?: boolean) => void,
  { signal }: { signal: AbortSignal },
) {
  pending.value = true;
  status.value = props.english
    ? `Waiting to commit ${next ?? "empty"}`
    : `等待提交 ${next ?? "空值"}`;
  return new Promise<void | false>((resolve, reject) => {
    const cleanup = () => {
      signal.removeEventListener("abort", cancel);
      pending.value = false;
      decision.value = undefined;
      fail.value = undefined;
    };
    const cancel = () => {
      cleanup();
      status.value = props.english
        ? "Cancelled; old result ignored"
        : "已取消，旧结果不再生效";
      resolve(false);
    };
    signal.addEventListener("abort", cancel, { once: true });
    decision.value = (allowed) => {
      cleanup();
      status.value = allowed
        ? props.english
          ? "Approved"
          : "已允许"
        : props.english
          ? "Rejected"
          : "已拒绝";
      resolve(allowed ? undefined : false);
    };
    fail.value = () => {
      cleanup();
      status.value = props.english
        ? "Request failed; value preserved"
        : "请求失败，保留原值";
      reject(
        new Error(props.english ? "Quantity request failed" : "数量提交失败"),
      );
    };
  });
}
onBeforeUnmount(() => decision.value?.(false));
</script>

<template>
  <div class="quantity-controls-demo">
    <h4>
      {{
        english ? "Quantity controls and step direction" : "数量控制与步进方向"
      }}
    </h4>
    <c-space wrap>
      <c-checkbox v-model="disableInput" edit-mode="direct">{{
        english ? "Buttons only" : "禁止手输"
      }}</c-checkbox>
      <c-checkbox v-model="disableIncrement" edit-mode="direct">{{
        english ? "Disable increase" : "禁用增加"
      }}</c-checkbox>
      <c-checkbox v-model="disableDecrement" edit-mode="direct">{{
        english ? "Disable decrease" : "禁用减少"
      }}</c-checkbox>
      <c-checkbox v-model="incrementButton" edit-mode="direct">{{
        english ? "Show increase" : "显示增加"
      }}</c-checkbox>
      <c-checkbox v-model="decrementButton" edit-mode="direct">{{
        english ? "Show decrease" : "显示减少"
      }}</c-checkbox>
      <c-checkbox v-model="press" edit-mode="direct">{{
        english ? "Long press" : "开启长按"
      }}</c-checkbox>
    </c-space>
    <c-input-number
      v-model="value"
      edit-mode="direct"
      mode="button"
      aria-label="数量控制示例"
      :disable-input="disableInput"
      :disable-increment="disableIncrement"
      :disable-decrement="disableDecrement"
      :increment-button="incrementButton"
      :decrement-button="decrementButton"
      :press="press"
      :min="0"
      :max="10"
      @step="(next, direction) => (lastStep = `${direction}: ${next}`)"
    />
    <p role="status">
      {{ english ? "Accepted step" : "已接受的步进" }}：{{ lastStep }}
    </p>
    <h4>
      {{
        english
          ? "Approve, reject or cancel an asynchronous commit"
          : "异步允许、拒绝与取消提交"
      }}
    </h4>
    <p>
      {{
        english
          ? "Step, type or clear the value, then choose an approval result below. Pending operations cannot overlap. External updates and disabling cancel the old request."
          : "加减、输入或清空后，在下方手动选择审批结果。等待时不能重复提交；外部回填或禁用会取消旧请求。"
      }}
    </p>
    <c-input-number
      v-model="approved"
      edit-mode="direct"
      mode="button"
      clearable
      aria-label="异步数量示例"
      :before-commit="beforeCommit"
      loading-mode="line"
      :disabled="blocked"
    />
    <c-space wrap>
      <c-button :disabled="!pending" @click="decision?.(true)">{{
        english ? "Approve" : "允许本次变更"
      }}</c-button>
      <c-button :disabled="!pending" @click="decision?.(false)">{{
        english ? "Reject" : "拒绝本次变更"
      }}</c-button>
      <c-button :disabled="!pending" @click="fail?.()">{{
        english ? "Simulate failure" : "模拟失败"
      }}</c-button>
      <c-button @click="approved = 10">{{
        english ? "Set external value to 10" : "外部回填 10"
      }}</c-button>
      <c-button @click="blocked = !blocked">{{
        blocked
          ? english
            ? "Enable"
            : "恢复可用"
          : english
            ? "Disable"
            : "禁用控件"
      }}</c-button>
    </c-space>
    <p role="status">
      {{ status }}；{{ english ? "Committed value" : "已提交值" }}：{{
        approved ?? "—"
      }}
    </p>
  </div>
</template>
```

### 格式化与插槽

Example source: src/input-number/__demos__/format-slots.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
const value = ref(12);
const formatter = (text: string) => text.replace(/\B(?=(\d{3})+(?!\d))/g, ",");
const parser = (text: string) => text.replace(/,/g, "");
</script>
<template>
  <c-input-number
    v-model="value"
    :formatter="formatter"
    :parser="parser"
    clearable
    mode="button"
  >
    <template #prepend>预算</template>
    <template #prefix>¥</template>
    <template #suffix>元</template>
    <template #append>含税</template>
    <template #plus>＋</template>
    <template #minus>－</template>
    <template #clear-icon="{ clear }"
      ><c-button html-type="button" aria-label="清空金额" @click="clear"
        >×</c-button
      ></template
    >
  </c-input-number>
</template>
```

### 小步长与范围边界

Example source: src/input-number/__demos__/number-boundaries.vue

```vue
<script setup lang="ts">
import { ref } from "vue";

const tiny = ref(0);
const negative = ref<number>();
const bounded = ref(0.1);
const amount = ref(12);
const formatter = (value: string) => "$" + value;
const parser = (value: string) => value.replace(/^\$/, "");
</script>

<template>
  <div class="number-boundaries-demo">
    <label>
      <span>科学计数法步长：1e-7</span>
      <c-input-number v-model="tiny" :step="1e-7" :precision="0" />
      <output>{{ tiny }}</output>
    </label>
    <label>
      <span>空值开始，最大值为 -1</span>
      <c-input-number v-model="negative" :max="-1" clearable />
      <output>{{ negative ?? "空值" }}</output>
    </label>
    <label>
      <span>边界优先：最大值 0.15，精度 1</span>
      <c-input-number
        v-model="bounded"
        :min="0"
        :max="0.15"
        :step="0.1"
        :precision="1"
      />
      <output>{{ bounded }}</output>
    </label>
    <label>
      <span>格式化展示与业务数字分离</span>
      <c-input-number
        v-model="amount"
        :formatter="formatter"
        :parser="parser"
        model-event="input"
      />
      <output>{{ amount }}</output>
    </label>
  </div>
</template>

<style scoped>
.number-boundaries-demo {
  display: flex;
  flex-direction: column;
  gap: 16px;
}
.number-boundaries-demo label {
  display: flex;
  flex-direction: column;
  gap: 6px;
}
.number-boundaries-demo output {
  font-variant-numeric: tabular-nums;
}
</style>
```

### 空值标记与有效的 0

接口用 -1 表示未填写时，同时配置 empty-values 与 empty-value。初始输入框为空而模型仍为 -1；点击“设为 0”后应显示 0；清空再次返回 -1。另一字段清空恢复为 0，演示清空输出不一定代表缺失。

Example source: src/input-number/__demos__/empty-value.vue

```vue
<script setup lang="ts">
import { reactive, ref } from "vue";
const model = reactive({ quantity: -1 as number | null | undefined });
const restored = ref<number | null | undefined>(12);
</script>
<template>
  <c-space direction="column">
    <p>-1 表示未填写，输入框显示空白；0 仍显示为有效数字。清空返回 -1。</p>
    <c-form :model="model" layout="vertical">
      <c-form-item field="quantity" label="数量">
        <c-input-number
          v-model="model.quantity"
          edit-mode="direct"
          clearable
          :empty-values="[null, undefined, -1]"
          :empty-value="-1"
        />
      </c-form-item>
    </c-form>
    <c-space wrap>
      <c-button @click="model.quantity = 0">设为 0</c-button>
      <c-button @click="model.quantity = -1">设为 -1</c-button>
    </c-space>
    <p>
      当前模型: <output>{{ String(model.quantity) }}</output>
    </p>
    <p>此字段清空后恢复为 0，0 仍是有效值，不会显示为空。</p>
    <c-form layout="vertical">
      <c-form-item label="清空恢复有效的 0">
        <c-input-number
          v-model="restored"
          edit-mode="direct"
          clearable
          :empty-value="0"
        />
        <output>{{ String(restored) }}</output>
      </c-form-item>
    </c-form>
  </c-space>
</template>
```

## 交互与表单

### 交互状态切换

<!-- demo-config-notes:start -->

#### 本组配置对照

| 配置        | 作用                          | 相关示例                   |
| ----------- | ----------------------------- | -------------------------- |
| `disabled`  | 禁用；未设置时继承            | 交互状态切换、表单继承     |
| `readonly`  | 只读；允许聚焦复制，禁止改值  | 交互状态切换、表单继承     |
| `clearable` | 允许清空可编辑字段            | 受控值与事件顺序、表单继承 |
| `min`       | 最小值                        | 交互状态切换               |
| `max`       | 最大值                        | 交互状态切换               |
| `error`     | 错误态；未设置时继承 FormItem | 交互状态切换               |

<!-- demo-config-notes:end -->

适用于数量、配额等数值输入。调整禁用、只读、错误反馈，用相同数据观察变化。控制区始终可用，可以随时恢复编辑；错误外观本身不会触发表单校验。

Example source: src/input-number/__demos__/state-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref(3);
const __demoState = __demoReactive({
  disabled: false,
  readonly: false,
  error: false,
});
</script>
<template>
  <c-space direction="column" :size="16">
    <c-space wrap>
      <c-checkbox v-model="__demoState['disabled']">disabled</c-checkbox>
      <c-checkbox v-model="__demoState['readonly']">readonly</c-checkbox>
      <c-checkbox v-model="__demoState['error']">error</c-checkbox>
    </c-space>
    <c-input-number
      v-model="value"
      :min="0"
      :max="10"
      v-bind="__demoState"
    ></c-input-number>
  </c-space>
</template>
```

### 受控值与事件顺序

Example source: src/input-number/__demos__/controlled-events.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const value = ref<number | undefined>(1)
const logs = ref<string[]>([])
function log(name: string, next?: number) {
  logs.value = [name + ': ' + (next ?? '空值'), ...logs.value].slice(0, 6)
}
</script>
<template>
  <div class="number-demo">
    <label>父组件接受更新
      <c-input-number v-model="value" clearable model-event="input" @input="(next: number | undefined) => log('input', next)" @update:model-value="(next: number | undefined) => log('update', next)" @change="(next: number | undefined) => log('change', next)" @clear="() => log('clear')" />
    </label>
    <label>固定受控值，父组件不接受更新
      <c-input-number :model-value="5" @update:model-value="(next: number | undefined) => log('rejected', next)" />
    </label>
    <p>第二个输入框允许编辑草稿，提交后恢复为 5。外部回填不会触发用户 change。</p>
    <ol aria-live="polite"><li v-for="(entry, index) in logs" :key="index">{{ entry }}</li></ol>
  </div>
</template>
<style scoped>
.number-demo, .number-demo label { display: flex; flex-direction: column; gap: 12px; }
</style>
```

### 表单继承

Example source: src/input-number/__demos__/form-inheritance.vue

```vue
<script setup lang="ts">
import { reactive, ref } from "vue";
const model = reactive({ quantity: 2, editable: 3 });
const disabled = ref(false);
const readonly = ref(false);
</script>
<template>
  <div class="number-demo">
    <c-checkbox v-model="disabled">表单禁用</c-checkbox>
    <c-checkbox v-model="readonly">表单只读</c-checkbox>
    <c-form :model="model" :disabled="disabled" :readonly="readonly" size="lg">
      <c-form-item field="quantity" label="继承状态">
        <c-input-number v-model="model.quantity" clearable />
      </c-form-item>
      <c-form-item field="editable" label="显式覆盖">
        <c-input-number
          v-model="model.editable"
          :disabled="false"
          :readonly="false"
          size="sm"
        />
      </c-form-item>
    </c-form>
  </div>
</template>
<style scoped>
.number-demo {
  display: flex;
  flex-direction: column;
  gap: 12px;
}
</style>
```

### 共享字段加载

`loading` 控制共享字段加载状态；`loading-mode` 为 `default`（指示器）或 `line`（底部不定进度线），默认 `default`。渲染统一由 FieldDecorator 负责，不隐式改变 disabled/readonly；需要禁止编辑时单独设置。

## API

### 空值识别与阅读空文案

`empty-values` 用于空值识别，`empty-value` 保留原清空输出；`empty-text` 仅在 `read-pretty` 空内容下展示，默认 `'-'`，字段 > FormItem > Form，自定义 read 插槽优先。显式配置 empty-values 后，内置 required 接入该策略，自定义校验仍收到原值。详见[统一说明](llms/zh-CN/guide/empty-values.md)。

| 参数         | 类型               | 缺省与范围                                            |
| ------------ | ------------------ | ----------------------------------------------------- |
| empty-values | readonly unknown[] | 字段 > FormItem > Form > 组件族默认；完整覆盖，不合并 |
| empty-text   | string             | 字段 > FormItem > Form > '-'；显式 '' 有效            |

以上是字段展示层 API；纯面板不因此新增阅读模式。Form 与 FormItem 提供继承配置。empty-value 的现有类型与默认输出仍按该组件原 API 执行。

### 清空输出

`empty-value` 指定当前组件已有清空动作的输出；省略时采用该组件默认返回。具体类型以组件 API 为准。它不改变 empty-values 的识别规则，也不改变 Form reset 的初始值。

`empty-value` 可显式设为 `null`（或 `() => null`），清空时原样提交 null；省略时保留组件原默认值。界面把 null 显示为空，不会把普通输入的空字符串自动转成 null。支持弹出编辑的字段中，清空先修改草稿，确认后提交，取消则保留原值。

### Props

| 属性          | 说明                                         | 类型                            | 默认值           |
| ------------- | -------------------------------------------- | ------------------------------- | ---------------- |
| model-value   | 受控值；undefined 表示空值/非受控            | `number`                        | —                |
| default-value | 非受控初始值                                 | `number`                        | —                |
| mode          | 步进按钮布局                                 | `embed \| button \| input`      | `embed`          |
| precision     | 小数位数 0–100，不小于 step 的小数位         | `number`                        | —                |
| step          | 正的有限步长，支持科学计数法                 | `number`                        | `1`              |
| disabled      | 禁用；未设置时继承                           | `boolean`                       | 继承，否则 false |
| error         | 错误态；未设置时继承 FormItem                | `boolean`                       | 继承，否则 false |
| max           | 最大值                                       | `number`                        | `Infinity`       |
| min           | 最小值                                       | `number`                        | `-Infinity`      |
| formatter     | 只格式化展示，不改变业务数字                 | `(text: string) => string`      | —                |
| parser        | 每次编辑解析一次原始输入                     | `(text: string) => string`      | —                |
| placeholder   | 输入提示                                     | `string`                        | —                |
| size          | 五档均完整实现，可继承                       | `xs \| sm \| md \| lg \| xl`    | 继承，否则 md    |
| variant       | 字段外观，可继承 InputGroup                  | `outline \| filled \| standard` | `outline`        |
| hint          | 浮动提示，可继承 InputGroup / FieldDecorator | `boolean`                       | 库默认           |
| clearable     | 允许清空可编辑字段                           | `boolean`                       | `false`          |
| model-event   | model 更新时机；change 仍只在提交时触发      | `change \| input`               | `change`         |
| readonly      | 只读；允许聚焦复制，禁止改值                 | `boolean`                       | 继承，否则 false |
| input-attrs   | 原生 input 补充属性                          | `Record<string, unknown>`       | —                |

### Events

| 事件               | 参数                                                       | 说明                                         |
| ------------------ | ---------------------------------------------------------- | -------------------------------------------- |
| input              | `(value: number \| undefined, text: string, event: Event)` | 编辑后解析值与展示文本                       |
| update:model-value | `(value: number \| undefined)`                             | 请求修改业务值                               |
| change             | `(value: number \| undefined, event: Event)`               | 提交、步进或清空                             |
| clear              | `(event: Event)`                                           | 主动清空                                     |
| focus              | `(event: FocusEvent)`                                      | 获取焦点                                     |
| blur               | `(event: FocusEvent)`                                      | 失去焦点                                     |
| keydown            | `(event: KeyboardEvent)`                                   | 原生键盘事件，可 preventDefault 拦截默认操作 |

### Slots

| 插槽             | 参数                                 | 说明           |
| ---------------- | ------------------------------------ | -------------- |
| prefix / suffix  | —                                    | 字段内部前后缀 |
| prepend / append | —                                    | 字段外部标签   |
| plus / minus     | —                                    | 步进按钮图标   |
| clear-icon       | `{ clear: (event?: Event) => void }` | 自定义清除按钮 |

### Methods

| 方法 / 属性 | 类型                               | 说明             |
| ----------- | ---------------------------------- | ---------------- |
| focus       | `(options?: FocusOptions) => void` | 聚焦，禁用时无效 |
| blur        | `() => void`                       | 失焦             |
| select      | `() => void`                       | 选中输入内容     |
| inputRef    | `HTMLInputElement \| undefined`    | 原生输入元素     |

## 类型定义 / Types

```ts
import type {
  InputNumberProps,
  InputNumberInstance,
  InputNumberMode,
  InputNumberModelEvent,
  InputNumberSize,
  InputNumberVariant,
  InputNumberFormatter,
  InputNumberParser,
} from "@cedar-design/ui";
```

## 样式变量

| Token                                              | Default                                |
| -------------------------------------------------- | -------------------------------------- |
| `--c-input-number-step-button-width`               | `var(--c-sys-control-height-md)`       |
| `--c-input-number-step-button-color`               | `var(--c-sys-color-content-secondary)` |
| `--c-input-number-step-button-disabled-color`      | `var(--c-sys-color-content-disabled)`  |
| `--c-input-number-step-button-border-color`        | `var(--c-sys-color-border-subtle)`     |
| `--c-input-number-step-button-background`          | `var(--c-sys-color-surface-muted)`     |
| `--c-input-number-step-button-hover-background`    | `var(--c-sys-color-state-hover)`       |
| `--c-input-number-step-button-active-background`   | `var(--c-sys-color-state-selected)`    |
| `--c-input-number-step-button-icon-size`           | `14px`                                 |
| `--c-input-number-step-button-transition-duration` | `0.2s`                                 |
| `--c-input-number-addon-background`                | `var(--c-sys-color-surface-muted)`     |
| `--c-input-number-addon-color`                     | `var(--c-sys-color-content-primary)`   |
| `--c-input-number-addon-border-color`              | `var(--c-sys-color-border-default)`    |
| `--c-input-number-border-width`                    | `1px`                                  |
| `--c-input-number-border-radius`                   | `var(--c-field-border-radius)`         |
| `--c-input-number-size-xs-step-button-width`       | `var(--c-sys-control-height-xs)`       |
| `--c-input-number-size-sm-step-button-width`       | `var(--c-sys-control-height-sm)`       |
| `--c-input-number-size-md-step-button-width`       | `var(--c-sys-control-height-md)`       |
| `--c-input-number-size-lg-step-button-width`       | `var(--c-sys-control-height-lg)`       |
| `--c-input-number-size-xl-step-button-width`       | `var(--c-sys-control-height-xl)`       |

旧的 `--c-field-number-*` Token 已移除，统一为以上 `--c-input-number-*`；不保留旧别名。字段通用外观继续使用 FieldDecorator 的 `--c-field-*` Token。

### Form 字段展示与确认

本组件支持 `edit-mode`，字段 > FormItem > Form 逐层继承；未指定时为 `direct`，保留原有交互。支持值：`direct / click / dblclick`。非 direct 编辑模式通过字段值入口打开编辑面板，并维护单份草稿；确认后才更新 v-model，取消、重置或启用 readPretty 时丢弃草稿。

Cedar 使用 edit-mode="click" / "dblclick" 在字段附近打开编辑浮层，Enter/F2 也可进入；取消/Escape 丢弃草稿，确认后提交。readPretty 为独立阅读属性，与 readonly、disabled 分开。

`before-commit(value, { previousValue, signal })` 可拦截弹层保存；FormItem 先校验候选值，失败保持编辑。`open / default-open / update:open` 控制编辑层。`#read="{ value, text }"` 可自定义阅读内容。集中示例见 Form 的“各类字段统一展示”。

`read-pretty` 为独立布尔属性，与 `readonly`、`disabled` 同级；字段 > FormItem > Form 继承，显式 `false` 覆盖父级。默认 `false`。纯阅读不显示编辑器。

统一光标色通过 `--c-field-caret-color` 设置（默认 `currentColor`）；本组件可用 `--c-input-number-caret-color` 单独覆盖，默认 `var(--c-field-caret-color)`。

显式 beforeCommit 等待会沿用现有 loadingMode 指示器并设置实际输入的 aria-busy。手动 loading 保持业务所有权，不会隐式只读；beforeCommit 守卫保留已有输入锁定规则。change/step 等通知返回 Promise 不控制等待。

---

Document: llms/zh-CN/components/input-tag.md

<!-- Source: src/input-tag/README.md; locale: zh-CN; page: /components/input-tag/ -->

# InputTag

用来输入标签。

## 阅读方向

标签按阅读顺序排列，标签值的数组顺序保持不变。空输入时 Backspace 删除业务数组中最后一个可关闭标签；Enter 添加标签，输入法组合期间不触发标签提交或删除。

## 基础示例

### 基础用法

标签输入框的基本用法。

Example source: src/input-tag/__demos__/basic.vue

```vue
<template>
  <c-input-tag :default-value="['test']" placeholder="Please Enter" clearable />
</template>
```

## 外观与状态

### 标签输入尺寸与状态

<!-- demo-config-notes:start -->

#### 本组配置对照

| 配置            | 作用                 | 相关示例           |
| --------------- | -------------------- | ------------------ |
| `default-value` | 默认值（非受控状态） | 标签输入尺寸与状态 |
| `placeholder`   | 占位符               | 标签输入尺寸与状态 |
| `size`          | 输入框的大小         | 标签输入尺寸与状态 |
| `clearable`     | 是否允许清空         | 标签输入尺寸与状态 |
| `disabled`      | 是否禁用             | 标签输入尺寸与状态 |
| `readonly`      | 是否为只读模式       | 标签输入尺寸与状态 |

<!-- demo-config-notes:end -->

比较尺寸和禁用/只读/错误外观，操作可编辑实例观察标签布局；空值协议保持独立。

<details>
<summary>配置说明与使用限制</summary>

#### 输入框状态

输入框有禁用、只读和错误三种状态。

#### 输入框尺寸

输入框分为 `xs`、`sm`、`md`、`lg`、`xl` 五种尺寸。

</details>

Example source: src/input-tag/__demos__/appearance-state-comparison.vue

```vue
<script setup lang="ts">
import { ref } from "vue"
import { proxyRefs as demoProxyRefs } from 'vue'

const scene1 = demoProxyRefs((() => {


const size = ref('md')
return { size }
})())
</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="size">
    <h4><span lang="zh-CN">输入框尺寸</span><span lang="en-US">size</span></h4>
    <c-space direction="column" size="lg">
        <c-radio-group type="button" v-model="scene1.size">
          <c-radio value="xs">xs</c-radio>
          <c-radio value="sm">sm</c-radio>
          <c-radio value="md">md</c-radio>
          <c-radio value="lg">lg</c-radio>
          <c-radio value="xl">xl</c-radio>
        </c-radio-group>
        <c-input-tag :default-value="['one']" placeholder="Please enter something" :size="scene1.size" clearable />
      </c-space>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="status">
    <h4><span lang="zh-CN">输入框状态</span><span lang="en-US">status</span></h4>
    <c-space direction="column" size="lg">
        <c-input-tag :default-value="['test']" placeholder="Please Enter" disabled />
        <c-input-tag :default-value="['test']" placeholder="Please Enter" readonly />
        <c-input-tag :default-value="['test']" placeholder="Please Enter" error />
      </c-space>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

## 内容与展示

### 最多展示标签数量

<!-- demo-config-notes:start -->

#### 本组配置对照

| 配置            | 作用                               | 相关示例         |
| --------------- | ---------------------------------- | ---------------- |
| `default-value` | 默认值（非受控状态）               | 最多展示标签数量 |
| `placeholder`   | 占位符                             | 最多展示标签数量 |
| `max-tag-count` | 最多展示的标签个数，`0` 表示不限制 | 最多展示标签数量 |
| `clearable`     | 是否允许清空                       | 最多展示标签数量 |

<!-- demo-config-notes:end -->

设置最多展示标签数量。

Example source: src/input-tag/__demos__/max.vue

```vue
<template>
  <c-input-tag
    :default-value="['one', 'two', 'three', 'four']"
    placeholder="Please Enter"
    :max-tag-count="3"
    clearable
  />
</template>
```

## 加载与等待

### 受控加载

| 属性 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| `loading` | 业务显式控制的加载状态 | `boolean` | `false` |


通过 loading 显式展示等待；普通事件返回值不参与加载。before-* 守卫按其契约管理内部等待状态。

Example source: src/input-tag/__demos__/loading.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const loading = ref(true)
</script>
<template>
  <c-space direction="column" style="width: 100%" :size="16">
    <c-form layout="vertical"><c-form-item label="加载状态 / Loading"><c-switch v-model="loading" /></c-form-item></c-form>
    <c-input-tag :loading="loading" :default-value="['示例 / Example']" />
    <p>通过 loading 显式控制等待展示，普通事件返回 Promise 不会自动加载。Loading is controlled by business state.</p>
  </c-space>
</template>
```

## API

### 空值识别与阅读空文案

`empty-values` 用于空值识别，`empty-value` 保留原清空输出；`empty-text` 仅在 `read-pretty` 空内容下展示，默认 `'-'`，字段 > FormItem > Form，自定义 read 插槽优先。显式配置 empty-values 后，内置 required 接入该策略，自定义校验仍收到原值。详见[统一说明](llms/zh-CN/guide/empty-values.md)。

| 参数         | 类型               | 缺省与范围                                            |
| ------------ | ------------------ | ----------------------------------------------------- |
| empty-values | readonly unknown[] | 字段 > FormItem > Form > 组件族默认；完整覆盖，不合并 |
| empty-text   | string             | 字段 > FormItem > Form > '-'；显式 '' 有效            |

以上是字段展示层 API；纯面板不因此新增阅读模式。Form 与 FormItem 提供继承配置。empty-value 的现有类型与默认输出仍按该组件原 API 执行。

### `<input-tag>` Props

| 参数名                    | 描述                               | 类型                                              |   默认值   |
| ------------------------- | ---------------------------------- | ------------------------------------------------- | :--------: |
| model-value **(v-model)** | 绑定值                             | `(string \| number \| TagData)[]`                 |    `-`     |
| default-value             | 默认值（非受控状态）               | `(string \| number \| TagData)[]`                 |    `[]`    |
| input-value **(v-model)** | 输入框的值                         | `string`                                          |    `-`     |
| default-input-value       | 输入框的默认值（非受控状态）       | `string`                                          |    `''`    |
| placeholder               | 占位符                             | `string`                                          |    `-`     |
| disabled                  | 是否禁用                           | `boolean`                                         |  `false`   |
| error                     | 是否为错误状态                     | `boolean`                                         |  `false`   |
| readonly                  | 是否为只读模式                     | `boolean`                                         |  `false`   |
| clearable                 | 是否允许清空                       | `boolean`                                         |  `false`   |
| size                      | 输入框的大小                       | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'`            |   `'md'`   |
| variant                   | 输入框的变体                       | `'filled' \| 'outline' \| 'standard'`             | `'filled'` |
| max-tag-count             | 最多展示的标签个数，`0` 表示不限制 | `number`                                          |    `0`     |
| retain-input-value        | 是否保留输入框的内容               | `boolean \| { create?: boolean; blur?: boolean }` |  `false`   |
| format-tag                | 格式化标签内容                     | `(data: TagData) => string`                       |    `-`     |
| unique-value              | 是否仅创建唯一的值                 | `boolean`                                         |  `false`   |
| field-names               | 自定义 `TagData` 中的字段          | `InputTagFieldNames`                              |    `-`     |
| tag-nowrap                | 标签内容不换行                     | `boolean`                                         |  `false`   |

### `<input-tag>` Events

| 事件名             | 描述                     | 参数                                                    |
| ------------------ | ------------------------ | ------------------------------------------------------- |
| change             | 值发生改变时触发         | value: `(string \| number \| TagData)[]`<br>ev: `Event` |
| input-value-change | 输入值发生改变时触发     | inputValue: `string`<br>ev: `Event`                     |
| press-enter        | 按下回车键时触发         | inputValue: `string`<br>ev: `KeyboardEvent`             |
| remove             | 点击标签的删除按钮时触发 | removed: `string \| number`<br>ev: `Event`              |
| clear              | 点击清除按钮时触发       | ev: `MouseEvent`                                        |
| focus              | 输入框获取焦点时触发     | ev: `FocusEvent`                                        |
| blur               | 输入框失去焦点时触发     | ev: `FocusEvent`                                        |

### `<input-tag>` Methods

| 方法名 | 描述             | 参数 | 返回值 |
| ------ | ---------------- | ---- | ------ |
| focus  | 使输入框获取焦点 | -    | -      |
| blur   | 使输入框失去焦点 | -    | -      |

### `<input-tag>` Slots

| 插槽名 |         描述         | 参数            |
| ------ | :------------------: | --------------- |
| tag    | 输入框标签的显示内容 | data: `TagData` |
| prefix |       前缀元素       | -               |
| suffix |       后缀元素       | -               |

### TagData

| 参数名   | 描述       | 类型               | 默认值  |
| -------- | ---------- | ------------------ | :-----: |
| value    | 标签值     | `string \| number` |   `-`   |
| label    | 标签内容   | `string`           |   `-`   |
| closable | 是否可关闭 | `boolean`          | `false` |
| tagProps | 标签属性   | `TagProps`         |   `-`   |

### 类型定义

组件导出以下类型定义

```ts
import type { InputTagInstance } from "@cedar-design/ui";
```

## InputTag 旧图标引用收尾

Cedar InputTag 实际嵌入 Tag 的 close-btn，不渲染旧 c-icon-hover 伪元素。本次移除旧 mixin 导入、默认／focus 的伪元素背景规则，以及重复的自定义 Tag 文字规则（文字由 Tag 自身负责）。关闭按钮的现有外观、点击删除和 readonly / disabled 行为不变；没有新增 hover 背景效果。

同步删除两端 tag-custom-icon-bg-hover，以及 Cedar input-tag-tag-remove-icon-color-bg / input-tag-tag-remove-icon-color-bg-focus。旧变量没有替代项，业务中对此的无效覆盖可删除；不保留别名。Maple 没有 InputTag 组件，仅同步清理共享 Tag 变量。

此前的跨组件保留项已关闭。check:token-consumers 现在检查 414 项 Badge / Tag 声明且无豁免，并编译 InputTag 防止旧图标选择器／变量回流；实际 DOM、关闭交互和自定义颜色由 InputTag 集成测试验证。553 项共享默认值数量不变：本次删除的共享变量此前仅登记名称。此阶段仍不代表 InputTag 全部 Token、浏览器视觉或键盘交互已完成治理。

## InputTag 外壳与内容职责

InputTag 的 outline / filled / standard 外壳由 FieldDecorator 管理。Form 不应重新设置其背景、边框或焦点阴影；本次删除了 Form 对旧 InputTag 状态类的重绘规则，保留校验提示职责。filled 的默认／hover／focus 继续走 FieldDecorator 的 fill-1 / fill-2 / fill-3 规则。

InputTag 的内容密度、默认标签底色和禁用文字由 input-tag-* 控制。内容选择器现在匹配实际的 c-field-decorator--size-* / --focus / --disabled 类名，而非不存在的旧 InputTag 状态类；disabled 优先于 focus。五档 xs / sm / md / lg / xl 内容规则均已覆盖；xl 的标签高度为 32px、输入文字为 16px、垂直内边距为 4px。

移除 33 项没有实际 CSS 消费的旧外壳变量：size-{xs,sm,md,lg}-height；color-text-error；color-placeholder、color-icon-clear、color-icon-clear-bg-hover；color-border-{default,error,disabled}（及其 -hover / -focus）；color-bg-{default,error}（及其 -hover / -focus）、color-bg-disabled（及 -hover）；color-shadow-{default,error}-focus、size-shadow-{default,error}-focus；border-radius、border-width、size-icon-clear、size-icon-clear-hover。以上后缀均属于 --c-input-tag-。没有兼容别名。

迁移时按职责选择实际入口：外壳背景用 field-variant-{variant}-background 系列，圆角用 field-border-radius，占位文字用 field-placeholder-text-color，清除图标用 field-clear-icon-color / field-clear-icon-size。几何优先使用 size 属性；不要覆盖 internal 变量。旧无消费变量不存在逐项等价替代；内容标签使用下列 InputTag 自身变量。

InputTag 保留 27 项内容变量，已加入无消费检查；两端 Badge / Tag 加 Cedar InputTag 共检查 441 项声明，内容 size / focus / disabled 级联覆盖 80 组。共享默认值契约仍为 553 项；Cedar-only InputTag 不冒充跨端共享组件。默认文字、禁用文字、标签底色与焦点底色分别引用 content-primary、content-disabled、surface-default、state-hover。禁用状态只重绘中性标签，不覆盖显式 color / status；业务自定义颜色的可读性由业务负责。父级 disabled / readonly 优先于 tagProps.closable / checkable，loading 或显式不可关闭的标签也不能用 Backspace 删除。已完成 Cedar 浏览器五档布局、xl 输入与键盘删除、明暗模式以及禁用自定义色的抽验，不代表全组件视觉验收。

### 当前内容变量

| 变量                                      | 默认值                                |
| ----------------------------------------- | ------------------------------------- |
| `--c-input-tag-size-xs-tag-height`        | `20px`                                |
| `--c-input-tag-size-sm-tag-height`        | `20px`                                |
| `--c-input-tag-size-md-tag-height`        | `24px`                                |
| `--c-input-tag-size-lg-tag-height`        | `28px`                                |
| `--c-input-tag-size-xl-tag-height`        | `32px`                                |
| `--c-input-tag-size-xs-font-size`         | `12px`                                |
| `--c-input-tag-size-sm-font-size`         | `14px`                                |
| `--c-input-tag-size-md-font-size`         | `14px`                                |
| `--c-input-tag-size-lg-font-size`         | `14px`                                |
| `--c-input-tag-size-xl-font-size`         | `16px`                                |
| `--c-input-tag-color-text-default`        | `var(--c-sys-color-content-primary)`  |
| `--c-input-tag-color-text-disabled`       | `var(--c-sys-color-content-disabled)` |
| `--c-input-tag-tag-margin-right`          | `4px`                                 |
| `--c-input-tag-tag-margin-y`              | `2px`                                 |
| `--c-input-tag-padding-x`                 | `4px`                                 |
| `--c-input-tag-size-xs-padding-y`         | `0px`                                 |
| `--c-input-tag-size-sm-padding-y`         | `2px`                                 |
| `--c-input-tag-size-md-padding-y`         | `2px`                                 |
| `--c-input-tag-size-lg-padding-y`         | `2px`                                 |
| `--c-input-tag-size-xl-padding-y`         | `4px`                                 |
| `--c-input-tag-tag-font-size`             | `12px`                                |
| `--c-input-tag-tag-color-bg`              | `var(--c-sys-color-surface-default)`  |
| `--c-input-tag-tag-color-bg-focus`        | `var(--c-sys-color-state-hover)`      |
| `--c-input-tag-tag-color-bg-disabled`     | `var(--c-sys-color-state-hover)`      |
| `--c-input-tag-tag-color-border`          | `var(--c-color-fill-3)`               |
| `--c-input-tag-tag-color-border-disabled` | `var(--c-color-fill-3)`               |
| `--c-input-tag-tag-color-border-focus`    | `var(--c-sys-color-state-hover)`      |

### Form 字段展示与确认

本组件支持 `edit-mode`，字段 > FormItem > Form 逐层继承；未指定时为 `direct`，保留原有交互。支持值：`direct / click / dblclick`。非 direct 编辑模式通过字段值入口打开编辑面板，并维护单份草稿；确认后才更新 v-model，取消、重置或启用 readPretty 时丢弃草稿。

Cedar 使用 edit-mode="click" / "dblclick" 在字段附近打开编辑浮层，Enter/F2 也可进入；取消/Escape 丢弃草稿，确认后提交。readPretty 为独立阅读属性，与 readonly、disabled 分开。

`before-commit(value, { previousValue, signal })` 可拦截弹层保存；FormItem 先校验候选值，失败保持编辑。`open / default-open / update:open` 控制编辑层。`#read="{ value, text }"` 可自定义阅读内容。集中示例见 Form 的“各类字段统一展示”。

`read-pretty` 为独立布尔属性，与 `readonly`、`disabled` 同级；字段 > FormItem > Form 继承，显式 `false` 覆盖父级。默认 `false`。纯阅读不显示编辑器。

## 配置清空后的值

`empty-value` 指定当前组件已有清空动作的输出；省略时采用该组件默认返回。具体类型以组件 API 为准。它不改变 empty-values 的识别规则，也不改变 Form reset 的初始值。

`empty-value` 可显式设为 `null`（或 `() => null`），清空时原样提交 null；省略时保留组件原默认值。界面把 null 显示为空，不会把普通输入的空字符串自动转成 null。支持弹出编辑的字段中，清空先修改草稿，确认后提交，取消则保留原值。

---

Document: llms/zh-CN/components/input.md

<!-- Source: src/input/README.md; locale: zh-CN; page: /components/input/ -->

# Input

基本表单组件，并在原生控件基础上进行了功能扩展，可以组合使用。

默认长度按 UTF-16 码元计算（emoji 通常占 2）；默认截断不会拆开有效的代理对，边界不足时舍去整个字符。若需按用户感知字符（字素簇）计数和裁剪，请配套提供 `word-length` 与 `word-slice`；自定义裁剪结果由业务负责。

## 阅读方向

输入框继承页面或局部容器的 `dir`；前后缀、清除操作和输入框组按阅读顺序排列。运行时切换方向保留原生输入节点、焦点和选区；光标、选区、混合文字与输入法组合由浏览器处理，不交换左右编辑键。父级重绘时保留正在组合的原生文本；旧选区恢复任务不会覆盖新的组合缓冲。

## 基础示例

### 表单控件尺寸对照

切换五档 size 和三种字段变体，比较 Input、Button、Select、日期时间及其他单行表单控件的高度。Button 在这里固定使用 outline。DatePicker/TimePicker 是面板，此处使用带输入框的 Date/Time 字段。示例同时展示有值、可清空、标签删除与长标签多选；Select/Cascader 设置 tag-nowrap 时保持同档高度，长标签文字省略、删除图标保留；标签行可横向滚动，清空按钮和箭头固定在外侧。被省略的标签正文支持悬停、键盘聚焦或点按查看完整文字，点外部或按 Esc 关闭，不改变选中值。可清空后恢复选中值重复比较。多行文本和允许换行的多选内容按内容撑高。

Example source: src/field-decorator/__demos__/control-sizes.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
const sizes = ["xs", "sm", "md", "lg", "xl"] as const;
const variants = ["outline", "filled", "standard"] as const;
const size = ref<(typeof sizes)[number]>("md");
const variant = ref<(typeof variants)[number]>("outline");
const options = [
  { value: "beijing", label: "Beijing" },
  { value: "shanghai", label: "Shanghai" },
];
const cascaderOptions = [{ value: "china", label: "China", children: options }];

const inputValue = ref("Beijing");
const selectValue = ref("beijing");
const cascaderValue = ref("beijing");
const selectMultiple = ref(["beijing", "shanghai"]);
const cascaderMultiple = ref(["beijing", "shanghai"]);
const selectOverflow = ref(["long", "beijing", "shanghai"]);
const cascaderOverflow = ref(["long", "beijing", "shanghai"]);
const selectedOptions = [
  ...options,
  {
    value: "long",
    label:
      "A very long selected option label for overflow comparison — full text preview keeps the selected value unchanged.",
  },
];
const selectedCascaderOptions = [
  { value: "china", label: "China", children: selectedOptions },
];
function resetSelections() {
  inputValue.value = "Beijing";
  selectValue.value = "beijing";
  cascaderValue.value = "beijing";
  selectMultiple.value = ["beijing", "shanghai"];
  cascaderMultiple.value = ["beijing", "shanghai"];
  selectOverflow.value = ["long", "beijing", "shanghai"];
  cascaderOverflow.value = ["long", "beijing", "shanghai"];
}
</script>
<template>
  <section
    aria-label="Form control size comparison"
    class="control-size-comparison"
  >
    <c-space wrap :size="12">
      <c-radio-group v-model="size" aria-label="Comparison size">
        <c-radio v-for="item in sizes" :key="item" :value="item">{{
          item
        }}</c-radio>
      </c-radio-group>
      <c-radio-group v-model="variant" aria-label="Comparison variant">
        <c-radio v-for="item in variants" :key="item" :value="item">{{
          item
        }}</c-radio>
      </c-radio-group>
    </c-space>
    <div class="control-size-comparison__grid">
      <div data-control="Input">
        <p>Input</p>
        <c-input :size="size" :variant="variant" placeholder="Input" />
      </div>
      <div data-control="Button">
        <p>Button</p>
        <c-button :size="size" variant="outline">Button</c-button>
      </div>
      <div data-control="Select">
        <p>Select</p>
        <c-select
          :size="size"
          :variant="variant"
          :options="options"
          placeholder="Select"
        />
      </div>
      <div data-control="Date">
        <p>Date</p>
        <c-date :size="size" :variant="variant" placeholder="Date" />
      </div>
      <div data-control="Time">
        <p>Time</p>
        <c-time :size="size" :variant="variant" placeholder="Time" />
      </div>
      <div data-control="InputNumber">
        <p>InputNumber</p>
        <c-input-number :size="size" :variant="variant" placeholder="Number" />
      </div>
      <div data-control="AutoComplete">
        <p>AutoComplete</p>
        <c-auto-complete
          :size="size"
          :variant="variant"
          :options="options"
          placeholder="AutoComplete"
        />
      </div>
      <div data-control="Cascader">
        <p>Cascader</p>
        <c-cascader
          :size="size"
          :variant="variant"
          :options="cascaderOptions"
          placeholder="Cascader"
        />
      </div>
      <div data-control="DateRange">
        <p>DateRange</p>
        <c-date-range
          :size="size"
          :variant="variant"
          :placeholder="['Start', 'End']"
        />
      </div>
      <div data-control="TimeRange">
        <p>TimeRange</p>
        <c-time-range
          :size="size"
          :variant="variant"
          :placeholder="['Start', 'End']"
        />
      </div>
    </div>

    <section
      aria-label="Selected control size comparison"
      class="control-size-comparison__states"
    >
      <c-space wrap align="center" :size="12">
        <span>Selected / Clearable / Multiple — 有值、可清空与多选不换行</span>
        <span
          >Hover or focus truncated text; tap on touch screens /
          悬停或聚焦省略正文查看全文；触屏点按查看，点外部关闭</span
        >
        <c-button size="sm" variant="outline" @click="resetSelections"
          >Reset / 恢复选中值</c-button
        >
      </c-space>
      <div class="control-size-comparison__grid">
        <div data-control="InputValue">
          <p>Input · clearable</p>
          <c-input
            v-model="inputValue"
            :size="size"
            :variant="variant"
            clearable
            placeholder="Input value"
          />
        </div>
        <div data-control="ButtonReference">
          <p>Button · reference</p>
          <c-button :size="size" variant="outline">Button</c-button>
        </div>
        <div data-control="SelectValue">
          <p>Select · clearable</p>
          <c-select
            v-model="selectValue"
            :size="size"
            :variant="variant"
            :options="selectedOptions"
            clearable
            placeholder="Select value"
          />
        </div>
        <div data-control="CascaderValue">
          <p>Cascader · clearable</p>
          <c-cascader
            v-model="cascaderValue"
            :size="size"
            :variant="variant"
            :options="selectedCascaderOptions"
            clearable
            placeholder="Cascader value"
          />
        </div>
        <div data-control="SelectMultiple">
          <p>Select · multiple / nowrap</p>
          <c-select
            v-model="selectMultiple"
            :size="size"
            :variant="variant"
            :options="selectedOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Select multiple"
          />
        </div>
        <div data-control="CascaderMultiple">
          <p>Cascader · multiple / nowrap</p>
          <c-cascader
            v-model="cascaderMultiple"
            :size="size"
            :variant="variant"
            :options="selectedCascaderOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Cascader multiple"
          />
        </div>
        <div data-control="SelectOverflow">
          <p>Select · long values / nowrap</p>
          <c-select
            v-model="selectOverflow"
            edit-mode="direct"
            :size="size"
            :variant="variant"
            :options="selectedOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Select long values"
          />
        </div>
        <div data-control="CascaderOverflow">
          <p>Cascader · long values / nowrap</p>
          <c-cascader
            v-model="cascaderOverflow"
            edit-mode="direct"
            :size="size"
            :variant="variant"
            :options="selectedCascaderOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Cascader long values"
          />
        </div>
      </div>
    </section>
  </section>
</template>
<style scoped>
.control-size-comparison,
.control-size-comparison__states {
  display: grid;
  gap: 24px;
}
.control-size-comparison__grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
  align-items: start;
  gap: 24px 16px;
}
.control-size-comparison__grid > div {
  min-width: 0;
}
.control-size-comparison__grid p {
  margin: 0 0 12px;
  font-size: 14px;
  line-height: 20px;
}
.control-size-comparison__grid :deep(.c-input-number),
.control-size-comparison__grid :deep(.c-auto-complete) {
  width: 100%;
}
</style>
```

输入框的基本用法。

Example source: src/input/__demos__/basic.vue

```vue
<template>
  <c-space direction="column">
    <c-input placeholder="请输入1" clearable variant="outline" />
    <c-input placeholder="请输入1" clearable variant="filled" />
  </c-space>
</template>
```

## 外观与状态

### 外观配置对比

<!-- demo-config-notes:start -->

#### 本组配置对照

| 配置          | 作用               | 相关示例           |
| ------------- | ------------------ | ------------------ |
| `placeholder` | 提示文字           | 表单反馈、浮动提示 |
| `hint`        | 提示文字是否浮起   | 表单反馈、浮动提示 |
| `clearable`   | 是否允许清空输入框 | 表单反馈、浮动提示 |
| `variant`     | 输入框变体         | 浮动提示           |

<!-- demo-config-notes:end -->

选择一个对比维度后，同屏展示它的全部可选值；其余配置和内容保持一致。可切换其他配置检查组合效果；输入类预览共享一个值。

<details>
<summary>配置说明与使用限制</summary>

#### 变体

设置 `variant` 来调整不同风格的输入框。
可选值为 `filled`、`outline` 和 `standard`。

#### 尺寸

输入框完整支持五种尺寸 `xs / sm / md / lg / xl`，默认 `md`。

#### 外观组合

适用于表单中的单行文本输入。调整变体、尺寸，用相同数据观察变化。内容保持一致，便于比较不同设置的实际效果。

</details>

Example source: src/input/__demos__/appearance-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref("示例内容");
const __demoAppearance = __demoReactive({ variant: "filled", size: "md" });

import { computed as demoComputed, ref as demoRef } from 'vue'
const demoCompareFields = [{"name":"variant","values":["filled","outline","standard"]},{"name":"size","values":["xs","sm","md","lg","xl"]}]
const demoCompareAxis = demoRef("variant")
const demoComparedOptions = demoComputed(() => demoCompareFields.find(field => field.name === demoCompareAxis.value)?.values ?? [])
</script>
<template>
  <c-space direction="column" :size="16">
    <c-form layout="vertical">
      <c-form-item layout="vertical" size="sm" label="variant">
        <c-radio-group
          v-model="__demoAppearance['variant']"
          aria-label="variant"
          :options="[
            { label: 'filled', value: 'filled' },
            { label: 'outline', value: 'outline' },
            { label: 'standard', value: 'standard' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
      <c-form-item layout="vertical" size="sm" label="size">
        <c-radio-group
          v-model="__demoAppearance['size']"
          aria-label="size"
          :options="[
            { label: 'xs', value: 'xs' },
            { label: 'sm', value: 'sm' },
            { label: 'md', value: 'md' },
            { label: 'lg', value: 'lg' },
            { label: 'xl', value: 'xl' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
    </c-form>
    <p class="demo-config-comparison-hint"><span lang="zh-CN">选择一个对比维度；其他配置和内容保持一致。输入类示例共享同一个值，便于比较外观。</span><span lang="en-US">Compare one dimension while keeping the other settings and content identical. Input specimens share the same value.</span></p>
<c-radio-group v-model="demoCompareAxis" aria-label="Compare configuration" :options="demoCompareFields.map(field => ({ label: field.name, value: field.name }))" />
<div class="demo-config-comparison">
<section v-for="sample in demoComparedOptions" :key="String(sample)">
<p><code>{{ demoCompareAxis }}={{ sample }}</code></p>
<c-input v-model="value" v-bind="{ ...__demoAppearance, [demoCompareAxis]: sample }"></c-input>
</section>
</div>
  </c-space>
</template>

<style scoped>
.demo-config-comparison { display: grid; grid-template-columns: repeat(auto-fit, minmax(min(100%, 220px), 1fr)); gap: 20px; min-width: 0; max-width: 100%; }
.demo-config-comparison > section { min-width: 0; }
.demo-config-comparison p { margin: 0 0 8px; }
html:not([lang='en-US']) .demo-config-comparison-hint > [lang='en-US'],
html[lang='en-US'] .demo-config-comparison-hint > [lang='zh-CN'] { display: none; }
</style>
```

### 表单反馈

通过 FormItem 的 `feedback` 和 `validate-status` 展示校验反馈。有外置 FormItem 标签时，Input 自动关闭内部浮动提示，避免重复标签。

Example source: src/input/__demos__/form-feedback.vue

```vue
<template>
  <c-form :model="model">
    <c-form-item field="account" label="账户" feedback :validate-status="status" :help="status === 'error' ? '请输入账户后重试' : undefined">
      <c-input v-model="model.account" placeholder="外置标签会关闭内部浮动提示" hint clearable />
    </c-form-item>
    <c-button status="primary" :loading="status === 'validating'" @click="validate">模拟异步校验</c-button>
  </c-form>
</template>

<script setup lang="ts">
import { reactive, ref } from 'vue'

const model = reactive({ account: '' })
const status = ref<'validating' | 'success' | 'error'>()
let request = 0
async function validate() {
  const current = ++request
  const value = model.account
  status.value = 'validating'
  await new Promise((resolve) => setTimeout(resolve, 500))
  if (current === request) status.value = value.trim() ? 'success' : 'error'
}
</script>
```

### 浮动提示

设置 `hint` 后，提示文字作为关联原生输入框的标签，在聚焦或输入非空值时浮起；`line` 控制描边或底线是否显示。桌面端默认不启用浮动提示，仍可使用普通 `placeholder`；移动端默认启用。`text-color`、`focus-color`、`blur-color` 可覆盖文字与提示颜色。

Example source: src/input/__demos__/floating-hint.vue

```vue
<template>
  <c-space direction="column" style="width: 100%">
    <c-input v-model="name" hint placeholder="姓名" clearable />
    <c-input v-model="email" hint variant="standard" placeholder="邮箱" />
    <c-input v-model="phone" hint placeholder="带前缀的电话" clearable><template #prefix>+86</template></c-input>
  </c-space>
</template>

<script setup lang="ts">
import { ref } from 'vue'

const name = ref('')
const email = ref('')
const phone = ref('')
</script>
```

## 输入内容与布局

### 数字统计

<!-- demo-config-notes:start -->

#### 本组配置对照

| 配置              | 作用                                                       | 相关示例                           |
| ----------------- | ---------------------------------------------------------- | ---------------------------------- |
| `placeholder`     | 提示文字                                                   | 数字统计、前缀、后缀、输入框组合   |
| `clearable`       | 是否允许清空输入框                                         | 数字统计、前缀、后缀、组合状态继承 |
| `max-length`      | 输入值的最大长度                                           | 数字统计                           |
| `show-word-limit` | 是否显示字数统计                                           | 数字统计                           |
| `default-value`   | 非受控初始值，仅创建时读取；后续修改不重置输入，不回写父级 | 组合状态继承                       |
| `disabled`        | 是否禁用，可继承 Form                                      | 组合状态继承                       |

<!-- demo-config-notes:end -->

设置 max-length 可以限制最大字数，配合 show-word-limit 可以显示字数统计。
超出长度时会截断，并通过 `update:model-value` 与 `input` 传出截断后的值。清空按 `clear → input → update:model-value → change` 通知，随后失焦不会补发 `change`。

Example source: src/input/__demos__/word-limit.vue

```vue
<template>
  <c-space direction="column">
    <c-input v-model="normalValue" :max-length="10" clearable show-word-limit placeholder="超出后截断" />
    <c-input
      v-model="errorOnlyValue"
      :max-length="{ length: 6, errorOnly: true }"
      show-word-limit
      placeholder="允许超出，但标记错误"
    />
  </c-space>
</template>

<script setup lang="ts">
import { ref } from 'vue'

const normalValue = ref('Cedar')
const errorOnlyValue = ref('超过六个字符后显示错误')
</script>
```

### 密码输入框

用于输入密码。

Example source: src/input/__demos__/password.vue

```vue
<template>
  <c-space direction="column">
    <c-input-password />
  </c-space>
</template>
```

### 前缀、后缀

通过指定 prefix 和 suffix 插槽来在输入框内添加前缀和后缀。

Example source: src/input/__demos__/prefix.vue

```vue
<template>
  <c-space direction="column">
    <c-input :style="{ width: '320px' }" placeholder="请输入">
      <template #prefix> +86 </template>
    </c-input>
    <c-input :style="{ width: '320px' }" placeholder="请输入">
      <template #suffix> RMB </template>
    </c-input>
    <c-input
      v-model="clearableValue"
      :style="{ width: '320px' }"
      clearable
      placeholder="自定义清除图标"
    >
      <template #clear-icon="{ clear }">
        <c-button
          html-type="button"
          class="prefix-demo__clear"
          aria-label="清空"
          @click="clear"
          >清空</c-button
        >
      </template>
    </c-input>
  </c-space>
</template>

<script setup lang="ts">
import { ref } from "vue";

const clearableValue = ref("Cedar");
</script>

<style scoped>
.prefix-demo__clear {
  border: 0;
  background: transparent;
  color: var(--color-text-2);
  cursor: pointer;
  font-size: 12px;
}
</style>
```

### 输入框组合

通过 input-group 可以组合使用输入框。

Example source: src/input/__demos__/group.vue

```vue
<template>
  <c-space direction="column">
    <c-radio-group v-model="variant">
      <c-radio value="filled">filled</c-radio>
      <c-radio value="outline">outline</c-radio>
      <c-radio value="standard">standard</c-radio>
    </c-radio-group>
    <c-input-group :variant="variant">
      <c-input :style="{ width: '160px' }" placeholder="first" />
      <c-input :style="{ width: '320px' }" placeholder="second" />
    </c-input-group>
    <c-input-group :variant="variant">
      <c-select :options="['Option1', 'Option2', 'Option3']" :style="{ width: '160px' }" placeholder="first" />
      <c-input :style="{ width: '320px' }" placeholder="second" />
    </c-input-group>

    <c-input-group :variant="variant">
      <c-select :options="['Option1', 'Option2', 'Option3']" :style="{ width: '160px' }" placeholder="first" />
      <c-auto-complete :style="{ width: '320px' }" placeholder="second" />
    </c-input-group>
    <c-input-group :variant="variant">
      <c-input-group-label>text</c-input-group-label>
      <c-input :style="{ width: '320px' }" placeholder="second" />
      <c-button status="primary">label</c-button>
    </c-input-group>
  </c-space>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
const variant = ref('filled')
</script>
```

### 组合状态继承

`InputGroup` 统一传递 `size / variant / disabled / readonly / hint`；子项显式设置的值（包括 `false`）优先。`InputPassword` 和清除按钮同样遵循继承后的状态。

Example source: src/input/__demos__/group-state.vue

```vue
<template>
  <c-space direction="column" style="width: 100%">
    <c-space>
      <c-button variant="outline" @click="disabled = !disabled">{{ disabled ? '启用组合' : '禁用组合' }}</c-button>
      <c-button variant="outline" @click="readonly = !readonly">{{ readonly ? '允许编辑' : '组合只读' }}</c-button>
    </c-space>
    <c-input-group variant="outline" :disabled="disabled" :readonly="readonly" :hint="false">
      <c-input-group-label>https://</c-input-group-label>
      <c-input v-model="domain" placeholder="输入域名" clearable />
      <c-input-group-label>.com</c-input-group-label>
    </c-input-group>
    <c-input-group variant="filled" :disabled="disabled" :readonly="readonly" :hint="false">
      <c-input v-model="first" placeholder="继承组合状态" clearable />
      <c-input default-value="可独立编辑" :disabled="false" :readonly="false" clearable />
    </c-input-group>
    <c-input-group size="lg" variant="outline" :disabled="disabled" :readonly="readonly" :hint="false">
      <c-input-group-label>密码</c-input-group-label>
      <c-input-password v-model="password" placeholder="密码切换继承禁用状态" clearable />
    </c-input-group>
  </c-space>
</template>

<script setup lang="ts">
import { ref } from 'vue'

const disabled = ref(false)
const readonly = ref(false)
const domain = ref('example')
const first = ref('继承状态')
const password = ref('CedarMaple')
</script>
```

## 值模型与交互

### 默认值与双向绑定

<!-- demo-config-notes:start -->

#### 本组配置对照

| 配置            | 作用                                                       | 相关示例                           |
| --------------- | ---------------------------------------------------------- | ---------------------------------- |
| `clearable`     | 是否允许清空输入框                                         | 主体与事件契约、清空按钮与手动删空 |
| `default-value` | 非受控初始值，仅创建时读取；后续修改不重置输入，不回写父级 | 默认值与双向绑定                   |
| `aria-label`    | 原生输入框的无障碍标签                                     | 默认值与双向绑定                   |
| `disabled`      | 是否禁用，可继承 Form                                      | 交互状态对比                       |
| `readonly`      | 是否只读，可继承 Form                                      | 交互状态对比                       |
| `error`         | 是否为错误状态，可继承 FormItem                            | 交互状态对比                       |

<!-- demo-config-notes:end -->

`modelValue` 是受控值，通过普通 `v-model` 绑定；父级提供的值优先，包括空字符串。`defaultValue` 是非受控初始值，仅在组件创建时读取；之后由组件内部保存用户输入。修改 `defaultValue` 不会重置现有文字，重新挂载才会重新读取，也不会在初始化时触发 `update:modelValue` 或写入父级表单。

需要表单默认值时，直接初始化绑定字段，例如 `const text = ref('北京')`，然后使用 `<c-input v-model="text" />`。

Example source: src/input/__demos__/default-value.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'

withDefaults(defineProps<{ english?: boolean }>(), { english: false })
const seed = ref('A: initial text')
const instanceKey = ref(0)
const lastUpdate = ref<string | null>(null)
const updateCount = ref(0)
const controlled = ref('')
function record(value: string) {
  lastUpdate.value = value
  updateCount.value += 1
}
function remount() {
  instanceKey.value += 1
  lastUpdate.value = null
  updateCount.value = 0
}
</script>

<template>
  <div>
    <p>
      {{
        english
          ? '1. Uncontrolled: defaultValue supplies the initial text. Typing updates the component itself; the seed below stays unchanged.'
          : '1. 非受控：defaultValue 提供初始文字。输入后由组件自己保存新值，下方的默认值变量不会随之变化。'
      }}
    </p>
    <c-input :key="instanceKey" :default-value="seed" aria-label="Uncontrolled input" @update:model-value="record" />
    <p>
      defaultValue = <code>{{ seed }}</code>
    </p>
    <p role="status">
      update:modelValue × {{ updateCount }}; {{ english ? 'last emitted value' : '最近一次用户更新' }} =
      <code>{{ lastUpdate === null ? (english ? '(none)' : '（尚未触发）') : JSON.stringify(lastUpdate) }}</code>
    </p>
    <c-space wrap>
      <c-button @click="seed = seed.startsWith('A:') ? 'B: new default' : 'A: initial text'">{{
        english ? 'Change defaultValue only' : '仅修改 defaultValue'
      }}</c-button>
      <c-button @click="remount">{{ english ? 'Remount input' : '重新挂载输入框' }}</c-button>
    </c-space>
    <p>
      {{
        english
          ? 'Try typing, then change defaultValue: the current text stays. Remount to read the latest defaultValue. Initialization never emits update:modelValue.'
          : '操作顺序：先输入，再修改 defaultValue，当前文字不会被覆盖；点击重新挂载后，才读取最新的默认值。初始化不会触发 update:modelValue。'
      }}
    </p>
    <p>
      {{
        english
          ? '2. Controlled: v-model is the source of truth. Its initial empty string takes precedence over defaultValue.'
          : '2. 受控：v-model 是数据来源。这里初始值为空字符串，仍优先于 defaultValue，不会自动填入默认文字。'
      }}
    </p>
    <c-input v-model="controlled" default-value="This default is ignored" aria-label="Controlled input" />
    <p role="status">
      v-model = <code>{{ JSON.stringify(controlled) }}</code>
    </p>
    <c-space wrap>
      <c-button @click="controlled = 'Parent supplied text'">{{
        english ? 'Update parent value' : '从父级设置值'
      }}</c-button>
      <c-button @click="controlled = ''">{{ english ? 'Clear parent value' : '清空父级值' }}</c-button>
    </c-space>
    <p>
      {{
        english
          ? 'For a form, initialize the bound field in the parent. defaultValue does not write an initial value into the parent form.'
          : '表单需要初始值时，请初始化父级绑定字段。defaultValue 不会把初始值写入父级表单。'
      }}
    </p>
  </div>
</template>
```

### 清空按钮与手动删空

将清空输出设为 null。先点击清空图标，观察模型为 null；恢复初值后用 Backspace 删光，观察模型为空字符串。普通输入不会自动套用 empty-value。

Example source: src/input/__demos__/empty-value.vue

```vue
<script setup lang="ts">
import { reactive } from "vue";
const model = reactive({ text: "Hello" as string | null });
</script>
<template>
  <c-space direction="column">
    <p>点击清空图标得到 null；用 Backspace 删光得到空字符串。</p>
    <c-form :model="model" layout="vertical">
      <c-form-item field="text" label="关键词">
        <c-input
          v-model="model.text"
          edit-mode="direct"
          clearable
          :empty-value="null"
        />
      </c-form-item>
    </c-form>
    <c-button @click="model.text = 'Hello'">恢复初值</c-button>
    <p>
      当前模型: <output>{{ JSON.stringify(model.text) }}</output>
    </p>
  </c-space>
</template>
```

### 交互状态对比

在同一实例上切换禁用、只读和错误状态后再操作控件，比较可编辑性和交互反馈。恢复开关位于目标控件外；错误外观本身不会执行校验。

<details>
<summary>配置说明与使用限制</summary>

#### 状态

输入框可以设置禁用和错误状态。

#### 交互状态切换

适用于表单中的单行文本输入。调整禁用、只读、错误反馈，用相同数据观察变化。控制区始终可用，可以随时恢复编辑；错误外观本身不会触发表单校验。

</details>

Example source: src/input/__demos__/state-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref("示例内容");
const __demoState = __demoReactive({
  disabled: false,
  readonly: false,
  error: false,
});
</script>
<template>
  <c-space direction="column" :size="16">
    <c-space wrap>
      <c-checkbox v-model="__demoState['disabled']">disabled</c-checkbox>
      <c-checkbox v-model="__demoState['readonly']">readonly</c-checkbox>
      <c-checkbox v-model="__demoState['error']">error</c-checkbox>
    </c-space>
    <c-input v-model="value" v-bind="__demoState"></c-input>
  </c-space>
</template>
```

### 主体与事件契约

两端维护独立复制的主体。输入按 input → update:modelValue 通知；清空按 clear → input → update:modelValue → change 通知，各一次，Form 对应语义也各接收一次。只读、禁用和组合输入期间禁止清空。受控提议被拒绝后恢复原生内容，包括不支持光标 API 的输入类型。

Example source: src/input/__demos__/event-pipeline.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const value = ref('可编辑内容')
const events = ref<string[]>([])
const record = (name: string) => { events.value = [...events.value.slice(-7), name] }
</script>
<template>
  <div class="input-pipeline-demo">
    <c-input v-model="value" clearable placeholder="输入后尝试清空" @clear="record('clear')" @input="record('input')" @update:model-value="record('update:modelValue')" @change="record('change')" />
    <p>输入：input → update；清空：clear → input → update → change。</p>
    <output>{{ events.join(' → ') || '等待操作' }}</output>
  </div>
</template>
<style scoped>
.input-pipeline-demo { display: flex; flex-direction: column; gap: 12px; }
.input-pipeline-demo p { margin: 0; }
</style>
```

### 提交前确认

字段提交也支持 `beforeCommit({ value, previousValue }, done, context)`：保留第二个 context 参数，第三个 done 可决定允许或拒绝；Promise 和 boolean 写法继续支持。声明 done 的回调必须调用完成函数，或返回 boolean/Promise。

守卫统一使用 `(payload, done, context)`：关闭 payload 为 `{ action }`，切换和提交为 `{ value, previousValue }`，Popup 为 `{ reason }`。context 提供 `signal` 和可选原始 `event`。返回 boolean/Promise，或调用 done()/done(false)；同步 void 等待 done，Promise&lt;void&gt; 放行。首次完成生效。等待期间自动管理 loading/disabled，取消后旧结果失效，不暴露内部按钮 refs。

Example source: src/input/__demos__/commit-protocol.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
const value = ref<string | null>("Project A");
const message = ref("");
async function beforeCommit(
  { value: next, previousValue }: { value: unknown; previousValue: unknown },
  _done: (allow?: boolean) => void,
  { signal }: { signal: AbortSignal },
) {
  if (next === previousValue) return true;
  await new Promise((resolve) => setTimeout(resolve, 500));
  if (signal.aborted) return false;
  message.value = `已保存: ${String(next)}`;
  return true;
}
</script>
<template>
  <c-space direction="column">
    <c-input
      v-model="value"
      edit-mode="click"
      clearable
      :empty-value="null"
      :before-commit="beforeCommit"
    />
    <p role="status">{{ message }}</p>
  </c-space>
</template>
```

### 共享字段加载

`loading` 控制共享字段加载状态；`loading-mode` 为 `default`（指示器）或 `line`（底部不定进度线），默认 `default`。渲染统一由 FieldDecorator 负责，不隐式改变 disabled/readonly；需要禁止编辑时单独设置。

## 加载与等待

### 加载状态

切换加载状态，对比默认指示器与底部加载线。加载期间仍可编辑输入；是否禁止编辑由 disabled / readonly 单独控制。

Example source: src/input/__demos__/loading.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const busy = ref(true)
const value = ref('加载时仍可编辑')
</script>
<template>
  <c-space direction="column" :size="16" style="width: 100%">
    <c-form layout="vertical">
      <c-form-item label="加载状态 / Loading"><c-switch v-model="busy" /></c-form-item>
      <c-form-item label="默认指示器 / Default"><c-input v-model="value" :loading="busy" placeholder="加载时仍可编辑 / Editable while loading" loading-mode="default" /></c-form-item>
      <c-form-item label="底部加载线 / Line"><c-input v-model="value" :loading="busy" placeholder="加载时仍可编辑 / Editable while loading" loading-mode="line" /></c-form-item>
    </c-form>
    <p>切换加载状态；加载时仍可输入和清空。Loading keeps the input editable.</p>
  </c-space>
</template>
```

## API

### 空值识别与阅读空文案

`empty-values` 用于空值识别，`empty-value` 保留原清空输出；`empty-text` 仅在 `read-pretty` 空内容下展示，默认 `'-'`，字段 > FormItem > Form，自定义 read 插槽优先。显式配置 empty-values 后，内置 required 接入该策略，自定义校验仍收到原值。详见[统一说明](llms/zh-CN/guide/empty-values.md)。

| 参数         | 类型               | 缺省与范围                                            |
| ------------ | ------------------ | ----------------------------------------------------- |
| empty-values | readonly unknown[] | 字段 > FormItem > Form > 组件族默认；完整覆盖，不合并 |
| empty-text   | string             | 字段 > FormItem > Form > '-'；显式 '' 有效            |

以上是字段展示层 API；纯面板不因此新增阅读模式。Form 与 FormItem 提供继承配置。empty-value 的现有类型与默认输出仍按该组件原 API 执行。

### `<Input>` Props

| 参数名                    | 描述                                                       | 类型                                                |   默认值    |
| ------------------------- | ---------------------------------------------------------- | --------------------------------------------------- | :---------: |
| model-value **(v-model)** | 绑定值                                                     | `string \| null`                                    |     `-`     |
| `loading` | 加载展示；不隐式禁用输入 | `boolean` | `false` |
| `loading-mode` | 加载布局：默认指示器或底部加载线 | `default / line` | `default` |
| model-modifiers           | `v-model` 修饰符，支持 `trim`                              | `{ trim?: boolean }`                                |    `{}`     |
| default-value             | 非受控初始值，仅创建时读取；后续修改不重置输入，不回写父级 | `string`                                            |    `''`     |
| variant                   | 输入框变体                                                 | `'filled' \| 'outline' \| 'standard'`               | `'outline'` |
| size                      | 输入框大小                                                 | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'`              |   `'md'`    |
| clearable                 | 是否允许清空输入框                                         | `boolean`                                           |   `false`   |
| empty-value               | 清空输出；省略时清空返回空字符串，不影响手动删除           | `string \| null \| (() => string \| null)`          | `undefined` |
| disabled                  | 是否禁用，可继承 Form                                      | `boolean`                                           |     `-`     |
| readonly                  | 是否只读，可继承 Form                                      | `boolean`                                           |     `-`     |
| error                     | 是否为错误状态，可继承 FormItem                            | `boolean`                                           |     `-`     |
| placeholder               | 提示文字                                                   | `string`                                            |     `-`     |
| hint                      | 提示文字是否浮起                                           | `boolean`                                           |   `false`   |
| line                      | 是否绘制边框或底线                                         | `boolean`                                           |   `true`    |
| text-color                | 输入文字颜色                                               | `string`                                            |     `-`     |
| focus-color               | 聚焦提示及支持的边框通道；不控制 caret                     | `string`                                            |     `-`     |
| blur-color                | 未聚焦时提示颜色                                           | `string`                                            |     `-`     |
| aria-label                | 原生输入框的无障碍标签                                     | `string`                                            |     `-`     |
| autofocus                 | 是否自动聚焦                                               | `boolean`                                           |   `false`   |
| enterkeyhint              | 移动端虚拟键盘回车键提示                                   | `string`                                            |     `-`     |
| max-length                | 输入值的最大长度                                           | `number \| { length: number; errorOnly?: boolean }` |     `0`     |
| show-word-limit           | 是否显示字数统计                                           | `boolean`                                           |   `false`   |
| word-length               | 字符长度的计算方法                                         | `(value: string) => number`                         |     `-`     |
| word-slice                | 字符截取方法，同 wordLength 一起使用                       | `(value: string, maxLength: number) => string`      |     `-`     |
| input-attrs               | 内部 input 元素的属性                                      | `object`                                            |     `-`     |

`disabled / readonly / size` 按子项 → InputGroup → FormItem/Form → 库默认值继承；Cedar 的尺寸还支持 ConfigProvider。`clearable` 只对非空且可编辑的输入生效：PC 在悬浮或焦点进入时显示，触控设备与 Maple 常驻显示。原生 `name / id / aria-* / data-*` 会透传给 input；`class / style` 留在外壳，`input-attrs` 不能覆盖受控值、类型、禁用、只读和长度策略。

### `<Input>` Events

| 事件名      | 描述                       | 参数                           |
| ----------- | -------------------------- | ------------------------------ |
| input       | 用户输入时触发             | value: `string`<br>ev: `Event` |
| change      | 失焦、回车提交或清空时触发 | value: `string`<br>ev: `Event` |
| press-enter | 用户按下回车时触发         | ev: `KeyboardEvent`            |
| clear       | 用户点击清除按钮时触发     | ev: `MouseEvent`               |
| focus       | 输入框获取焦点时触发       | ev: `FocusEvent`               |
| blur        | 输入框失去焦点时触发       | ev: `FocusEvent`               |

### `<Input>` Methods

| 方法名 | 描述             | 参数 | 返回值 |
| ------ | ---------------- | ---- | ------ |
| focus  | 使输入框获取焦点 | -    | -      |
| blur   | 使输入框失去焦点 | -    | -      |
| select | 选中输入内容     | -    | -      |

### `<input>` Slots

| 插槽名     |      描述      | 参数                   |
| ---------- | :------------: | ---------------------- |
| suffix     |    后缀元素    | -                      |
| prefix     |    前缀元素    | -                      |
| clear-icon | 自定义清除按钮 | `clear(event?: Event)` |

### `<InputPassword>` Props

| 参数名             | 描述                                    | 类型      | 默认值  |
| ------------------ | --------------------------------------- | --------- | :-----: |
| visibility-toggle  | 是否显示密码可见性按钮                  | `boolean` | `true`  |
| default-visibility | 默认是否可见，非受控                    | `boolean` | `false` |
| visibility         | 受控密码可见性，支持 v-model:visibility | `boolean` |   `-`   |

InputPassword 支持所有 Input 属性、事件、插槽与方法。

### `<InputGroup>` Props

| 参数名   | 描述         | 类型                            | 默认值                           |
| -------- | ------------ | ------------------------------- | -------------------------------- |
| size     | 组内默认尺寸 | `ComponentSize`                 | 继承 Form/ConfigProvider 或 `md` |
| variant  | 组内默认变体 | `filled \| outline \| standard` | `filled`                         |
| disabled | 组内禁用状态 | `boolean`                       | 继承 Form 或 `false`             |
| readonly | 组内只读状态 | `boolean`                       | 继承 Form 或 `false`             |
| hint     | 组内浮动提示 | `boolean`                       | 库默认值                         |

### `<InputPassword>` Events

| 参数名            | 描述                 | 参数              |
| ----------------- | -------------------- | ----------------- |
| visibility-change | visibility改变时触发 | `visible:boolean` |

## 类型定义

组件导出以下类型定义

```ts
import type { InputProps } from "@cedar-design/ui";
```

公开类型 / Public types: `InputEmits`, `InputSlots`, `InputExpose`, `InputGroupSlots`, `InputPasswordEmits`, `InputPasswordSlots`, `InputPasswordExpose`.

### 表单展示继承

支持 `edit-mode`：`direct / click / dblclick`。未设置时继承 FormItem/Form，独立使用时默认 direct；readPretty 以纯文本阅读，编辑浮层默认确认后更新 v-model。可选 before-commit 在候选校验通过后拦截保存。使用方式与对比 Demo 统一见 Form 文档。

### 输入光标主题

| CSS 变量                | 默认值         | 说明                             |
| ----------------------- | -------------- | -------------------------------- |
| `--c-input-caret-color` | `currentColor` | 输入光标颜色，可独立于文字色覆盖 |

统一光标色通过 `--c-field-caret-color` 设置（默认 `currentColor`）；本组件可用 `--c-input-caret-color` 单独覆盖，默认 `var(--c-field-caret-color)`。

---

Document: llms/zh-CN/components/layout.md

<!-- Source: src/layout/README.md; locale: zh-CN; page: /components/layout/ -->

# Layout

页面的基础布局框架，常与组件嵌套使用，构建页面整体布局。

## 基础示例

### 基本用法

典型的页面布局

Example source: src/layout/__demos__/basic.vue

```vue
<template>
  <c-layout style="height: 300px">
    <c-layout-header class="layout-header">Header</c-layout-header>
    <c-layout-content class="layout-content">Content</c-layout-content>
    <c-layout-footer class="layout-footer">Footer</c-layout-footer>
  </c-layout>
  <br />
  <c-layout style="height: 300px">
    <c-layout-header class="layout-header">Header</c-layout-header>
    <c-layout>
      <c-layout-sider class="layout-sider">Sider</c-layout-sider>
      <c-layout-content class="layout-content">Content</c-layout-content>
    </c-layout>
    <c-layout-footer class="layout-footer">Footer</c-layout-footer>
  </c-layout>
  <br />
  <c-layout style="height: 300px">
    <c-layout-header class="layout-header">Header</c-layout-header>
    <c-layout>
      <c-layout-content class="layout-content">Content</c-layout-content>
      <c-layout-sider class="layout-sider">Sider</c-layout-sider>
    </c-layout>
    <c-layout-footer class="layout-footer">Footer</c-layout-footer>
  </c-layout>
  <br />
  <c-layout style="height: 300px">
    <c-layout-header class="layout-header">Header</c-layout-header>
    <c-layout>
      <c-layout-sider class="layout-sider" style="width: 64px">Sider</c-layout-sider>
      <c-layout-sider class="layout-sider" style="width: 206px; margin-left: 1px">Sider </c-layout-sider>
      <c-layout-content class="layout-content">Content</c-layout-content>
    </c-layout>
    <c-layout-footer class="layout-footer">Footer</c-layout-footer>
  </c-layout>
</template>

<style scoped lang="less">
.layout-header {
  height: 100px;
  display: flex;
  justify-content: center;
  align-items: center;
  background-color: var(--c-color-primary-light-3);
  color: var(--c-color-text-1);
}

.layout-content {
  height: 100px;
  display: flex;
  justify-content: center;
  align-items: center;
  background-color: var(--c-color-primary-light-4);
  color: var(--c-color-text-1);
}

.layout-sider {
  min-height: 100px;
  background-color: var(--c-color-primary);

  :deep(.c-layout-sider-children) {
    display: flex;
    justify-content: center;
    align-items: center;
    color: var(--c-color-text-1);
  }
}

.layout-footer {
  height: 100px;
  display: flex;
  justify-content: center;
  align-items: center;
  background-color: var(--c-color-primary);
  color: var(--c-color-text-1);
}
</style>
```

## 布局与排列

### 固定头尾与独立滚动

设置容器高度，对内容区域开启 `scrollable`。`scrollTo` 支持坐标和原生滚动选项。

Example source: src/layout/__demos__/scroll.vue

```vue
<template>
  <c-layout class="scroll-layout">
    <c-layout-header bordered class="bar">
      固定头部
      <c-button
        size="sm"
        @click="content?.scrollTo({ top: 0, behavior: 'smooth' })"
        >回到顶部</c-button
      >
    </c-layout-header>
    <c-layout-content ref="content" scrollable @scroll="onScroll">
      <div v-for="item in 30" :key="item" class="row">
        内容 {{ item }} · 只有内容区域滚动
      </div>
    </c-layout-content>
    <c-layout-footer bordered class="bar"
      >固定底部 · 已滚动 {{ offset }}px</c-layout-footer
    >
  </c-layout>
</template>
<script setup lang="ts">
import { ref } from "vue";
import type { LayoutContentInstance } from "../index";
const content = ref<LayoutContentInstance>();
const offset = ref(0);
const onScroll = (event: Event) => {
  offset.value = Math.round((event.target as HTMLElement).scrollTop);
};
</script>
<style scoped>
.scroll-layout {
  height: 320px;
  background: var(--c-color-bg-2);
}
.bar {
  padding: 12px 16px;
  display: flex;
  align-items: center;
  justify-content: space-between;
}
.row {
  padding: 16px;
  border-bottom: 1px solid var(--c-color-border-2);
}
</style>
```

### 侧栏位置与折叠模式

`placement` 自动调整侧栏位置和箭头方向。`width` 模式改变内容可用宽度，`transform` 模式保留内容宽度。零宽度折叠时仍保留展开按钮，内部内容不可聚焦。

Example source: src/layout/__demos__/sider-options.vue

```vue
<template>
  <div class="controls">
    <c-radio-group v-model="placement"
      ><c-radio value="left">左侧</c-radio
      ><c-radio value="right">右侧</c-radio></c-radio-group
    >
    <c-radio-group v-model="mode"
      ><c-radio value="width">宽度折叠</c-radio
      ><c-radio value="transform">位移折叠</c-radio></c-radio-group
    >
    <label>完全收起 <c-switch v-model="zero" /></label>
    <c-button size="sm" @click="collapsed = !collapsed">{{
      collapsed ? "展开" : "收起"
    }}</c-button>
  </div>
  <c-layout has-sider class="options-layout">
    <c-layout-sider
      v-model:collapsed="collapsed"
      :placement="placement"
      :collapse-mode="mode"
      :collapsed-width="zero ? 0 : 48"
      :width="200"
      bordered
      collapsible
    >
      <div v-for="item in 12" :key="item" class="item">
        {{ item }} · 项目导航和工作空间
      </div>
    </c-layout-sider>
    <c-layout-content scrollable class="content">
      <h4>内容区域</h4>
      <p>切换左右位置和折叠方式。完全收起后仍可通过边缘按钮展开。</p>
      <p>Tab 可聚焦折叠按钮，Enter 或空格可切换状态。</p>
    </c-layout-content>
  </c-layout>
</template>
<script setup lang="ts">
import { ref } from "vue";
const placement = ref<"left" | "right">("left");
const mode = ref<"width" | "transform">("width");
const collapsed = ref(false);
const zero = ref(false);
</script>
<style scoped>
.controls {
  display: flex;
  gap: 16px;
  flex-wrap: wrap;
  margin-bottom: 16px;
  align-items: center;
}
.controls label {
  display: flex;
  align-items: center;
  gap: 8px;
}
.options-layout {
  height: 300px;
  background: var(--c-color-bg-2);
}
.item {
  padding: 16px;
}
.content {
  padding: 16px;
}
</style>
```

## 内容与展示

### 可伸缩侧边栏

可以用鼠标进行拖拽放大缩小的侧边栏，需要用到的参数：resize-directions。

Example source: src/layout/__demos__/resize.vue

```vue
<template>
  <c-layout>
    <c-layout-header class="layout-header">Header</c-layout-header>
    <c-layout>
      <c-layout-sider class="layout-sider" :resize-directions="['right']"> Sider </c-layout-sider>
      <c-layout-content class="layout-content">Content</c-layout-content>
    </c-layout>
    <c-layout-footer class="layout-footer">Footer</c-layout-footer>
  </c-layout>
</template>

<style scoped lang="less">
.layout-header {
  height: 100px;
  display: flex;
  justify-content: center;
  align-items: center;
  background-color: var(--c-color-primary-light-3);
  color: var(--c-color-text-1);
}

.layout-content {
  height: 100px;
  display: flex;
  justify-content: center;
  align-items: center;
  background-color: var(--c-color-primary-light-4);
  color: var(--c-color-text-1);
}

.layout-sider {
  min-height: 100px;
  background-color: var(--c-color-primary);

  :deep(.c-layout-sider-children) {
    display: flex;
    justify-content: center;
    align-items: center;
    color: var(--c-color-text-1);
  }
}

.layout-footer {
  height: 100px;
  display: flex;
  justify-content: center;
  align-items: center;
  background-color: var(--c-color-primary);
  color: var(--c-color-text-1);
}
</style>
```

### 侧栏折叠

通过 `v-model:collapsed` 控制折叠，也可以使用 `default-collapsed` 设置非受控初始状态。

Example source: src/layout/__demos__/collapse.vue

```vue
<template>
  <c-layout class="collapse-layout" has-sider>
    <c-layout-sider v-model:collapsed="collapsed" collapsible>
      <div class="sider-content">{{ collapsed ? '导航' : '侧栏导航区域' }}</div>
    </c-layout-sider>
    <c-layout>
      <c-layout-header class="header">可折叠侧栏</c-layout-header>
      <c-layout-content class="content">
        <c-button @click="collapsed = !collapsed">{{ collapsed ? '展开侧栏' : '收起侧栏' }}</c-button>
        <p>侧栏和内容区共享可用高度，底部触发器保持在侧栏底部。</p>
      </c-layout-content>
    </c-layout>
  </c-layout>
</template>

<script setup lang="ts">
import { ref } from 'vue'
const collapsed = ref(false)
</script>

<style scoped>
.collapse-layout { height: 300px; background: var(--c-color-bg-2); }
.sider-content, .header, .content { padding: 16px; }
.header { background: var(--c-color-bg-3); }
</style>
```

## 阅读方向

继承最近的 `dir="ltr|rtl"`，支持运行时切换与局部覆盖。内容继承阅读方向。Sider 的 placement=left/right 保持物理侧，折叠和 ResizeBox 的物理手柄语义不反转；标题与内容本身可使用局部 dir。

## API

### Layout Props

| 参数名    | 描述                                                               | 类型    | 默认值 |
| --------- | ------------------------------------------------------------------ | ------- | :----: |
| scrollable | 是否在自身启用原生滚动（需要约束高度） | boolean | false |
| has-sider | 表示子元素里有 Sider，一般不用指定。可用于服务端渲染时避免样式闪动 | boolean | false  |

### Layout-Header Slots

| 插槽名  | 描述 | 参数 |
| ------- | :--: | ---- |
| default | 内容 | -    |

### Layout-content Slots

| 插槽名  | 描述 | 参数 |
| ------- | :--: | ---- |
| default | 内容 | -    |

### Layout-Footer Slots

| 插槽名  | 描述 | 参数 |
| ------- | :--: | ---- |
| default | 内容 | -    |

### Layout-Sider Props

| 参数名            | 描述                                                                                                 | 类型                                          | 默认值  |
| ----------------- | ---------------------------------------------------------------------------------------------------- | --------------------------------------------- | :-----: |
| theme             | 主题颜色                                                                                             | 'dark' \| 'light'                             | 'light' |
| collapsed         | 当前收起状态                                                                                         | boolean                                       |    -    |
| default-collapsed | 默认的收起状态                                                                                       | boolean                                       |  false  |
| collapsible       | 是否可收起                                                                                           | boolean                                       |  false  |
| width             | 宽度                                                                                                 | number \| string                              |   200   |
| collapsed-width   | 收缩宽度                                                                                             | number                                        |   48    |
| reverse-arrow     | 翻转折叠提示箭头的方向，当 Sider 在右边时可以使用                                                    | boolean                                       |  false  |
| breakpoint        | 触发响应式布局的断点, 详见响应式栅格                                                                 | 'xxl' \| 'xl' \| 'lg' \| 'md' \| 'sm' \| 'xs' |    -    |
| resize-directions | 可以用 ResizeBox 替换原生的 aside 标签，这个参数即 ResizeBox的 directions 参数。详情请看 ResizeBox。 | Array<'left' \| 'right' \| 'top' \| 'bottom'> |    -    |
| hide-trigger      | 隐藏底部折叠触发器                                                                                   | boolean                                       |  false  |

### Layout-Sider Events

| 事件名     | 描述                                                             | 参数                                                     |
| ---------- | ---------------------------------------------------------------- | -------------------------------------------------------- |
| collapse   | 展开-收起时的事件，有点击 trigger 以及响应式反馈两种方式可以触发 | collapsed: boolean<br>type: 'clickTrigger'\|'responsive' |
| breakpoint | 触发响应式布局断点时的事件                                       | collapsed: boolean                                       |

### Layout-Sider Slots

| 插槽名  |         描述         | 参数               |
| ------- | :------------------: | ------------------ |
| trigger | 自定义底部折叠触发器 | collapsed: boolean |

## 类型定义

组件导出以下类型定义

```ts
import type { LayoutProps } from '@cedar-design/ui'
```

### 新增布局能力

| 组件 | 属性 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- | --- |
| Content | scrollable | boolean | false | 自身作为原生滚动容器 |
| Header / Footer / Sider | bordered | boolean | false | 显示与内容相邻的边框 |
| Sider | placement | 'left' / 'right' | 'left' | 侧栏所在方向，自动处理箭头；reverse-arrow 仍兼容 |
| Sider | collapse-mode | 'width' / 'transform' | 'width' | 折叠时改变内容宽度或移动内容 |

Layout、Content、Sider 均提供 `scroll` 事件（参数为原生 Event）及 `scrollTo(options: ScrollToOptions)` / `scrollTo(x: number, y: number)` 方法。Sider 默认在内部内容节点滚动。`width` 支持数字像素或 CSS 长度字符串；百分比宽度与 transform 模式组合不推荐，建议用 px/rem 等确定长度。

折叠按钮使用原生 button，支持 Tab、Enter 和空格；`collapsed-width="0"` 时隐藏区域设为 inert，展开入口保留在侧栏边缘。自定义 trigger 插槽应使用展示内容，避免嵌套按钮。

---

Document: llms/zh-CN/components/link.md

<!-- Source: src/link/README.md; locale: zh-CN; page: /components/link/ -->

# Link

链接的基本样式。

## 基础示例

### 基础用法

链接的基本用法。

Example source: src/link/__demos__/basic.vue

```vue
<template>
  <c-link href="https://example.com/" target="_blank" rel="noopener noreferrer"
    >访问示例网站</c-link
  >
</template>
```

## 外观与状态

### 链接尺寸与语义颜色

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `status` | 链接的状态 | 链接尺寸与语义颜色、链接模式、下划线 |
| `href` | 链接地址 | 链接模式、悬浮态底色 |
| `size` | 文字、图标和加载图标尺寸 | 链接尺寸与语义颜色 |
| `icon` | 图标 | 链接尺寸与语义颜色 |
| `loading` | 链接是否为加载中状态 | 链接尺寸与语义颜色 |
| `target` | 原生链接打开目标 | 链接模式 |
<!-- demo-config-notes:end -->

比较尺寸和语义颜色；导航目标、禁用拦截和加载反馈保留独立行为示例。

<details>
<summary>配置说明与使用限制</summary>

#### 五种尺寸

通过 `size` 设置五档尺寸，文字、图标和加载图标同步缩放，默认 `md`。

#### 链接状态

链接使用统一语义状态，例如 `default`（默认）、`success`、`warning` 和 `danger`。

</details>

Example source: src/link/__demos__/appearance-comparison.vue

```vue
<script setup lang="ts">
import { proxyRefs as demoProxyRefs } from 'vue'

const scene1 = demoProxyRefs((() => {

const sizes = ['xs', 'sm', 'md', 'lg', 'xl'] as const
return { sizes }
})())
</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="size">
    <h4><span lang="zh-CN">五种尺寸</span><span lang="en-US">size</span></h4>
    <c-space direction="column" size="md">
        <c-space v-for="size in scene1.sizes" :key="size" wrap size="md" align="center">
          <c-link :size="size" status="primary">{{ size }} 链接</c-link>
          <c-link :size="size" status="primary" icon>{{ size }} 图标</c-link>
          <c-link :size="size" loading>{{ size }} 加载中</c-link>
        </c-space>
      </c-space>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="link-status">
    <h4><span lang="zh-CN">链接状态</span><span lang="en-US">link status</span></h4>
    <c-space wrap size="sm">
        <c-link status="default">默认链接</c-link>
        <c-link status="primary">主要链接</c-link>
        <c-link status="secondary">次要链接</c-link>
        <c-link status="tertiary">三级链接</c-link>
        <c-link status="info">信息链接</c-link>
        <c-link status="success">成功链接</c-link>
        <c-link status="warning">警告链接</c-link>
        <c-link status="danger">危险链接</c-link>
      </c-space>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

### 链接模式

设置 `href` 后渲染为可导航链接；使用 `target="_blank"` 时建议同时设置 `rel="noopener noreferrer"`。

Example source: src/link/__demos__/link-mode.vue

```vue
<template>
  <c-space size="sm">
    <c-link
      status="primary"
      href="https://example.com/"
      target="_blank"
      rel="noopener noreferrer"
    >
      href 链接
    </c-link>
  </c-space>
</template>
```

### 下划线

通过 `underline` 设置下划线的显示策略。

Example source: src/link/__demos__/link-underline.vue

```vue
<template>
  <c-space size="sm">
    <c-link status="primary" underline="always">始终显示</c-link>
    <c-link status="primary" underline="hover">悬停显示</c-link>
    <c-link status="primary" underline="none">不显示</c-link>
  </c-space>
</template>
```

### 禁用状态

禁用状态下不会触发导航或点击事件。

Example source: src/link/__demos__/link-disabled.vue

```vue
<template>
  <c-link disabled>禁用状态</c-link>
</template>
```

### 悬浮态底色

两端均支持 `hoverable`（默认 `false`）：开启后增加内边距与悬浮/按下底色，不影响下划线策略。键盘聚焦使用 `:focus-visible` 显示焦点轮廓，无需开启 hoverable。

Example source: src/link/__demos__/hoverable.vue

```vue
<template>
  <c-space size="sm">
    <c-link hoverable href="#link">悬浮态底色</c-link>
    <c-link href="#link">Tab 键聚焦</c-link>
  </c-space>
</template>
```

两端 Link 主体、Props、主样式和测试采用独立同源复制；仅组件前缀、本地图标与主题 token 适配不同，不共享核心或实例。

禁用或加载时移除 href/target/rel，禁止导航和 click，并退出 Tab 顺序（即使传入 tabindex）。普通状态原样透传原生属性。加载图标优先于 icon 插槽；动态图标插槽会随渲染更新。

## 内容与展示

### 图标

通过 `icon` 设置带图标的链接，设置为 `true` 时候显示默认图标。

Example source: src/link/__demos__/link-icon.vue

```vue
<template>
  <c-space size="sm">
    <c-link icon>默认图标</c-link>
    <c-link>
      <template #icon><c-icon-edit /></template>
      自定义图标
    </c-link>
  </c-space>
</template>
```

## 交互与控制

### 加载中状态

通过设置 `loading` 可以让链接处于加载中状态。处于加载中状态的链接不会触发点击事件。

Example source: src/link/__demos__/link-loading.vue

```vue
<script setup lang="ts">
import { onBeforeUnmount, ref } from "vue";

const loading = ref(false);
const ready = ref(false);
const href =
  "data:text/plain;charset=utf-8," + encodeURIComponent("示例报告：准备完成。");
let timer: ReturnType<typeof setTimeout> | undefined;

function prepareDownload(event: MouseEvent) {
  if (ready.value) {
    return;
  }
  event.preventDefault();
  loading.value = true;
  // 模拟业务准备；完成后再次激活链接，交给浏览器原生下载。
  timer = setTimeout(() => {
    ready.value = true;
    loading.value = false;
    timer = undefined;
  }, 1000);
}
onBeforeUnmount(() => clearTimeout(timer));
</script>
<template>
  <c-space size="sm">
    <c-link :href="href" download="report.txt" loading>加载中</c-link>
    <c-link
      :href="href"
      download="report.txt"
      :loading="loading"
      @click="prepareDownload"
    >
      {{ loading ? "准备中" : ready ? "下载示例报告" : "准备下载报告" }}
    </c-link>
  </c-space>
  <p>
    首次点击或按 Enter 准备报告；完成后再次激活链接，浏览器下载文本文件。loading
    由业务手动控制。
  </p>
</template>
```

## API

### 原生链接与手动加载

导航请提供 href。禁用或加载时，原本有 href 的链接保留 link 角色，移除导航属性并退出 Tab 顺序。download、hreflang、referrerpolicy 和 ARIA 等原生属性直接透传。loading 优先于 icon 插槽。click 是 MouseEvent 通知事件，遵守 Vue 的 once 语义，不根据监听器返回的 Promise 管理 loading；没有导航目标的业务操作使用 Button。

加载示例首次激活时由业务准备报告，完成后再次激活交给浏览器原生下载；卸载时取消准备任务。


### `<Link>` Props

| 属性 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| `size` | 文字、图标与加载图标的五档尺寸 | 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' | 'md' |
| `href` | 原生链接地址 | string | - |
| `target` | 原生打开目标 | string | - |
| `rel` | 原生链接关系 | string | - |
| `status` | 链接语义状态 | SemanticStatus | 'default' |
| `underline` | 下划线策略 | 'always' \| 'hover' \| 'none' | 'none' |
| `hoverable` | 显示带内边距的悬浮/按下底色 | boolean | false |
| `icon` | 显示默认前置图标；icon 插槽优先 | boolean | false |
| `loading` | 显示加载图标并阻止导航与点击 | boolean | false |
| `disabled` | 禁用链接 | boolean | false |


### `<Link>` Events

| 事件名 | 说明           | 参数                          |
| ------ | -------------- | ----------------------------- |
| click  | 点击触发的事件 | `(event: MouseEvent) => void` |

### Slots

| 插槽 | 说明 |
| --- | --- |
| default | 链接内容 |
| icon | 自定义图标，loading 时被加载图标替代 |

### 类型定义

组件导出以下类型定义

```ts
import type { LinkProps, LinkSize, LinkUnderline, LinkInstance } from '@cedar-design/ui'
```

### 样式迁移

内部类名统一为 `c-link--status-*`、`c-link--underline-*`、`c-link--disabled`、`c-link--loading` 和 `c-link__icon`。请迁移旧的单连字符选择器，优先通过 `--c-link-*` CSS 变量定制。焦点支持 `--c-link-focus-width`（2px）、`--c-link-focus-offset`（2px）、`--c-link-focus-color`（currentColor）、`--c-link-focus-opacity`（0.8）。减少动态效果偏好下关闭加载旋转和过渡。

文字配色与 Button 的 text 变体一致：default 使用 content-primary，secondary / tertiary 使用 content-secondary，彩色状态使用对应 content 语义色，禁用和加载使用 content-disabled。两品牌明暗模式均继承这些规则。

尺寸变量：`--c-link-size-xs-font-size`, `--c-link-size-sm-font-size`, `--c-link-size-md-font-size`, `--c-link-size-lg-font-size`, `--c-link-size-xl-font-size`。默认分别为 12 / 13 / 14 / 16 / 18px；md 引用原有 `--c-link-font-size`，图标和加载图标使用 1em。

---

Document: llms/zh-CN/components/list.md

<!-- Source: src/list/README.md; locale: zh-CN; page: /components/list/ -->

# List

最基础的列表展示，可承载文字、列表、图片、段落，常用于后台数据展示页面。

## 基础示例

### 基础用法

列表的基本使用方法。可用于承载文字、列表、图片和段落。

Example source: src/list/__demos__/basic.vue

```vue
<template>
  <c-list>
    <template #header> List title </template>
    <c-list-item>Beijing Bytedance Technology Co., Ltd.</c-list-item>
    <c-list-item>Bytedance Technology Co., Ltd.</c-list-item>
    <c-list-item>Beijing Toutiao Technology Co., Ltd.</c-list-item>
    <c-list-item>Beijing Volcengine Technology Co., Ltd.</c-list-item>
    <c-list-item>China Beijing Bytedance Technology Co., Ltd.</c-list-item>
  </c-list>
</template>
<script lang="ts" setup>
</script>
```

## 外观与状态

### 不同尺寸

列表组件提供了三种大小 `sm, md, lg` ，可根据业务需求自行选择。

Example source: src/list/__demos__/size.vue

```vue
<template>
  <c-space direction="column" size="lg">
    <c-radio-group v-model="size" type="button">
      <c-radio value="sm">sm</c-radio>
      <c-radio value="md">md</c-radio>
      <c-radio value="lg">lg</c-radio>
    </c-radio-group>
    <c-list :size="size">
      <template #header> List title </template>
      <c-list-item>Beijing Bytedance Technology Co., Ltd.</c-list-item>
      <c-list-item>Bytedance Technology Co., Ltd.</c-list-item>
      <c-list-item>Beijing Toutiao Technology Co., Ltd.</c-list-item>
      <c-list-item>Beijing Volcengine Technology Co., Ltd.</c-list-item>
      <c-list-item>China Beijing Bytedance Technology Co., Ltd.</c-list-item>
    </c-list>
  </c-space>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
const size = ref('md')
</script>
```

## 内容与布局

### 前缀与后缀

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `bordered` | 外边框 | 自定义内容 |
| `data` | 数据，与 item 插槽配合 | 自定义内容 |
<!-- demo-config-notes:end -->

`list-item` 只提供 `prefix` / 默认内容 / `suffix` 三列布局。头像、标题、操作都由业务自己组合。

Example source: src/list/__demos__/prefix-suffix.vue

```vue
<template>
  <c-list>
    <c-list-item v-for="item in items" :key="item.title">
      <template #prefix>
        <c-avatar shape="square">{{ item.initial }}</c-avatar>
      </template>
      <template #suffix>
        <c-button size="sm">编辑</c-button>
      </template>
      <div class="list-item-title">{{ item.title }}</div>
      <div class="list-item-description">{{ item.description }}</div>
    </c-list-item>
  </c-list>
</template>

<script lang="ts" setup>
const items = [
  {
    initial: 'B',
    title: 'Beijing Bytedance Technology Co., Ltd.',
    description: 'Beijing ByteDance Technology Co., Ltd. is an enterprise located in China.',
  },
  {
    initial: 'T',
    title: 'Beijing Toutiao Technology Co., Ltd.',
    description: 'Toutiao is a content platform under ByteDance.',
  },
  {
    initial: 'V',
    title: 'Beijing Volcengine Technology Co., Ltd.',
    description: 'Volcengine provides cloud and AI infrastructure.',
  },
]
</script>

<style scoped>
.list-item-title {
  font-weight: var(--c-font-weight-500);
}

.list-item-description {
  margin-top: 4px;
  color: var(--c-color-text-2);
}
</style>
```

### 自定义内容

主体和两侧插槽都可以放任意内容。分页、栅格请自行组合 `Pagination` / `Grid`。

Example source: src/list/__demos__/actions-layout.vue

```vue
<template>
  <c-list :bordered="false" :data="dataSource">
    <template #item="{ item }">
      <c-list-item>
        <template #prefix>
          <c-avatar shape="square">
            <img alt="avatar" :src="item.avatar" />
          </c-avatar>
        </template>
        <template #suffix>
          <img class="list-demo-cover" alt="cover" :src="item.imageSrc" />
        </template>
        <div class="list-item-title">{{ item.title }}</div>
        <div class="list-item-description">{{ item.description }}</div>
      </c-list-item>
    </template>
  </c-list>
</template>

<script lang="ts" setup>
const names = ['Socrates', 'Balzac', 'Plato']
const avatarSrc = [
  '//p1-arco.byteimg.com/tos-cn-i-uwbnlip3yd/a8c8cdb109cb051163646151a4a5083b.png~tplv-uwbnlip3yd-webp.webp',
  '//p1-arco.byteimg.com/tos-cn-i-uwbnlip3yd/e278888093bef8910e829486fb45dd69.png~tplv-uwbnlip3yd-webp.webp',
  '//p1-arco.byteimg.com/tos-cn-i-uwbnlip3yd/9eeb1800d9b78349b24682c3518ac4a3.png~tplv-uwbnlip3yd-webp.webp',
]
const imageSrc = [
  '//p1-arco.byteimg.com/tos-cn-i-uwbnlip3yd/29c1f9d7d17c503c5d7bf4e538cb7c4f.png~tplv-uwbnlip3yd-webp.webp',
  '//p1-arco.byteimg.com/tos-cn-i-uwbnlip3yd/04d7bc31dd67dcdf380bc3f6aa07599f.png~tplv-uwbnlip3yd-webp.webp',
  '//p1-arco.byteimg.com/tos-cn-i-uwbnlip3yd/1f61854a849a076318ed527c8fca1bbf.png~tplv-uwbnlip3yd-webp.webp',
]
const dataSource = names.map((title, index) => ({
  avatar: avatarSrc[index],
  title,
  description:
    'Beijing ByteDance Technology Co., Ltd. is an enterprise located in China. ByteDance has products such as TikTok, Toutiao, volcano video and Douyin (the Chinese version of TikTok).',
  imageSrc: imageSrc[index],
}))
</script>

<style scoped>
.list-item-title {
  font-weight: var(--c-font-weight-500);
}

.list-item-description {
  margin-top: 4px;
  color: var(--c-color-text-2);
}

.list-demo-cover {
  display: block;
  width: 120px;
  height: 80px;
  object-fit: cover;
  border-radius: var(--c-border-radius-md);
}
</style>
```

同时提供默认插槽与 `data` 时，默认插槽优先，`item` 插槽不会被调用。`loading` 仅表示整张列表首次加载或刷新；需要滚动分页时请使用 [InfiniteScroll](llms/zh-CN/components/infinite-scroll.md) 组合。

## 滚动与虚拟列表

### 容器滚动

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `data` | 数据，与 item 插槽配合 | 容器滚动、无限长列表、虚拟定位 |
| `virtual-list-props` | 数据模式虚拟化；default插槽存在时忽略 | 无限长列表、虚拟定位 |
| `max-height` | 普通列表最大高度；数字px/CSS长度，0不限 | 容器滚动 |
| `scrollbar` | 普通列表自定义滚动条；false使用原生滚动 | 容器滚动 |
| `size` | 仅实现 sm/md/lg，不支持 xs/xl | 容器滚动 |
| `split` | 头尾及列表项分隔线，与边框独立 | 容器滚动 |
<!-- demo-config-notes:end -->

Example source: src/list/__demos__/bounded-scroll.vue

```vue
<script setup>
const rows = Array.from({ length: 20 }, (_, index) => ({ id: index, name: '记录 ' + (index + 1) }))
</script>
<template>
  <c-space direction="column" style="width: 100%">
    <c-list :data="rows" :max-height="180" :scrollbar="false">
      <template #header>原生滚动条</template>
      <template #item="{ item }"><c-list-item>{{ item.name }}</c-list-item></template>
    </c-list>
    <c-list :data="rows" max-height="12rem" :scrollbar="{ type: 'track' }" size="sm" :split="false">
      <template #header>自定义滚动条，无分隔线</template>
      <template #item="{ item }"><c-list-item>{{ item.name }}</c-list-item></template>
    </c-list>
  </c-space>
</template>
```

### 无限长列表

通过指定 `virtualListProps` 来开启虚拟列表，在大量数据时获得高性能表现。
在使用虚拟列表时，如果列表元素之间高度变化较大可能导致滚动时视口出现空白区域，可通过调整 `virtualListProps.buffer`
属性解决，[使用方式](vue/docs/faq#%E8%99%9A%E6%8B%9F%E5%88%97%E8%A1%A8%E7%9A%84%E4%BD%BF%E7%94%A8)。

Example source: src/list/__demos__/virtual-list.vue

```vue
<template>
  <h3 :style="{ color: 'var(--c-color-text-2)' }">10000 items</h3>
  <c-list
    :style="{ width: `600px` }"
    :virtualListProps="{
      height: 560,
    }"
    :data="list"
  >
    <template #item="{ item, index }">
      <c-list-item :key="index">
        <template #prefix>
          <c-avatar shape="square">A</c-avatar>
        </template>
        <div>{{ item.title }}</div>
        <div class="list-item-description">{{ item.description }}</div>
      </c-list-item>
    </template>
  </c-list>
</template>

<script lang="ts" setup>
import { reactive } from 'vue'

const list = reactive(
  Array(10000)
    .fill(null)
    .map((_, index) => {
      const prefix = `0000${index}`.slice(-5)
      return {
        title: 'Beijing Bytedance Technology Co., Ltd.',
        description: `(${prefix}) Beijing ByteDance Technology Co., Ltd. is an enterprise located in China.`,
      }
    }),
)
</script>

<style scoped>
.list-item-description {
  margin-top: 4px;
  color: var(--c-color-text-2);
}
</style>
```

### 虚拟定位

示例使用 `Space direction="column"` 将操作区放在列表上方，列表独占可用宽度；`estimatedSize` 是未测量行的估计高度，不要求业务行采用固定高度。

定位优先使用已渲染行的真实边界，行高测量会同步更新虚拟留白。程序滚动触发的渲染保留当前对齐；不同位置的原生滚动、新命令、数据替换、停用或卸载会取消旧补偿。`auto` 对已完整可见行不改变滚动位置和渲染窗口；这不代表持续追踪任意异步行高变化。

Example source: src/list/__demos__/virtual-navigation.vue

```vue
<script setup>
import { ref } from 'vue'
const list = ref()
const rows = Array.from({ length: 1000 }, (_, id) => ({ id, name: '记录 ' + (id + 1) }))
</script>
<template>
  <c-space direction="column" style="width: 100%">
    <c-space wrap>
      <c-button @click="list.scrollIntoView({ key: 499, align: 'top' })">第 500 项置顶</c-button>
      <c-button @click="list.scrollIntoView({ key: 499, align: 'bottom' })">第 500 项置底</c-button>
      <c-button @click="list.scrollIntoView({ key: 499, align: 'auto' })">仅滚动到可见</c-button>
    </c-space>
    <c-list ref="list" :data="rows" :virtual-list-props="{ height: 240, itemKey: 'id', estimatedSize: 48, buffer: 10 }">
      <template #item="{ item, index }"><c-list-item><template #prefix>{{ index + 1 }}</template>{{ item.name }}</c-list-item></template>
    </c-list>
  </c-space>
</template>
```

## 生命周期

### 保留命令与 KeepAlive 生命周期

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `data` | 数据，与 item 插槽配合 | 保留命令与 KeepAlive 生命周期 |
| `virtual-list-props` | 数据模式虚拟化；default插槽存在时忽略 | 保留命令与 KeepAlive 生命周期 |
<!-- demo-config-notes:end -->

Example source: src/list/__demos__/virtual-lifecycle.vue

```vue
<script setup lang="ts">
import { ref } from "vue";

const active = ref(true);
const mounted = ref(true);
const rows = Array.from({ length: 100 }, (_, key) => ({ key }));
let retained:
  | { scrollIntoView: (options: { key: number; align: "top" }) => void }
  | undefined;
const capture = (instance: typeof retained) => {
  if (instance) retained = instance;
};
const jump = () => retained?.scrollIntoView({ key: 50, align: "top" });
</script>

<template>
  <div>
    <c-button @click="active = !active">Activate / deactivate</c-button>
    <c-button @click="mounted = !mounted">Mount / dispose cache</c-button>
    <c-button @click="jump">Retained command: row 51</c-button>
    <p>Inactive/disposed commands do nothing. Activation never replays them.</p>
    <KeepAlive v-if="mounted">
      <c-list
        v-if="active"
        :ref="capture"
        :data="rows"
        :virtual-list-props="{
          height: 100,
          fixedSize: true,
          estimatedSize: 20,
          buffer: 2,
          itemKey: 'key',
        }"
      >
        <template #item="{ item }"
          ><div style="height: 20px">{{ item.key + 1 }}</div></template
        >
      </c-list>
    </KeepAlive>
  </div>
</template>
```

## API

### List Props

| 属性 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| data | 数据，与 item 插槽配合 | unknown[] | undefined |
| size | 仅实现 sm/md/lg，不支持 xs/xl | 'sm' \| 'md' \| 'lg' | md |
| bordered | 外边框 | boolean | true |
| split | 头尾及列表项分隔线，与边框独立 | boolean | true |
| loading | 首次加载/刷新反馈，不管理分页 | boolean | false |
| max-height | 普通列表最大高度；数字px/CSS长度，0不限 | number \| string | 0 |
| virtual-list-props | 数据模式虚拟化；default插槽存在时忽略 | ListVirtualListProps | undefined |
| scrollbar | 普通列表自定义滚动条；false使用原生滚动 | boolean \| ListScrollbarProps | true |

虚拟列表使用独立视口，不额外嵌套自定义滚动条。virtualListProps.height 优先于 maxHeight；均省略时虚拟视口默认 200px。数字/带单位CSS长度受支持，非法或非正 max-height 不限制高度。

ListVirtualListProps 支持 height、threshold、fixedSize、estimatedSize、buffer、itemKey、component。没有废弃的 isStaticItemHeight；data 统一由 List.data 提供。数据量小于或等于 threshold 时渲染全部；非固定高度使用测量值与 estimatedSize 估计，buffer 控制前后预渲染行数。

ListScrollbarProps 支持 type: 'track'|'embed'、outerClass、outerStyle、hide、disableHorizontal、disableVertical。属性作为 JavaScript 对象字段使用 camelCase。

### Events / Methods

- scroll(event: Event)：真实滚动事件，一次滚动通知一次。
- scrollIntoView({ index?, key?, align })：虚拟列表定位，index 优先；align 为 top/bottom/auto。auto 在项目已完整可见时不滚动，否则最小滚动使其可见。无效目标、非虚拟模式不操作。

### Slots

List：default（优先于data）、item({ item, index })、header、footer、empty。空态仅无默认插槽、无数据、非加载时渲染。ListItem：prefix、default、suffix，保持列表项语义，不管理按钮/业务交互。

### 类型

ListProps、ListSize、ListVirtualListProps、ListScrollbarProps、ListExpose、ListSlots、ListEmits、ListInstance、ListItemInstance。

List 与 InfiniteScroll 分工独立：List管理展示与可选虚拟视口；无限分页应组合 InfiniteScroll 的 status/target 交互，不在 List 中重复维护加载状态机。

## 样式变量

| Token | Default |
| --- | --- |
| `--c-list-background` | `transparent` |
| `--c-list-empty-padding` | `16px` |
| `--c-list-empty-color` | `var(--c-list-text-color)` |
| `--c-list-loading-padding` | `0px` |
| `--c-list-border-width` | `1px` |
| `--c-list-border-color` | `var(--c-color-neutral-3)` |
| `--c-list-border-radius` | `var(--c-border-radius-md)` |
| `--c-list-text-color` | `var(--c-color-text-1)` |
| `--c-list-font-size` | `var(--c-font-size-body-3)` |
| `--c-list-line-height` | `var(--c-line-height)` |
| `--c-list-text-color-header` | `var(--c-color-text-1)` |
| `--c-list-font-size-header` | `var(--c-font-size-title-1)` |
| `--c-list-font-weight-header` | `var(--c-font-weight-500)` |
| `--c-list-line-height-header` | `1.5` |
| `--c-list-size-sm-padding-vertical-header` | `var(--c-spacing-4)` |
| `--c-list-size-sm-padding-horizontal-header` | `var(--c-spacing-8)` |
| `--c-list-size-sm-padding-vertical-item` | `9px` |
| `--c-list-size-sm-padding-horizontal-item` | `var(--c-spacing-8)` |
| `--c-list-size-md-padding-vertical-header` | `var(--c-spacing-6)` |
| `--c-list-size-md-padding-horizontal-header` | `var(--c-spacing-8)` |
| `--c-list-size-md-padding-vertical-item` | `13px` |
| `--c-list-size-md-padding-horizontal-item` | `var(--c-spacing-8)` |
| `--c-list-size-lg-padding-vertical-header` | `var(--c-spacing-7)` |
| `--c-list-size-lg-padding-horizontal-header` | `var(--c-spacing-8)` |
| `--c-list-size-lg-padding-vertical-item` | `17px` |
| `--c-list-size-lg-padding-horizontal-item` | `var(--c-spacing-8)` |
| `--c-list-item-prefix-margin-right` | `var(--c-spacing-8)` |
| `--c-list-item-suffix-margin-left` | `var(--c-spacing-8)` |
| `--c-list-size-sm-padding-vertical-footer` | `var(--c-list-size-sm-padding-vertical-item)` |
| `--c-list-size-sm-padding-horizontal-footer` | `var(--c-list-size-sm-padding-horizontal-item)` |
| `--c-list-size-md-padding-vertical-footer` | `var(--c-list-size-md-padding-vertical-item)` |
| `--c-list-size-md-padding-horizontal-footer` | `var(--c-list-size-md-padding-horizontal-item)` |
| `--c-list-size-lg-padding-vertical-footer` | `var(--c-list-size-lg-padding-vertical-item)` |
| `--c-list-size-lg-padding-horizontal-footer` | `var(--c-list-size-lg-padding-horizontal-item)` |

---

Document: llms/zh-CN/components/loading.md

<!-- Source: src/loading/README.md; locale: zh-CN; page: /components/loading/ -->

# Loading

用于页面、区块或容器的加载中状态。

## 基础示例

### 基础用法

显示加载指示器与提示文字。包裹内容和指令用法见后续示例。

Example source: src/loading/__demos__/basic.vue

```vue
<template>
  <c-loading tip="加载中" />
</template>
```

## 外观与状态

### 加载图形、尺寸与颜色

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `size` | 加载指示器的尺寸；数字表示 px | 加载图形、尺寸与颜色 |
| `type` | 加载动画类型 | 加载图形、尺寸与颜色 |
| `color` | 加载指示器和提示文案的颜色 | 加载图形、尺寸与颜色 |
<!-- demo-config-notes:end -->

对比相同加载状态的图形、尺寸和颜色；容器遮罩与指令用法保持独立。

Example source: src/loading/__demos__/appearance-comparison.vue

```vue
<script setup lang="ts">


</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="size">
    <h4><span lang="zh-CN">大小</span><span lang="en-US">size</span></h4>
    <c-space align="center" justify="space-between">
        <c-loading size="sm" />
        <c-loading type="cube" size="sm" />
        <c-loading type="wave" size="sm" />
        <c-loading type="rect" size="sm" />
        <c-loading type="disappear" size="sm" />
        <c-loading :size="32" />
      </c-space>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="color">
    <h4><span lang="zh-CN">颜色</span><span lang="en-US">color</span></h4>
    <c-space align="center" justify="space-between">
        <c-loading color="var(--c-color-info)" />
        <c-loading type="cube" color="var(--c-color-success)" />
        <c-loading type="wave" color="var(--c-color-warning)" />
        <c-loading type="rect" color="var(--c-color-danger)" />
        <c-loading type="disappear" color="var(--c-color-text-disabled)" />
      </c-space>
  </section>

  <section class="demo-comparison-case demo-comparison-case--3" data-comparison-scene="type">
    <h4><span lang="zh-CN">类型</span><span lang="en-US">type</span></h4>
    <c-space align="center" justify="space-between">
        <c-loading />
        <c-loading type="cube" />
        <c-loading type="wave" />
        <c-loading type="rect" />
        <c-loading type="disappear" />
      </c-space>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

## 布局与排列

### 包裹内容

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `tip` | 提示文案 | 包裹内容 |
| `loading` | 是否为加载中状态（仅在包裹内容时生效） | 包裹内容 |
<!-- demo-config-notes:end -->

Example source: src/loading/__demos__/wrap.vue

```vue
<template>
  <c-button style="margin-bottom: 8px" @click="loading = !loading">
    {{ loading ? "关闭" : "打开" }}
  </c-button>
  <c-loading tip="LOADING" :loading="loading">
    <c-card
      title="介绍"
      description="Cedar 是一个基于 Vue 3 的企业级桌面端组件库。"
    />
  </c-loading>
</template>

<script lang="ts" setup>
import { ref } from "vue";

const loading = ref(false);
</script>
```

## 内容与展示

### 加载指令

两种指令示例分别维护加载状态，控件与宿主卡片通过 `Space direction="column"` 纵向排列；关闭一个不会影响另一个遮罩。

Example source: src/loading/__demos__/directive.vue

```vue
<template>
  <c-space direction="column">
    <h4>简单用法</h4>
    <c-switch v-model="simpleLoading" />
    <c-card
      v-c-loading="simpleLoading"
      title="介绍"
      description="v-c-loading 会在当前容器内渲染 Loading 遮罩，不会改变内容结构。"
    />

    <h4>复杂配置</h4>
    <c-switch v-model="configuredLoading" />
    <c-card
      v-c-loading="{
        loading: configuredLoading,
        tip: '加载中...',
        color: 'var(--c-color-primary)',
        background: 'color-mix(in srgb, var(--c-color-bg-1) 72%, transparent)',
      }"
      title="介绍"
      description="v-c-loading 会在当前容器内渲染 Loading 遮罩，不会改变内容结构。"
    />
  </c-space>
</template>

<script lang="ts" setup>
import { ref } from "vue";

const simpleLoading = ref(false);
const configuredLoading = ref(false);
</script>
```

## API

### `<Loading>` Props

| 属性      | 说明                                   | 类型                                          | 默认值   |
| --------- | -------------------------------------- | --------------------------------------------- | -------- |
| type      | 加载动画类型                           | `circle \| wave \| cube \| rect \| disappear` | `circle` |
| size      | 加载指示器的尺寸；数字表示 px          | `xs \| sm \| md \| lg \| xl \| number`        | `md`     |
| radius    | `circle` 类型的半径                    | `string \| number`                            | -        |
| color     | 加载指示器和提示文案的颜色             | `string`                                      | -        |
| loading   | 是否为加载中状态（仅在包裹内容时生效） | `boolean`                                     | `false`  |
| tip       | 提示文案                               | `string`                                      | -        |
| hide-icon | 是否隐藏加载指示器                     | `boolean`                                     | `false`  |

`v-c-loading` 支持布尔值简写，也支持 `{ loading, tip, type, size, radius, color, hideIcon, fullscreen, background }` 配置对象。对象形式中的 `loading` 控制加载状态，其余组件属性与 `Loading` 保持一致。

#### 注册方式

`v-c-loading` 使用 Cedar 内置的 `Loading` 组件渲染指示器。`c-` 前缀可以避免与其他组件库的同名指令冲突，使用前可通过以下任一方式注册。

```ts
// 1. 全量安装：自动注册 Loading 组件和 v-c-loading 指令
import CedarVue from "@cedar-design/ui";

app.use(CedarVue);
```

```ts
// 2. 按需安装 Loading：同时注册组件和指令
import { Loading } from "@cedar-design/ui";

app.use(Loading);
```

```ts
// 3. 只手动注册指令
import { vLoading } from "@cedar-design/ui";

app.directive("c-loading", vLoading);
```

使用 `CedarResolver()` 时，`unplugin-vue-components` 会自动解析模板中的 `v-c-loading`；`directives: false` 会关闭指令自动解析。

### `<Loading>` Slots

| 插槽名  | 说明                   |
| ------- | ---------------------- |
| default | 需要展示加载遮罩的内容 |
| tip     | 自定义提示内容         |
| icon    | 自定义加载指示器     |

`icon` 插槽替换全部内置 `type` 动画；未提供时使用 ConfigProvider 的 `loading` 插槽，再回退到内置动画。`hide-icon=true` 隐藏所有指示器，提示内容仍可显示。

## 类型定义

组件导出以下类型定义：

```ts
import type { LoadingProps } from "@cedar-design/ui";
```

加载指令的遮罩会阻止点击默认行为和冒泡，点击遮罩不会触发 Card 或父级的普通 `@click`；关闭加载后恢复正常点击。遮罩不会禁用底层控件的键盘操作，如需完全禁止操作，请同时设置控件的 `disabled`。

### 覆盖层样式

| 变量 | 说明 |
| --- | --- |
| `--c-loading-overlay-background` | 指令覆盖层背景色；background 选项可覆盖该值。 |

内容覆盖层类名：`.c-loading__content-overlay`。

指令每次更新都替换完整配置，省略的选项以及布尔值 `true` 使用默认值。加载中修改 `fullscreen` 会在宿主与所属文档的 body 之间迁移遮罩，宿主内容保持原位。多个全屏实例按数量持有滚动锁：关闭局部实例不会解除全屏锁，最后一个全屏实例结束时保留外部原有的锁类。

---

Document: llms/zh-CN/components/map.md

<!-- Source: src/map/README.md; locale: zh-CN; page: /components/map/ -->

# Map

## 基础示例

### 基础用法

无需登录或配置密钥即可运行。点击按钮更新本地位置模型；未接入 SDK 时显示降级提示并禁用搜索，不请求定位权限。真实地图的选点与搜索需要应用接入 SDK 适配器后再验收。

Example source: src/map/__demos__/basic.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const location = ref({ longitude: 116.397, latitude: 39.908, address: '北京示例位置' })
function reset() { location.value = { longitude: 116.397, latitude: 39.908, address: '北京示例位置' } }
</script>
<template>
  <c-space direction="column">
    <p>未接入地图 SDK 时显示降级状态，不请求定位权限、不发送真实接口请求。按钮只演示本地位置模型。</p>
    <c-space wrap>
      <c-button @click="location = { longitude: 121.4737, latitude: 31.2304, address: '上海示例位置' }">使用上海示例位置</c-button>
      <c-button @click="reset">重置位置</c-button>
    </c-space>
    <p role="status">当前位置：{{ location.address }}（{{ location.longitude }}, {{ location.latitude }}）</p>
    <c-map v-model="location" map-type="amaps" style="height: 300px" />
  </c-space>
</template>
```

## 内容与展示

### 特殊说明

地图SDK正在迁移：当前源码未提供原map-core运行时导入；MapService、SearchService、LngLat的类型声明不等于可用依赖，缺任一依赖时初始化会进入降级显示，不代表真实地图初始化成功。恢复正式适配器／第三方生命周期契约前，不将降级渲染测试当地图服务验收。

内部300ms中心更新和500ms选点等待用于抑制程序化moveend反向解析，不是CSS动画完成时长或公开CSS变量；不应通过覆盖视觉duration Token控制它们。真实SDK下的计时取消、停用／卸载、旧回调／异步结果及监听释放尚待独立验证；MapSelect地址回填和定位也不由缺SDK测试覆盖。

Example source: src/map/__demos__/auth.vue

```vue
<template>
  <c-alert status="info" title="地图 SDK 接入">
    本地示例不需要登录、令牌或外部图片。生产应用须自行接入地图 SDK 适配器、配置服务与授权域名，再验证搜索、选点和定位；当前降级展示不代表 SDK 已接入成功。
  </c-alert>
</template>
```

## 数据与选项

### 国际地图配置

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `map-type` | 要显示的地图类型。 | 国际地图配置 |
| `is-international` | 指示地图是否为谷歌地图。 | 国际地图配置 |
<!-- demo-config-notes:end -->

通过 `map-type="google"` 和 `is-international` 配置国际地图；未接入 SDK 时保留同样的降级展示。

Example source: src/map/__demos__/google.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const location = ref({ longitude: -0.1276, latitude: 51.5072, address: 'London sample location' })
</script>
<template>
  <c-space direction="column">
    <p>国际地图使用 is-international 和 map-type="google"。未配置 SDK 时保留降级展示，应用须自行接入适配器和地图服务；示例不保存密钥或 token。</p>
    <c-map v-model="location" map-type="google" is-international style="height: 300px" />
    <p role="status">{{ location.address }}</p>
  </c-space>
</template>
```

[//]: # '### v-model'
[//]: # '使用v-model语法，会自动更新值，并且不会丢失类型'
[//]: # 'Example source: src/map/__demos__/use-vmodel.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const location = ref({ longitude: 116.397, latitude: 39.908, address: '北京示例位置' })
</script>
<template>
  <c-space direction="column">
    <c-map v-model="location" map-type="amaps" style="height: 300px" />
    <p role="status">{{ location.address }}（{{ location.longitude }}, {{ location.latitude }}）</p>
  </c-space>
</template>
```'

## API

### Map Props

| 属性                    | 说明                                         | 类型                                         | 默认值           |
| ----------------------- | -------------------------------------------- | -------------------------------------------- | ---------------- |
| model-value(**v-model**) | 地图的初始值，表示所选位置的信息。           | `Object`                                     | -                |
| default-value            | 用来设置默认地图中心点                       | `{ [key in valueKeyAlias[keys]]: any }`      | -                |
| driver                  | `Fetch.genDriiver`的返回值                   | `Driver`                                     | `-`              |
| fetch                   | `Fetch.genFetch`的返回值                     | `CoreService`                                | `-`              |
| geocoder-url             | geocoderUrl接口路径                          | `string`                                     | `-`              |
| geocoder-handler         | 用于处理地图编码服务的响应。                 | `(longitude: number, latitude: number)=>{})` | -                |
| base-path                | 地图的基础路径，配置获取地图数据的基础 URL。 | `String`                                     | `'/pe/powerpro'` |
| is-international         | 指示地图是否为谷歌地图。                     | `Boolean`                                    | -                |
| show-name                | 是否展示悬浮框名称                           | `boolean`                                    | `false`          |
| show-locate-me-button      | 是否展示定位到当前位置按钮                   | `boolean`                                    | `false`          |
| show-edit-address-button   | 是否展示修改地点悬浮按钮                     | `boolean`                                    | `false`          |
| show-map-tips             | 是否展示地图上方tips                         | `boolean`                                    | `false`          |
| map-type                 | 要显示的地图类型。                           | `'qqmaps'\|'bmapGL'\|'amaps'`                | `'amaps'`        |
| enable-gis-search         | 是否启用gis搜索(**开启时`fetch`为必传**)     | `boolean`                                    | `false`          |
| value-key-scope           | 一个字符串数组，表示要在地图上显示的值列表。 | `Array`                                      | `valueKeyScope`  |
| value-key-alias           | 一个对象，表示地图键到值的映射关系。         | `Object`                                     | `valueKeyAlias`  |

### MapSelect Props

| map-style | 直接设置到地图上面的style，可以设置地图的高度。 | `object` | `{ height: '300px'}` |

### Map Events

| 事件名          | 说明                       | 参数                      |
| --------------- | -------------------------- | ------------------------- |
| change          | 当地址发生变化时触发       | `(value: ModelValueType)` |
| init            | 初始化地图完成时触发       | `(value: ModelValueType)` |
| loading:address | 选择地点，地址解析中触发   | `-`                       |
| loaded:address  | 选择地点，地址解析完成触发 | `-`                       |

## 类型定义

### valueKeyAlias

```ts
{
  longitude: 'longitude',
  latitude: 'latitude',
  address: 'address',
  name: 'name',
  adcode: 'adcode',
  city: 'city',
  countryCode: 'countryCode',
  country: 'country',
}
```

### valueKeyScope

```ts
;['longitude', 'latitude', 'address', 'name', 'adcode', 'city', 'country', 'countryCode']
```

### ModelValueType

ModelValueType里面的key取决于valueKeyAlias

```ts
interface ModelValueType {
  adcode?: string
  city?: string
  country?: string
  countryCode?: string
  address?: string
  latitude?: number
  longitude?: number
  name?: string
}
```

组件导出以下类型定义

```ts
import type { MapProps } from '@cedar-design/ui'
```

---

Document: llms/zh-CN/components/mention.md

<!-- Source: src/mention/README.md; locale: zh-CN; page: /components/mention/ -->

# Mention

用于在输入中提及某人或某事，常用于发布、聊天或评论功能。

## 基础示例

### 基础用法

用于在输入中提及某人或某事，常用于发布、聊天或评论功能。

Example source: src/mention/__demos__/basic.vue

```vue
<template>
  <c-space direction="column" size="lg" style="width: 100%">
    <c-mention v-model="value" :data="['Bytedance', 'Bytedesign', 'Bytenumner']" placeholder="enter something" />
    <c-mention
      v-model="text"
      :data="['Bytedance', 'Bytedesign', 'Bytenumner']"
      type="textarea"
      placeholder="enter something" />
  </c-space>
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const value = ref('')
const text = ref('')
</script>
```

## 自定义与插槽

### 自定义触发字符

<!-- demo-config-notes:start -->

#### 本组配置对照

| 配置     | 作用                 | 相关示例       |
| -------- | -------------------- | -------------- |
| `data`   | 用于自动补全的数据   | 自定义触发字符 |
| `prefix` | 触发自动补全的关键字 | 自定义触发字符 |

<!-- demo-config-notes:end -->

指定 `prefix` 来自定义触发字符。默认为 `@`，可以自定义为任意字符。

Example source: src/mention/__demos__/prefix.vue

```vue
<template>
  <c-space direction="column" size="lg" style="width: 100%">
    <c-mention :data="['Bytedance', 'Bytedesign', 'Bytenumner']" placeholder="input @" />
    <c-mention :data="['Bytedance', 'Bytedesign', 'Bytenumner']" prefix="#" placeholder="input #" />
    <c-mention :data="['Bytedance', 'Bytedesign', 'Bytenumner']" prefix="$" placeholder="input $" />
  </c-space>
</template>

<script lang="ts" setup>
</script>
```

## 生命周期与边界

### 镜像重定位生命周期

Example source: src/mention/__demos__/mirror-lifecycle.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import Mention from "../index";

const active = ref(true);
const mounted = ref(true);
const disabled = ref(false);
const searches = ref(0);
const value = ref("第一行\n第二行\n第三行\n@al");
</script>

<template>
  <div>
    <c-button html-type="button" @click="active = !active"
      >切换 KeepAlive</c-button
    >
    <c-button html-type="button" @click="mounted = !mounted"
      >卸载／挂载</c-button
    >
    <c-button html-type="button" @click="disabled = !disabled"
      >切换禁用</c-button
    >
    <p>
      搜索通知：{{ searches }}。在文本域滚动后输入
      @al，停用再激活，继续输入检查镜像定位。
    </p>
    <KeepAlive v-if="mounted">
      <Mention
        v-if="active"
        v-model="value"
        type="textarea"
        :disabled="disabled"
        :data="['alice', 'alex']"
        :rows="3"
        @search="searches++"
      />
    </KeepAlive>
  </div>
</template>
```

样式从当前 textarea 所属窗口读取，旧观察器不能跨停用／激活提交；几何及样式读取返回后再次核对，防止重入卸载。停用／卸载的保留输入、弹层事件和 focus／blur 命令无效；禁用时不接受输入或 focus，活动实例仍允许 blur。公开方法签名、颜色和 CSS 变量不变。Maple 无对应 Mention 运行时，不新增移动端副本。

## 加载与等待

### 受控加载

| 属性 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| `loading` | 业务显式控制的加载状态 | `boolean` | `false` |


通过 loading 显式展示等待；普通事件返回值不参与加载。before-* 守卫按其契约管理内部等待状态。

Example source: src/mention/__demos__/loading.vue

```vue
<script setup lang="ts">
import { onBeforeUnmount, ref } from 'vue'
import type { OptionsLoader } from '../../_hooks/use-option-request'
const loading = ref(true)
const requests = new Set<(failed?: boolean) => void>()
const pending = ref(0)
const status = ref('等待数据 / Waiting for data')
const load: OptionsLoader<string> = (query, { signal }) => new Promise((resolve, reject) => {
  const finish = (failed = false) => {
    requests.delete(finish)
    pending.value = requests.size
    signal.removeEventListener('abort', cancel)
    if (failed) reject(new Error('Candidate request failed'))
    else resolve(['Alice', 'Bob'].filter(name => name.toLowerCase().includes(query.toLowerCase())))
  }
  const cancel = () => finish()
  requests.add(finish)
  pending.value = requests.size
  signal.addEventListener('abort', cancel, { once: true })
})
function settle(failed = false) {
  status.value = failed ? '请求失败，可继续输入重试 / Failed; type to retry' : '数据已返回 / Data received'
  ;[...requests].forEach(finish => finish(failed))
}
onBeforeUnmount(() => settle())
</script>
<template>
  <c-space direction="column" style="width: 100%" :size="16">
    <h4>业务控制 / Manual loading</h4>
    <c-switch v-model="loading" aria-label="业务加载状态 / Manual loading" />
    <c-mention edit-mode="direct" :loading="loading" :data="['Alice', 'Bob']" placeholder="单行输入 @ / Single line" />
    <c-mention edit-mode="direct" type="textarea" :loading="loading" :data="['Alice', 'Bob']" placeholder="多行输入 @ / Multiple lines" />
    <p>loading 只控制显示，两种输入框均可继续编辑。普通事件返回 Promise 不会触发等待。Loading does not disable editing or await notification handlers.</p>
    <h4>数据源等待 / Remote candidates</h4>
    <c-mention edit-mode="direct" :data="load" placeholder="输入 @a，手动返回候选数据 / Type @a" @load-error="() => {}" />
    <c-space>
      <c-button :disabled="!pending" @click="settle()">返回数据 / Resolve</c-button>
      <c-button :disabled="!pending" @click="settle(true)">模拟失败 / Reject</c-button>
    </c-space>
    <p role="status">{{ pending ? '请求中，仍可输入 / Pending; editing remains available' : status }}</p>
  </c-space>
</template>
```

## API

### 空值识别与阅读空文案

`empty-values` 用于空值识别，`empty-value` 保留原清空输出；`empty-text` 仅在 `read-pretty` 空内容下展示，默认 `'-'`，字段 > FormItem > Form，自定义 read 插槽优先。显式配置 empty-values 后，内置 required 接入该策略，自定义校验仍收到原值。详见[统一说明](llms/zh-CN/guide/empty-values.md)。

| 参数         | 类型               | 缺省与范围                                            |
| ------------ | ------------------ | ----------------------------------------------------- |
| empty-values | readonly unknown[] | 字段 > FormItem > Form > 组件族默认；完整覆盖，不合并 |
| empty-text   | string             | 字段 > FormItem > Form > '-'；显式 '' 有效            |

以上是字段展示层 API；纯面板不因此新增阅读模式。Form 与 FormItem 提供继承配置。empty-value 的现有类型与默认输出仍按该组件原 API 执行。

### `<mention>` Props

| 参数名                    | 描述                 | 类型                                                                                                       |   默认值    | 版本   |
| ------------------------- | -------------------- | ---------------------------------------------------------------------------------------------------------- | :---------: | :----- |
| model-value **(v-model)** | 绑定值               | `string`                                                                                                   |     `-`     |        |
| default-value             | 默认值（非受控状态） | `string`                                                                                                   |    `''`     |        |
| data                      | 用于自动补全的数据   | `(string \| number \| SelectOptionData \| SelectOptionGroup)[]` / `(query, { signal }) => Array / Promise` | `undefined` |        |
| prefix                    | 触发自动补全的关键字 | `string \| string[]`                                                                                       |    `'@'`    |        |
| split                     | 选中项的前后分隔符   | `string`                                                                                                   |    `' '`    |        |
| type                      | 输入框或文本域       | `'input' \| 'textarea'`                                                                                    |  `'input'`  |        |
| disabled                  | 是否禁用             | `boolean`                                                                                                  |   `false`   |        |
| clearable                 | 是否允许清空输入框   | `boolean`                                                                                                  |   `false`   | 2.23.0 |

### `<mention>` Events

| 事件名 | 描述                                        | 参数                                                          | 版本   |
| ------ | ------------------------------------------- | ------------------------------------------------------------- | :----- |
| change | 值发生改变时触发                            | value: `string`                                               |        |
| search | 动态搜索时触发，2.47.0 版本增加 prefix 参数 | value: `string`<br>prefix: `string`                           |        |
| select | 选择下拉选项时触发                          | value: `string \| number \| Record<string, any> \| undefined` |        |
| clear  | 用户点击清除按钮时触发                      | -                                                             | 2.23.0 |
| focus  | 文本框获取焦点时触发                        | ev: `FocusEvent`                                              | 2.42.0 |
| blur   | 文本框失去焦点时触发                        | ev: `FocusEvent`                                              | 2.42.0 |

### `<mention>` Methods

| 方法名 | 描述             | 参数 | 返回值 | 版本   |
| ------ | ---------------- | ---- | ------ | :----- |
| focus  | 使输入框获取焦点 | -    | -      | 2.24.0 |
| blur   | 使输入框失去焦点 | -    | -      | 2.24.0 |

### `<mention>` Slots

| 插槽名 |   描述   | 参数               | 版本   |
| ------ | :------: | ------------------ | :----- |
| option | 选项内容 | data: `OptionInfo` | 2.13.0 |

### 类型定义

组件导出以下类型定义

```ts
import type { MentionInstance } from "@cedar-design/ui";
```

Mention 复用 Input／Textarea 的排版和间距，测量镜像复制原生输入框计算样式。自定义请覆盖对应输入组件变量；不再提供无效的 mention-font-size、mention-line-height 或 mention-padding-*。

### Form 字段展示与确认

Cedar 使用 edit-mode="click" / "dblclick" 在字段附近打开编辑浮层，Enter/F2 也可进入；取消/Escape 丢弃草稿，确认后提交。readPretty 为独立阅读属性，与 readonly、disabled 分开。

## 配置清空后的值

`empty-value` 指定当前组件已有清空动作的输出；省略时采用该组件默认返回。具体类型以组件 API 为准。它不改变 empty-values 的识别规则，也不改变 Form reset 的初始值。

`empty-value` 可显式设为 `null`（或 `() => null`），清空时原样提交 null；省略时保留组件原默认值。界面把 null 显示为空，不会把普通输入的空字符串自动转成 null。支持弹出编辑的字段中，清空先修改草稿，确认后提交，取消则保留原值。

候选属性 `data` 支持数组或 `(query, { signal }) => 数组/Promise`。加载、取消、过期结果隔离由组件内部处理，失败触发 load-error。单选/多选分组初始化以空字符串查询，搜索型字段在查询变化时调用；树形字段根数据与原有 load-more 子节点懒加载独立。

input 与 textarea 都显示手动 loading 和当前显式 data 加载函数的等待。等待显示不会隐式禁用编辑；search 通知返回 Promise 不启动任务。旧数据请求不会清理新请求的指示器，load-error 保留原始错误。

---

Document: llms/zh-CN/components/menu.md

<!-- Source: src/menu/README.md; locale: zh-CN; page: /components/menu/ -->

# Menu 菜单

用于收纳针对当前对象的临时命令，例如更多操作、右键菜单和按钮的附加操作。选择表单数据请使用 Select；选择层级数据请使用 Cascader。

---

## 基础示例

### 更多操作

使用默认插槽传入触发元素，通过 `options` 定义命令。菜单开启后会为触发元素添加 `c-menu-open` 类名。

Example source: src/menu/__demos__/basic.vue

```vue
<template>
  <c-menu :options="options">
    <c-button variant="tonal" :elevation="false" aria-label="更多操作"><template #icon><c-icon-more /></template></c-button>
  </c-menu>
</template>

<script setup lang="ts">
const options = [
  { label: '编辑', value: 'edit' },
  { label: '复制', value: 'copy' },
  { type: 'divider' },
  { label: '删除', value: 'delete' },
]
</script>
```

## 外观与状态

### 禁用状态

Example source: src/menu/__demos__/disabled.vue

```vue
<template>
  <c-space wrap>
    <c-menu disabled>
      <c-button disabled>菜单禁用</c-button>
      <template #content><c-menu-option label="Option 1" /></template>
    </c-menu>
    <c-menu>
      <c-button>选项禁用</c-button>
      <template #content>
        <c-menu-option label="可用选项" />
        <c-menu-option label="禁用选项" disabled />
        <c-menu-option label="另一个可用选项" />
      </template>
    </c-menu>
  </c-space>
</template>
```

## 选项与层级

### 分组、子菜单与选项内容

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `options` | 命令树 | 分组、子菜单与选项内容、选中与视觉强调 |
| `hide-on-select` | 激活命令后关闭浮层 | 选中与视觉强调 |
| `submenu-trigger` | 各级子菜单的展开方式，对所有层级统一生效 | 选中与视觉强调 |
<!-- demo-config-notes:end -->

比较平级分组、层级菜单和自定义选项内容。展开子菜单或选择选项，观察各自的数据层级；受控选中与外部定位独立展示。

<details>
<summary>配置说明与使用限制</summary>

#### 选项分组

分组标题与选项左对齐，标题行高 20px、上下各 4px 留白（总高 28px）；后续分组额外间隔 8px，首组不添加组间距。

在 `options` 中使用 `{ type: 'group', children }` 分组，不需要额外的分组组件。

#### 多级菜单

带 `children` 的普通选项自动成为子菜单。所有层级的子菜单共用 `submenu-trigger`，默认悬停展开；改成 `'click'` 时同样对所有层级生效，不能逐项配置，避免同一棵菜单里出现两种展开方式。

#### 自定义选项内容

选项的 `label`、`icon`、`extra` 都支持文本、VNode 或接收 `{ option, active, level }` 的渲染函数。需要统一渲染整组数据时，使用 `option-label`、`option-icon`、`option-extra` 作用域插槽。

`active` 只表示当前选项自身是否匹配菜单的选中值。选中子项时，父分支的 `active` 仍为 `false`；后代选中及展开状态只用于组件内部的路径强调，不作为渲染参数公开。根 Menu 使用 `modelValue/defaultValue` 控制选中值、`open/defaultOpen` 控制展开。`MenuOption` 的视觉强调统一使用 `highlight`，不会改变选中值。

</details>

Example source: src/menu/__demos__/structure-comparison.vue

```vue
<script setup lang="ts">
import { h } from "vue"
import { proxyRefs as demoProxyRefs } from 'vue'

const scene1 = demoProxyRefs((() => {

const options = [
  { type: 'group', label: '文件操作', children: [{ label: '新建', value: 'new' }, { label: '打开', value: 'open' }] },
  { type: 'group', label: '编辑操作', children: [{ label: '复制', value: 'copy' }, { label: '粘贴', value: 'paste' }] },
]
return { options }
})())

const scene2 = demoProxyRefs((() => {

const options = [
  { label: '首页', value: 'home' },
  { label: '产品', children: [
    { label: '产品概览', value: 'overview' },
    { label: '解决方案', children: [{ label: '企业版', value: 'enterprise' }, { label: '团队版', value: 'team' }] },
  ] },
  { label: '关于我们', value: 'about' },
]
return { options }
})())

const scene3 = demoProxyRefs((() => {


const icon = (text: string) => h('span', { 'aria-hidden': 'true' }, text)

const options = [
  { label: '编辑', value: 'edit', icon: icon('✎'), extra: '⌘ E' },
  { label: ({ active }: { active: boolean }) => h('strong', active ? '已选中复制' : '复制'), value: 'copy', icon: icon('⧉'), extra: '⌘ C' },
  { label: '删除', value: 'delete', icon: icon('⌫'), extra: '⌫', disabled: true },
]
return { icon, options }
})())
</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="group">
    <h4><span lang="zh-CN">选项分组</span><span lang="en-US">group</span></h4>
    <c-menu :options="scene1.options">
        <c-button>选项分组</c-button>
      </c-menu>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="submenu">
    <h4><span lang="zh-CN">多级菜单</span><span lang="en-US">submenu</span></h4>
    <c-menu :options="scene2.options">
        <c-button>多级菜单</c-button>
      </c-menu>
  </section>

  <section class="demo-comparison-case demo-comparison-case--3" data-comparison-scene="option-content">
    <h4><span lang="zh-CN">自定义选项内容</span><span lang="en-US">option content</span></h4>
    <c-menu :options="scene3.options">
        <c-button>自定义选项内容</c-button>
      </c-menu>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

### 选中与视觉强调

对比渲染函数、作用域插槽和手写 MenuOption。父分支可以有选中路径样式，但 active 仍为 false；highlight 也不会把选项变成选中值。

Example source: src/menu/__demos__/active-rendering.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
import type { MenuRenderContext } from '@cedar-design/ui'

const selectedValue = ref('account')
const status = ({ active }: MenuRenderContext) => active ? '当前项已选中' : '当前项未选中'
const options = [
  { label: '设置', value: 'settings', extra: status, children: [
    { label: '账户', value: 'account', extra: status },
    { label: '通知', value: 'notifications', extra: status },
  ] },
  { label: '帮助', value: 'help', extra: status },
]
const helpLabel = ({ active }: MenuRenderContext) => active ? '帮助（已选中）' : '帮助（未选中，仅视觉强调）'
</script>

<template>
  <p>当前值：{{ selectedValue }}。默认选中“账户”；父分支“设置”处于选中路径，但 active=false。</p>
  <c-space wrap>
    <c-menu v-model="selectedValue" :options="options" :hide-on-select="false" submenu-trigger="click">
      <c-button>渲染函数中的 active</c-button>
    </c-menu>
    <c-menu v-model="selectedValue" :options="options" :hide-on-select="false" submenu-trigger="click">
      <c-button>作用域插槽中的 active</c-button>
      <template #option-extra="{ active }">
        <c-tag :status="active ? 'primary' : 'default'">{{ active ? '当前项已选中' : '当前项未选中' }}</c-tag>
      </template>
    </c-menu>
    <c-menu v-model="selectedValue" :hide-on-select="false">
      <c-button>自定义子项与 highlight</c-button>
      <template #content>
        <c-menu-option value="account">
          <template #default="{ active }">账户：{{ active ? '已选中' : '未选中' }}</template>
        </c-menu-option>
        <c-menu-option value="help" :label="helpLabel" highlight />
      </template>
    </c-menu>
  </c-space>
</template>
```

## 触发与定位

### 右键菜单

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `trigger` | 根菜单触发方式 | 右键菜单、触发方式 |
| `options` | 命令树 | 右键菜单、定位策略 |
| `align-point` | 按触发时的鼠标坐标定位；打开后保持该位置，再次右键时更新 | 右键菜单 |
| `placement` | 浮层相对触发元素的首选方位，默认 bottom；启用默认的 auto-fit-position 时，空间不足会自动翻转并约束到可视区域，不保证最终停在该侧 | 弹出方向 |
| `strategy` | 根菜单及全部子菜单的定位策略 | 定位策略 |
| `submenu-trigger` | 各级子菜单的展开方式，对所有层级统一生效 | 定位策略 |
<!-- demo-config-notes:end -->

在目标区域内点击鼠标右键触发，需要同时设置 `trigger="contextMenu"` 和 `align-point`。菜单固定在本次右键触发的位置，移动鼠标不会改变位置；再次右键时才更新定位点。

Example source: src/menu/__demos__/context-menu.vue

```vue
<script setup lang="ts">
const options = [
  { label: 'Option 1', value: 'option-1' },
  { label: 'Option 2', value: 'option-2' },
  { label: 'Option 3', value: 'option-3' },
]
</script>

<template>
  <c-menu trigger="contextMenu" align-point :options="options" style="display: block">
    <div class="c-menu-context-target">右键点击</div>
  </c-menu>
</template>

<style scoped>
.c-menu-context-target {
  display: flex;
  align-items: center;
  justify-content: center;
  height: 160px;
  background-color: var(--c-sys-color-surface-muted);
}
</style>
```

### 与 SplitButton 组合

SplitButton 已封装按钮与下拉命令菜单的组合，并通过 `MenuOption` 定义附加操作，完整用法见 [SplitButton](llms/zh-CN/components/split-button.md)。

### 触发方式

Example source: src/menu/__demos__/trigger.vue

```vue
<template>
  <c-space wrap>
    <c-menu trigger="click">
      <c-button>点击触发</c-button>
      <template #content>
        <c-menu-option label="Option 1" />
        <c-menu-option label="Option 2" />
      </template>
    </c-menu>
    <c-menu trigger="hover">
      <c-button>悬浮触发</c-button>
      <template #content>
        <c-menu-option label="Option 1" />
        <c-menu-option label="Option 2" />
      </template>
    </c-menu>
  </c-space>
</template>
```

### 弹出方向

Example source: src/menu/__demos__/placement.vue

```vue
<template>
  <c-space wrap>
    <c-menu placement="bottom-start">
      <c-button>Bottom Left</c-button>
      <template #content>
        <c-menu-option>Option 1</c-menu-option>
        <c-menu-option>Option 2</c-menu-option>
        <c-menu-option>Option 3</c-menu-option>
      </template>
    </c-menu>

    <c-menu placement="bottom">
      <c-button>Bottom</c-button>
      <template #content>
        <c-menu-option>Option 1</c-menu-option>
        <c-menu-option>Option 2</c-menu-option>
        <c-menu-option>Option 3</c-menu-option>
      </template>
    </c-menu>

    <c-menu placement="bottom-end">
      <c-button>Bottom Right</c-button>
      <template #content>
        <c-menu-option>Option 1</c-menu-option>
        <c-menu-option>Option 2</c-menu-option>
        <c-menu-option>Option 3</c-menu-option>
      </template>
    </c-menu>

    <c-menu placement="top-start">
      <c-button>Top Left</c-button>
      <template #content>
        <c-menu-option>Option 1</c-menu-option>
        <c-menu-option>Option 2</c-menu-option>
        <c-menu-option>Option 3</c-menu-option>
      </template>
    </c-menu>

    <c-menu placement="top">
      <c-button>Top</c-button>
      <template #content>
        <c-menu-option>Option 1</c-menu-option>
        <c-menu-option>Option 2</c-menu-option>
        <c-menu-option>Option 3</c-menu-option>
      </template>
    </c-menu>

    <c-menu placement="top-end">
      <c-button>Top Right</c-button>
      <template #content>
        <c-menu-option>Option 1</c-menu-option>
        <c-menu-option>Option 2</c-menu-option>
        <c-menu-option>Option 3</c-menu-option>
      </template>
    </c-menu>
  </c-space>
</template>
```

### 定位策略

根菜单和各级子菜单响应式使用同一 `strategy`，默认 `absolute`，可选 `fixed`。切换策略不会改变激活值或主动关闭菜单。`popup-container` 独立控制挂载位置；`fixed` 不保证脱离 transform 祖先的包含块。

Example source: src/menu/__demos__/positioning.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
import type { MenuStrategy } from '@cedar-design/ui'

const strategy = ref<MenuStrategy>('fixed')
const options = [
  { label: '操作', children: [
    { label: '导出', children: [
      { label: 'CSV', value: 'csv' },
      { label: 'JSON', value: 'json' },
    ] },
    { label: '复制', value: 'copy' },
  ] },
]
</script>

<template>
  <c-space direction="column">
    <c-button @click="strategy = strategy === 'fixed' ? 'absolute' : 'fixed'">
      切换定位：{{ strategy }}
    </c-button>
    <c-menu :strategy="strategy" :options="options" submenu-trigger="click">
      <c-button>打开三级菜单</c-button>
      <template #footer>
        <c-button variant="text" @click.stop="strategy = strategy === 'fixed' ? 'absolute' : 'fixed'">
          展开时切换：{{ strategy }}
        </c-button>
      </template>
    </c-menu>
    <small>所有层级继承同一定位策略；挂载容器仍由 popup-container 单独控制。</small>
  </c-space>
</template>
```

### 高度限制

Example source: src/menu/__demos__/popup-height.vue

```vue
<template>
  <c-space wrap>
    <c-menu :popup-max-height="120">
      <c-button>限制为 120px</c-button>
      <template #content>
        <c-menu-option v-for="item in options" :key="item" :label="item" />
      </template>
    </c-menu>
    <c-menu :popup-max-height="false">
      <c-button>不限制高度</c-button>
      <template #content>
        <c-menu-option v-for="item in options" :key="item" :label="item" />
      </template>
    </c-menu>
  </c-space>
</template>

<script lang="ts" setup>
const options = Array.from({ length: 8 }, (_, index) => `Option ${index + 1}`);
</script>
```

## 状态与内容定制

### 选中值与 select 事件

使用 `v-model` 管理当前激活值。激活命令时先触发 `update:modelValue`，再触发 `select(value, option, event)`；`select` 表示激活菜单项，不表示表单值变化。

Example source: src/menu/__demos__/selection.vue

```vue
<template>
  <c-space direction="column">
    <c-menu v-model="active" :options="options" @select="handleSelect">
      <c-button>{{ selectedLabel || "请选择操作" }}</c-button>
    </c-menu>
    <span
      >当前值：{{ active || "-" }}，最近选择：{{ selectedLabel || "-" }}</span
    >
  </c-space>
</template>

<script lang="ts" setup>
import { ref } from "vue";

const active = ref("edit");
const selectedLabel = ref("编辑");
const options = [
  { label: '编辑', value: 'edit' },
  { label: '复制', value: 'copy' },
  { label: '删除', value: 'delete' },
]

const handleSelect = (_value: unknown, option: { label?: string | number }) => {
  selectedLabel.value = String(option.label ?? "");
};
</script>
```

### 受控打开状态

Example source: src/menu/__demos__/controlled.vue

```vue
<template>
  <c-space direction="column">
    <c-button @mousedown.stop @click.stop="open = !open">{{
      open ? "关闭菜单" : "打开菜单"
    }}</c-button>
    <c-menu v-model:open="open">
      <c-button>菜单触发器</c-button>
      <template #content>
        <c-menu-option label="Option 1" />
        <c-menu-option label="Option 2" />
      </template>
    </c-menu>
  </c-space>
</template>

<script lang="ts" setup>
import { ref } from "vue";

const open = ref(false);
</script>
```

### 页脚

Example source: src/menu/__demos__/footer.vue

```vue
<template>
  <c-menu>
    <c-button>页脚</c-button>
    <template #content>
      <c-menu-option>Option 1</c-menu-option>
      <c-menu-option>Option 2</c-menu-option>
    </template>
    <template #footer>
      <div style="padding: 8px 12px">自定义页脚</div>
    </template>
  </c-menu>
</template>
```

## 阅读方向

继承最近的 `dir="ltr|rtl"`，支持运行时切换与局部覆盖。子级沿阅读方向展开；进入子级与返回父级的左右键跟随当前方向，上下键与首尾定位保持顺序并跳过禁用项。挂载到外部容器的菜单继承来源方向，切换方向不改变选中值。

## API

### 主值与默认值

使用普通 `v-model`。`modelValue` 表示选中选项的 value；`defaultValue` 仅在创建时初始化非受控值，后续修改不会重置当前状态。显式绑定值优先，初始化不发出 `update:modelValue`。

### `<Menu>` Props

| 参数名 | 描述 | 类型 | 默认值 |
| --- | --- | --- | :---: |
| options | 命令树 | `MenuOptionData[]` | `[]` |
| field-names | `label/value/children/disabled` 字段映射 | `MenuFieldNames` | `-` |
| model-value **(v-model)** | 当前激活值，用于受控高亮 | `MenuValue` | `-` |
| open **(v-model)** | 浮层是否可见 | `boolean` | `-` |
| default-open | 非受控默认可见状态 | `boolean` | `false` |
| trigger | 根菜单触发方式 | `'hover' \| 'click' \| 'focus' \| 'contextMenu'` | `'click'` |
| submenu-trigger | 各级子菜单的展开方式，对所有层级统一生效 | `'hover' \| 'click'` | `'hover'` |
| placement | 浮层相对触发元素的首选方位，默认 bottom；启用默认的 auto-fit-position 时，空间不足会自动翻转并约束到可视区域，不保证最终停在该侧 | `MenuPlacement` | `'bottom'` |
| `strategy` | 根菜单及全部子菜单的定位策略 | `'absolute' \| 'fixed'` | `'absolute'` |
| popup-container | 浮层挂载容器 | `string \| HTMLElement \| false` | `-` |
| popup-max-height | 默认限制、自定义像素高度或不限高 | `boolean \| number` | `true` |
| hide-on-select | 激活命令后关闭浮层 | `boolean` | `true` |
| auto-fit-popup-width | 浮层宽度跟随触发器 | `boolean` | `false` |
| disabled | 禁用菜单 | `boolean` | `false` |
| align-point | 按触发时的鼠标坐标定位；打开后保持该位置，再次右键时更新 | `boolean` | `false` |

### `MenuOptionData`

| 字段 | 描述 | 类型 |
| --- | --- | --- |
| type | 普通命令、分组或分隔线 | `'item' \| 'group' \| 'divider'` |
| label | 主内容 | `VNodeChild \| (context) => VNodeChild` |
| icon | 前置图标 | `VNodeChild \| (context) => VNodeChild` |
| extra | 右侧辅助内容，如快捷键 | `VNodeChild \| (context) => VNodeChild` |
| value | 激活命令时传给事件的值 | `any` |
| children | 子命令；普通项带 children 时成为子菜单 | `MenuOptionData[]` |
| disabled | 禁用当前项及其后代 | `boolean` |
| show | 是否渲染 | `boolean` |
| ripple | 是否显示点击波纹 | `boolean` |
| props | 透传给命令行元素的 HTML 属性 | `HTMLAttributes` |

渲染上下文为 `{ option, active, level }`。`type: 'group'` 只负责视觉分组，不增加子项层级；`type: 'divider'` 不可聚焦或激活。

### Events

| 事件名 | 描述 | 参数 |
| --- | --- | --- |
| update:model-value | 当前选中值更新请求 | `value: MenuValue` |
| open-change | 浮层显示状态更新请求 | `open: boolean` |
| select | 用户激活菜单项 | `value, option, event` |

### Slots

| 插槽名 | 描述 | 参数 |
| --- | --- | --- |
| default | 触发元素 | - |
| content | 追加手写内容，适合与 `MenuOption` 组合 | - |
| footer | 页脚 | - |
| option-label | 统一渲染选项主内容 | `{ option, active, level }` |
| option-icon | 统一渲染选项图标 | `{ option, active, level }` |
| option-extra | 统一渲染选项右侧内容 | `{ option, active, level }` |

### `<MenuOption>`

保留给 SplitButton 和少量手写 `content` 场景。Props 包含 `label`、`value`、`disabled`、`ripple`、`highlight`；`label` 渲染函数及 `default`、`icon`、`suffix` 插槽统一接收 `{ option, active, level }`；点击时触发 `click`。`highlight` 只控制视觉强调，不提交选中值。分组和子菜单只通过 `options` 描述，不再导出 `MenuGroup`、`MenuSubmenu`。

### 实例与键盘

实例提供 `open()`、`close()`、`resize()`、`setReference(reference?)`。根菜单支持上下键、Home/End、Enter；子菜单通过右键进入、左键或 Escape 返回，Escape 每次只关闭最上层并恢复焦点。

样式类、CSS 变量与内部 DOM 标记统一使用 `c-menu-*` / `--c-menu-*` / `data-menu-*`。

### 状态与时长变量

禁用优先于选中、指针 hover 和键盘焦点。选中后的 hover 使用独立角色，默认继承选中背景；可单独覆盖以增加 hover 反馈。两端的选中背景都直接绘制在选项上。

| Token | Default |
| --- | --- |
| `--c-menu-option-bg-selected-hover` | `var(--c-menu-option-bg-selected)` |

### 数据身份与触发器切换

可重排的数据项应提供稳定、唯一的 `value`，内部 Vue key 由业务值生成；数字 `0`、字符串 `'0'`、布尔值 `false` 保持不同身份。没有显式 value 的分组、分隔符或展示项按原始选项对象维持渲染身份，不新增公开 key 别名。点击另一个已经因 hover 打开的同级触发按钮，会关闭原先的菜单；点击子菜单内部不会误关父级。


### 方位语义与配置入口

MenuPlacement 复用 TriggerPlacement 的十二方位值域；属性和类型均表达浮层相对触发器的首选方位。旧 MenuPosition 已删除。

---

Document: llms/zh-CN/components/message.md

<!-- Source: src/message/README.md; locale: zh-CN; page: /components/message/ -->

# Message 全局提示

用于展示轻量级、非模态的全局反馈。Cedar 与 Maple 共享同一套公开契约、队列、计时和命令式服务；两端分别维护源码和端侧外观。

## 基础示例

### 基本使用

直接调用 `Message(...)` 创建 `default` 提示。

Example source: src/message/__demos__/basic.vue

```vue
<template>
  <c-button @click="handleClick">Info Message</c-button>
</template>
<script lang="ts">
import { defineComponent } from "vue";
import { Message } from "@cedar-design/ui";

export default defineComponent({
  setup() {
    return {
      handleClick() {
        Message.info("This is an info message");
      },
    };
  },
});
</script>
```

## 外观与状态

### 消息状态

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `status` | 语义状态 | 外观组合 |
| `position` | 消息自身在可视区域中的 top/center/bottom 区域，默认 top；不相对触发元素定位 | 外观组合 |
| `closable` | 是否显示关闭按钮 | 外观组合 |
| `duration` | 自动关闭时长（ms），`0` 不自动关闭 | 外观组合 |
| `variant` | 视觉强调层级 | 外观组合 |
<!-- demo-config-notes:end -->

状态统一为 `default / info / success / warning / danger / loading`。函数方法使用 `error`，组件状态使用标准语义 `danger`；普通提示直接调用 `Message(...)`，不提供 `normal` 别名。

Example source: src/message/__demos__/type.vue

```vue
<template>
  <div>
    <c-space>
      <c-button @click="() => Message.info('This is an info message!')"
        >Info Message</c-button
      >
      <c-button
        @click="() => Message.success('This is a success message!')"
        status="success"
        >Success Message
      </c-button>
      <c-button
        @click="() => Message.warning('This is a warning message!')"
        status="warning"
        >Warning Message
      </c-button>
      <c-button
        @click="() => Message.error('This is an error message!')"
        status="danger"
        >Error Message</c-button
      >
    </c-space>
  </div>
  <div style="margin-top: 20px">
    <c-space>
      <c-button @click="() => Message('This is a default message!')"
        >Default Message</c-button
      >
      <c-button
        @click="
          () =>
            Message({
              content: 'This is a default message!',
              icon: renderIcon,
            })
        "
        >Default Message With Icon
      </c-button>
      <c-button @click="handleLoading" status="primary"
        >Loading Message
      </c-button>
    </c-space>
  </div>
</template>

<script lang="ts">
import { defineComponent, h } from "vue";
import { IconExclamationCircleFill } from "@cedar-design/icons-vue";
import { Message } from "@cedar-design/ui";

export default defineComponent({
  setup() {
    const renderIcon = () => h(IconExclamationCircleFill);

    const handleLoading = () => {
      const message = Message.loading("This is a loading message!");
      setTimeout(() => {
        message.close();
        Message.success("Loaded");
      }, 2000);
    };

    return {
      renderIcon,
      handleLoading,
      Message,
    };
  },
});
</script>
```

### 视觉变体

视觉变体与 status 独立：neutral 是中性浮层与状态图标；tonal 是低强调状态色底与深色正文；solid 是高强调实色底与配套前景。Cedar 与 Maple 默认均为 neutral；显式 solid / tonal 保持相同视觉语义。default/loading 的 solid 保留深色底，loading 图标仍表达进度。两端导出 MessageVariant，函数调用、setDefaultOptions 和相同 id 更新都支持 variant。

Example source: src/message/__demos__/variant.vue

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

const variants = ["neutral", "tonal", "solid"] as const;
</script>

<template>
  <c-space wrap>
    <c-button
      @click="Message.success({ content: 'neutral (default)', closable: true })"
      >neutral (default)</c-button
    >
    <c-button
      v-for="variant in variants"
      :key="variant"
      @click="Message.success({ content: variant, variant, closable: true })"
      >{{ variant }}</c-button
    >
  </c-space>
</template>
```

### 外观组合

适用于操作结果的即时反馈。调整变体、状态，用相同数据观察变化。内容保持一致，便于比较不同设置的实际效果。

Example source: src/message/__demos__/appearance-lab.vue

```vue
<script setup lang="ts">
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const open = ref(false);
const __demoAppearance = __demoReactive({
  variant: "neutral",
  status: "default",
});

import { computed as demoComputed, ref as demoRef } from 'vue'
const demoCompareFields = [{"name":"variant","values":["neutral","tonal","solid"]},{"name":"status","values":["default","info","success","warning","danger","loading"]}]
const demoCompareAxis = demoRef("variant")
const demoComparedOptions = demoComputed(() => demoCompareFields.find(field => field.name === demoCompareAxis.value)?.values ?? [])
</script>
<template>
  <c-space direction="column" :size="16">
    <c-form layout="vertical">
      <c-form-item layout="vertical" size="sm" label="variant">
        <c-radio-group
          v-model="__demoAppearance['variant']"
          aria-label="variant"
          :options="[
            { label: 'neutral', value: 'neutral' },
            { label: 'tonal', value: 'tonal' },
            { label: 'solid', value: 'solid' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
      <c-form-item layout="vertical" size="sm" label="status">
        <c-select
          v-model="__demoAppearance['status']"
          :clearable="false"
          :options="[
            { label: 'default', value: 'default' },
            { label: 'info', value: 'info' },
            { label: 'success', value: 'success' },
            { label: 'warning', value: 'warning' },
            { label: 'danger', value: 'danger' },
            { label: 'loading', value: 'loading' },
          ]"
          aria-label="status"
        />
      </c-form-item>
    </c-form>
    <p class="demo-config-comparison-hint"><span lang="zh-CN">选择一个对比维度；其他配置和内容保持一致。输入类示例共享同一个值，便于比较外观。</span><span lang="en-US">Compare one dimension while keeping the other settings and content identical. Input specimens share the same value.</span></p>
<c-radio-group v-model="demoCompareAxis" aria-label="Compare configuration" :options="demoCompareFields.map(field => ({ label: field.name, value: field.name }))" />
<c-space wrap><c-button v-for="sample in demoComparedOptions" :key="String(sample)" @click="() => { __demoAppearance[demoCompareAxis] = sample; open = true }">{{ demoCompareAxis }}={{ sample }}</c-button></c-space>
<c-message
      v-model:open="open"
      status="success"
      position="center"
      closable
      :duration="0"
      v-bind="__demoAppearance"
    >
      Declarative message
      <template #action>
        <c-button size="sm" variant="text" @click="open = false"
          >Close</c-button
        >
      </template>
    </c-message>
  </c-space>
</template>

<style scoped>
.demo-config-comparison { display: grid; grid-template-columns: repeat(auto-fit, minmax(min(100%, 220px), 1fr)); gap: 20px; min-width: 0; max-width: 100%; }
.demo-config-comparison > section { min-width: 0; }
.demo-config-comparison p { margin: 0 0 8px; }
html:not([lang='en-US']) .demo-config-comparison-hint > [lang='en-US'],
html[lang='en-US'] .demo-config-comparison-hint > [lang='zh-CN'] { display: none; }
</style>
```

## 布局与排列

### 位置

两端均支持 `top / center / bottom`。

Example source: src/message/__demos__/location.vue

```vue
<template>
  <c-space>
    <c-button
      @click="() => Message.info({ content: 'This is an info message!' })"
      >Top Message</c-button
    >
    <c-button
      @click="
        () =>
          Message.info({
            content: 'This is an info message!',
            position: 'bottom',
          })
      "
      >Bottom Message</c-button
    >
    <c-button
      @click="
        () =>
          Message.info({
            content: 'This is an info message!',
            position: 'center',
          })
      "
      >Center Message</c-button
    >
  </c-space>
</template>
<script lang="ts">
import { defineComponent } from "vue";
import { Message } from "@cedar-design/ui";

export default defineComponent({
  setup() {
    return {
      Message,
    };
  },
});
</script>
```

## 内容与展示

### 显示时长

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `status` | 语义状态 | 组件调用 |
| `position` | 消息自身在可视区域中的 top/center/bottom 区域，默认 top；不相对触发元素定位 | 组件调用 |
| `closable` | 是否显示关闭按钮 | 组件调用 |
| `duration` | 自动关闭时长（ms），`0` 不自动关闭 | 组件调用 |
<!-- demo-config-notes:end -->

`duration` 单位为毫秒，`0` 表示常驻；`Message.loading(...)` 默认常驻。

展示期限独立于 CSS 进出动效。重启、hover 暂停、清理或卸载使旧计时回调失效，关闭状态在回调执行时再次检查；不会用动效 Token 修改业务展示时长。

KeepAlive 停用取消计时，激活从当前配置完整 duration 重启；停用期间更新、卸载后保留的 restart 不调度。hover 正时长已耗尽时恢复会请求关闭，显式重置为0仍常驻。仅有限正 duration 自动关闭，负数和非有限值不调度。

服务等待真实离场完成再清理和调用 onClosed，不再强制150ms或200ms退出。未挂载就 close/clear 的条目直接清理；此时服务 onClosed 仍报告完成，但组件未产生 open/opened/close 动画事件。业务 duration 与 CSS 过渡时长分开。

减少动效偏好下，独立样式取消根/进出过渡及装饰图标淡入，保留静态定位、颜色和业务展示期限；子图标自身动效仍由Icon规范负责。隔离Less检查不是实际OS验收。

Example source: src/message/__demos__/time.vue

```vue
<template>
  <c-button @click="handleClick">Duration 1000ms</c-button>
</template>
<script lang="ts">
import { defineComponent } from "vue";
import { Message } from "@cedar-design/ui";

export default defineComponent({
  setup() {
    const handleClick = () => {
      Message.info({
        content: "This is an info message!",
        duration: 1000,
      });
    };
    return {
      handleClick,
    };
  },
});
</script>
```

### 更新已有提示

同一挂载容器和位置内，相同 `id` 更新原实例，不创建重复 DOM。仅当 `resetOnUpdate` 为 `true` 时，更新会重新计算完整显示时长。

Example source: src/message/__demos__/update.vue

```vue
<template>
  <c-button @click="handleClick">Update Info Message</c-button>
</template>
<script lang="ts">
import { defineComponent, ref } from "vue";
import { Message } from "@cedar-design/ui";

export default defineComponent({
  setup() {
    const index = ref(0);
    const handleClick = () => {
      Message.info({
        id: "myInfo",
        content: `This is an info message ${index.value++}`,
        duration: 2000,
        resetOnUpdate: true,
      });
    };
    return {
      index,
      handleClick,
    };
  },
});
</script>
```

### 悬停暂停

`pauseOnHover` 会保存剩余时间，鼠标离开后从剩余时间继续，而不是重新开始完整时长。

Example source: src/message/__demos__/pause-on-hover.vue

```vue
<template>
  <c-button @click="handleClick">Reset On Hover</c-button>
</template>
<script lang="ts">
import { defineComponent } from "vue";
import { Message } from "@cedar-design/ui";

export default defineComponent({
  setup() {
    const handleClick = () => {
      Message.info({
        content: "Hover to pause auto close",
        duration: 3000,
        pauseOnHover: true,
      });
    };
    return {
      handleClick,
    };
  },
});
</script>
```

### 组件调用

声明式组件适合由页面状态控制显示，并支持 `icon`、`action` 插槽和完整开关生命周期。

Example source: src/message/__demos__/component.vue

```vue
<script setup lang="ts">
import { ref } from "vue";

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

<template>
  <c-button status="primary" @click="open = true">Open Message</c-button>
  <c-message
    v-model:open="open"
    status="success"
    position="center"
    closable
    :duration="0"
  >
    Declarative message
    <template #action>
      <c-button size="sm" variant="text" @click="open = false">Close</c-button>
    </template>
  </c-message>
</template>
```

## 自定义与插槽

### 自定义图标

Example source: src/message/__demos__/custom-icon.vue

```vue
<template>
  <c-button @click="handleClick">Info Message</c-button>
</template>

<script lang="ts">
import { defineComponent, h } from "vue";
import { IconFaceSmileFill } from "@cedar-design/icons-vue";
import { Message } from "@cedar-design/ui";

export default defineComponent({
  setup() {
    const handleClick = () => {
      Message.info({
        content: "This is an info message!",
        icon: () => h(IconFaceSmileFill),
      });
    };
    return {
      handleClick,
    };
  },
});
</script>
```

## 交互与控制

### 可关闭

Example source: src/message/__demos__/closable.vue

```vue
<template>
  <c-button @click="handleClick">Closeable Message</c-button>
</template>
<script lang="ts">
import { defineComponent } from "vue";
import { Message } from "@cedar-design/ui";

export default defineComponent({
  setup() {
    const handleClick = () => {
      Message.info({
        content: "This is an info message!",
        closable: true,
      });
    };
    return {
      handleClick,
    };
  },
});
</script>
```

### Loading 与多实例

Example source: src/message/__demos__/loading.vue

```vue
<template>
  <c-space>
    <c-button status="primary" @click="handleLoading">Loading</c-button>
  </c-space>
</template>

<script lang="ts">
import { defineComponent } from "vue";
import { Message } from "@cedar-design/ui";

export default defineComponent({
  setup() {
    const handleLoading = () => {
      const message = Message.loading("This is a loading message");
      setTimeout(() => {
        message.close();
        Message.success("Loaded");
      }, 2000);
    };

    return {
      handleLoading,
    };
  },
});
</script>
```

Example source: src/message/__demos__/multiple.vue

```vue
<template>
  <c-button @click="handleClick">Multiple Messages</c-button>
</template>
<script lang="ts">
import { defineComponent } from "vue";
import { Message } from "@cedar-design/ui";

export default defineComponent({
  setup() {
    const handleClick = () => {
      const message1 = Message.info("Message 1");
      Message.success("Message 2");
      Message.warning("Message 3");
      setTimeout(() => {
        message1.close();
      }, 1000);
    };
    return {
      handleClick,
    };
  },
});
</script>
```

## 阅读方向

继承最近的 `dir="ltr|rtl"`，支持运行时切换与局部覆盖。内容、图标与关闭按钮间距随阅读方向排列；方向切换不改变消息类型、计时或关闭语义。函数式调用遵循显式配置或文档方向。

## API

### Props / MessageOptions

| 属性                  | 说明                                   | 类型                                                         | 默认值          |
| --------------------- | -------------------------------------- | ------------------------------------------------------------ | --------------- |
| open / `v-model:open` | 是否显示（组件）                       | `boolean`                                                    | `false`         |
| id                    | 队列内唯一标识，相同 id 更新原实例     | `string \| number`                                           | 自动生成        |
| status                | 语义状态                               | `default \| info \| success \| warning \| danger \| loading` | `default`       |
| variant | 视觉强调层级 | `neutral \| tonal \| solid` | `neutral` |
| position              | 消息自身在可视区域中的 top/center/bottom 区域，默认 top；不相对触发元素定位 | `top \| center \| bottom`                                    | `top`           |
| content               | 内容                                   | `MessageContent`                                             | -               |
| icon                  | 自定义图标                             | `MessageContent`                                             | -               |
| action                | 操作区内容                             | `MessageContent`                                             | -               |
| duration              | 自动关闭时长（ms），`0` 不自动关闭     | `number`                                                     | `3000`          |
| showIcon              | 是否显示状态图标                       | `boolean`                                                    | `true`          |
| closable              | 是否显示关闭按钮                       | `boolean`                                                    | `false`         |
| pauseOnHover          | 悬停时暂停并保存剩余时间               | `boolean`                                                    | `false`         |
| resetOnUpdate         | 相同 id 更新时是否重置完整时长         | `boolean`                                                    | `false`         |
| closeButtonAriaLabel  | 关闭按钮无障碍名称                     | `string`                                                     | `Close message` |
| popupContainer        | 挂载容器；函数调用按容器和位置隔离队列 | `string \| HTMLElement \| false`                             | `body`          |

函数选项另支持 `onOpen / onOpened / onClose / onClosed`，关闭回调接收当前 `id`。

### 事件

`update:open`、`open`、`opened`、`close`、`closed`；每次开关周期各触发一次。

### 方法

| 方法                                              | 说明                     |
| ------------------------------------------------- | ------------------------ |
| `Message(options \| string)`                      | 打开默认提示             |
| `Message.info/success/warning/error/loading(...)` | 打开对应状态提示         |
| `Message.clear(position?)`                        | 清空全部或指定位置的提示 |
| `Message.setDefaultOptions(options)`              | 设置后续调用的默认值     |
| `Message.resetDefaultOptions()`                   | 恢复默认值               |

返回 `{ close() }`；重复调用 `close()` 不会重复触发关闭生命周期。

### 插槽

`default`、`icon`、`action`。

## 公开 CSS 变量

视觉变体与 status 独立：neutral 是中性浮层与状态图标；tonal 是低强调状态色底与深色正文；solid 是高强调实色底与配套前景。Cedar 与 Maple 默认均为 neutral；显式 solid / tonal 保持相同视觉语义。default/loading 的 solid 保留深色底，loading 图标仍表达进度。两端导出 MessageVariant，函数调用、setDefaultOptions 和相同 id 更新都支持 variant。

颜色命名为 `--c-message-{variant}-{status}-{bg|content-color|icon-color|border-color|close-color}`。bg 控制面板底，content-color 控制正文与未单独设色的 action，icon-color 控制状态图标，border-color 控制边线，close-color 控制关闭按钮。自定义背景时需要同时验证三个前景。几何变量保留端侧密度，不要求两端强行同值。变量必须作用于实际 Teleport 容器祖先。

| 变量 | 默认值 |
| --- | --- |
| `--c-message-neutral-default-bg` | `var(--c-sys-color-surface-overlay)` |
| `--c-message-neutral-default-content-color` | `var(--c-sys-color-content-primary)` |
| `--c-message-neutral-default-icon-color` | `var(--c-sys-color-content-primary)` |
| `--c-message-neutral-default-border-color` | `var(--c-sys-color-border-default)` |
| `--c-message-neutral-default-close-color` | `var(--c-sys-color-content-secondary)` |
| `--c-message-neutral-info-bg` | `var(--c-sys-color-surface-overlay)` |
| `--c-message-neutral-info-content-color` | `var(--c-sys-color-content-primary)` |
| `--c-message-neutral-info-icon-color` | `var(--c-sys-color-content-info)` |
| `--c-message-neutral-info-border-color` | `var(--c-sys-color-border-default)` |
| `--c-message-neutral-info-close-color` | `var(--c-sys-color-content-secondary)` |
| `--c-message-neutral-success-bg` | `var(--c-sys-color-surface-overlay)` |
| `--c-message-neutral-success-content-color` | `var(--c-sys-color-content-primary)` |
| `--c-message-neutral-success-icon-color` | `var(--c-sys-color-content-success)` |
| `--c-message-neutral-success-border-color` | `var(--c-sys-color-border-default)` |
| `--c-message-neutral-success-close-color` | `var(--c-sys-color-content-secondary)` |
| `--c-message-neutral-warning-bg` | `var(--c-sys-color-surface-overlay)` |
| `--c-message-neutral-warning-content-color` | `var(--c-sys-color-content-primary)` |
| `--c-message-neutral-warning-icon-color` | `var(--c-sys-color-content-warning)` |
| `--c-message-neutral-warning-border-color` | `var(--c-sys-color-border-default)` |
| `--c-message-neutral-warning-close-color` | `var(--c-sys-color-content-secondary)` |
| `--c-message-neutral-danger-bg` | `var(--c-sys-color-surface-overlay)` |
| `--c-message-neutral-danger-content-color` | `var(--c-sys-color-content-primary)` |
| `--c-message-neutral-danger-icon-color` | `var(--c-sys-color-content-danger)` |
| `--c-message-neutral-danger-border-color` | `var(--c-sys-color-border-default)` |
| `--c-message-neutral-danger-close-color` | `var(--c-sys-color-content-secondary)` |
| `--c-message-neutral-loading-bg` | `var(--c-sys-color-surface-overlay)` |
| `--c-message-neutral-loading-content-color` | `var(--c-sys-color-content-primary)` |
| `--c-message-neutral-loading-icon-color` | `var(--c-sys-color-content-brand)` |
| `--c-message-neutral-loading-border-color` | `var(--c-sys-color-border-default)` |
| `--c-message-neutral-loading-close-color` | `var(--c-sys-color-content-secondary)` |
| `--c-message-tonal-default-bg` | `var(--c-sys-color-surface-muted)` |
| `--c-message-tonal-default-content-color` | `var(--c-sys-color-content-primary)` |
| `--c-message-tonal-default-icon-color` | `var(--c-sys-color-content-primary)` |
| `--c-message-tonal-default-border-color` | `transparent` |
| `--c-message-tonal-default-close-color` | `var(--c-sys-color-content-primary)` |
| `--c-message-tonal-info-bg` | `rgba(var(--c-blue-6), 0.12)` |
| `--c-message-tonal-info-content-color` | `var(--c-sys-color-content-primary)` |
| `--c-message-tonal-info-icon-color` | `var(--c-sys-color-content-info)` |
| `--c-message-tonal-info-border-color` | `transparent` |
| `--c-message-tonal-info-close-color` | `var(--c-sys-color-content-primary)` |
| `--c-message-tonal-success-bg` | `var(--c-color-success-light-1)` |
| `--c-message-tonal-success-content-color` | `var(--c-sys-color-content-primary)` |
| `--c-message-tonal-success-icon-color` | `var(--c-sys-color-content-success)` |
| `--c-message-tonal-success-border-color` | `transparent` |
| `--c-message-tonal-success-close-color` | `var(--c-sys-color-content-primary)` |
| `--c-message-tonal-warning-bg` | `var(--c-color-warning-light-1)` |
| `--c-message-tonal-warning-content-color` | `var(--c-sys-color-content-primary)` |
| `--c-message-tonal-warning-icon-color` | `var(--c-sys-color-content-warning)` |
| `--c-message-tonal-warning-border-color` | `transparent` |
| `--c-message-tonal-warning-close-color` | `var(--c-sys-color-content-primary)` |
| `--c-message-tonal-danger-bg` | `var(--c-color-danger-light-1)` |
| `--c-message-tonal-danger-content-color` | `var(--c-sys-color-content-primary)` |
| `--c-message-tonal-danger-icon-color` | `var(--c-sys-color-content-danger)` |
| `--c-message-tonal-danger-border-color` | `transparent` |
| `--c-message-tonal-danger-close-color` | `var(--c-sys-color-content-primary)` |
| `--c-message-tonal-loading-bg` | `var(--c-color-primary-light-1)` |
| `--c-message-tonal-loading-content-color` | `var(--c-sys-color-content-primary)` |
| `--c-message-tonal-loading-icon-color` | `var(--c-sys-color-content-brand)` |
| `--c-message-tonal-loading-border-color` | `transparent` |
| `--c-message-tonal-loading-close-color` | `var(--c-sys-color-content-primary)` |
| `--c-message-solid-default-bg` | `#333` |
| `--c-message-solid-default-content-color` | `var(--c-sys-color-content-on-dark)` |
| `--c-message-solid-default-icon-color` | `var(--c-sys-color-content-on-dark)` |
| `--c-message-solid-default-border-color` | `transparent` |
| `--c-message-solid-default-close-color` | `var(--c-sys-color-content-on-dark)` |
| `--c-message-solid-info-bg` | `var(--c-sys-color-status-info)` |
| `--c-message-solid-info-content-color` | `var(--c-sys-color-content-on-bright)` |
| `--c-message-solid-info-icon-color` | `var(--c-sys-color-content-on-bright)` |
| `--c-message-solid-info-border-color` | `transparent` |
| `--c-message-solid-info-close-color` | `var(--c-sys-color-content-on-bright)` |
| `--c-message-solid-success-bg` | `var(--c-sys-color-status-success)` |
| `--c-message-solid-success-content-color` | `var(--c-sys-color-content-on-bright)` |
| `--c-message-solid-success-icon-color` | `var(--c-sys-color-content-on-bright)` |
| `--c-message-solid-success-border-color` | `transparent` |
| `--c-message-solid-success-close-color` | `var(--c-sys-color-content-on-bright)` |
| `--c-message-solid-warning-bg` | `var(--c-sys-color-status-warning)` |
| `--c-message-solid-warning-content-color` | `var(--c-sys-color-content-on-bright)` |
| `--c-message-solid-warning-icon-color` | `var(--c-sys-color-content-on-bright)` |
| `--c-message-solid-warning-border-color` | `transparent` |
| `--c-message-solid-warning-close-color` | `var(--c-sys-color-content-on-bright)` |
| `--c-message-solid-danger-bg` | `var(--c-sys-color-status-danger)` |
| `--c-message-solid-danger-content-color` | `var(--c-sys-color-content-on-bright)` |
| `--c-message-solid-danger-icon-color` | `var(--c-sys-color-content-on-bright)` |
| `--c-message-solid-danger-border-color` | `transparent` |
| `--c-message-solid-danger-close-color` | `var(--c-sys-color-content-on-bright)` |
| `--c-message-solid-loading-bg` | `#333` |
| `--c-message-solid-loading-content-color` | `var(--c-sys-color-content-on-dark)` |
| `--c-message-solid-loading-icon-color` | `var(--c-sys-color-content-on-dark)` |
| `--c-message-solid-loading-border-color` | `transparent` |
| `--c-message-solid-loading-close-color` | `var(--c-sys-color-content-on-dark)` |
| `--c-message-wrapper-margin-top` | `var(--c-spacing-12)` |
| `--c-message-wrapper-margin-bottom` | `var(--c-spacing-12)` |
| `--c-message-wrapper-padding-horizontal` | `var(--c-spacing-5)` |
| `--c-message-z-index` | `var(--c-z-index-message)` |
| `--c-message-padding-top` | `var(--c-spacing-5)` |
| `--c-message-padding-bottom` | `var(--c-spacing-5)` |
| `--c-message-padding-left` | `var(--c-spacing-7)` |
| `--c-message-padding-right` | `var(--c-spacing-7)` |
| `--c-message-margin-bottom` | `var(--c-spacing-7)` |
| `--c-message-border-radius` | `var(--c-border-radius-sm)` |
| `--c-message-icon-font-size` | `20px` |
| `--c-message-content-font-size` | `var(--c-font-size-body-3)` |
| `--c-message-icon-margin-right` | `var(--c-spacing-4)` |
| `--c-message-box-shadow` | `var(--c-shadow2-down)` |
| `--c-message-border-width` | `1px` |
| `--c-message-border-style` | `solid` |
| `--c-message-close-icon-font-size` | `12px` |
| `--c-message-close-btn-margin-left` | `var(--c-spacing-4)` |
| `--c-message-close-icon-hover-size` | `20px` |
| `--c-message-close-icon-hover-opacity` | `0.08` |
| `--c-message-transition-duration` | `var(--c-transition-duration-1)` |
| `--c-message-transition-duration-icon` | `var(--c-transition-duration-4)` |
| `--c-message-transition-timing-function` | `var( --c-transition-timing-function-linear )` |
| `--c-message-transition-timing-function-icon` | `var( --c-transition-timing-function-overshoot )` |

close/closed 通知回调抛错不会保留已关闭项目或空管理器宿主，资源清理独立于通知回调执行。

---

Document: llms/zh-CN/components/nav-menu.md

<!-- Source: src/nav-menu/README.md; locale: zh-CN; page: /components/nav-menu/ -->

# NavMenu 导航菜单

通过 `options` 定义导航结构，支持纵向展开、横向下拉及横向溢出收纳。子菜单由 `children` 自动产生，也可用 `NavMenu.Item` 定义独立一级入口；无需 SubMenu/ItemGroup 组件。

### 程序化滚动的生命周期

`scrollTo(key)` 展开路径后等待渲染，再以 nearest 对齐原生定位；返回 `Promise<void>`。连续调用只执行最新仍有效的请求。禁用、options／fieldNames／mode／responsive／折叠配置变化、KeepAlive 停用及卸载使旧请求失效；重新激活后请显式发起新请求，不会重放旧滚动。取消不回滚已经执行的浏览器滚动，不新增 CSS duration Token 或公共取消方法。

NavMenu 有两种清晰的使用方式：导航树使用 `options`，业务筛选等独立入口使用 `NavMenu.Item`。下面先介绍常用导航，再逐步进入层级、响应式和高级定制。

## 基础示例

### 基础导航

#### 纵向导航

最常见的侧边导航。通过 `options` 和 `children` 声明层级，使用 `v-model` 获取当前页面。

Example source: src/nav-menu/__demos__/basic.vue

```vue
<template>
  <div class="nav-menu-demo">
    <c-nav-menu v-model="selected" :options="options" />
    <p>当前页面：{{ selected }}</p>
  </div>
</template>

<script setup lang="ts">
import { ref } from "vue";
import { options } from "./data";

const selected = ref<string | number | null>(0);
</script>

<style scoped>
.nav-menu-demo {
  width: 240px;
  max-width: 100%;
}
</style>
```

#### 横向导航

用于页面顶部导航。一级菜单横向排列，含有 `children` 的入口通过浮层展示下级菜单。

Example source: src/nav-menu/__demos__/horizontal-sub-menu.vue

```vue
<template>
  <div class="nav-menu-demo">
    <c-nav-menu v-model="selected" mode="horizontal" :options="options" />
    <p>当前页面：{{ selected }}</p>
  </div>
</template>

<script setup lang="ts">
import { ref } from "vue";
import { options } from "./data";

const selected = ref<string | number | null>("cloud");
</script>

<style scoped>
.nav-menu-demo {
  min-height: 180px;
}
</style>
```

## 外观与布局

### 外观

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `options` | 导航结构 | 外观 |
| `size` | 尺寸 | 外观 |
| `mode` | 导航方向 | 外观 |
<!-- demo-config-notes:end -->

#### 尺寸

NavMenu 支持 `xs`、`sm`、`md`、`lg` 和 `xl` 五档组件尺寸。

Example source: src/nav-menu/__demos__/size.vue

```vue
<template>
  <div v-for="size in sizes" :key="size" style="margin-bottom: 16px">
    <p>尺寸：{{ size }}</p>
    <c-nav-menu :options="options" :size="size" mode="horizontal" />
  </div>
</template>
<script setup lang="ts">
import { options } from './data'
const sizes = ['xs', 'sm', 'md', 'lg', 'xl'] as const
</script>
```

## 层级与响应式

### 层级与响应式

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `options` | 导航结构 | 层级与响应式 |
| `accordion` | 同层只展开一个分支 | 层级与响应式 |
| `default-value` | 非受控初始选中值 | 层级与响应式 |
| `collapsed` | 折叠状态，支持 v-model:collapsed | 层级与响应式 |
| `mode` | 导航方向 | 层级与响应式 |
<!-- demo-config-notes:end -->

#### 多级菜单与手风琴

`accordion` 让同一层级只展开一个分支；初始选中深层页面时，菜单会自动展开其祖先路径。

Example source: src/nav-menu/__demos__/sub-menu.vue

```vue
<template>
  <c-nav-menu :options="options" accordion default-value="compute" />
</template>
<script setup lang="ts">
import { options } from './data'

</script>
```

#### 折叠菜单

适合空间有限的侧边栏。折叠后保留图标，分支改由浮层展开。

Example source: src/nav-menu/__demos__/collapsed.vue

```vue
<template>
  <div class="nav-menu-demo">
    <c-button @click="collapsed = !collapsed">{{
      collapsed ? "展开菜单" : "折叠菜单"
    }}</c-button>
    <c-nav-menu
      :options="options"
      :collapsed="collapsed"
      default-value="cloud"
    />
  </div>
</template>

<script setup lang="ts">
import { ref } from "vue";
import { options } from "./data";

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

<style scoped>
.nav-menu-demo {
  display: grid;
  justify-items: start;
  gap: 12px;
  width: 240px;
  max-width: 100%;
}

.nav-menu-demo :deep(.c-nav-menu) {
  width: 100%;
}
</style>
```

#### 横向溢出收纳

横向空间不足时，末尾菜单自动收入“更多”。可拖动示例容器右下角观察变化。

Example source: src/nav-menu/__demos__/breakpoint.vue

```vue
<template>
  <div class="nav-menu-demo">
    <p>拖动虚线容器右下角，观察菜单项收入“更多”。</p>
    <div class="nav-menu-demo__resizable">
      <c-nav-menu :options="options" mode="horizontal" />
    </div>
  </div>
</template>

<script setup lang="ts">
import { options } from "./data";
</script>

<style scoped>
.nav-menu-demo p {
  margin-top: 0;
}

.nav-menu-demo__resizable {
  width: 520px;
  max-width: 100%;
  min-width: 240px;
  min-height: 180px;
  overflow: auto;
  resize: horizontal;
  border-right: 1px dashed var(--c-color-border-2);
  border-bottom: 1px dashed var(--c-color-border-2);
}
</style>
```

## 导航入口与业务面板

### 独立入口与业务面板

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `mode` | 导航方向 | 独立入口与业务面板 |
| `active-item` | 受控的具名 NavMenu.Item 激活项，支持 v-model:active-item | 独立入口与业务面板 |
<!-- demo-config-notes:end -->

`NavMenu.Item` 适合分类、地区和高级筛选等独立入口。它有自己的值和展开状态，不参与导航树的互斥选择。

#### 横向筛选栏

同时展示普通下拉、横向通栏选项和自定义筛选面板，是顶部业务导航的完整示例。

Example source: src/nav-menu/__demos__/items-horizontal.vue

```vue
<script setup lang="ts">
import { computed, ref } from 'vue'
import type { NavMenuKey, NavMenuOption } from '..'

const category = ref<NavMenuKey | null>(null)
const region = ref<NavMenuKey | null>(null)
const keyword = ref('')
const appliedKeyword = ref('')
const categories: NavMenuOption[] = [
  { key: 'all', label: '全部分类' },
  { key: 'design', label: '设计资源' },
  { key: 'development', label: '开发工具' },
]
const regions: NavMenuOption[] = [
  { key: 'all', label: '全部地区' },
  { key: 'east', label: '华东' },
  { key: 'south', label: '华南' },
  { key: 'north', label: '华北' },
]
const categoryLabel = computed(() => categories.find((item) => item.key === category.value)?.label ?? '未选择')
const regionLabel = computed(() => regions.find((item) => item.key === region.value)?.label ?? '未选择')
function resetFilters(close: () => void) {
  keyword.value = ''
  appliedKeyword.value = ''
  close()
}
function applyFilters(close: () => void) {
  appliedKeyword.value = keyword.value.trim()
  close()
}
</script>
<template>
  <div>
    <c-nav-menu mode="horizontal">
      <c-nav-menu-item v-model="category" label="分类" :options="categories" />
      <c-nav-menu-item
        v-model="region"
        label="地区"
        :options="regions"
        options-mode="horizontal"
        popup-layout="full-width"
      />
      <c-nav-menu-item label="更多筛选" :highlight="!!appliedKeyword" popup-layout="full" :hide-on-select="false">
        <template #content="{ close }">
          <div style="height: 100%; display: flex; flex-direction: column; gap: 16px">
            <div style="flex: 1; min-height: 0; overflow-y: auto">
              <c-space direction="column" style="width: 100%">
                <strong>按关键词筛选</strong>
                <c-input v-model="keyword" placeholder="输入资源名称" aria-label="资源名称" />
              </c-space>
            </div>
            <c-space>
              <c-button @click="resetFilters(close)">重置</c-button>
              <c-button @click="applyFilters(close)">应用</c-button>
            </c-space>
          </div>
        </template>
      </c-nav-menu-item>
    </c-nav-menu>
    <p aria-live="polite">分类：{{ categoryLabel }}；地区：{{ regionLabel }}；关键词：{{ appliedKeyword || '不限' }}</p>
  </div>
</template>
```

#### 纵向工作台

页面入口负责互斥高亮，项目选择和高级筛选独立管理；全高面板从菜单右侧展开。

Example source: src/nav-menu/__demos__/items-vertical.vue

```vue
<script setup lang="ts">
import { computed, ref } from 'vue'
import type { NavMenuKey, NavMenuOption } from '../types'

const section = ref<NavMenuKey | null>('overview')
const project = ref<NavMenuKey | null>(null)
const keyword = ref('')
const appliedKeyword = ref('')
const projects: NavMenuOption[] = [
  { key: 'website', label: '官网改版' },
  { key: 'dashboard', label: '数据平台' },
  { key: 'archived', label: '已归档项目', disabled: true },
]
const projectLabel = computed(() => projects.find(item => item.key === project.value)?.label ?? '未选择')
</script>

<template>
  <div class="vertical-items-demo">
    <c-nav-menu v-model:active-item="section" mode="vertical" class="vertical-items-demo__menu">
      <c-nav-menu-item label="工作概览" name="overview" />
      <c-nav-menu-item label="我的任务" name="tasks" />
      <c-nav-menu-item
        v-model="project"
        label="选择项目"
        :options="projects"
        options-mode="vertical"
        placement="right-start"
      />
      <c-nav-menu-item
        label="高级筛选"
        :highlight="!!appliedKeyword"
        popup-layout="full-height"
        placement="right-start"
        :popup-style="{ width: 'min(360px, 100vw)' }"
      >
        <template #content="{ close }">
          <c-space direction="column" style="width: 100%; height: 100%">
            <h3>任务筛选</h3>
            <p>应用后高亮入口，保留“高级筛选”标题。</p>
            <c-input v-model="keyword" placeholder="输入任务关键词" aria-label="任务关键词" />
            <c-space>
              <c-button @click="appliedKeyword = keyword.trim(); close()">应用</c-button>
              <c-button @click="keyword = ''; appliedKeyword = ''; close()">重置</c-button>
              <c-button @click="close()">关闭</c-button>
            </c-space>
          </c-space>
        </template>
      </c-nav-menu-item>
    </c-nav-menu>
    <div aria-live="polite">
      <h3>{{ section === 'overview' ? '工作概览' : '我的任务' }}</h3>
      <p>当前项目：{{ projectLabel }}</p>
      <p>关键词：{{ appliedKeyword || '不限' }}</p>
      <p>页面入口互斥选中，项目和高级筛选独立控制。</p>
    </div>
  </div>
</template>

<style scoped>
.vertical-items-demo { display: flex; flex-wrap: wrap; gap: 24px; align-items: flex-start; }
.vertical-items-demo__menu { width: 200px; max-width: 100%; flex: none; }
</style>
```

#### 入口状态与视觉强调

通过插槽直接显示业务 `active` 和面板 `open`。独立入口匹配有效选项时才 active；`highlight` 可以单独覆盖外观。具名入口只在选择叶子项后更新 activeItem，打开面板不会提前激活。

Example source: src/nav-menu/__demos__/entry-state.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
import type { NavMenuKey } from '..'

const value = ref<NavMenuKey | null>(null)
const activeItem = ref<NavMenuKey | null>(null)
const highlight = ref<boolean | undefined>(undefined)
const options = [{ key: 0, label: '数字零' }, { key: '', label: '空字符串' }, { key: 'account', label: '账户' }]
const highlightText = () => highlight.value === undefined ? '跟随业务 active' : String(highlight.value)
</script>

<template>
  <c-space direction="column">
    <c-space wrap>
      <c-button @click="highlight = undefined">跟随业务状态</c-button>
      <c-button @click="highlight = true">强制强调</c-button>
      <c-button @click="highlight = false">取消强调</c-button>
      <c-button @click="value = null">清空主值</c-button>
      <c-button @click="value = 'missing'">设为未匹配值</c-button>
    </c-space>
    <p>独立入口主值：{{ JSON.stringify(value) }}；highlight：{{ highlightText() }}。</p>
    <c-nav-menu mode="horizontal" class="entry-state-menu">
      <c-nav-menu-item v-model="value" :options="options" :highlight="highlight">
        <template #label="{ active, open }">独立入口 active={{ active }} / open={{ open }}</template>
      </c-nav-menu-item>
    </c-nav-menu>
    <p>具名当前入口：{{ activeItem ?? '无' }}。只打开面板不会改变 activeItem；选择叶子项后才切换。</p>
    <c-nav-menu v-model:active-item="activeItem" mode="horizontal" class="entry-state-menu">
      <c-nav-menu-item name="first" :options="options">
        <template #label="{ active, open }">入口一 active={{ active }} / open={{ open }}</template>
      </c-nav-menu-item>
      <c-nav-menu-item name="second" :options="options">
        <template #label="{ active, open }">入口二 active={{ active }} / open={{ open }}</template>
      </c-nav-menu-item>
    </c-nav-menu>
  </c-space>
</template>

<style scoped>
.entry-state-menu {
  width: 100%;
  min-width: 0;
}
</style>
```

#### 标题更新策略

Item 的标题默认跟随选中项，也可以通过 `#label` 保持固定标题，或把选中值与显示标题分开管理。高亮状态可以由根菜单统一管理，也可以由每个 Item 独立管理。

##### 统一激活

为 Item 设置唯一 `name`，再通过根菜单的 `v-model:active-item` 统一保持单选高亮。打开一级入口只展开面板，不会提前激活；选择叶子节点后才更新当前高亮项，每个面板的内部值仍独立保留。确实需要初始高亮时，可以显式设置 `active-item` 或 `default-active-item`。

Example source: src/nav-menu/__demos__/item-label.vue

```vue
<script setup lang="ts">
import { computed, ref } from "vue";
import type { NavMenuKey } from "../types";

const options = [
  { key: 0, label: "全部分类" },
  { key: "design", label: "设计" },
  { key: "development", label: "开发" },
];
const activeItem = ref<NavMenuKey | null>(null);
const automatic = ref<NavMenuKey | null>(null);
const fixed = ref<NavMenuKey | null>(null);
const manual = ref<NavMenuKey | null>(null);
const manualLabel = ref("手动标题");
const appliedValue = ref<NavMenuKey | null>(null);
const automaticLabel = computed(
  () =>
    options.find((option) => option.key === automatic.value)?.label ?? "未选择",
);
const fixedLabel = computed(
  () => options.find((option) => option.key === fixed.value)?.label ?? "未选择",
);
const selectedLabel = computed(
  () =>
    options.find((option) => option.key === manual.value)?.label ?? "未选择",
);
const pending = computed(() => manual.value !== appliedValue.value);

function applyLabel() {
  if (manual.value === null) return;
  manualLabel.value = `当前：${selectedLabel.value}`;
  appliedValue.value = manual.value;
}

function reset() {
  manual.value = appliedValue.value = null;
  manualLabel.value = "手动标题";
}
</script>

<template>
  <div class="item-label-demo">
    <c-nav-menu v-model:active-item="activeItem" mode="horizontal">
      <c-nav-menu-item
        v-model="automatic"
        name="automatic"
        label="自动标题"
        :options="options"
      />
      <c-nav-menu-item v-model="fixed" name="fixed" :options="options">
        <template #label>固定标题</template>
      </c-nav-menu-item>
      <c-nav-menu-item v-model="manual" name="manual" :options="options">
        <template #label>{{ manualLabel }}</template>
      </c-nav-menu-item>
    </c-nav-menu>

    <div class="item-label-demo__status" aria-live="polite">
      <p>
        <strong>自动标题：</strong>选择后入口直接显示“{{ automaticLabel }}”。
      </p>
      <p>
        <strong>固定标题：</strong>入口始终显示“固定标题”，当前选择“{{
          fixedLabel
        }}”。
      </p>
      <p>
        <strong>手动标题：</strong>当前选择“{{ selectedLabel }}”，入口显示“{{
          manualLabel
        }}”。
        <span v-if="pending">选择尚未应用到标题。</span>
      </p>
    </div>

    <c-space wrap>
      <c-button :disabled="!pending || manual === null" @click="applyLabel">
        {{ pending ? `应用手动标题：${selectedLabel}` : "手动标题已同步" }}
      </c-button>
      <c-button @click="reset">重置手动标题</c-button>
    </c-space>

    <p class="item-label-demo__tip">
      当前激活入口：{{ activeItem ?? "暂无" }}。打开入口不会激活，选择叶子节点后才会统一切换高亮；各面板内部数据仍各自保留。
    </p>
  </div>
</template>

<style scoped>
.item-label-demo {
  display: grid;
  grid-template-columns: minmax(0, 1fr);
  min-width: 0;
  gap: 16px;
  min-height: 220px;
}

.item-label-demo__status {
  display: grid;
  gap: 8px;
}

.item-label-demo__status p,
.item-label-demo__tip {
  margin: 0;
}

.item-label-demo__tip {
  color: var(--c-color-text-3);
}
</style>
```

##### 独立激活

不设置 `name` 时，每个 Item 根据自己的值独立高亮，适合多个筛选条件同时生效。下例初始同时选中了分类和地区，因此两个入口都会高亮；清空其中一项不会影响另一项。

Example source: src/nav-menu/__demos__/item-label-independent.vue

```vue
<script setup lang="ts">
import { computed, ref } from 'vue'
import type { NavMenuKey, NavMenuOption } from '..'

const categories: NavMenuOption[] = [
  { key: 'design', label: '设计资源' },
  { key: 'development', label: '开发工具' },
  { key: 'document', label: '文档资料' },
]
const regions: NavMenuOption[] = [
  { key: 'east', label: '华东' },
  { key: 'south', label: '华南' },
  { key: 'north', label: '华北' },
]

const category = ref<NavMenuKey | null>('design')
const region = ref<NavMenuKey | null>('east')
const categoryLabel = computed(
  () => categories.find(option => option.key === category.value)?.label ?? '未选择',
)
const regionLabel = computed(
  () => regions.find(option => option.key === region.value)?.label ?? '未选择',
)
</script>

<template>
  <div class="item-label-independent-demo">
    <c-nav-menu mode="horizontal">
      <c-nav-menu-item v-model="category" label="选择分类" :options="categories" />
      <c-nav-menu-item v-model="region" label="选择地区" :options="regions" />
    </c-nav-menu>

    <div class="item-label-independent-demo__status" aria-live="polite">
      <p><strong>分类：</strong>{{ categoryLabel }}</p>
      <p><strong>地区：</strong>{{ regionLabel }}</p>
    </div>

    <c-space>
      <c-button :disabled="category === null" @click="category = null">清空分类</c-button>
      <c-button :disabled="region === null" @click="region = null">清空地区</c-button>
    </c-space>

    <p class="item-label-independent-demo__tip">
      两个 Item 未设置 name，各自根据选中值更新标题和高亮，互不清除；面板仍互斥展开。
    </p>
  </div>
</template>

<style scoped>
.item-label-independent-demo {
  display: grid;
  gap: 16px;
  min-height: 180px;
}

.item-label-independent-demo__status {
  display: flex;
  flex-wrap: wrap;
  gap: 8px 24px;
}

.item-label-independent-demo__status p,
.item-label-independent-demo__tip {
  margin: 0;
}

.item-label-independent-demo__tip {
  color: var(--c-color-text-3);
}
</style>
```

## 数据与状态控制

### 数据与状态控制

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `options` | 导航结构 | 数据与状态控制 |
| `model-value` | 当前选中 key，支持 v-model；null 表示无选中 | 数据与状态控制 |
| `expanded-keys` | 受控展开分支 | 数据与状态控制 |
| `field-names` | key/label/children/disabled 字段映射 | 数据与状态控制 |
| `disabled` | 全局禁用选择和用户展开 | 数据与状态控制 |
| `default-value` | 非受控初始选中值 | 数据与状态控制 |
<!-- demo-config-notes:end -->

#### 受控选择与展开

受控属性始终以父级传入值为准。示例可切换是否接受更新请求，以观察选择与展开状态的区别。

Example source: src/nav-menu/__demos__/controlled.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
import type { NavMenuKey } from '../types'
import { options } from './data'
const selected = ref<NavMenuKey | null>(0)
const expanded = ref<NavMenuKey[]>([])
const acceptUpdates = ref(true)
const lastRequest = ref('尚未操作')
function select(key: NavMenuKey | null) {
  lastRequest.value = `请求选择：${key}`
  if (acceptUpdates.value) selected.value = key
}
function expand(keys: NavMenuKey[]) {
  lastRequest.value = `请求展开：${keys.join('、') || '无'}`
  if (acceptUpdates.value) expanded.value = keys
}
</script>
<template>
  <div>
    <c-button @click="acceptUpdates = !acceptUpdates">{{ acceptUpdates ? '当前接受更新，点击拒绝' : '当前拒绝更新，点击接受' }}</c-button>
    <c-nav-menu :options="options" :model-value="selected" :expanded-keys="expanded" @update:model-value="select" @update:expanded-keys="expand" />
    <p aria-live="polite">{{ lastRequest }}；实际选中：{{ selected }}；实际展开：{{ expanded.join('、') || '无' }}</p>
  </div>
</template>
```

Example source: src/nav-menu/__demos__/item-controlled.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'

const accepted = ref(true)
const open = ref(false)
const value = ref<string | number | null>(null)
const options = [
  { key: 0, label: '不限' },
  { key: 'design', label: '设计' },
  { key: 'disabled', label: '禁用选项', disabled: true },
]
function updateOpen(next: boolean) {
  if (accepted.value) {
    open.value = next
  }
}
function updateValue(next: string | number | null) {
  if (accepted.value) {
    value.value = next
  }
}
</script>
<template>
  <c-button @click="accepted = !accepted">{{
    accepted ? '当前接受更新，点击拒绝' : '当前拒绝更新，点击接受'
  }}</c-button>
  <c-nav-menu>
    <c-nav-menu-item
      :open="open"
      :model-value="value"
      :options="options"
      label="受控筛选"
      @update:open="updateOpen"
      @update:model-value="updateValue"
    />
    <c-nav-menu-item label="禁用入口" disabled :options="options" />
  </c-nav-menu>
  <p>选中：{{ value ?? '未选择' }}；展开：{{ open }}</p>
</template>
```

Example source: src/nav-menu/__demos__/panel-state.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
import type { NavMenuInstance } from '..'

const menu = ref<NavMenuInstance>()
const unmountOnClose = ref(false)
const options = [{ key: 0, label: '不限' }, { key: 'design', label: '设计资源' }]
</script>
<template>
  <c-space direction="column" style="width: 100%">
    <c-space>
      <span>关闭后卸载</span>
      <c-switch v-model="unmountOnClose" />
      <c-button @click="menu?.close()">关闭当前面板</c-button>
    </c-space>
    <c-nav-menu ref="menu" mode="horizontal">
      <c-nav-menu-item label="草稿表单" :unmount-on-close="unmountOnClose">
        <template #content="{ close }">
          <c-space direction="column" style="width: 100%">
            <c-input default-value="" placeholder="输入后关闭，再打开查看草稿" aria-label="面板内部草稿" />
            <c-button @click="close">关闭并返回入口</c-button>
          </c-space>
        </template>
      </c-nav-menu-item>
      <c-nav-menu-item label="分类" :options="options" />
    </c-nav-menu>
    <p>默认保留面板内部草稿；开启卸载后再次展开会重新创建。关闭面板不会提交或重置业务筛选值。</p>
  </c-space>
</template>
```

#### 业务字段映射

使用 `field-names` 接入不同字段结构，同时展示分组、分隔线、禁用、隐藏和整菜单禁用。

Example source: src/nav-menu/__demos__/field-names.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
import type { NavMenuOption } from '../types'
const disabled = ref(false)
const fieldNames = { key: 'id', label: 'name', children: 'items', disabled: 'unavailable' }
const options: NavMenuOption[] = [
  { type: 'group', name: '工作空间', items: [
    { id: 0, name: '概览' },
    { id: 'projects', name: '项目', items: [{ id: 'active', name: '进行中' }, { id: 'archived', name: '已归档', unavailable: true }] },
  ] },
  { type: 'divider' },
  { id: 'settings', name: '设置' },
  { id: 'hidden', name: '隐藏入口', show: false },
]
</script>
<template>
  <div>
    <c-button @click="disabled = !disabled">{{ disabled ? '启用菜单' : '禁用整个菜单' }}</c-button>
    <c-nav-menu :options="options" :field-names="fieldNames" :disabled="disabled" :default-value="0" default-expand-all />
  </div>
</template>
```

#### 节点内容定制

作用域插槽负责统一定制节点内容，选项本身也可以提供 VNode 或渲染函数。

Example source: src/nav-menu/__demos__/custom-content.vue

```vue
<template>
  <c-nav-menu :options="options">
    <template #label="{ option, active }"><strong :style="{ fontWeight: active ? 700 : 400 }">{{ option.label }}</strong></template>
    <template #extra="{ option }"><c-tag v-if="option.key === 'inbox'">3</c-tag></template>
  </c-nav-menu>
</template>
<script setup lang="ts">
import { h } from 'vue'
import type { NavMenuOption } from '..'
const options: NavMenuOption[] = [
  { key: 'workspace', type: 'group', label: '工作空间', children: [
    { key: 'inbox', label: '收件箱' }, { key: 'docs', label: '文档', icon: h('span', '文') },
  ] },
  { type: 'divider' }, { key: 'settings', label: '设置' },
]
</script>
```

## NavMenu API

| 属性 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| options | 导航结构 | NavMenuOption[] | [] |
| model-value | 当前选中 key，支持 v-model；null 表示无选中 | string / number / null | undefined |
| default-value | 非受控初始选中值 | string / number / null | null |
| active-item | 受控的具名 NavMenu.Item 激活项，支持 v-model:active-item | string / number / null | undefined |
| default-active-item | 非受控的具名 NavMenu.Item 初始激活项 | string / number / null | null |
| expanded-keys | 受控展开分支 | (string / number)[] | undefined |
| default-expanded-keys | 非受控初始展开分支 | (string / number)[] | [] |
| default-expand-all | 初始展开所有分支 | boolean | false |
| auto-expand-selected | 纵向非折叠时展开选中项祖先；受控时发出更新请求 | boolean | true |
| accordion | 同层只展开一个分支 | boolean | false |
| mode | 导航方向 | vertical / horizontal | vertical |
| collapsed | 折叠状态，支持 v-model:collapsed | boolean | undefined |
| default-collapsed | 非受控初始折叠 | boolean | false |
| theme | 主题 | light / dark | 继承 Sider，否则 light |
| size | 尺寸 | xs / sm / md / lg / xl | md |
| disabled | 全局禁用选择和用户展开 | boolean | false |
| field-names | key/label/children/disabled 字段映射 | NavMenuFieldNames | 默认同名 |
| responsive | 横向菜单启用更多收纳 | boolean | true |
| indent | 每层缩进（px） | number | 24 |
| root-indent | 根缩进（px） | number | 12 |
| collapsed-width | 折叠宽度（px） | number | 56 |
| icon-size | 图标尺寸（px） | number | 20 |
| popup-container | 浮层挂载容器，false 为当前位置 | Trigger 对应类型 | 继承 Trigger 定义 |
| popup-class | 浮层附加类名 | string / array / object | — |
| overflow-label | 更多入口标签 | string | 更多 |
| node-props | 节点 DOM 属性和事件；内部选择、禁用和键盘语义保留 | (context) => Record<string, unknown> | — |

受控属性以传入值为准；更新事件只是请求。`default-*` 仅初始化，不跟随后续修改。单选值与展开状态相互独立，`showOption` 不会更改选中值。

### NavMenuOption

```ts
interface NavMenuOption {
  key?: string | number
  type?: 'item' | 'group' | 'divider'
  label?: VNodeChild | ((context: NavMenuRenderContext) => VNodeChild)
  icon?: VNodeChild | ((context: NavMenuRenderContext) => VNodeChild)
  extra?: VNodeChild | ((context: NavMenuRenderContext) => VNodeChild)
  children?: NavMenuOption[]
  disabled?: boolean
  show?: boolean
  props?: HTMLAttributes
}
```

普通选项必须提供唯一且稳定的 key（自定义字段时使用映射后的 key）；数字 0 是合法 key。group/divider 可省略 key，但动态重排时建议显式提供。重复 key 或普通项缺失 key 会报错，避免选中路径混乱。show=false 的节点及其子树不渲染；禁用分支向下继承禁用。存在 children 的普通项负责展开，叶项负责选择。

### 事件

| 事件 | 参数 |
| --- | --- |
| update:model-value | key / null |
| update:active-item | name / null |
| update:expanded-keys | keys |
| update:collapsed | collapsed |
| select | key, 原始 option, 原始 Event |

### 插槽

默认插槽用于放置独立的 `CNavMenuItem`。存在默认插槽时，横向菜单使用滚动，`responsive` 不进行更多收纳。

label/icon/extra 渲染函数、同名插槽及 nodeProps 均接收 `{ option, active, expanded, level }`。`active` 只表示当前节点自身匹配 modelValue，祖先路径强调留在内部；`expanded` 表示分支展开，level 从 0 开始。

### 两端对应关系

两端面板均在首次展开时创建，关闭或切换入口后默认保留挂载，内部草稿和分支展开状态继续保留。设置 `unmount-on-close` 后，在关闭过渡结束时卸载面板；再次展开会重新创建内部组件，但不会清空 Item 自身的选中值。草稿提交、重置和筛选生效时机由业务决定。

根 `close()` 只请求关闭 Item 面板并恢复入口焦点，不改变选中值、active-item 或桌面导航树的 expanded-keys。受控 open 拒绝更新时仍保持展开。没有 options 且没有 content 插槽的入口不展开；异步 options 到达后按当前 open 状态展示。KeepAlive 停用期间隐藏面板并请求关闭，重新激活时仍以受控值为准。

Item 的选中值、展开状态、事件、插槽上下文及 `select/close/setOpen` 方法保持一致。两端根菜单都提供 `close/resize/setActiveItem`。`name` 必须在当前菜单内唯一，动态修改后会释放旧名称；同一次更新允许交换名称或在重排时复用旧名称，以更新完成后的名称检查重复。纵向选项会在初始值、受控值或 options 更新时展开当前值的可用祖先路径；用户仍可手动收起分支。

| 能力 | Cedar | Maple |
| --- | --- | --- |
| 根菜单 | options 导航树或 Item 入口；默认 vertical | 仅 Item 筛选栏；默认 horizontal |
| popup-layout | dropdown（默认）/ full-width / full-height / full | full-width（默认）/ full |
| 面板起点 | 当前入口底边 | 整个筛选栏底边；独立 Item 使用自身底边 |
| 触发与定位 | trigger / placement | 固定点击向下展开 |
| 遮罩与滚动 | 非模态，不锁背景滚动 | 根级 overlay / overlay-closable / lock-scroll / esc-to-close / z-index |
| 主题 | theme 可覆盖 | 跟随全局主题，无 theme 属性 |
| 导航树专用方法 | showOption / scrollTo / setCollapsed | — |

两端 `NavMenuPopupLayout` 分别导出本端支持的值域；Maple 的 `NavMenuMode` 仅为 horizontal，`options-mode` 仍支持两个方向。入口 default 插槽替换入口内部内容，移动端位于原生按钮中，请使用文本、图标等非交互内容；表单和操作按钮放在 content 插槽。

### 方法

| 方法 | 说明 |
| --- | --- |
| close() | 请求关闭所有 Item 面板并恢复入口焦点，不修改导航树展开状态 |
| showOption(key?) | 展开指定项的祖先路径，默认当前选中项；不选择 |
| scrollTo(key?) | 先展开，再滚动到该项；受控展开需父级接受 |
| resize() | 手动重新计算横向溢出 |
| setCollapsed(value) | 更新非受控折叠或发出受控更新请求 |
| setActiveItem(value) | 更新具名 Item 的非受控激活项或发出受控更新请求 |

### 箭头方向

横向下拉入口收起朝下、展开朝上；纵向内联分支收起朝右、展开朝下；向右弹出的子菜单收起朝右、展开朝左。独立 Item 根据 placement 显示方向，展开后反向。箭头跟随实际 open 状态，受控状态未接受更新时不切换。

### 键盘

纵向 Up/Down 与横向 Left/Right 移动焦点，Home/End 到首尾；Right 展开纵向分支，Down 打开横向分支；Left 返回父级，弹出层 Escape 关闭当前层并恢复参考项焦点。Enter/空格激活节点。禁用项跳过；输入框保留原生按键。横向缩窄导致当前项进入“更多”时，焦点迁移至更多入口。

## NavMenu.Item API

标题默认跟随匹配的选中选项。`label` 插槽优先级最高：固定标题可写 `<template #label>高级筛选</template>`；手动标题可绑定独立的响应式变量。原 `update-label` 已移除。

`v-model` 保存面板的选中值。插槽 `active` 只表示业务上的当前入口：提供 name 且处于根菜单中时，由根 activeItem 是否等于该 name 决定；独立入口则由主值是否匹配 options 中的普通选项决定（包括 0 和空字符串）。未知值、分组和分隔项不激活独立入口。`highlight` 仅覆盖视觉强调，true 强制强调、false 取消强调，省略时跟随 active；它不改变 active 或主值。打开面板不会激活入口。

`CNavMenuItem`（也可写 `NavMenu.Item`）是自定义一级入口，不参与根菜单普通导航树的 `modelValue`。未提供 `name` 时，Item 根据自己的值独立高亮，适合分类、地区等多个筛选条件同时生效；提供唯一 `name` 后，由根菜单的 `activeItem/defaultActiveItem` 统一保持单选高亮。两种模式都只允许同一时间展开一个 Item 面板，且不会清空其他面板的内部值。普通一级导航仍使用根 NavMenu 的 `options + v-model`。每个入口通过自己的 `options` 定义菜单，或通过 `content` 插槽完全替换面板。默认插槽自定义入口内部内容，`label`、`icon` 插槽局部自定义入口，`option-label`、`option-icon`、`option-extra` 自定义选项。

有默认插槽时，横向菜单使用滚动而不收入“更多”，避免复制包含表单的入口。纯 `options` 菜单继续支持自动溢出收纳。新 Item 不兼容旧的子组件收集协议。同一 NavMenu 下的 Item 面板互斥，点击其他入口会请求关闭已打开的面板；受控 open 需要业务接受 update:open。

| Item 属性 | 说明 | 默认 |
| --- | --- | --- |
| name | 稳定且唯一的入口标识；提供后由根菜单 activeItem 互斥管理当前入口；视觉覆盖另用 highlight | — |
| label | 未选中或选中值未匹配 options 时的入口标题，支持 VNode / 渲染函数 | — |
| options / fieldNames | 与 NavMenu 相同的选项和字段映射 | `[]` |
| model-value / default-value | 独立受控值 / 初始值，支持字符串、数字和 null | `undefined` / `null` |
| highlight | 入口视觉强调覆盖，不改变业务 active 或选中值；省略时跟随 active | — |
| hide-on-select | 调用 select 后关闭面板 | `true` |
| unmount-on-close | 关闭过渡结束后卸载面板；默认保留首次展开后的内容 | false |
| open / default-open | 受控 / 初始面板状态 | `undefined` / `false` |
| disabled | 禁用入口（同时遵循父菜单 disabled） | `undefined` |
| trigger | Trigger 触发方式 | `click` |
| placement | 普通下拉的位置；全高面板使用 right/left 系列时紧贴入口对应边缘 | `bottom-start` |
| popup-layout | `dropdown` 普通下拉 / `full-width` 入口下方通栏 / `full-height` 右侧全高 / `full` 入口下方宽高铺满 | `dropdown` |
| popup-style | 面板 CSS，可覆盖全高面板宽度、方向和尺寸 | — |
| popup-container / popup-class | Trigger 挂载容器及浮层类名 | 跟随父菜单 |
| options-mode | 默认选项面板的横向 / 纵向排列 | `vertical` |

所有入口插槽和 `content` 插槽收到 `{ modelValue, selectedOption, active, open, select, close }`。`select(key, event?)` 发出 `update:modelValue` 和 `select(key, option, event)`；自定义面板可以选择 options 外的值，此时 option 为 undefined；独立入口 active 为 false，如需强调可显式设置 highlight。`close()` 关闭并恢复入口焦点。受控值只有父组件接受后才影响标题和业务 active。入口插槽的 active 表示入口状态；label 渲染函数的 active 则表示其上下文 option 自身是否匹配 Item 的主值，未匹配时为 false。`hideOnSelect` 独立于值是否被接受，需手动确认时设为 false。

Item 还发出 `update:open`、入口 `click`，暴露 `select`、`close`、`setOpen` 方法。通栏 / 全高是非模态浮层，不锁定页面滚动或限制焦点；默认挂载到 body，使用自定义容器时需避免祖先 transform 改变 fixed 定位基准。

## 从旧版本迁移

旧子组件收集协议和状态别名已移除。新的 `NavMenu.Item` 是独立一级入口，与旧 Item 的用法不同。

| 旧用法 | 新用法 |
| --- | --- |
| 旧 Item / SubMenu / ItemGroup 组件 | 导航树使用 options、children、type=group；自定义一级入口使用新的 NavMenu.Item |
| selectedKeys/defaultSelectedKeys 数组 | modelValue/defaultValue 单个 key |
| openKeys/defaultOpenKeys | expandedKeys/defaultExpandedKeys |
| menu-item-click | select(key, option, event) |
| pop / popButton 模式 | vertical + collapsed；横向仍用 horizontal |
| 子组件 title/icon 插槽 | 根 label/icon/extra 作用域插槽或 option VNode |
| 内置折叠按钮与 breakpoint | 外部按钮控制 collapsed；布局响应式交由容器 |
| triggerProps/tooltipProps 全量透传 | 明确的 popupContainer/popupClass 属性 |

所有库内演示、组件导出、全局类型和 resolver 均已迁移。样式改为 BEM `c-nav-menu__*` 与 `c-nav-menu--*`，旧选择器与未使用 token 不再保留。

## 设计参考

参考工作区 Naive UI 2.44.1 Menu 的 options 树、祖先路径和内容渲染设计；未引入 Naive UI 或 TreeMate 运行时依赖。浮层由本库 Trigger 提供，公开 API 使用 Cedar 命名约定。

## 样式变量

| 变量 | 默认值 |
| --- | --- |
| --c-nav-menu-font-size | `var(~'--c-font-size-body-3')` |
| --c-nav-menu-border-radius | `var(~'--c-border-radius-sm')` |
| --c-nav-menu-light-bg | `var(~'--c-color-bg-2')` |
| --c-nav-menu-light-item-bg-hover | `var(~'--c-color-fill-2')` |
| --c-nav-menu-light-item-bg-selected | `var(~'--c-color-fill-2')` |
| --c-nav-menu-light-item-text-color | `var(~'--c-color-text-2')` |
| --c-nav-menu-light-item-text-color-selected | `rgb(var(~'--c-primary-6'))` |
| --c-nav-menu-light-item-text-color-disabled | `var(~'--c-color-text-4')` |
| --c-nav-menu-dark-bg | `var(~'--c-color-menu-dark-bg')` |
| --c-nav-menu-dark-item-bg-hover | `var(~'--c-color-menu-dark-hover')` |
| --c-nav-menu-dark-item-bg-selected | `var(~'--c-color-menu-dark-hover')` |
| --c-nav-menu-dark-item-text-color | `var(~'--c-color-text-4')` |
| --c-nav-menu-dark-item-text-color-selected | `var(~'--c-color-white')` |
| --c-nav-menu-dark-item-text-color-disabled | `var(~'--c-color-text-2')` |
| --c-nav-menu-row-height | `40px` |
| --c-nav-menu-row-height-xs | `28px` |
| --c-nav-menu-row-height-sm | `32px` |
| --c-nav-menu-row-height-lg | `48px` |
| --c-nav-menu-row-height-xl | `56px` |
| --c-nav-menu-content-gap | `8px` |
| --c-nav-menu-content-padding | `12px` |
| --c-nav-menu-icon-size | `20px` |
| --c-nav-menu-arrow-size | `12px` |
| --c-nav-menu-focus-width | `2px` |
| --c-nav-menu-focus-offset | `-2px` |
| --c-nav-menu-divider-width | `1px` |
| --c-nav-menu-divider-color | `var(--c-color-border-2)` |
| --c-nav-menu-popup-min-width | `180px` |
| --c-nav-menu-popup-max-height | `320px` |
| --c-nav-menu-popup-shadow | `0 6px 24px rgb(0 0 0 / 12%)` |
| --c-nav-menu-motion-duration | `150ms` |
| --c-nav-menu-panel-width | `min(400px, 100vw)` |

`popup-layout="full"` 从入口底边开始，宽度占满视口，高度占满下方剩余视口区域。Maple 同名布局从整个筛选栏底边开始；移动端默认 full-width，桌面端默认 dropdown。


## 阅读方向与键盘交互

NavMenu 继承最近的原生 `dir` 并支持动态切换。横向菜单的左右键按阅读方向移动焦点；纵向上下键不反转。RTL 下左键展开/进入子级，右键收起/返回父级，LTR 相反；Escape 关闭浮层并返回触发项。

数据菜单的嵌套浮层优先向阅读结束侧展开，空间不足时自动调整，浮层继承来源作用域。显式 `NavMenu.Item` 的物理 `placement` 保持原意。切换方向不会选中菜单或清空筛选值。

---

Document: llms/zh-CN/components/notification.md

<!-- Source: src/notification/README.md; locale: zh-CN; page: /components/notification/ -->

# Notification 通知提醒框

全局展示通知提醒，将信息及时有效的传达给用户。

## 基础示例

### 基本用法

基本用法。

Example source: src/notification/__demos__/basic.vue

```vue
<template>
  <c-space>
    <c-button @click="handleNotification"> Open Notification </c-button>
  </c-space>
</template>
<script lang="ts" setup>
import { Notification } from '@cedar-design/ui'

const handleNotification = () => {
  Notification.info({
    title: 'Notification',
    content: 'This is a notification!',
  })
}
</script>
```

## 阅读方向

继承最近的 `dir="ltr|rtl"`，支持运行时切换与局部覆盖。弹出角落显式命名的 left/right 保持物理侧；图标、内容、关闭与底部动作采用阅读方向。函数式调用应使用明确方向或文档方向，不借用其他应用实例的上下文。

## API

clear 同步释放条目与 ID，随后即使在同一个更新周期重加相同 ID，也会使用独立内部实例和新的完整展示计时；活动 ID 的普通更新仍原位更新。内部实例键不作为公共变量／API 暴露，clear 仍不额外触发业务 onClose。组件样式入口在减少动效下关闭 opacity／左右进入、appear、离开过渡及起始位移，不依赖全局极短时长兜底；静态布局／配色、业务展示期限不变。真实 OS 与浏览器矩阵另行验收。

duration（默认 3000ms，0 持续显示）是业务展示计时，不是 CSS 动效时长。close 每个挂载实例只通知一次，立即取消计时器；离场期间的更新／重复关闭不再安排自动关闭。reset-on-update 只重启活动且未关闭实例的计时。KeepAlive 停用取消计时，重新激活从完整配置时长计时；卸载和已失效回调不会补发 close。列表仍通过实际 TransitionGroup 的离场完成卸载，不按 duration 等待 CSS 动画。现有六项 transition-* Token 控制 opacity／左右进入／离开效果，不改变自动关闭期限；正常消费者覆写检查不等于真实 OS 减少动效验收。

### `Notification` 全局方法

`Notification` 提供的全局方法，可以通过以下三种方法使用：

1. 通过 `this.$notification` 调用
2. 在 Composition API 中，通过 `getCurrentInstance().appContext.config.globalProperties.$notification` 调用
3. 导入 `Notification`，通过 `Notification` 本身调用

当通过 `import` 方式使用时，组件没有办法获取当前的 Vue Context，如 i18n 或 route 等注入在 AppContext
上的内容无法在内部使用，需要在调用时手动传入 AppContext，或者为组件全局指定 AppContext

```ts
import { createApp } from 'vue'
import { Notification } from '@cedar-design/ui'

const app = createApp(App)
Notification._context = app._context
```

### NotificationMethod

| 参数名  | 描述                   | 类型                                                                                             | 默认值 |
| ------- | ---------------------- | ------------------------------------------------------------------------------------------------ | :----: |
| info    | 显示信息提醒框         | `(    config: string \| NotificationConfig,    appContext?: AppContext  ) => NotificationReturn` |  `-`   |
| success | 显示成功提醒框         | `(    config: string \| NotificationConfig,    appContext?: AppContext  ) => NotificationReturn` |  `-`   |
| warning | 显示警告提醒框         | `(    config: string \| NotificationConfig,    appContext?: AppContext  ) => NotificationReturn` |  `-`   |
| error   | 显示错误提醒框         | `(    config: string \| NotificationConfig,    appContext?: AppContext  ) => NotificationReturn` |  `-`   |
| remove  | 清除对应 `id` 的提醒框 | `(id: string) => void`                                                                           |  `-`   |
| clear   | 清除全部提醒框         | `(position?: NotificationPosition) => void`                                                      |  `-`   |

### NotificationConfig

| 参数名           | 描述                        | 类型                                                 | 默认值  | 版本   |
| ---------------- | --------------------------- | ---------------------------------------------------- | :-----: | :----- |
| content          | 内容                        | `RenderContent`                                      |   `-`   |        |
| title            | 标题                        | `RenderContent`                                      |   `-`   |        |
| icon             | 图标                        | `RenderFunction`                                     |   `-`   |        |
| id               | 唯一id                      | `string`                                             |   `-`   |        |
| style            | 样式                        | `CSSProperties`                                      |   `-`   |        |
| class            | 样式类名                    | `ClassName`                                          |   `-`   |        |
| position         | 通知自身在可视区域中的物理角落，默认 top-right；四角使用上下在前的 kebab-case 拼写 | `'top-left'\|'top-right'\|'bottom-left'\|'bottom-right'` | `top-right` |        |
| showIcon         | 是否显示图标                | `boolean`                                            | `true`  |        |
| closable         | 是否可关闭                  | `boolean`                                            | `false` |        |
| duration         | 显示的持续时间，单位为 `ms` | `number`                                             | `3000`  |        |
| footer           | 底部内容                    | `RenderFunction`                                     |   `-`   | 2.25.0 |
| closeIcon        | 关闭按钮图标                | `RenderFunction`                                     |   `-`   |        |
| closeIconElement | 关闭按钮元素                | `RenderFunction`                                     |   `-`   |        |
| onClose          | 关闭时的回调函数            | `(id: number \| string) => void`                     |   `-`   |        |

### NotificationReturn

| 参数名 | 描述               | 类型         | 默认值 |
| ------ | ------------------ | ------------ | :----: |
| close  | 关闭当前通知提醒框 | `() => void` |  `-`   |

### 类型定义

组件导出以下类型定义

```ts
import type { NotificationInstance, NotificationConfig, NotificationReturn } from '@cedar-design/ui'
```

## 公开 CSS 变量

面板使用 surface-overlay，正文／标题使用 content-primary，关闭按钮使用 content-secondary，边框使用 border-default。状态图标使用可读 content 状态色；info 不再引用品牌填充色，loading 使用 content-brand。颜色变量按状态分组；自定义背景须同时检查内容、图标与关闭按钮。纯文本 action／footer 继承面板正文色；自带样式的插槽内容由业务负责。

wrapper-* 控制列表位置／留白；padding-*、margin-* 控制面板布局；icon-*、title-*、content-* 控制各部分排版；close-* 控制关闭按钮；border-*、box-shadow 控制边框／阴影；transition-* 控制动效；z-index 控制层级。本阶段保留几何与动效默认值。下表列出实际声明，未声明所有历史几何变量均已验证消费。

| 变量 | 默认值 |
| --- | --- |
| `--c-notification-wrapper-margin-top` | `var(--c-spacing-8)` |
| `--c-notification-wrapper-margin-bottom` | `var(--c-spacing-8)` |
| `--c-notification-wrapper-margin-left` | `var(--c-spacing-8)` |
| `--c-notification-wrapper-margin-right` | `var(--c-spacing-8)` |
| `--c-notification-z-index` | `var(--c-z-index-notification)` |
| `--c-notification-border-radius` | `var(--c-border-radius-md)` |
| `--c-notification-margin-bottom` | `var(--c-spacing-8)` |
| `--c-notification-width` | `300px` |
| `--c-notification-padding-top` | `var(--c-spacing-8)` |
| `--c-notification-padding-bottom` | `var(--c-spacing-8)` |
| `--c-notification-padding-left` | `var(--c-spacing-8)` |
| `--c-notification-padding-right` | `var(--c-spacing-8)` |
| `--c-notification-icon-font-size` | `24px` |
| `--c-notification-title-font-size` | `var(--c-font-size-title-1)` |
| `--c-notification-title-font-weight` | `var(--c-font-weight-500)` |
| `--c-notification-content-font-size` | `var(--c-font-size-body-3)` |
| `--c-notification-icon-margin-right` | `var(--c-spacing-7)` |
| `--c-notification-title-margin-bottom` | `var(--c-spacing-2)` |
| `--c-notification-footer-margin-top` | `var(--c-spacing-7)` |
| `--c-notification-box-shadow` | `0 4px 12px rgba(0, 0, 0, 0.15)` |
| `--c-notification-border-width` | `1px` |
| `--c-notification-border-style` | `solid` |
| `--c-notification-close-icon-color` | `var(--c-sys-color-content-secondary)` |
| `--c-notification-close-icon-font-size` | `12px` |
| `--c-notification-close-icon-top` | `var(--c-spacing-6)` |
| `--c-notification-close-icon-right` | `var(--c-spacing-6)` |
| `--c-notification-close-icon-hover-size` | `20px` |
| `--c-notification-normal-bg` | `var(--c-sys-color-surface-overlay)` |
| `--c-notification-normal-icon-color` | `var(--c-sys-color-content-primary)` |
| `--c-notification-normal-title-color` | `var(--c-sys-color-content-primary)` |
| `--c-notification-normal-content-color` | `var(--c-sys-color-content-primary)` |
| `--c-notification-normal-border-color` | `var(--c-sys-color-border-default)` |
| `--c-notification-info-bg` | `var(--c-sys-color-surface-overlay)` |
| `--c-notification-info-icon-color` | `var(--c-sys-color-content-info)` |
| `--c-notification-info-title-color` | `var(--c-sys-color-content-primary)` |
| `--c-notification-info-content-color` | `var(--c-sys-color-content-primary)` |
| `--c-notification-info-border-color` | `var(--c-sys-color-border-default)` |
| `--c-notification-success-bg` | `var(--c-sys-color-surface-overlay)` |
| `--c-notification-success-icon-color` | `var(--c-sys-color-content-success)` |
| `--c-notification-success-title-color` | `var(--c-sys-color-content-primary)` |
| `--c-notification-success-content-color` | `var(--c-sys-color-content-primary)` |
| `--c-notification-success-border-color` | `var(--c-sys-color-border-default)` |
| `--c-notification-warning-bg` | `var(--c-sys-color-surface-overlay)` |
| `--c-notification-warning-icon-color` | `var(--c-sys-color-content-warning)` |
| `--c-notification-warning-title-color` | `var(--c-sys-color-content-primary)` |
| `--c-notification-warning-content-color` | `var(--c-sys-color-content-primary)` |
| `--c-notification-warning-border-color` | `var(--c-sys-color-border-default)` |
| `--c-notification-error-bg` | `var(--c-sys-color-surface-overlay)` |
| `--c-notification-error-icon-color` | `var(--c-sys-color-content-danger)` |
| `--c-notification-error-title-color` | `var(--c-sys-color-content-primary)` |
| `--c-notification-error-content-color` | `var(--c-sys-color-content-primary)` |
| `--c-notification-error-border-color` | `var(--c-sys-color-border-default)` |
| `--c-notification-transition-duration` | `var(--c-transition-duration-2)` |
| `--c-notification-transition-duration-enter` | `var(--c-transition-duration-4)` |
| `--c-notification-transition-duration-leave` | `var(--c-transition-duration-3)` |
| `--c-notification-transition-timing-function` | `var(--c-transition-timing-function-linear)` |
| `--c-notification-transition-timing-function-enter` | `var(--c-transition-timing-function-overshoot)` |
| `--c-notification-transition-timing-function-leave` | `var(--c-transition-timing-function-standard)` |

Teleport 后主题变量按实际 DOM 祖先继承；放在内容内部的变量不会向上传到服务创建的容器。

close/closed 通知回调抛错不会保留已关闭项目或空管理器宿主，资源清理独立于通知回调执行。

---

Document: llms/zh-CN/components/overflow-list.md

<!-- Source: src/overflow-list/README.md; locale: zh-CN; page: /components/overflow-list/ -->

# OverflowList

## 基础示例

### 基础用法

折叠列表的基本使用方法。

Example source: src/overflow-list/__demos__/basic.vue

```vue
<template>
  <c-form auto-label-width>
    <c-form-item label="Tag Number">
      <c-input-number v-model="number" :min="0" :max="20" style="width: 200px" />
    </c-form-item>
    <c-form-item label="List Width">
      <c-slider v-model="width" :min="0" :max="800" />
    </c-form-item>
  </c-form>
  <div :style="{ width: `${width}px`, marginTop: '20px' }">
    <c-overflow-list>
      <div>DIV Element</div>
      <c-tag v-for="item of tags" :key="item">Tag{{ item }}</c-tag>
    </c-overflow-list>
  </div>
</template>

<script lang="ts" setup>
import { computed, ref } from 'vue'

const width = ref(500)
const number = ref(10)
const tags = computed(() => Array.from({ length: number.value }, (_, idx) => idx + 1))
</script>
```

## 布局与排列

### 折叠方向

通过 `from` 属性可以设置折叠的方向。

Example source: src/overflow-list/__demos__/from.vue

```vue
<template>
  <c-form auto-label-width>
    <c-form-item label="Tag Number">
      <c-input-number v-model="number" :min="0" :max="20" style="width: 200px" />
    </c-form-item>
    <c-form-item label="List Width">
      <c-slider v-model="width" :min="0" :max="800" />
    </c-form-item>
  </c-form>
  <div :style="{ width: `${width}px`, marginTop: '20px' }">
    <c-overflow-list from="start">
      <div>DIV Element</div>
      <c-tag v-for="item of tags" :key="item">Tag{{ item }}</c-tag>
    </c-overflow-list>
  </div>
</template>

<script lang="ts" setup>
import { computed, ref } from 'vue'

const width = ref(500)
const number = ref(10)
const tags = computed(() => Array.from({ length: number.value }, (_, idx) => idx + 1))
</script>
```

## API

### `<overflow-list>` Props

| 参数名 | 描述               | 类型               | 默认值  |
| ------ | ------------------ | ------------------ | :-----: |
| min    | 最少展示的元素个数 | `number`           |   `0`   |
| margin | 项目间隔           | `number`           |   `8`   |
| from   | 折叠方向           | `'start' \| 'end'` | `'end'` |

### `<overflow-list>` Events

| 事件名 | 描述               | 参数            |
| ------ | ------------------ | --------------- |
| change | 溢出数量改变时触发 | value: `number` |

### `<overflow-list>` Slots

| 插槽名   |   描述   | 参数             |
| -------- | :------: | ---------------- |
| overflow | 折叠元素 | number: `number` |

### 类型定义

组件导出以下类型定义

```ts
import type { BadgeInstance } from '@cedar-design/ui'
```

---

Document: llms/zh-CN/components/overlay.md

<!-- Source: src/overlay/README.md; locale: zh-CN; page: /components/overlay/ -->

# Overlay 背景层

用于在页面内容上方创建背景层，并可承载需要强调的内容。

## 基础示例

### 基本使用

通过 `v-model:open` 控制显示状态。默认点击背景区域或按 Escape 会关闭；点击默认插槽内容不会关闭。

Example source: src/overlay/__demos__/basic.vue

```vue
<template>
  <c-button status="primary" @click="open = true">打开背景层</c-button>
  <c-overlay v-model:open="open">
    <div class="overlay-demo-content">背景层内容</div>
  </c-overlay>
</template>

<script setup lang="ts">
import { ref } from "vue";

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

<style scoped>
.overlay-demo-content {
  padding: 24px;
  background: var(--c-color-bg-2);
  border-radius: var(--c-border-radius-md);
}
</style>
```

## API

### Props

| 参数               | 说明                                         | 类型                             | 默认值   |
| ------------------ | -------------------------------------------- | -------------------------------- | -------- |
| `v-model:open`     | 是否显示                                     | `boolean`                        | `false`  |
| `default-open`     | 非受控模式下是否默认显示                     | `boolean`                        | `false`  |
| `overlay-closable` | 点击背景区域是否关闭                         | `boolean`                        | `true`   |
| `lock-scroll`      | 是否锁定挂载容器滚动                         | `boolean`                        | `true`   |
| `unmount-on-close` | 关闭后是否卸载插槽内容                       | `boolean`                        | `true`   |
| `esc-to-close`     | 是否按 Escape 关闭                           | `boolean`                        | `true`   |
| `popup-container`  | Teleport 挂载位置；`false` 表示原地渲染       | `string \| HTMLElement \| false` | `'body'` |
| `z-index`          | 自定义层级                                   | `number`                         | `-`      |

### Events

| 事件名        | 说明         | 参数            |
| ------------- | ------------ | --------------- |
| `update:open` | 显示状态变化 | `boolean`       |
| `open`        | 开始打开     | `-`             |
| `opened`      | 打开动画结束 | `-`             |
| `close`       | 开始关闭     | `-`             |
| `closed`      | 关闭动画结束 | `-`             |
| `click`       | 点击背景区域 | `MouseEvent`    |
| `key-escape`  | 按下 Escape  | `KeyboardEvent` |

### Slots

| 插槽名    | 说明             |
| --------- | ---------------- |
| `default` | 背景层上方的内容 |

## 公开 CSS 变量

以下为实际 :root 默认值。业务定制优先使用组件变量；内部定位变量不属于公开 API。

| 变量 | 默认值 | 意义与场景 |
| --- | --- | --- |
| `--c-overlay-background-color` | `var(--c-sys-color-scrim)` | 仅遮罩背景，不影响前景内容透明度 |
| `--c-overlay-animation-duration` | `var(--c-sys-motion-duration-slow)` | 组件入退场时长；reduced-motion 可覆盖 |
| `--c-overlay-content-z-index` | `var(--c-sys-layer-raised)` | 内容高于遮罩的局部层级 |

### 减少动态效果

内置 CSS 过渡遵循 `prefers-reduced-motion: reduce`。关闭过渡不改变最终显隐、选中／展开状态及事件语义；插槽内自定义动画由应用自行控制。

---

Document: llms/zh-CN/components/page-header.md

<!-- Source: src/page-header/README.md; locale: zh-CN; page: /components/page-header/ -->

# PageHeader 页头

返回按钮只派发 `back` 事件，不自动调用路由或浏览器历史。示例通过 Message 显示通知；真实返回目的地由调用方处理。原生按钮支持点击、Enter 和空格。

展示当前页面的标题、上下文和相关操作。API 参照 Naive UI；组件不负责固定定位、背景等业务布局与皮肤能力，可通过 `class` / `style` 实现。

## 基础示例

### 基础用法

使用 Card 承载页头、Space 排列操作。桌面端将标题、副标题和右侧“关注”“创建任务”横向展示，点击操作查看消息反馈。

Example source: src/page-header/__demos__/basic.vue

```vue
<template>
  <c-card variant="outline" size="md">
    <c-page-header
      show-back
      title="设计系统"
      subtitle="项目概览"
      @back="onBack"
    >
      <template #extra>
        <c-space size="sm" wrap>
          <c-button @click="onFollow">关注</c-button>
          <c-button status="primary" @click="onCreate">创建任务</c-button>
        </c-space>
      </template>
    </c-page-header>
  </c-card>
</template>

<script setup lang="ts">
import { Message } from "@cedar-design/ui";

const onBack = () => Message.info("点击返回");
const onFollow = () => Message.success("已关注项目");
const onCreate = () => Message.info("点击创建任务");
</script>
```

## 内容与展示

### 面包屑与透明表面

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `title` | 页头的主标题 | 面包屑与透明表面、完整结构 |
| `subtitle` | 页头的次标题 | 面包屑与透明表面、完整结构 |
| `show-back` | 是否显示返回按钮 | 完整结构 |
<!-- demo-config-notes:end -->

比较面包屑导航和透明背景下的标题层级；完整业务内容另见独立案例。

<details>
<summary>配置说明与使用限制</summary>

#### 页头上方内容

使用 Card 承载页头，通过 `header` 插槽在标题上方展示面包屑，区分页面路径与当前页面信息。

#### 透明底色

页头默认透明。使用 Card 的 `tonal` 变体提供底色，展示页头自然融入外层表面，无需自定义背景样式。

</details>

Example source: src/page-header/__demos__/surface-comparison.vue

```vue
<script setup lang="ts">
import { Message } from "@cedar-design/ui"
import { proxyRefs as demoProxyRefs } from 'vue'

const scene2 = demoProxyRefs((() => {


const onFollow = () => Message.success("已关注项目");
return { onFollow }
})())
</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="breadcrumb">
    <h4><span lang="zh-CN">页头上方内容</span><span lang="en-US">breadcrumb</span></h4>
    <c-card variant="outline" size="md">
        <c-page-header title="设计系统" subtitle="项目概览">
          <template #header>
            <c-breadcrumb>
              <c-breadcrumb-item>工作台</c-breadcrumb-item>
              <c-breadcrumb-item>项目</c-breadcrumb-item>
              <c-breadcrumb-item>设计系统</c-breadcrumb-item>
            </c-breadcrumb>
          </template>
        </c-page-header>
      </c-card>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="transparent">
    <h4><span lang="zh-CN">透明底色</span><span lang="en-US">transparent</span></h4>
    <c-card variant="tonal" size="md">
        <c-page-header title="设计系统" subtitle="项目概览">
          <template #extra><c-button @click="scene2.onFollow">关注</c-button></template>
          <span>页头默认透明，可以融入页面背景。</span>
        </c-page-header>
      </c-card>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

### 完整结构

使用 Card 承载页头，通过 Space、Row / Col、Descriptions、Grid、Statistic 和 Divider 组合项目资料、统计和底部信息，无需自定义样式。桌面端标题与操作横向排列，资料和统计随栅格断点换行。

Example source: src/page-header/__demos__/content.vue

```vue
<template>
  <c-card variant="outline" size="md">
    <c-page-header
      show-back
      title="设计系统"
      subtitle="项目概览"
      @back="onBack"
    >
      <template #header>
        <c-breadcrumb>
          <c-breadcrumb-item>工作台</c-breadcrumb-item>
          <c-breadcrumb-item>项目</c-breadcrumb-item>
        </c-breadcrumb>
      </template>
      <template #avatar
        ><c-avatar shape="square" :size="40">D</c-avatar></template
      >
      <template #extra>
        <c-space size="sm" wrap>
          <c-button @click="onFollow">关注</c-button>
          <c-button status="primary" @click="onCreate">创建任务</c-button>
        </c-space>
      </template>
      <c-row :gutter="[24, 24]" align="center" justify="space-between">
        <c-col :xs="24" :lg="14">
          <c-space direction="column" size="lg">
            <span>统一设计规范与组件资源，帮助团队高效协作。</span>
            <c-descriptions :column="2" size="sm">
              <c-descriptions-item label="负责人">林晓</c-descriptions-item>
              <c-descriptions-item label="所属团队"
                >设计平台</c-descriptions-item
              >
            </c-descriptions>
          </c-space>
        </c-col>
        <c-col :xs="24" :lg="8">
          <c-grid :cols="3" :col-gap="24">
            <c-grid-item
              ><c-statistic title="组件" :value="48" tabular-nums
            /></c-grid-item>
            <c-grid-item
              ><c-statistic title="进行中" :value="12" tabular-nums
            /></c-grid-item>
            <c-grid-item
              ><c-statistic title="成员" :value="8" tabular-nums
            /></c-grid-item>
          </c-grid>
        </c-col>
      </c-row>
      <template #footer>
        <c-divider :spacing="[0, 16]" />
        <c-space justify="space-between" size="sm" wrap>
          <small>项目编号 DS-001</small>
          <small>最近更新：今天</small>
        </c-space>
      </template>
    </c-page-header>
  </c-card>
</template>

<script setup lang="ts">
import { Message } from "@cedar-design/ui";

const onBack = () => Message.info("点击返回");
const onFollow = () => Message.success("已关注项目");
const onCreate = () => Message.info("点击创建任务");
</script>
```

## 阅读方向

继承最近的 `dir="ltr|rtl"`，支持运行时切换与局部覆盖。返回按钮位于阅读起点，默认返回图形在 RTL 下指向右侧。标题、副标题与扩展区沿阅读顺序排列；自定义返回插槽不自动镜像。

## API

### PageHeader Props

| 属性     | 说明             | 类型      | 默认值  |
| -------- | ---------------- | --------- | ------- |
| show-back | 是否显示返回按钮 | `boolean` | `false` |
| title    | 页头的主标题     | `string`  | `-`     |
| subtitle | 页头的次标题     | `string`  | `-`     |
| extra    | 右侧附加内容     | `string`  | `-`     |

### PageHeader Events

| 事件名 | 说明               | 参数           |
| ------ | ------------------ | -------------- |
| back   | 点击返回按钮时触发 | event: `Event` |

### PageHeader Slots

| 插槽名   | 说明           | 参数 |
| -------- | -------------- | ---- |
| header   | 页头上方内容   | -    |
| back     | 自定义返回图标 | -    |
| avatar   | 头像           | -    |
| title    | 主标题         | -    |
| subtitle | 次标题         | -    |
| extra    | 右侧额外内容   | -    |
| default  | 页头正文内容   | -    |
| footer   | 页头底部内容   | -    |

## 类型定义

```ts
import type { PageHeaderProps } from '@cedar-design/ui'
```

## 同源实现与平台边界

两端各自保存完整源码，不引用公共核心，不共享组件实例或响应式状态；修改时同步维护两份实现。主体、Props、关键样式及配对测试纳入只读源码一致性检查，主题 token 和安装入口各自维护。

返回按钮统一使用原生 button，支持键盘触发并派发 back(MouseEvent)。Cedar 内部类名由 c-page-header-xxx 调整为 c-page-header__xxx；图标资源仍由本库提供。

### 返回交互变量

`--c-page-header-back-hover-size`（30px）控制反馈圆尺寸，不推动标题布局；`--c-page-header-back-hover-bg`（`var(--c-sys-color-state-hover)`）控制反馈背景。hover 仅应用于支持悬停的精细指针，所有输入模式均保留键盘 focus-visible 反馈。

---

Document: llms/zh-CN/components/pagination.md

<!-- Source: src/pagination/README.md; locale: zh-CN; page: /components/pagination/ -->

# Pagination

两端统一 API、交互与演示，支持按容器宽度自适应布局。

## 基础示例

### 基础与双向绑定

Example source: src/pagination/__demos__/basic.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const current = ref(1)
</script>
<template>
  <div class="pagination-demo">
    <c-pagination v-model="current" :total="50" />
    <span>Current: {{ current }}</span>
  </div>
</template>
<style scoped>
.pagination-demo { display: grid; gap: 16px; min-width: 0; }
.pagination-demo-controls { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; }
</style>
```

## 外观与状态

### 五档尺寸与阴影

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `total` | 数据总数（必填） | 五档尺寸与阴影、禁用与单页隐藏 |
| `show-page-size` | 显示条数选择器 | 五档尺寸与阴影、禁用与单页隐藏 |
| `show-jumper` | 完整模式显示独立跳转框；简洁模式已有页码输入 | 五档尺寸与阴影、禁用与单页隐藏 |
| `size` | 所有内部控件尺寸 | 五档尺寸与阴影 |
| `elevation` | 页码按钮阴影；true 使用 2 级 | 五档尺寸与阴影 |
| `disabled` | 禁用所有交互 | 禁用与单页隐藏 |
<!-- demo-config-notes:end -->

Example source: src/pagination/__demos__/size.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const size = ref<'xs' | 'sm' | 'md' | 'lg' | 'xl'>('md')
const elevation = ref(false)
</script>
<template>
  <div class="pagination-demo">
    <c-radio-group v-model="size"><c-radio v-for="value in ['xs', 'sm', 'md', 'lg', 'xl']" :key="value" :value="value">{{ value }}</c-radio></c-radio-group>
    <div class="pagination-demo-controls"><c-switch v-model="elevation" /> Elevation</div>
    <c-pagination :size="size" :elevation="elevation" :total="50" show-page-size show-jumper />
  </div>
</template>
<style scoped>
.pagination-demo { display: grid; gap: 16px; min-width: 0; }
.pagination-demo-controls { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; }
</style>
```

### 禁用与单页隐藏

Example source: src/pagination/__demos__/disabled.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const disabled = ref(true)
const single = ref(false)
</script>
<template>
  <div class="pagination-demo">
    <div class="pagination-demo-controls"><c-switch v-model="disabled" /> Disabled<c-switch v-model="single" /> Single page</div>
    <c-pagination :total="single ? 5 : 200" :disabled="disabled" hide-on-single-page show-jumper show-page-size show-total />
  </div>
</template>
<style scoped>
.pagination-demo { display: grid; gap: 16px; min-width: 0; }
.pagination-demo-controls { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; }
</style>
```

## 分页模式与信息

### 简洁模式

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `total` | 数据总数（必填） | 简洁模式、更多页码与省略跳转、总数、每页条数与跳页 |
| `show-total` | 显示总数 | 简洁模式、总数、每页条数与跳页 |
| `show-page-size` | 显示条数选择器 | 简洁模式、总数、每页条数与跳页 |
| `responsive` | 按容器宽度自动切换简洁模式 | 更多页码与省略跳转、总数、每页条数与跳页 |
| `simple` | 显式启用简洁模式 | 简洁模式 |
| `default-value` | 非受控初始页码 | 更多页码与省略跳转 |
<!-- demo-config-notes:end -->

Example source: src/pagination/__demos__/simple.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const current = ref(3)
</script>
<template>
  <div class="pagination-demo">
    <c-pagination v-model="current" :total="200" simple show-total show-page-size />
  </div>
</template>
<style scoped>
.pagination-demo { display: grid; gap: 16px; min-width: 0; }
.pagination-demo-controls { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; }
</style>
```

### 更多页码与省略跳转

Example source: src/pagination/__demos__/more-page-size.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const buffer = ref(2)
const more = ref(false)
</script>
<template>
  <div class="pagination-demo">
    <div class="pagination-demo-controls"><c-radio-group v-model="buffer"><c-radio v-for="value in [0, 1, 2]" :key="value" :value="value">Buffer {{ value }}</c-radio></c-radio-group><c-switch v-model="more" /> Show more</div>
    <c-pagination :total="500" :default-value="12" :buffer-size="buffer" :show-more="more" :responsive="false" />
  </div>
</template>
<style scoped>
.pagination-demo { display: grid; gap: 16px; min-width: 0; }
.pagination-demo-controls { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; }
</style>
```

### 总数、每页条数与跳页

比较三种分页附加能力。更改页码或每页条数时观察对应输出，数据总数与自动修正另行说明。

Example source: src/pagination/__demos__/auxiliary-controls-comparison.vue

```vue
<script setup lang="ts">
import { ref } from "vue"
import { proxyRefs as demoProxyRefs } from 'vue'

const scene2 = demoProxyRefs((() => {

const pageSize = ref(10)

const current = ref(5)
return { pageSize, current }
})())
</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="show-total">
    <h4><span lang="zh-CN">自定义总数插槽</span><span lang="en-US">Custom total slot</span></h4>
    <div class="pagination-demo">
        <c-pagination :total="200" show-total><template #total="{ total }">{{ total }} records</template></c-pagination>
      </div>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="show-page-size">
    <h4><span lang="zh-CN">每页条数与公共选择器配置</span><span lang="en-US">Page size and shared selector options</span></h4>
    <div class="pagination-demo">
        <c-pagination v-model="scene2.current" v-model:page-size="scene2.pageSize" :total="200" show-page-size :page-size-options="[10, 20, 50, 100]" :page-size-props="{
      placement: 'bottom-start'
    }" />
        <span>Current: {{ scene2.current }} · Page size: {{ scene2.pageSize }}</span>
      </div>
  </section>

  <section class="demo-comparison-case demo-comparison-case--3" data-comparison-scene="show-jumper">
    <h4><span lang="zh-CN">跳转与前后缀插槽</span><span lang="en-US">Jumper and prefix/suffix slots</span></h4>
    <div class="pagination-demo">
        <c-pagination :total="200" show-jumper :responsive="false">
          <template #jumper-prepend>Go to</template><template #jumper-append>page</template>
        </c-pagination>
      </div>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }
.demo-comparison-case--1 {

.pagination-demo { display: grid; gap: 16px; min-width: 0; }
.pagination-demo-controls { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; }

}
.demo-comparison-case--2 {

.pagination-demo { display: grid; gap: 16px; min-width: 0; }
.pagination-demo-controls { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; }

}
.demo-comparison-case--3 {

.pagination-demo { display: grid; gap: 16px; min-width: 0; }
.pagination-demo-controls { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; }

}
</style>
```

## 条数、跳转与按钮

### 自定义分页按钮与样式

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `total` | 数据总数（必填） | 自定义分页按钮与样式 |
| `default-value` | 非受控初始页码 | 自定义分页按钮与样式 |
| `buffer-size` | 当前页两侧的页码数 | 自定义分页按钮与样式 |
| `responsive` | 按容器宽度自动切换简洁模式 | 自定义分页按钮与样式 |
| `page-item-style` | 数字页码基础样式 | 自定义分页按钮与样式 |
| `active-page-item-style` | 叠加到当前数字页码的样式 | 自定义分页按钮与样式 |
<!-- demo-config-notes:end -->

Example source: src/pagination/__demos__/custom-page-button.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'

</script>
<template>
  <div class="pagination-demo">
    <c-pagination :total="300" :default-value="10" :buffer-size="0" :responsive="false" :page-item-style="{ borderRadius: '8px' }" :active-page-item-style="{ fontWeight: '700' }">
      <template #page-item="{ page }">{{ page }}</template>
      <template #page-item-step="{ type }">{{ type === 'previous' ? 'Prev' : 'Next' }}</template>
      <template #page-item-ellipsis>✦</template>
    </c-pagination>
  </div>
</template>
<style scoped>
.pagination-demo { display: grid; gap: 16px; min-width: 0; }
.pagination-demo-controls { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; }
</style>
```

## 响应式与数据变化

### 容器宽度与窄屏布局

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `total` | 数据总数（必填） | 容器宽度与窄屏布局、数据变化与自动调整、完整功能交互 |
| `show-total` | 显示总数 | 容器宽度与窄屏布局、数据变化与自动调整、完整功能交互 |
| `show-page-size` | 显示条数选择器 | 容器宽度与窄屏布局、数据变化与自动调整、完整功能交互 |
| `show-jumper` | 完整模式显示独立跳转框；简洁模式已有页码输入 | 容器宽度与窄屏布局、完整功能交互 |
| `responsive` | 按容器宽度自动切换简洁模式 | 容器宽度与窄屏布局 |
| `auto-adjust` | 条数变化时保留首条位置；总数减少时修正越界页码 | 数据变化与自动调整 |
<!-- demo-config-notes:end -->

Example source: src/pagination/__demos__/responsive.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const width = ref(360)
const responsive = ref(true)
</script>
<template>
  <div class="pagination-demo">
    <c-radio-group v-model="width" wrap><c-radio v-for="value in [280, 360, 480, 640]" :key="value" :value="value">{{ value }}px</c-radio></c-radio-group>
    <div class="pagination-demo-controls"><c-switch v-model="responsive" /> Responsive</div>
    <div :style="{ width: width + 'px', maxWidth: '100%' }"><c-pagination :total="250" :responsive="responsive" show-total show-jumper show-page-size /></div>
  </div>
</template>
<style scoped>
.pagination-demo { display: grid; grid-template-columns: minmax(0, 1fr); gap: 16px; min-width: 0; }
.pagination-demo-controls { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; }
</style>
```

### 数据变化与自动调整

Example source: src/pagination/__demos__/auto-adjust.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const total = ref(200)
const current = ref(18)
const autoAdjust = ref(true)
function reset() { total.value = 200; current.value = 18 }
</script>
<template>
  <div class="pagination-demo">
    <div class="pagination-demo-controls"><c-switch v-model="autoAdjust" /> Auto adjust<c-button @click="total = 25">Reduce total</c-button><c-button @click="reset">Reset</c-button></div>
    <c-pagination v-model="current" :total="total" :auto-adjust="autoAdjust" show-total show-page-size />
    <span>Current: {{ current }} · Total: {{ total }}</span>
  </div>
</template>
<style scoped>
.pagination-demo { display: grid; gap: 16px; min-width: 0; }
.pagination-demo-controls { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; }
</style>
```

### 完整功能交互

Example source: src/pagination/__demos__/all.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const total = ref(true)
const jumper = ref(true)
const pageSize = ref(true)
</script>
<template>
  <div class="pagination-demo">
    <div class="pagination-demo-controls"><c-switch v-model="total" /> Total<c-switch v-model="jumper" /> Jumper<c-switch v-model="pageSize" /> Page size</div>
    <c-pagination :total="125" :show-total="total" :show-jumper="jumper" :show-page-size="pageSize" />
  </div>
</template>
<style scoped>
.pagination-demo { display: grid; gap: 16px; min-width: 0; }
.pagination-demo-controls { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; }
</style>
```

## 阅读方向

继承最近的 `dir="ltr|rtl"`，支持运行时切换与局部覆盖。页码与上一页/下一页含义保持不变，默认前后图形跟随阅读方向。输入页码、禁用边界和选择不因方向切换而改变；自定义图形插槽由业务决定方向。

## API

主值使用普通 `v-model`：`modelValue` 表示当前页码，从 1 开始；pageSize 仍独立控制每页条数。`defaultValue` 仅在创建时初始化非受控状态，之后修改不会重置当前值；初始化不触发 `update:modelValue`。提供 `modelValue` 时由父级控制，以受控值为准。

<!-- same-source-api:start -->
### Props

| 属性 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| total | 数据总数（必填） | `number` | `—` |
| model-value | 当前页码，支持 v-model | `number` | `—` |
| default-value | 非受控初始页码 | `number` | `1` |
| page-size | 每页条数，支持 v-model:page-size | `number` | `—` |
| default-page-size | 非受控初始条数 | `number` | `10` |
| disabled | 禁用所有交互 | `boolean` | `false` |
| hide-on-single-page | 不足两页时隐藏 | `boolean` | `false` |
| simple | 显式启用简洁模式 | `boolean` | `false` |
| show-total | 显示总数 | `boolean` | `false` |
| show-more | 完整模式追加向后跳页按钮 | `boolean` | `false` |
| show-jumper | 完整模式显示独立跳转框；简洁模式已有页码输入 | `boolean` | `false` |
| show-page-size | 显示条数选择器 | `boolean` | `false` |
| page-size-options | 正整数条数选项 | `number[]` | `[10, 20, 30, 40, 50]` |
| page-size-props | 可选的条数 Select 受限配置；placement 默认 bottom-start，经 Select.triggerProps 交给 Trigger 自动定位；不能覆盖分页值、选项和尺寸 | `PaginationPageSizeProps` | `—` |
| size | 所有内部控件尺寸 | `'xs' / 'sm' / 'md' / 'lg' / 'xl'` | `'md'` |
| page-item-style | 数字页码基础样式 | `CSSProperties` | `—` |
| active-page-item-style | 叠加到当前数字页码的样式 | `CSSProperties` | `—` |
| base-size | 完整模式省略阈值的基础数 | `number` | `6` |
| buffer-size | 当前页两侧的页码数 | `number` | `2` |
| elevation | 页码按钮阴影；true 使用 2 级 | `boolean / number` | `false` |
| responsive | 按容器宽度自动切换简洁模式 | `boolean` | `true` |
| compact-breakpoint | 简洁模式的最大容器宽度，单位 px | `number` | `480` |
| auto-adjust | 条数变化时保留首条位置；总数减少时修正越界页码 | `boolean` | `true` |

### Events

| Event | Description | Arguments |
| --- | --- | --- |
| update:model-value | 请求更新页码 | `number` |
| change | 页码提交变化（与 update:modelValue 成对） | `number` |
| update:page-size | 请求更新条数 | `number` |
| page-size-change | 条数提交变化（与 update:page-size 成对） | `number` |

### Slots

| Slot | Description | Scope |
| --- | --- | --- |
| total | 总数 | `{ total: number }` |
| page-item | 数字页码 | `{ page: number }` |
| page-item-step | 上一页、下一页 | `{ type: 'previous' / 'next' }` |
| page-item-ellipsis | 省略跳转按钮 | `—` |
| jumper-prepend | 独立跳转框前缀 | `—` |
| jumper-append | 独立跳转框后缀 | `—` |

### Methods

| Method | Description |
| --- | --- |

<!-- same-source-api:end -->

## 行为说明

容器宽度不超过 `compact-breakpoint` 时自动使用简洁模式；桌面侧栏与移动端规则相同。保留总数和条数选择器，辅助控件换行，上一页、下一页按钮跟随 size，不再在窄屏强制放大（默认 36px）。设置 `responsive=false` 保留完整页码，极窄时仅页码列表横向滚动，不撑宽页面。

简洁模式的当前页输入框承担跳转功能，不重复展示独立 jumper。`page-item`、`page-item-ellipsis`、`jumper-prepend`、`jumper-append` 仅在完整模式的对应控件中渲染。

页码按钮支持 Tab、Enter、Space，当前页使用 `aria-current=page`。跳转框使用数字键盘提示，Enter 或失焦提交；空值、非数字、小数不跳转，整数越界限制到有效页码。禁用状态阻止所有提交。

`auto-adjust` 在条数改变时尽量保留原页面首条数据的位置，总数减少时限制到最后一页，零条数据时页码回到 1。受控模式只发出更新请求，显示由父组件决定；父组件同一批更新明确设置 modelValue 时优先遵循该值。

完整模式和简洁模式的“前往”输入框均显示当前页码。点击翻页、外部更新 modelValue 或切换每页条数触发页码调整时同步回显；非法输入恢复为当前页码。

### PaginationPageSizeProps

每页条数选择器按已选文字与下拉箭头自适应宽度，两者之间仅保留条目间距，切换选项或语言时自动更新。可通过 `--c-pagination-select-width` 自定义宽度。弹出菜单仍按选项内容独立计算宽度。

两端支持相同配置：`disabled?: boolean`、`placement?: 'top' | 'top-start' | 'top-end' | 'bottom' | 'bottom-start' | 'bottom-end'`、`popupContainer?: string | HTMLElement | false`、`class?: string`、`style?: CSSProperties`。外层 disabled 优先。默认 placement 为 bottom-start。

此配置不再透传任意 SelectProps/MenuProps。分页值、选项和尺寸分别使用 page-size、page-size-options、size。

## 类型定义

```ts
import type { PaginationProps, PaginationInstance, PaginationPageSizeProps } from '@cedar-design/ui'
```

## 样式变量

| Token | Default |
| --- | --- |
| `--c-pagination-text-color` | `var(--c-color-text-1)` |
| `--c-pagination-font-size` | `var(--c-sys-font-size-md)` |
| `--c-pagination-gap` | `var(--c-sys-space-5)` |
| `--c-pagination-item-gap` | `var(--c-sys-space-2)` |
| `--c-pagination-focus-space` | `3px` |
| `--c-pagination-size-xs` | `24px` |
| `--c-pagination-size-sm` | `28px` |
| `--c-pagination-size-md` | `36px` |
| `--c-pagination-size-lg` | `44px` |
| `--c-pagination-size-xl` | `52px` |
| `--c-pagination-item-padding` | `var(--c-sys-space-4)` |
| `--c-pagination-item-border-radius` | `var(--c-sys-radius-md)` |
| `--c-pagination-icon-size` | `16px` |
| `--c-pagination-input-width` | `32px` |
| `--c-pagination-select-width` | `max-content` |
| `--c-pagination-touch-size` | `44px` |
| `--c-pagination-focus-width` | `2px` |
| `--c-pagination-focus-offset` | `1px` |
| `--c-pagination-focus-color` | `var(--c-color-primary)` |
| `--c-pagination-item-background` | `transparent` |
| `--c-pagination-hover-background` | `var(--c-color-fill-1)` |
| `--c-pagination-active-background` | `var(--c-color-primary-light-1)` |
| `--c-pagination-active-color` | `var(--c-color-primary)` |
| `--c-pagination-disabled-color` | `var(--c-color-text-4)` |
| `--c-pagination-disabled-background` | `var(--c-color-fill-1)` |


### 方位语义与配置入口

普通使用无需配置方位：默认 bottom-start，空间不足时底层 Trigger 自动翻转和约束。pageSizeProps.placement 仅是条数 Select 的受限覆盖入口，链路为 Pagination → Select.triggerProps.placement → Trigger；不是分页器自身位置。

---

Document: llms/zh-CN/components/palette.md

<!-- Source: src/style/palette/README.md; locale: zh-CN; page: /components/palette/ -->

# 色板 Palette

### 介绍

Cedar 色阶以 CSS 变量提供，前缀一律 `--c-*`（与 Maple 的 `--mp-*` 同构）。
业务页优先用 [颜色 Color](llms/zh-CN/components/style/color.md) 语义工具类（如 `c-text-1` / `c-fill-2`）；需要精细色阶或主题覆盖时再直接引用色阶变量。

完整色阶见 `style/color/css-variables.less`，语义见 `style/theme/css-variables.less`；暗色由 `:root[cedar-theme=dark]` 覆盖。

### 功能色阶（1–10）

通道值为 `R, G, B`，使用时包一层 `rgb()` / `rgba()`：

```css
color: rgb(var(--c-primary-6));
background: rgba(var(--c-primary-6), 0.12);
```

```html
<div style="background: rgb(var(--c-primary-6)); color: #fff">primary-6</div>
<div style="background: rgb(var(--c-success-6)); color: #fff">success-6</div>
```

定制主色示例：

```css
:root {
  --c-brand-6: 0, 190, 190;
  --c-brand-5: 55, 209, 204;
  --c-brand-7: 14, 153, 158;
}
```

`--c-primary-*` 映射到 `--c-brand-*`，覆盖 brand 色阶即可联动主色。更多见 [主题定制](llms/zh-CN/guide/theme.md)。

## 基础示例

### 色阶预览

Example source: src/style/palette/__demos__/colors.vue

```vue
<template>
  <div class="palette-demo">
    <div class="section-title">功能色阶</div>
    <div class="hue-grid">
      <div v-for="hue in functionalHues" :key="hue.name" class="hue-block">
        <div class="hue-label">{{ hue.label }}</div>
        <div class="swatch-row">
          <div
            v-for="step in steps"
            :key="`${hue.name}-${step}`"
            class="swatch"
            :style="{
              background: `rgb(var(--c-${hue.name}-${step}))`,
              color: step > 5 ? '#fff' : '#000',
            }"
            :title="`--c-${hue.name}-${step}`"
          >
            <span class="swatch-name">{{ step }}</span>
          </div>
        </div>
      </div>
    </div>

    <div class="section-title">色相色阶</div>
    <div class="hue-grid">
      <div v-for="hue in chromaticHues" :key="hue.name" class="hue-block">
        <div class="hue-label">{{ hue.label }}</div>
        <div class="swatch-row">
          <div
            v-for="step in steps"
            :key="`${hue.name}-${step}`"
            class="swatch"
            :style="{
              background: `rgb(var(--c-${hue.name}-${step}))`,
              color: step > 5 ? '#fff' : '#000',
            }"
            :title="`--c-${hue.name}-${step}`"
          >
            <span class="swatch-name">{{ step }}</span>
          </div>
        </div>
      </div>
    </div>
  </div>
</template>

<script lang="ts" setup>
const steps = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];

const functionalHues = [
  { name: "primary", label: "Primary（主色）" },
  { name: "success", label: "Success" },
  { name: "warning", label: "Warning" },
  { name: "danger", label: "Danger" },
  { name: "link", label: "Link" },
  { name: "gray", label: "Gray" },
];

const chromaticHues = [
  { name: "brand", label: "Brand" },
  { name: "red", label: "Red" },
  { name: "orangered", label: "Orangered" },
  { name: "orange", label: "Orange" },
  { name: "gold", label: "Gold" },
  { name: "yellow", label: "Yellow" },
  { name: "lime", label: "Lime" },
  { name: "green", label: "Green" },
  { name: "cyan", label: "Cyan" },
  { name: "blue", label: "Blue" },
  { name: "purple", label: "Purple" },
  { name: "pinkpurple", label: "Pinkpurple" },
  { name: "magenta", label: "Magenta" },
];
</script>

<style lang="less" scoped>
.palette-demo {
  color: var(--c-color-text-1);
}

.section-title {
  margin: 16px 0 12px;
  font-size: 16px;
  font-weight: 600;
}

.hue-grid {
  display: grid;
  grid-template-columns: repeat(3, minmax(0, 1fr));
  gap: 16px 20px;
  margin-bottom: 8px;
}

.hue-block {
  min-width: 0;
}

.hue-label {
  margin-bottom: 6px;
  font-size: 13px;
  color: var(--c-color-text-3);
}

.swatch-row {
  display: flex;
  gap: 2px;
  overflow: hidden;
  border-radius: var(--c-border-radius-md, 4px);
}

.swatch {
  flex: 1;
  min-width: 0;
  height: 36px;
  display: flex;
  align-items: center;
  justify-content: center;
  font-size: 11px;
  font-variant-numeric: tabular-nums;
}

.swatch-name {
  overflow: hidden;
  text-overflow: ellipsis;
  white-space: nowrap;
  padding: 0 2px;
}

@media (max-width: 991px) {
  .hue-grid {
    grid-template-columns: repeat(2, minmax(0, 1fr));
  }
}

@media (max-width: 767px) {
  .hue-grid {
    grid-template-columns: 1fr;
  }
}
</style>
```

---

Document: llms/zh-CN/components/paper.md

<!-- Source: src/paper/README.md; locale: zh-CN; page: /components/paper/ -->

# Paper 基础表面

Paper 是承载内容的底层表面：背景、圆角、可选边框与阴影。不提供 variant、status、标题或内容结构，不添加默认内边距。需要完整卡片结构时使用 Card；只需要布局时使用 div 或 Space。

适用于自定义面板、表单分区、侧栏底板以及弹层内部表面。Paper 不负责弹层定位、焦点管理，也不会自动赋予按钮语义。交互内容请使用 Button 等语义组件。

```html
<c-paper bordered>基础边框</c-paper>
<c-paper bordered :elevation="2" style="padding: 16px">边框与阴影独立</c-paper>
<c-paper :width="120" height="4rem" :radius="8" />
```

## 基础示例

### 演示

Example source: src/paper/__demos__/basic.vue

```vue
<template>
  <c-space wrap>
    <c-paper :width="120" :height="80">Surface</c-paper>
    <c-paper bordered :width="120" :height="80">Border</c-paper>
    <c-paper bordered :elevation="2" style="padding: 16px">Border + shadow</c-paper>
    <c-paper :radius="12" :width="120" :height="80" :elevation="2">Radius</c-paper>
    <c-paper round :width="80" :height="80" bordered />
    <c-paper inline bordered>Inline</c-paper>
    <c-paper ripple bordered :width="120" :height="80">Ripple</c-paper>
  </c-space>
</template>
```

内置动效遵循 prefers-reduced-motion: reduce：保留内容与状态反馈，关闭装饰性旋转、扫光和波纹。Icon 名称切换跳过等待，并取消尚未结束的切换。Ripple 时长变量只控制 CSS，250ms 生命周期计时未改变，每段视觉时长应不超过 250ms；自定义动画类由调用方负责适配。

## 交互与控制

### 动态属性

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `bordered` | 显示边框，与 elevation 独立 | 动态属性 |
| `round` | 50% 圆角；宽高相等时为圆形 | 动态属性 |
| `radius` | 圆角，显式值优先于 round | 动态属性 |
| `elevation` | false 关闭；true 使用 2 级；数字为 0–24 | 动态属性 |
| `width` | 宽度 | 动态属性 |
| `height` | 高度 | 动态属性 |
<!-- demo-config-notes:end -->

边框与阴影独立切换；显式 radius 优先于 round，取消显式值后恢复圆形。Paper 不提供按钮语义，示例在内部使用原生按钮，并由父级统计冒泡的 click。

Example source: src/paper/__demos__/live-properties.vue

```vue
<script setup>
import { ref } from "vue";

const bordered = ref(false);
const round = ref(false);
const explicitRadius = ref(false);
const elevated = ref(false);
const clicks = ref(0);
</script>

<template>
  <section class="paper-live-demo">
    <div class="controls">
      <c-checkbox v-model="bordered"> Paper border</c-checkbox>
      <c-checkbox v-model="round"> Round paper</c-checkbox>
      <c-checkbox v-model="explicitRadius"> Explicit radius</c-checkbox>
      <c-checkbox v-model="elevated"> Paper shadow</c-checkbox>
    </div>
    <p role="status">Surface clicks: {{ clicks }}</p>
    <c-paper
      data-testid="live-paper"
      :bordered="bordered"
      :round="round"
      :radius="explicitRadius ? '12' : undefined"
      :elevation="elevated ? 2 : false"
      width="160"
      :height="100"
      @click="clicks++"
    >
      <c-button html-type="button">Surface action</c-button>
    </c-paper>
  </section>
</template>

<style scoped>
.controls {
  display: flex;
  flex-wrap: wrap;
  gap: 12px;
}
.controls label {
  display: inline-flex;
  align-items: center;
  gap: 4px;
}
[data-testid="live-paper"] {
  display: flex;
  align-items: center;
  justify-content: center;
}
</style>
```

## API

### Props

| 属性 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| bordered | 显示边框，与 elevation 独立 | boolean | false |
| elevation | false 关闭；true 使用 2 级；数字为 0–24 | boolean / number | false |
| ripple | 启用水波效果，不自动赋予按钮语义 | boolean | false |
| radius | 圆角，显式值优先于 round | number / string | — |
| width | 宽度 | number / string | — |
| height | 高度 | number / string | — |
| round | 50% 圆角；宽高相等时为圆形 | boolean | false |
| inline | 使用 inline-flex | boolean | false |

radius、width、height 的数字和数字字符串使用 px，其他字符串按 CSS 长度传递，例如 1rem、50%、calc(100% - 8px)。类名、原生属性和自定义样式透传到根容器。

### Events

| 事件 | 说明 | 参数 |
| --- | --- | --- |
| click | 点击时触发一次 | MouseEvent |

### Slots

| 插槽 | 说明 |
| --- | --- |
| default | 表面内部内容 |

### 样式变量

| 变量 | 默认值 |
| --- | --- |
| --c-paper-background | `var(--c-sys-color-surface-default)` |
| --c-paper-border-radius | `4px` |
| --c-paper-border-width | `1px` |
| --c-paper-border-color | `var(--c-sys-color-border-default)` |
| --c-paper-transition-duration | `var(--c-sys-motion-duration-slow)` |

内置主题可覆盖背景和圆角。bordered=false 不占边框空间，开启后使用 border-box；固定宽高包含边框。背景、边框和阴影彼此独立。

### 类型

```ts
import type { PaperProps, PaperInstance } from '@cedar-design/ui'
```

## 独立同源维护

两端分别保存主体、Props、样式、token 和契约测试，只调整前缀及本地导入；不引用跨库核心，不共享组件实例或状态。

Maple 迁移说明：默认背景改为主题表面色，默认不再显示手形光标；inline 内部类改为 mp-paper--inline。原有尺寸、圆角、阴影与水波 API 保留。

---

Document: llms/zh-CN/components/people-select.md

<!-- Source: src/people-select/README.md; locale: zh-CN; page: /components/people-select/ -->

# PeopleSelect 人员选择

`options` 接收人员数组或加载函数，组件内部管理等待、取消与过期结果；`fallback-option` 同步读取独立的响应式回显数据，异步查询完成后更新该数据即可回显。头像由 `avatar` 提供。组件提供可选的电话、聊天图标，拨号、聊天和权限仍由业务实现。

## 全局默认属性与局部覆盖

```ts
import { PeopleSelect, type PeopleSelectProps } from "@cedar-design/ui";
PeopleSelect.setPropsDefaults({
  options: (query, { signal }) => peopleService.search(query, signal),
  fallbackOption: (id) => personCache.value[id] ?? { value: id, label: id },
  showPhone: true,
  showChat: true,
  call: (person) => businessPhone.call(person.mobile),
  chat: (person) => businessChat.open(person.value),
} satisfies PeopleSelectProps);
```

```vue
<c-people-select v-model="personId" />
<!-- 本页覆盖候选接口与聊天行为，关闭电话图标 -->
<c-people-select
  v-model="personId"
  :options="loadMyTeam"
  :chat="openTeamChat"
  :show-phone="false"
  read-pretty
/>
<!-- 数组覆盖全局加载函数；空数组也表示明确使用本地空数据 -->
<c-people-select v-model="personId" :options="[]" />
```

局部属性优先于全局默认。图标只在阅读态展示；默认 show-phone/show-chat 为 false。启用显示但没有处理函数时，按钮禁用；未选人员、禁用状态也不能触发动作。函数返回 Promise 时按钮自动等待，失败触发 action-error(error, call|chat)。组件不自动打开 tel: 链接，也不包含聊天 SDK。业务需要独立处理读取权限与操作权限时，可覆盖操作区域。

setPropsDefaults 在挂载前配置一次，修改组件定义的默认属性；不是按应用或租户隔离的上下文。SSR 不应逐请求修改，动态页面/租户配置推荐封装业务组件并透传 props。

## 自定义操作区域

```vue
<c-people-select v-model="personId" read-pretty>
  <template #actions="{ person, disabled }">
    <business-person-actions :person="person" :disabled="disabled" />
  </template>
</c-people-select>
```

操作区域优先级：actions 插槽 → render-actions → 内置电话/聊天按钮。它们均不会触发字段编辑或更改已选人员。

## 基础示例

### 完整业务示例

Example source: src/people-select/__demos__/injected-services.vue

```vue
<script setup lang="ts">
import { onMounted, ref } from 'vue'
const personId = ref<string | null>('alice')
const log = ref('')
const people = [
 { value: 'alice', label: 'Alice', mobile: '13800000000', avatar: 'data:image/svg+xml,%3Csvg xmlns="http://www.w3.org/2000/svg" width="24" height="24"%3E%3Ccircle cx="12" cy="12" r="12" fill="%236579af"/%3E%3C/svg%3E' },
 { value: 'bob', label: 'Bob', mobile: '13900000000' },
]
const displayed = ref<Record<string, (typeof people)[number]>>({})
// 模拟详情请求：回显数据独立更新，不加入候选列表。
onMounted(() => { setTimeout(() => { displayed.value.alice = people[0] }, 600) })
const fallbackOption = (id: string) => displayed.value[id] ?? { value: id, label: id }
async function options(query: string, { signal }: { signal: AbortSignal }) {
 await new Promise(resolve => setTimeout(resolve, 200))
 if (signal.aborted) return []
 return people.filter(person => person.label.toLowerCase().includes(query.toLowerCase()))
}
async function call(person: { value: string; mobile?: string }) { log.value = `Call: ${person.mobile || person.value}` }
async function chat(person: { value: string }) { log.value = `Chat: ${person.value}` }
</script>
<template>
 <c-space direction="column">
  <c-people-select v-model="personId" :options="options" :fallback-option="fallbackOption" clearable :empty-value="null" />
  <c-people-select v-model="personId" :fallback-option="fallbackOption" show-phone show-chat :call="call" :chat="chat" read-pretty />
  <p role="status">{{ log }}</p>
 </c-space>
</template>
```

## API

### 空值识别与阅读空文案

`empty-values` 用于空值识别，`empty-value` 保留原清空输出；`empty-text` 仅在 `read-pretty` 空内容下展示，默认 `'-'`，字段 > FormItem > Form，自定义 read 插槽优先。显式配置 empty-values 后，内置 required 接入该策略，自定义校验仍收到原值。详见[统一说明](llms/zh-CN/guide/empty-values.md)。

| 参数         | 类型               | 缺省与范围                                            |
| ------------ | ------------------ | ----------------------------------------------------- |
| empty-values | readonly unknown[] | 字段 > FormItem > Form > 组件族默认；完整覆盖，不合并 |
| empty-text   | string             | 字段 > FormItem > Form > '-'；显式 '' 有效            |

以上是字段展示层 API；纯面板不因此新增阅读模式。Form 与 FormItem 提供继承配置。empty-value 的现有类型与默认输出仍按该组件原 API 执行。

| 属性                    | 说明                                             | 默认值 |
| ----------------------- | ------------------------------------------------ | ------ |
| v-model / default-value | 字符串 ID，null 表示显式清空                     | — / '' |
| options                 | 人员数组，或 (query, { signal }) => 数组/Promise | —      |
| fallback-option         | boolean / (id) => PeopleSelectOption             | true   |
| show-avatar             | 展示 avatar                                      | true   |
| show-phone / show-chat  | 阅读态电话 / 聊天图标                            | false  |
| call / chat             | (person) => void/Promise，由业务实现             | —      |
| render-actions          | ({ person, disabled }) => VNodeChild             | —      |
| is-label / read-pretty  | 阅读态，仅解析已选人员，不加载候选               | false  |
| disabled / readonly     | 省略继承表单状态                                 | —      |
| empty-value             | 清空结果；可指定 null 或返回 null 的函数         | ''     |

人员数据为 `{ value: string, label: string, avatar?: string, mobile?: string, disabled?: boolean }`。

signal 可选地传给 fetch 取消过期请求；不是 HTTP 参数，也不会回滚服务器操作。忽略 signal 时，组件仍隔离旧结果。函数结果默认不再本地二次过滤，filter-option 只配置本地匹配策略。

事件：update:model-value、change、clear、search、load-error(error, options)、action-error(error, call|chat)。实例方法：refresh()、focus()、blur()。无独立 request 属性，无需外部 useAsyncData 或专用 provider key。

`empty-value` 可显式设为 `null`（或 `() => null`），清空时原样提交 null；省略时保留组件原默认值。界面把 null 显示为空，不会把普通输入的空字符串自动转成 null。支持弹出编辑的字段中，清空先修改草稿，确认后提交，取消则保留原值。

`fallback-option` 与候选 options 独立，不返回 Promise、不主动发请求。回显优先使用当前候选项，不存在时读取 fallback；传入 false 关闭未匹配值的回显。

### 业务请求如何接收取消信号

组件为每次操作创建 AbortController，把 signal 传入加载函数。业务需要逐层透传给请求库。fetch 原生支持 AbortSignal；Axios 0.22+ 支持 signal；ofetch、Ky 会向底层 fetch 传递或合并这个信号。未支持的封装需要把 abort 事件适配到自己的取消方法。取消客户端请求不能回滚服务端已完成的操作。

```ts
async function loadPeople(query, { signal }) {
  const response = await fetch(`/api/people?q=${encodeURIComponent(query)}`, {
    signal,
  });
  if (!response.ok) throw new Error("People request failed");
  return response.json();
}

// Axios: preserve signal through your service wrapper.
async function loadWithAxios(query, { signal }) {
  const { data } = await axios.get("/api/people", {
    params: { q: query },
    signal,
  });
  return data;
}

// Other fetch wrappers:
const loadWithOfetch = (query, { signal }) =>
  ofetch("/api/people", { query: { q: query }, signal });
const loadWithKy = (query, { signal }) =>
  ky.get("/api/people", { searchParams: { q: query }, signal }).json();
```

[AbortSignal](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) · [Axios cancellation](https://axios-http.com/docs/cancellation) · [ofetch](https://github.com/unjs/ofetch) · [Ky](https://github.com/sindresorhus/ky#cancellation)

### 共享字段加载

`loading-mode="line"` 使用 FieldDecorator 的共享加载线；默认模式保留本组件已有的加载展示。加载状态本身不隐式设置 disabled 或 readonly。

---

Document: llms/zh-CN/components/popconfirm.md

<!-- Source: src/popconfirm/README.md; locale: zh-CN; page: /components/popconfirm/ -->

# Popconfirm

点击元素，弹出气泡式的确认框。

## 基础示例

### 基础用法

点击按钮打开确认框；确认或取消后收起。示例只演示确认交互，不执行业务数据删除。

Example source: src/popconfirm/__demos__/basic.vue

```vue
<template>
  <c-popconfirm content="Are you sure you want to delete?">
    <c-button>Click To Delete</c-button>
  </c-popconfirm>
</template>

<script lang="ts" setup>
</script>
```

## 外观与状态

### 确认框类型

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `content` | 内容 | 确认框类型 |
| `type` | 气泡确认框的类型 | 确认框类型 |
<!-- demo-config-notes:end -->

通过 `type` 属性可以设置确认框类型。

Example source: src/popconfirm/__demos__/type.vue

```vue
<template>
  <c-space>
    <c-popconfirm content="Are you sure you want to delete?" type="info">
      <c-button>Click To Delete</c-button>
    </c-popconfirm>
    <c-popconfirm content="Are you sure you want to delete?" type="success">
      <c-button>Click To Delete</c-button>
    </c-popconfirm>
    <c-popconfirm content="Are you sure you want to delete?" type="warning">
      <c-button>Click To Delete</c-button>
    </c-popconfirm>
    <c-popconfirm content="Are you sure you want to delete?" type="error">
      <c-button>Click To Delete</c-button>
    </c-popconfirm>
  </c-space>
</template>

<script lang="ts" setup>
</script>
```

## 布局与排列

### 弹出位置

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `content` | 内容 | 弹出位置 |
| `placement` | 浮层相对触发元素的首选方位，默认 top；启用默认的 auto-fit-position 时，空间不足会自动翻转并约束到可视区域，不保证最终停在该侧 | 弹出位置 |
<!-- demo-config-notes:end -->

`popconfirm` 支持 12 个不同的方位。分别为：`上左` `上` `上右` `下左` `下` `下右` `左上` `左` `左下` `右上` `右` `右下`。

Example source: src/popconfirm/__demos__/placement.vue

```vue
<template>
  <div :style="{ position: 'relative', width: '440px', height: '280px' }">
    <c-popconfirm content="This is a Popconfirm" placement="top-start">
      <c-button class="button" :style="{ position: 'absolute', top: '0', left: '70px' }">TL</c-button>
    </c-popconfirm>
    <c-popconfirm content="This is a Popconfirm" placement="top">
      <c-button class="button" :style="{ position: 'absolute', top: '0', left: '180px' }">TOP</c-button>
    </c-popconfirm>
    <c-popconfirm content="This is a Popconfirm" placement="top-end">
      <c-button class="button" :style="{ position: 'absolute', top: '0', left: '290px' }">TR</c-button>
    </c-popconfirm>
    <c-popconfirm content="This is a Popconfirm" placement="bottom-start">
      <c-button class="button" :style="{ position: 'absolute', top: '240px', left: '70px' }">BL</c-button>
    </c-popconfirm>
    <c-popconfirm content="This is a Popconfirm" placement="bottom">
      <c-button class="button" :style="{ position: 'absolute', top: '240px', left: '180px' }">BOTTOM</c-button>
    </c-popconfirm>
    <c-popconfirm content="This is a Popconfirm" placement="bottom-end">
      <c-button class="button" :style="{ position: 'absolute', top: '240px', left: '290px' }">BR</c-button>
    </c-popconfirm>
    <c-popconfirm content="This is a Popconfirm" placement="left-start">
      <c-button class="button" :style="{ position: 'absolute', top: '60px', left: '10px' }">LT</c-button>
    </c-popconfirm>
    <c-popconfirm content="This is a Popconfirm" placement="left">
      <c-button class="button" :style="{ position: 'absolute', top: '120px', left: '10px' }">LEFT</c-button>
    </c-popconfirm>
    <c-popconfirm content="This is a Popconfirm" placement="left-end">
      <c-button class="button" :style="{ position: 'absolute', top: '180px', left: '10px' }">LB</c-button>
    </c-popconfirm>
    <c-popconfirm content="This is a Popconfirm" placement="right-start">
      <c-button class="button" :style="{ position: 'absolute', top: '60px', left: '350px' }">RT</c-button>
    </c-popconfirm>
    <c-popconfirm content="This is a Popconfirm" placement="right">
      <c-button class="button" :style="{ position: 'absolute', top: '120px', left: '350px' }">RIGHT</c-button>
    </c-popconfirm>
    <c-popconfirm content="This is a Popconfirm" placement="right-end">
      <c-button class="button" :style="{ position: 'absolute', top: '180px', left: '350px' }">RB</c-button>
    </c-popconfirm>
  </div>
</template>

<script lang="ts" setup>
</script>
```

## 内容与展示

### before 钩子与 done 兼容

`beforeConfirm(done) / beforeCancel(done)` 为统一入口，不新增另一套命名。


只记录日志的同步钩子应显式 return true；同步 undefined 表示仍在等待回调。注意：以前返回 `Promise<void>` 却不调用 done 的异步钩子，现在会在 Promise 完成后放行。


Example source: src/popconfirm/__demos__/guard-protocol.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import type { PopconfirmBeforeConfirm } from "@cedar-design/ui";
const open = ref(false);
const mode = ref("promise");
const allowed = ref(false);
const status = ref("");
const check: PopconfirmBeforeConfirm = (payload, done, { signal }) => {
  status.value = `等待： ${payload.action}`;
  if (mode.value === "done") {
    setTimeout(() => {
      status.value = allowed.value ? "允许" : "阻止";
      done(!signal.aborted && allowed.value);
    }, 500);
    return;
  }
  return new Promise<boolean>((resolve) =>
    setTimeout(() => {
      status.value = allowed.value ? "允许" : "阻止";
      resolve(!signal.aborted && allowed.value);
    }, 500),
  );
};
</script>
<template>
  <c-space direction="column" align="stretch">
    <c-switch v-model="allowed" />
    <c-form-item layout="vertical" size="sm" label="mode">
      <c-radio-group
        aria-label="mode"
        v-model="mode"
        :options="[
          { value: 'promise', label: 'Promise' },
          { value: 'done', label: 'done 回调' },
        ]"
        variant="button"
        size="sm"
      />
    </c-form-item>
    <c-button @click="open = true">打开</c-button>
    <c-popconfirm
      v-model:open="open"
      :before-confirm="check"
      @guard-error="status = 'Error'"
    >
      <template #default
        ><c-button v-if="true" @click="open = true">Confirm action</c-button
        ><span v-else>通过 beforeClose 关闭</span></template
      >
    </c-popconfirm>
    <p role="status">{{ status }}</p>
  </c-space>
</template>
```


Promise 与 done 共用一次完成状态：`false` / `done(false)` 阻止，`true` / `done()` 允许；Promise&lt;void&gt; 正常完成允许。重复完成只生效一次，异常触发 guard-error，取消或卸载后迟到结果无效。此类关闭/确认回调同步返回 void 时保留原回调协议，等待 done。


守卫统一使用 `(payload, done, context)`：关闭 payload 为 `{ action }`，切换和提交为 `{ value, previousValue }`，Popup 为 `{ reason }`。context 提供 `signal` 和可选原始 `event`。返回 boolean/Promise，或调用 done()/done(false)；同步 void 等待 done，Promise&lt;void&gt; 放行。首次完成生效。等待期间自动管理 loading/disabled，取消后旧结果失效，不暴露内部按钮 refs。

## 自定义与插槽

### 自定义按钮

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `content` | 内容 | 自定义按钮 |
| `confirm-button-text` | 确认按钮的内容 | 自定义按钮 |
| `cancel-text` | 取消按钮的内容 | 自定义按钮 |
<!-- demo-config-notes:end -->

自定义按钮的文字或图标。

Example source: src/popconfirm/__demos__/custom.vue

```vue
<template>
  <c-popconfirm content="Do you want to discard the draft?" confirmButtonText="Discard" cancelText="No">
    <c-button>Discard</c-button>
  </c-popconfirm>
</template>

<script lang="ts" setup>
</script>
```

## 阅读方向

继承最近的 `dir="ltr|rtl"`，支持运行时切换与局部覆盖。内容与动作采用逻辑对齐，确认与取消顺序按阅读方向排列；方向切换不触发确认或取消，显式弹出方位仍沿用原有物理/逻辑约定。

## API

### `<popconfirm>` Props

| 参数名                      | 描述                                                                                      | 类型                                                                                                     |  默认值  |
| --------------------------- | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | :------: |
| content                     | 内容                                                                                      | `string`                                                                                                 |   `-`    |
| placement                    | 浮层相对触发元素的首选方位，默认 top；启用默认的 auto-fit-position 时，空间不足会自动翻转并约束到可视区域，不保证最终停在该侧 | `'top' \| 'top-start' \| 'top-end' \| 'bottom' \| 'bottom-start' \| 'bottom-end' \| 'left' \| 'left-start' \| 'left-end' \| 'right' \| 'right-start' \| 'right-end'` | `'top'`  |
| open **(v-model)** | 气泡确认框是否可见                                                                        | `boolean`                                                                                                |   `-`    |
| default-open       | 气泡确认框默认是否可见（非受控模式）                                                      | `boolean`                                                                                                | `false`  |
| type                        | 气泡确认框的类型                                                                          | `'info' \| 'success' \| 'warning' \| 'error'`                                                            | `'info'` |
| confirm-button-text                     | 确认按钮的内容                                                                            | `string`                                                                                                 |   `-`    |
| cancel-text                 | 取消按钮的内容                                                                            | `string`                                                                                                 |   `-`    |
| confirm-button-loading                  | 确认按钮是否为加载中状态                                                                  | `boolean`                                                                                                | `false`  |
| confirm-button-props             | 确认按钮的Props                                                                           | `ButtonProps`                                                                                            |   `-`    |
| cancel-button-props         | 取消按钮的Props                                                                           | `ButtonProps`                                                                                            |   `-`    |
| content-class               | 弹出框内容的类名                                                                          | `ClassName`                                                                                              |   `-`    |
| content-style               | 弹出框内容的样式                                                                          | `CSSProperties`                                                                                          |   `-`    |
| arrow-class                 | 弹出框箭头的类名                                                                          | `ClassName`                                                                                              |   `-`    |
| arrow-style                 | 弹出框箭头的样式                                                                          | `CSSProperties`                                                                                          |   `-`    |
| popup-container             | 弹出框的挂载点                                                                            | `string \| HTMLElement \| false`                                                                                  |   `-`    |
| `before-confirm` | 返回 boolean/Promise 或调用 done；首次完成生效 | `PopconfirmBeforeConfirm` | — |
| `before-cancel` | 返回 boolean/Promise 或调用 done；首次完成生效 | `PopconfirmBeforeConfirm` | — |

### `<popconfirm>` Events

| 事件名               | 描述                           | 参数               |
| -------------------- | ------------------------------ | ------------------ |
| open-change | 气泡确认框的显隐状态改变时触发 | open: `boolean` |
| confirm              | 点击确认按钮时触发             | -                  |
| cancel               | 点击取消按钮时触发             | -                  |

### `<popconfirm>` Slots

| 插槽名  | 描述 | 参数 |
| ------- | :--: | ---- |
| icon    | 图标 | -    |
| content | 内容 | -    |

### 类型定义

组件导出以下类型定义

```ts
import type { PopconfirmInstance } from '@cedar-design/ui'
```


### 方位语义与配置入口

placement 直接复用 TriggerPlacement / triggerPlacements；旧 TriggerPosition / TRIGGER_POSITIONS 别名已删除，方位值域不变。

### 守卫等待反馈

before-* 等待期间显示加载反馈并标记 aria-busy；拒绝或失败后恢复，重复提交不再启动同一操作。普通事件返回的 Promise 不参与加载。

---

Document: llms/zh-CN/components/popover.md

<!-- Source: src/popover/README.md; locale: zh-CN; page: /components/popover/ -->

# Popover 气泡卡片

点击触发元素后展示结构化内容。Popover 可以包含按钮、表单和其他交互元素；纯文字说明使用 Tooltip。

## 基础示例

### 基础用法

Example source: src/popover/__demos__/basic.vue

```vue
<template>
  <c-popover title="设备状态">
    <c-button>点击查看</c-button>
    <template #content>
      <p>设备：生产线 A-03</p>
      <p>状态：运行中</p>
    </template>
  </c-popover>
</template>
```

## 交互与控制

### 交互内容与状态保留

Popover 默认 `unmount-on-close="false"`，关闭后保留表单草稿。

Example source: src/popover/__demos__/interactive.vue

```vue
<template>
  <c-popover v-model:open="open" title="快速备注">
    <c-button>编辑备注</c-button>
    <template #content>
      <c-space direction="column">
        <c-input v-model="draft" placeholder="关闭后再次打开，草稿仍会保留" />
        <c-button status="primary" @click="open = false">完成</c-button>
      </c-space>
    </template>
  </c-popover>
</template>

<script setup lang="ts">
import { ref } from 'vue'

const open = ref(false)
const draft = ref('')
</script>
```

## 阅读方向

继承最近的 `dir="ltr|rtl"`，支持运行时切换与局部覆盖。内容默认对齐阅读起点，弹层继承来源方向；逻辑 start/end 对齐随方向变化，显式 left/right 方位保持物理语义。

## API

Popover 继承 Trigger 的定位、容器、受控状态、关闭策略和公开方法。

| 属性 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| title | 标题 | `string` | — |
| content | 正文 | `string` | — |
| trigger | 触发方式 | `TriggerEvent \| TriggerEvent[]` | `click` |
| placement | 浮层相对触发元素的首选方位，默认 bottom；启用默认的 auto-fit-position 时，空间不足会自动翻转并约束到可视区域，不保证最终停在该侧 | `TriggerPlacement` | `bottom` |
| show-arrow | 是否显示箭头 | `boolean` | `true` |
| popup-offset | 沿方位主轴的距离 | `number` | `10` |
| unmount-on-close | 关闭后卸载内容；默认保留交互草稿 | `boolean` | `false` |
| close-on-click-reference | 再次点击触发元素时关闭 | `boolean` | `true` |

事件为 `update:open`、`open-change`、`open`、`opened`、`close`、`closed`、`click-outside`。插槽为 `default`、`title` 和 `content`。属性内容与插槽同时存在时插槽优先。

实际面板包含统一的 content/title/body 三层。触发元素通过 `aria-controls`、`aria-expanded` 与面板关联；外部 reference 和 SVG 同样支持。

## 同源约定

Cedar 与 Maple 独立保存同一份主体、Props、外观映射和结构样式。无样式定位场景直接使用 Trigger；Popover 不提供 `defaultStyle`、`popoverClass` 或 `elevation`，自定义外观使用组件 Token、`content-class` 或 `content-style`。

## 公开 CSS 变量

以下为实际 :root 默认值。业务定制优先使用组件变量；内部定位变量不属于公开 API。

| 变量 | 默认值 | 意义与场景 |
| --- | --- | --- |
| `--c-popover-background` | `var(--c-sys-color-surface-overlay)` | 内容与箭头背景 |
| `--c-popover-text-color` | `var(--c-sys-color-content-secondary)` | 正文前景 |
| `--c-popover-border-color` | `var(--c-sys-color-border-default)` | 内容与箭头边框颜色 |
| `--c-popover-border-width` | `1px` | 内容与箭头边框宽度 |
| `--c-popover-border-radius` | `var(--c-sys-radius-md)` | 内容圆角 |
| `--c-popover-box-shadow` | `var(--c-shadow2-down)` | 内容阴影，保留平台差异 |
| `--c-popover-arrow-z-index` | `1` | 箭头在当前浮层内的堆叠层级 |
| `--c-popover-padding-horizontal` | `var(--c-sys-space-7)` | 内容横向内边距 |
| `--c-popover-padding-vertical` | `var(--c-sys-space-6)` | 内容纵向内边距 |
| `--c-popover-font-size` | `var(--c-sys-font-size-md)` | 内容字号 |
| `--c-popover-line-height` | `var(--c-line-height)` | 内容行高 |
| `--c-popover-title-text-color` | `var(--c-sys-color-content-primary)` | 标题前景 |
| `--c-popover-title-font-size` | `var(--c-sys-font-size-lg)` | 标题字号 |
| `--c-popover-title-font-weight` | `var(--c-sys-font-weight-medium)` | 标题字重 |
| `--c-popover-title-content-gap` | `var(--c-sys-space-2)` | 标题与正文间距 |
| `--c-popover-animation-duration` | `var(--c-sys-motion-duration-standard)` | 组件入退场时长；reduced-motion 可覆盖 |

Maple 暗色保留圆角 2px，阴影保留平台差异。内容与箭头共享背景／边框变量，不再受 Trigger 样式加载顺序影响。

使用 Teleport 时，变量需放在实际 popup 的作用域中（例如通过 `popup-style`）；触发按钮上的变量不会自动继承到浮层。

---

Document: llms/zh-CN/components/progress-group.md

<!-- Source: src/progress-group/README.md; locale: zh-CN; page: /components/progress-group/ -->

# ProgressGroup 分段进度条

将多个数值展示为同一条进度轨中的分段，并提供对应图例。

## 基础示例

### 基础用法

`items` 中每项的 `value` 都以 `max` 为基准计算宽度，开启 `show-text` 可展示累计百分比。

Example source: src/progress-group/__demos__/basic.vue

```vue
<script setup lang="ts">
import type { ProgressGroupItem } from '@cedar-design/ui'

const items: ProgressGroupItem[] = [
  { label: '系统', value: 24, color: '#64748b' },
  { label: '应用', value: 8, color: '#f53f3f' },
  { label: '多媒体', value: 42, color: '#00b42a' },
]
</script>

<template>
  <c-progress-group :items="items" :max="128" show-text style="max-width: 520px" />
</template>
```

## 外观与状态

### 进度组尺寸与颜色

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `items` | 分段数据 | 进度组尺寸与颜色 |
| `size` | 进度轨尺寸 | 进度组尺寸与颜色 |
| `color` | 分段未指定颜色时使用的默认颜色 | 进度组尺寸与颜色 |
| `show-text` | 是否展示累计百分比 | 进度组尺寸与颜色 |
<!-- demo-config-notes:end -->

比较同类分段数据的尺寸和颜色覆盖；方向、环形布局、总量溢出与键盘操作另行展示。

<details>
<summary>配置说明与使用限制</summary>

#### 尺寸

通过 `size` 设置进度轨粗细。

#### 颜色与纯进度轨

通过 `color` 统一设置默认颜色，也可以在每个 item 上覆盖；省略所有标签可隐藏图例。

</details>

Example source: src/progress-group/__demos__/appearance-comparison.vue

```vue
<script setup lang="ts">
import { proxyRefs as demoProxyRefs } from 'vue'

const scene1 = demoProxyRefs((() => {

const items = [
  { value: 24 },
  { value: 18, color: "#722ed1" },
  { value: 30, color: "#0fc6c2" },
];

const sizes = ["xs", "sm", "md", "lg", "xl"] as const;
return { items, sizes }
})())

const scene2 = demoProxyRefs((() => {

const inheritedColorItems = [
  { label: "文档", value: 20 },
  { label: "测试", value: 35 },
];

const trackOnlyItems = [
  { value: 16 },
  { value: 22, color: "#722ed1" },
  { value: 28, color: "#0fc6c2" },
];
return { inheritedColorItems, trackOnlyItems }
})())
</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="sizes">
    <h4><span lang="zh-CN">尺寸</span><span lang="en-US">sizes</span></h4>
    <c-space direction="column" size="16px" style="max-width: 520px">
        <div
          v-for="size in scene1.sizes"
          :key="size"
          style="
            display: grid;
            grid-template-columns: 24px 1fr;
            align-items: center;
            gap: 12px;
          "
        >
          <span>{{ size }}</span>
          <c-progress-group :items="scene1.items" :size="size" />
        </div>
      </c-space>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="color">
    <h4><span lang="zh-CN">颜色与纯进度轨</span><span lang="en-US">color</span></h4>
    <c-space direction="column" size="24px" style="max-width: 520px">
        <c-progress-group :items="scene2.inheritedColorItems" color="#ff7d00" show-text />
        <c-progress-group :items="scene2.trackOnlyItems" size="lg" />
      </c-space>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

## 布局与排列

### 排列方向

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `items` | 分段数据 | 排列方向 |
| `show-text` | 是否展示累计百分比 | 排列方向 |
| `orientation` | 线形进度轨的横纵朝向，默认 horizontal；仅 mode=line 生效 | 排列方向 |
| `size` | 进度轨尺寸 | 排列方向 |
<!-- demo-config-notes:end -->

`orientation="vertical"` 可展示纵向分段进度条；纵向模式需要容器提供明确高度。

Example source: src/progress-group/__demos__/orientation.vue

```vue
<script setup lang="ts">
const items = [
  { label: "系统", value: 24, color: "#64748b" },
  { label: "应用", value: 18, color: "#f53f3f" },
  { label: "媒体", value: 32, color: "#00b42a" },
];
</script>

<template>
  <c-space wrap size="64px" align="flex-start">
    <c-progress-group :items="items" show-text style="width: 420px" />
    <c-progress-group
      :items="items"
      orientation="vertical"
      size="lg"
      show-text
      style="height: 220px"
    />
  </c-space>
</template>
```

## 内容与展示

### 环形分段进度

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `mode` | 展示模式 | 环形分段进度 |
| `items` | 分段数据 | 环形分段进度 |
| `show-text` | 是否展示累计百分比 | 环形分段进度 |
| `circle-size` | 环形模式的直径 | 环形分段进度 |
| `stroke-width` | 环形模式的轨道宽度 | 环形分段进度 |
<!-- demo-config-notes:end -->

设置 `mode="circle"` 展示分段圆环。通过 `circle-size` 控制直径，`stroke-width` 控制环宽，状态内容位于圆心。

Example source: src/progress-group/__demos__/circle.vue

```vue
<script setup lang="ts">
const items = [
  { label: "系统", value: 24, color: "#64748b" },
  { label: "应用", value: 18, color: "#f53f3f" },
  { label: "媒体", value: 32, color: "#00b42a" },
];
</script>

<template>
  <c-space wrap size="48px" align="flex-start">
    <c-progress-group mode="circle" :items="items" show-text />
    <c-progress-group
      mode="circle"
      :items="items"
      :circle-size="168"
      :stroke-width="12"
      show-text
    >
      <template #text="{ value, max }">
        <div style="text-align: center">
          <strong>{{ value }}</strong
          ><br /><small>/ {{ max }} GB</small>
        </div>
      </template>
    </c-progress-group>
  </c-space>
</template>
```

## 交互与控制

### 超额数据与键盘提示

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `items` | 分段数据 | 超额数据与键盘提示 |
| `max` | 所有分段计算占比时的总值 | 超额数据与键盘提示 |
| `tooltip` | 是否启用分段悬浮/聚焦提示 | 超额数据与键盘提示 |
| `show-text` | 是否展示累计百分比 | 超额数据与键盘提示 |
| `aria-label` | 分组的无障碍名称 | 超额数据与键盘提示 |
| `mode` | 展示模式 | 超额数据与键盘提示 |
<!-- demo-config-notes:end -->

示例按钮由父级更新 `max`、`items` 和 `tooltip`，同步驱动线形与环形；它们不是组件内置的编辑事件。可切换容量 100/200、清空/恢复数据、关闭/开启提示。关闭提示后分段不再进入 Tab 顺序，清空后不保留提示。鼠标悬浮优先于键盘焦点，离开悬浮段后回到焦点段提示。

Example source: src/progress-group/__demos__/overflow-keyboard.vue

```vue
<script setup>
import { ref } from "vue";

const initialItems = [
  { label: "A", value: 70 },
  { label: "B", value: 50, color: "#722ed1" },
  { label: "C", value: 10, color: "#0fc6c2" },
];
const items = ref(initialItems);
const max = ref(100);
const tooltip = ref(true);
</script>
<template>
  <c-space direction="column" size="24px" data-demo-capacity>
    <c-space wrap>
      <c-button @click="max = max === 100 ? 200 : 100"
        >Capacity: {{ max }}</c-button
      >
      <c-button @click="items = items.length ? [] : initialItems">{{
        items.length ? "Clear data" : "Restore data"
      }}</c-button>
      <c-button @click="tooltip = !tooltip"
        >Tooltips: {{ tooltip ? "on" : "off" }}</c-button
      >
    </c-space>
    <c-progress-group
      :items="items"
      :max="max"
      :tooltip="tooltip"
      show-text
      aria-label="Capacity line"
    />
    <c-progress-group
      mode="circle"
      :items="items"
      :max="max"
      :tooltip="tooltip"
      show-text
      aria-label="Capacity circle"
    />
    <p aria-live="polite">
      Items: {{ items.length }}; capacity: {{ max }}; tooltips:
      {{ tooltip ? "on" : "off" }}
    </p>
  </c-space>
</template>
```

线形与环形按数据顺序累计裁剪到 max；图例和提示仍保留每项原始占比。例如 70+50 时第二段实际显示 30%，图例仍为 50%。非有限值和负数归零，非法 max 回退 100。Tab 聚焦可见分段展示提示，Escape 关闭；鼠标离开不会关闭仍处于焦点的提示。用 aria-label 为整个分组命名。

size 五档均实现，仅影响线形厚度（2/4/8/12/16px）；环形用 circle-size（支持 number/CSS长度）和 stroke-width。累计文本开关为 show-text，自定义插槽为 text，已删除旧布尔 status / status 插槽。

使用 `text` 和 `item-trailing` 插槽自定义累计状态与图例尾部内容。

鼠标悬浮或键盘聚焦分段时会显示提示并加粗当前分段。item 的 `tip` 可覆盖默认文案，`tooltip` 插槽可完全自定义内容。

Example source: src/progress-group/__demos__/slots.vue

```vue
<script setup lang="ts">
const items = [
  { label: '设计稿', value: 18, color: '#165dff', tip: '设计稿占用 18 GB' },
  { label: '组件', value: 36, color: '#722ed1' },
  { label: '测试', value: 20, color: '#0fc6c2' },
]
</script>

<template>
  <c-progress-group :items="items" show-text style="max-width: 520px">
    <template #text="{ value, max }">已使用 {{ value }} / {{ max }} GB</template>
    <template #item-trailing="{ item }">{{ item.value }} GB</template>
    <template #tooltip="{ item, percent }">{{ item.label }} · {{ item.value }} GB · {{ Math.round(percent) }}%</template>
  </c-progress-group>
</template>
```

## 阅读方向

横向分段、高亮与提示使用同一逻辑起点；垂直进度仍从上到下，圆环保持原有角度与数据顺序。

## API

### Props

| 属性 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| aria-label | 分组的无障碍名称 | `string` | — |
| items | 分段数据 | `ProgressGroupItem[]` | `[]` |
| mode | 展示模式 | `'line' \| 'circle'` | `'line'` |
| max | 所有分段计算占比时的总值 | `number` | `100` |
| show-text | 是否展示累计百分比 | `boolean` | `false` |
| size | 进度轨尺寸 | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` |
| color | 分段未指定颜色时使用的默认颜色 | `string` | `content-brand` |
| circle-size | 环形模式的直径 | `number \| string` | `120` |
| stroke-width | 环形模式的轨道宽度 | `number` | `8` |
| tooltip | 是否启用分段悬浮/聚焦提示 | `boolean` | `true` |
| orientation | 线形进度轨的横纵朝向，默认 horizontal；仅 mode=line 生效 | `'horizontal' \| 'vertical'` | `'horizontal'` |

### Item

| 属性 | 说明 | 类型 |
| --- | --- | --- |
| label | 图例名称 | `string` |
| value | 分段数值 | `number` |
| color | 分段颜色 | `string` |
| icon | 图例图标组件 | `Component` |
| slot | 自定义插槽名前缀 | `string` |
| tip | 自定义提示文案 | `string` |

### Slots

| 名称 | 插槽参数 |
| --- | --- |
| text | `{ percent, value, max }` |
| tooltip | `{ item, index, percent }` |
| item / item-leading / item-label / item-trailing | `{ item, index, percent }` |

### 样式变量

| 变量 | 默认值 |
| --- | --- |
| `--c-progress-group-gap` | `var(--c-sys-space-3)` |
| `--c-progress-group-item-gap` | `var(--c-sys-space-2)` |
| `--c-progress-group-dot-size` | `var(--c-sys-space-4)` |
| `--c-progress-group-radius` | `9999px` |
| `--c-progress-group-track-color` | `var(--c-sys-color-state-hover)` |
| `--c-progress-group-text-color` | `var(--c-sys-color-content-primary)` |
| `--c-progress-group-muted-color` | `var(--c-sys-color-content-secondary)` |
| `--c-progress-group-font-size` | `var(--c-sys-font-size-sm)` |
| `--c-progress-group-tooltip-bg` | `var(--c-sys-color-surface-tooltip)` |
| `--c-progress-group-tooltip-color` | `var(--c-sys-color-content-on-dark)` |

图形标记默认使用 system content-brand。颜色优先级：item.color → 组件 color → 默认值。自定义颜色需自行验证对比度；几何 Token 保留平台差异。

### Geometry and motion variables

Built-in effects respect `prefers-reduced-motion: reduce`. Track thickness applies to both horizontal and vertical layouts; circle geometry remains prop-driven.

| Token | Default |
| --- | --- |
| `--c-progress-group-transition-duration` | `var(--c-sys-motion-duration-standard)` |
| `--c-progress-group-tooltip-duration` | `var(--c-sys-motion-duration-fast)` |
| `--c-progress-group-tooltip-max-width` | `240px` |
| `--c-progress-group-tooltip-padding` | `5px var(--c-sys-space-4)` |
| `--c-progress-group-tooltip-radius` | `var(--c-sys-radius-md)` |
| `--c-progress-group-tooltip-font-size` | `var(--c-sys-font-size-xs)` |
| `--c-progress-group-tooltip-line-height` | `1.4` |
| `--c-progress-group-tooltip-offset` | `var(--c-sys-space-4)` |
| `--c-progress-group-text-font-weight` | `var(--c-sys-font-weight-medium)` |
| `--c-progress-group-size-xs-thickness` | `2px` |
| `--c-progress-group-size-sm-thickness` | `4px` |
| `--c-progress-group-size-md-thickness` | `8px` |
| `--c-progress-group-size-lg-thickness` | `12px` |
| `--c-progress-group-size-xl-thickness` | `16px` |

---

Document: llms/zh-CN/components/progress.md

<!-- Source: src/progress/README.md; locale: zh-CN; page: /components/progress/ -->

# Progress 进度条

展示确定或不确定任务进度。两端主体、API 与样式为独立同源代码。

## 基础示例

### 基础用法

Example source: src/progress/__demos__/basic.vue

```vue
<template>
  <c-progress :percent="20" :style="{ width: '50%' }" />
  <br />
  <br />
  <c-progress :percent="30" :style="{ width: '50%' }">
    <template v-slot:text="scope">进度 {{ scope.percent }}%</template>
  </c-progress>
</template>
```

## 外观与状态

### 进度尺寸与状态

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `size` | 五档预设或自定义长度；线形厚度、环形直径 | 进度尺寸与状态 |
| `percent` | 0–100 百分比，保留小数；支持十进制数字字符串，非法值归零，越界裁剪 | 进度尺寸与状态 |
| `mode` | 线形或环形 | 进度尺寸与状态 |
| `stroke-width` | 覆盖轨道厚度，数字按 px，字符串支持 CSS 长度 | 进度尺寸与状态 |
| `status` | default/primary/secondary/tertiary/info/success/warning/danger；default 确定进度达到 100 时推导 success | 进度尺寸与状态 |
<!-- demo-config-notes:end -->

在相同进度范围内比较尺寸和状态色；环形、分段和不确定进度保留独立模型。

Example source: src/progress/__demos__/appearance-comparison.vue

```vue
<script setup lang="ts">
import { proxyRefs as demoProxyRefs } from 'vue'

const scene1 = demoProxyRefs((() => {

const sizes = ["xs", "sm", "md", "lg", "xl"] as const;
return { sizes }
})())

const scene2 = demoProxyRefs((() => {

const statuses = [
  "default",
  "primary",
  "secondary",
  "tertiary",
  "info",
  "success",
  "warning",
  "danger",
] as const;
return { statuses }
})())
</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="size">
    <h4><span lang="zh-CN">五档与自定义尺寸</span><span lang="en-US">size</span></h4>
    <c-space direction="column" size="16px">
        <c-space wrap size="16px" align="center" v-for="size in scene1.sizes" :key="size">
          <span>{{ size }}</span
          ><c-progress :size="size" :percent="42" /><c-progress
            mode="circle"
            :size="size"
            :percent="42"
          />
        </c-space>
        <c-progress :size="10" :percent="12.5" />
        <c-progress size="0.75rem" :stroke-width="6" :percent="60" />
        <c-progress mode="circle" size="6rem" :percent="75" />
      </c-space>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="status">
    <h4><span lang="zh-CN">八种状态</span><span lang="en-US">status</span></h4>
    <c-space direction="column" size="16px">
        <c-progress
          v-for="status in scene2.statuses"
          :key="status"
          :status="status"
          :percent="60"
          ><template #text>{{ status }}</template></c-progress
        >
        <c-progress :percent="100" />
      </c-space>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

## 内容与展示

### 环形进度

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `percent` | 0–100 百分比，保留小数；支持十进制数字字符串，非法值归零，越界裁剪 | 环形进度、分段进度、不确定进度与动画 |
| `mode` | 线形或环形 | 环形进度、不确定进度与动画、渐变、起点、隐藏轨道与文本 |
| `status` | default/primary/secondary/tertiary/info/success/warning/danger；default 确定进度达到 100 时推导 success | 环形进度、分段进度 |
| `steps` | 仅线形的分段数，向下取整并限制为 0–1000；不确定模式忽略 | 分段进度 |
| `size` | 五档预设或自定义长度；线形厚度、环形直径 | 分段进度 |
| `indeterminate` | 不确定进度；省略 aria-valuenow，不自动推导成功 | 不确定进度与动画 |
<!-- demo-config-notes:end -->

Example source: src/progress/__demos__/circle.vue

```vue
<template>
  <c-space wrap size="lg">
    <c-progress mode="circle" :percent="percent" />
    <c-progress mode="circle" status="warning" :percent="percent" />
    <c-progress mode="circle" status="danger" :percent="percent" />
    <c-progress mode="circle" status="success" :percent="percent" />
  </c-space>
  <div :style="{ marginTop: '20px' }">
    <c-slider v-model="percent" :max="100" :step="10" :style="{ width: '150px' }" />
  </div>
</template>
<script lang="ts" setup>
import { ref } from 'vue'
const percent = ref(20)
</script>
```

### 分段进度

Example source: src/progress/__demos__/step.vue

```vue
<template>
  <c-space direction="column" size="16px">
    <c-progress :steps="5" :percent="40" />
    <c-progress :steps="10" :percent="75" status="warning" size="lg" />
    <c-progress :steps="5" :percent="100" />
  </c-space>
</template>
```

### 不确定进度与动画

Example source: src/progress/__demos__/loop.vue

```vue
<template>
  <c-space direction="column" size="16px">
    <c-progress indeterminate aria-label="Loading" />
    <c-progress mode="circle" indeterminate aria-label="Loading" />
    <c-progress :percent="60" animation />
  </c-space>
</template>
```

### 渐变、起点、隐藏轨道与文本

Example source: src/progress/__demos__/advanced.vue

```vue
<script setup>
import { ref } from "vue";

const gradient = ref(false);
</script>
<template>
  <c-space direction="column" size="16px">
    <c-switch v-model="gradient" aria-label="Gradient" />
    <c-progress
      :percent="65"
      :color="gradient ? { '0%': '#722ed1', '100%': '#0fc6c2' } : '#722ed1'"
      buffer-color="#eee5ff"
    />
    <c-space wrap size="24px">
      <c-progress
        mode="circle"
        :percent="65"
        :rotate="90"
        :color="gradient ? { '0%': '#722ed1', '100%': '#0fc6c2' } : '#722ed1'"
      />
      <c-progress mode="circle" :percent="65" :track="false"
        ><template #text="{ percent }"
          >{{ percent }} / 100</template
        ></c-progress
      >
    </c-space>
  </c-space>
</template>
```

## 阅读方向

线性进度从阅读起点增长，活动与不确定进度动画沿阅读方向运动。百分比、数值和圆环角度不反转，减少动态效果的设置仍生效。

## API

### Props

| 属性 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| mode | 线形或环形 | `line \| circle` | `line` |
| percent | 0–100 百分比，保留小数；支持十进制数字字符串，非法值归零，越界裁剪 | `number \| string` | `0` |
| size | 五档预设或自定义长度；线形厚度、环形直径 | `ProgressSize` | `md` |
| stroke-width | 覆盖轨道厚度，数字按 px，字符串支持 CSS 长度 | `number \| string` | 随 size |
| steps | 仅线形的分段数，向下取整并限制为 0–1000；不确定模式忽略 | `number` | `0` |
| status | default/primary/secondary/tertiary/info/success/warning/danger；default 确定进度达到 100 时推导 success | `ProgressStatus` | `default` |
| color | 进度颜色或渐变 stop 映射，优先于 status | `string \| Record<string, string>` | — |
| track-color | 背景轨道颜色 | `string` | — |
| buffer-color | 线形剩余轨道装饰色/渐变，不代表独立缓冲百分比 | `ProgressColor` | — |
| track | 显示背景轨道；false 同时隐藏缓冲装饰层 | `boolean` | `true` |
| show-text | 显示文本；xs 环形隐藏文本避免溢出 | `boolean` | `true` |
| text-class | 文本容器类名 | `string` | — |
| rotate | 环形起点从十二点顺时针旋转的角度 | `number` | `0` |
| animation | 确定线形进度扫光动画，不应用于 steps | `boolean` | `false` |
| indeterminate | 不确定进度；省略 aria-valuenow，不自动推导成功 | `boolean` | `false` |

### 尺寸语义

| size | xs | sm | md | lg | xl |
| --- | --- | --- | --- | --- | --- |
| 线形厚度 / 环形默认描边 (px) | 2 | 3 | 4 | 6 | 8 |
| 环形直径 (px) | 16 | 48 | 64 | 80 | 96 |

`size=12` / `size="12"` 表示 12px；`size="2rem"`、`"50%"`、`"calc(100% - 2px)"` 保留 CSS 长度。自定义线形 size 控制厚度，自定义环形 size 控制直径；stroke-width 始终优先控制厚度。非正数或非法长度回退 md。环形百分比直径需要父容器有明确宽度。五档均实际实现，xs 环形不显示文本。Cedar 未传 size 时继承 ConfigProvider，Maple 未传时默认 md。

### Slots

| 插槽 | 参数 | 说明 |
| --- | --- | --- |
| text | `{ percent: number }` | 优先级高于 default |
| default | `{ percent: number }` | 自定义显示文本 |

不确定进度默认显示省略号，可用 text 插槽提供业务文案。组件本身不操作值、无更新事件；请提供 `aria-label` 标识业务任务。所有内置动画尊重系统减少动态效果设置。

### 类型定义

导出 `ProgressProps`、`ProgressInstance`、`ProgressSize`、`ProgressMode`、`ProgressStatus`、`ProgressColor` 和运行时 `progressProps`。

## 样式变量

| 变量 | 默认值 |
| --- | --- |
| `--c-progress-font-size` | `var(--c-sys-font-size-sm)` |
| `--c-progress-text-color` | `var(--c-sys-color-content-secondary)` |
| `--c-progress-track-color` | `var(--c-sys-color-state-hover)` |
| `--c-progress-default-color` | `var(--c-sys-color-content-brand)` |
| `--c-progress-primary-color` | `var(--c-sys-color-content-brand)` |
| `--c-progress-secondary-color` | `var(--c-sys-color-content-secondary)` |
| `--c-progress-tertiary-color` | `var(--c-sys-color-content-tertiary)` |
| `--c-progress-info-color` | `var(--c-sys-color-content-info)` |
| `--c-progress-success-color` | `var(--c-sys-color-content-success)` |
| `--c-progress-warning-color` | `var(--c-sys-color-content-warning)` |
| `--c-progress-danger-color` | `var(--c-sys-color-content-danger)` |
| `--c-progress-line-border-radius` | `9999px` |
| `--c-progress-text-gap` | `var(--c-sys-space-4)` |
| `--c-progress-steps-gap` | `var(--c-sys-space-2)` |
| `--c-progress-transition-duration` | `var(--c-sys-motion-duration-standard)` |
| `--c-progress-animation-duration` | `1.5s` |

环形确定进度的 success/danger 默认显示完成/失败图标（包括 xs）；text 插槽可覆盖，ARIA 数值始终保留。

---

Document: llms/zh-CN/components/radio.md

<!-- Source: src/radio/README.md; locale: zh-CN; page: /components/radio/ -->

# Radio

在一组相关且互斥数据中，用户仅能选择一个选项。

分组示例覆盖父级接受/拒绝更新、只读和异步选项回显；移除选项不会清空业务值。示例外层 Space 的纵向布局使用 `direction="column"`，与选择组自身的 `orientation="vertical"` 分开理解。

## 阅读方向

单选组继承来源 dir。RTL 的左右方向键按可见方向移动，跳过禁用项；上下键、Home/End 保持逻辑顺序。普通与按钮式单选组均保留单一 Tab 入口，方向切换不修改已选业务值。

## 基础示例

### 基本使用

单选框的基本用法。

Example source: src/radio/__demos__/basic.vue

```vue
<template>
  <c-space wrap size="lg" fill>
    <c-radio value="radio">Radio</c-radio>
    <c-radio value="disabled radio" default-value="disabled radio" disabled>Disabled Radio </c-radio>
    <c-radio-group v-model="type" variant="button">
      <c-radio value="rounded1">Rounded1</c-radio>
      <c-radio value="rounded">Rounded</c-radio>
      <c-radio value="capsule">Capsule</c-radio>
    </c-radio-group>
  </c-space>
</template>

<script lang="ts">
</script>
```

## 分组与布局

### 单选组声明方式

<!-- demo-config-notes:start -->

#### 本组配置对照

| 配置       | 作用                            | 相关示例                                         |
| ---------- | ------------------------------- | ------------------------------------------------ |
| `value`    | 选项的`value`                   | 单选组声明方式、单选框组方向、按钮类型的单选框组 |
| `disabled` | 是否禁用；未设置时继承表单/分组 | 单选组声明方式、布局                             |

<!-- demo-config-notes:end -->

比较子项与 options 声明，选择不同项观察组值；自定义字段与异步数据仍单独展示。

<details>
<summary>配置说明与使用限制</summary>

#### 单选框组

通过`RadioGroup`组件展示单选框组

#### 单选框组选项

`RadioGroup`通过`options`属性设置子元素

</details>

Example source: src/radio/__demos__/group-declaration-comparison.vue

```vue
<script setup lang="ts">
import { ref } from "vue"
import { proxyRefs as demoProxyRefs } from 'vue'

const scene2 = demoProxyRefs((() => {


    const value1 = ref('plain 1')


    const plainOptions = ['plain 1', 'plain 2', 'plain 3']



    const value2 = ref('1')


    const options = [
      { label: 'option 1', value: '1' },
      { label: 'option 2', value: '2' },
      { label: 'option 3', value: '3', disabled: true },
    ]
return { value1, plainOptions, value2, options }
})())
</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="group">
    <h4><span lang="zh-CN">单选框组</span><span lang="en-US">group</span></h4>
    <c-space direction="column" size="lg">
        <c-radio-group>
          <c-radio value="A">A</c-radio>
          <c-radio value="B">B</c-radio>
          <c-radio value="C">C</c-radio>
          <c-radio value="D">D</c-radio>
        </c-radio-group>
        <c-radio-group>
          <c-radio value="A">A</c-radio>
          <c-radio value="B">B</c-radio>
          <c-radio value="C">C</c-radio>
          <c-radio value="D" disabled>D</c-radio>
        </c-radio-group>
      </c-space>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="group-options">
    <h4><span lang="zh-CN">单选框组选项</span><span lang="en-US">group options</span></h4>
    <c-space direction="column" size="lg">
        <c-radio-group v-model="scene2.value1" :options="scene2.plainOptions" />
        <c-radio-group v-model="scene2.value2" :options="scene2.options" />
        <c-radio-group v-model="scene2.value2" :options="scene2.options">
          <template #label="{ data }">
            <c-tag>{{ data.label }}</c-tag>
          </template>
        </c-radio-group>
      </c-space>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

### 单选框组方向

通过设置`orientation="vertical"`可以展示竖直的单选框组。

Example source: src/radio/__demos__/group-direction.vue

```vue
<template>
  <c-radio-group orientation="vertical">
    <c-radio value="A">A</c-radio>
    <c-radio value="B">B</c-radio>
    <c-radio value="C">C</c-radio>
    <c-radio value="D">D</c-radio>
  </c-radio-group>
</template>
<script lang="ts">
</script>
```

### 按钮类型的单选框组

通过指定`variant="button"`，可以显示按钮类型的单选框组。

Example source: src/radio/__demos__/button-type.vue

```vue
<template>
  <c-radio-group variant="button">
    <c-radio value="Beijing">Beijing</c-radio>
    <c-radio value="Shanghai">Shanghai</c-radio>
    <c-radio value="Guangzhou">Guangzhou</c-radio>
    <c-radio value="Shenzhen">Shenzhen</c-radio>
  </c-radio-group>
</template>
<script lang="ts">
</script>
```

### 布局

使用`RadioGroup`传入`Radio`配合`Grid`组件实现灵活布局。

Example source: src/radio/__demos__/grid-layout.vue

```vue
<template>
  <c-radio-group v-model="checkedValue">
    <c-grid :cols="3" :colGap="24" :rowGap="16">
      <c-grid-item>
        <c-radio value="1">Option 1</c-radio>
      </c-grid-item>
      <c-grid-item>
        <c-radio value="2" disabled>Option 2</c-radio>
      </c-grid-item>
      <c-grid-item>
        <c-radio value="3">Option 3</c-radio>
      </c-grid-item>
      <c-grid-item>
        <c-radio value="4">Option 4</c-radio>
      </c-grid-item>
      <c-grid-item>
        <c-radio value="5">Option 5</c-radio>
      </c-grid-item>
    </c-grid>
  </c-radio-group>
</template>

<script lang="ts">
import { ref } from 'vue'

export default {
  setup() {
    const checkedValue = ref('1')

    return {
      checkedValue,
    }
  },
}
</script>
```

### 分组状态与只读

`model-value !== undefined` 表示受控，父级不回写时保留原值；`default-value` 只初始化非受控值。分组内只由 Group 发出 `update:model-value → change(value, event?)`，并通知 FormItem 一次，子项不重复发值变化事件。
原生输入的选中值、ARIA 状态和选中样式与模型保持一致。受控分组拒绝选择时，同时恢复原选中项和被点击项；标签、Enter 和空格激活各只提出一次更新。
Group 的 `disabled`、`readonly`、`error` 未设置时继承表单，显式 `false` 可以覆盖表单；子项不能绕过 Group 的禁用或只读限制。

Example source: src/radio/__demos__/group-state.vue

```vue
<script setup>
import { ref } from 'vue'

const accepted = ref('a')
const proposed = ref('')
const readonly = ref(false)
const options = [{ label: '设备 A', value: 'a' }, { label: '设备 B', value: 'b' }]
</script>

<template>
  <c-space direction="column">
    <div>
      <p>非受控：default-value 只用于初始值</p>
      <c-radio-group :default-value="'a'" :options="options" />
    </div>
    <div>
      <p>受控：父级接受更新 {{ accepted }}</p>
      <c-radio-group v-model="accepted" :options="options" :readonly="readonly" />
      <c-button size="sm" @click="readonly = !readonly">{{ readonly ? '解除只读' : '设为只读' }}</c-button>
    </div>
    <div>
      <p>父级拒绝更新：仅记录提议 {{ proposed }}</p>
      <c-radio-group :model-value="''" :options="options" @update:model-value="proposed = $event" />
    </div>
  </c-space>
</template>
```

### 按钮尺寸

两端均支持 `variant="button"`。RadioGroup 的 `size` 支持 `xs / sm / md / lg / xl`，只调整按钮高度；普通圆形 Radio 不随 size 缩放。未设置时继承表单/全局尺寸，最终默认为 md。Group 的 variant 优先于子项。

Example source: src/radio/__demos__/button-sizes.vue

```vue
<script setup lang="ts">
const sizes = ['xs', 'sm', 'md', 'lg', 'xl'] as const
const options = [
  { label: '日', value: 'day' },
  { label: '周', value: 'week' },
  { label: '月', value: 'month' },
]
</script>
<template>
  <section class="radio-demo">
    <div v-for="size in sizes" :key="size">
      <p>{{ size }}</p>
      <c-radio-group variant="button" :size="size" default-value="week" :options="options" :aria-label="size" />
    </div>
    <p>纵向与只读</p>
    <c-radio-group variant="button" orientation="vertical" readonly default-value="day" :options="options" aria-label="只读周期" />
  </section>
</template>
<style scoped>
.radio-demo { display: flex; flex-direction: column; align-items: flex-start; gap: 12px; }
.radio-demo p { margin: 0 0 8px; }
</style>
```

## 选项与值模型

### 独立值模型与方法

<!-- demo-config-notes:start -->

#### 本组配置对照

| 配置            | 作用                            | 相关示例               |
| --------------- | ------------------------------- | ---------------------- |
| `default-value` | 非受控初始值                    | 独立值模型与方法、受控 |
| `value`         | 选项的`value`                   | 独立值模型与方法       |
| `readonly`      | 是否只读；未设置时继承表单/分组 | 独立值模型与方法       |
| `disabled`      | 是否禁用；未设置时继承表单/分组 | 独立值模型与方法       |

<!-- demo-config-notes:end -->

Radio 的值为 string / number / boolean 或 null，null 表示未选中；重复点击已选项不会取消，父级可写 null 清空。
两端统一使用 `default-value` 初始化非受控值；受控提议被拒绝时保持原值。用户选择按 `update:model-value → change(value, event?)` 通知，命令式调用的 event 为 undefined。
提供 `select()`、`focus(options?)`、`blur()`。禁用禁止选择和聚焦，只读允许聚焦、禁止改值。Enter 按下与空格释放激活当前控件，长按不重复激活，失焦/停用会取消待处理的空格操作。

Example source: src/radio/__demos__/control-value.vue

```vue
<script setup>
import { ref } from 'vue'
const control = ref()
const value = ref(null)

</script>
<template>
  <c-space direction="column">
    <p>null 表示未选中；重复选择不会取消。 当前值：{{ value }}</p>
    <c-radio ref="control" v-model="value" :value="false">选择 false 选项</c-radio>
    <c-space wrap>
      <c-button size="sm" @click="control?.select()">选中</c-button>
      <c-button size="sm" @click="control?.focus()">聚焦</c-button>
      <c-button size="sm" @click="value = null">重置</c-button>
    </c-space>
    
    <p>只读允许聚焦，禁用不允许操作；Enter/空格只影响当前控件。</p>
    <c-radio :default-value="true" readonly>只读</c-radio>
    <c-radio :default-value="true" disabled>禁用</c-radio>
  </c-space>
</template>
```

### 选项数据与标签

两端均支持原始值或对象选项。`field-names` 映射 `label/value/disabled/readonly/indeterminate`；只读选项允许聚焦但不能改值，Checkbox 的半选仅用于展示。
`label` 插槽接收 `{ data, checked }`，优先于标签渲染函数 `(data, checked) => VNodeChild`。data 为保留业务字段的归一化副本，不修改输入对象；未提供标签时显示值的文字。
显式传入 `options` 时替代默认插槽，包括 `[]`；不传时使用默认插槽。选项值限字符串、有限数字或布尔值；缺失/非法值及同类型重复值被忽略（保留第一项）。`false`、`0`、`''` 和 `'0'` 是不同选项。异步选项变更不反向修改模型。
RadioGroup 默认 `null`，表示未选中；外部写入 `null` 清空。`''` 是有效选项，不再作为空状态标记。

Example source: src/radio/__demos__/option-data.vue

```vue
<script setup lang="ts">
import { h, ref } from 'vue'

const value = ref<string | number | boolean | null>(null)
const fields = { value: 'id', label: 'name', disabled: 'unavailable', readonly: 'locked' }
const options = ref([
  { id: false, name: '布尔 false' },
  { id: 0, name: '数字 0' },
  { id: '', name: '空字符串' },
  { id: 'locked', name: '只读选项', locked: true },
  { id: 'disabled', name: '禁用选项', unavailable: true },
])
const renderOptions = [
  { value: 'render', label: (_data: unknown, checked: boolean) => h('strong', checked ? '已选择' : '渲染函数标签') },
]
</script>

<template>
  <section class="option-demo">
    <p>字段映射与标签插槽；只读可聚焦，禁用不可操作。</p>
    <c-radio-group v-model="value" :options="options" :field-names="fields" orientation="vertical">
      <template #label="{ data, checked }">{{ data.label }} {{ checked ? '✓' : '' }}</template>
    </c-radio-group>
    <p>当前值：{{ JSON.stringify(value) }}</p>
    <c-button @click="value = null">清空</c-button>
    <p>标签也支持渲染函数；不传 options 时使用默认插槽，传入 [] 时保持空组。</p>
    <c-radio-group :options="renderOptions" />
  </section>
</template>

<style scoped>
.option-demo { display: flex; flex-direction: column; gap: 12px; }
.option-demo p { margin: 0; }
</style>
```

### 受控

通过`v-model`(`model-value`)属性控制是否选中

Example source: src/radio/__demos__/controlled.vue

```vue
<template>
  <c-space wrap size="lg">
    <c-radio v-model="checked1">v-model</c-radio>
    <c-radio :model-value="true">binding "true"</c-radio>
    <c-radio :model-value="checked2">binding value2</c-radio>
    <c-radio :default-value="true">uncontrolled state</c-radio>
  </c-space>
  <div :style="{ marginTop: '20px' }">
    <c-space wrap size="lg">
      <c-button status="primary" @click="handleSetCheck"> {{ checked2 ? 'uncheck' : 'check' }} value2 </c-button>
      <c-button @click="handleReset"> reset all</c-button>
    </c-space>
  </div>
</template>

<script lang="ts">
import { ref } from 'vue'

export default {
  setup() {
    const checked1 = ref(false)
    const checked2 = ref(false)

    const handleSetCheck = () => {
      checked2.value = !checked2.value
    }

    const handleReset = () => {
      checked1.value = false
      checked2.value = false
    }

    return {
      checked1,
      checked2,
      handleSetCheck,
      handleReset,
    }
  },
}
</script>
```

## 交互与键盘

### 交互状态切换

<!-- demo-config-notes:start -->

#### 本组配置对照

| 配置       | 作用                            | 相关示例     |
| ---------- | ------------------------------- | ------------ |
| `value`    | 选项的`value`                   | 交互状态切换 |
| `disabled` | 是否禁用；未设置时继承表单/分组 | 交互状态切换 |
| `readonly` | 是否只读；未设置时继承表单/分组 | 交互状态切换 |
| `error`    | 错误态；未设置时继承表单/分组   | 交互状态切换 |

<!-- demo-config-notes:end -->

适用于互斥选项。调整禁用、只读、错误反馈，用相同数据观察变化。控制区始终可用，可以随时恢复编辑；错误外观本身不会触发表单校验。

Example source: src/radio/__demos__/state-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref("design");
const __demoState = __demoReactive({
  disabled: false,
  readonly: false,
  error: false,
});
</script>
<template>
  <c-space direction="column" :size="16">
    <c-space wrap>
      <c-checkbox v-model="__demoState['disabled']">disabled</c-checkbox>
      <c-checkbox v-model="__demoState['readonly']">readonly</c-checkbox>
      <c-checkbox v-model="__demoState['error']">error</c-checkbox>
    </c-space>
    <c-radio v-model="value" value="design" v-bind="__demoState">设计</c-radio>
  </c-space>
</template>
```

### 键盘导航

Tab 进入已选项（没有已选项时进入第一个可用项）；方向键循环，Home / End 跳到首尾，跳过禁用项。只读项可聚焦但不改变值。导航仅作用于当前分组，不拦截面板内其他按钮的键盘事件。

Example source: src/radio/__demos__/keyboard-navigation.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const value = ref<string | number | boolean | null>('email')
const options = [
  { label: '邮件', value: 'email' },
  { label: '只读', value: 'locked', readonly: true },
  { label: '禁用', value: 'disabled', disabled: true },
  { label: '短信', value: 'sms' },
]
</script>
<template>
  <section class="radio-demo">
    <p>Tab 进入分组；方向键循环，Home / End 跳到首尾。只读项可聚焦，不改变选值。</p>
    <c-radio-group v-model="value" :options="options" aria-label="通知方式" />
    <p>当前值：{{ value }}</p>
    <c-button @click="value = null">清空</c-button>
  </section>
</template>
<style scoped>
.radio-demo { display: flex; flex-direction: column; gap: 12px; }
.radio-demo p { margin: 0; }
</style>
```

## 控件与内容定制

### 原生控件与自定义图标

<!-- demo-config-notes:start -->

#### 本组配置对照

| 配置       | 作用                            | 相关示例                           |
| ---------- | ------------------------------- | ---------------------------------- |
| `value`    | 选项的`value`                   | 原生控件与自定义图标、自定义单选框 |
| `readonly` | 是否只读；未设置时继承表单/分组 | 原生控件与自定义图标               |

<!-- demo-config-notes:end -->

两端均使用原生 radio input。Group 的 name 供原生表单提交，子项可覆盖。aria-label/input-attrs 作用于 input；组件管理的 type、checked、disabled、tabindex 不允许覆盖。图标插槽仅替换图标；#radio 替换全部可见内容，使用时须提供可访问名称。

Example source: src/radio/__demos__/native-control.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const value = ref<string | number | boolean | null>('email')
</script>
<template>
  <section class="native-radio-demo">
    <p>图标与原生 input 属性</p>
    <c-radio-group v-model="value" name="channel" aria-label="通知方式">
      <c-radio value="email" :icon-size="24" checked-color="rebeccapurple" :input-attrs="{ id: 'radio-email' }">
        <template #checked-icon><span aria-hidden="true">●</span></template>
        <template #unchecked-icon><span aria-hidden="true">○</span></template>
        邮件
      </c-radio>
      <c-radio value="sms">短信</c-radio>
      <c-radio value="readonly" readonly>只读</c-radio>
    </c-radio-group>
    <p>当前值：{{ value }}</p>
  </section>
</template>
<style scoped>
.native-radio-demo { display: flex; flex-direction: column; gap: 12px; }
.native-radio-demo p { margin: 0; }
</style>
```

### 自定义单选框

使用 #radio 插槽自定义单选框的展示。

Example source: src/radio/__demos__/custom-radio.vue

```vue
<template>
  <c-radio-group default-value="1">
    <c-radio value="1">
      <template #radio="{ checked }">
        <c-tag :model-value="checked" checkable>This is a tag radio 1</c-tag>
      </template>
    </c-radio>
    <c-radio value="2">
      <template #radio="{ checked }">
        <c-tag :model-value="checked" checkable>This is a tag radio 2</c-tag>
      </template>
    </c-radio>
    <c-radio value="3">
      <template #radio="{ checked }">
        <c-tag :model-value="checked" checkable>This is a tag radio 3</c-tag>
      </template>
    </c-radio>
  </c-radio-group>

  <div :style="{ marginTop: '20px' }">
    <c-radio-group>
      <template v-for="item in 2" :key="item">
        <c-radio :value="item">
          <template #radio="{ checked }">
            <c-space wrap align="flex-start" class="custom-radio-card" :class="{ 'custom-radio-card-checked': checked }">
              <div class="custom-radio-card-mask">
                <div class="custom-radio-card-mask-dot" />
              </div>
              <div>
                <div class="custom-radio-card-title">radio Card {{ item }}</div>
                <div>this is a text</div>
              </div>
            </c-space>
          </template>
        </c-radio>
      </template>
    </c-radio-group>
  </div>
</template>

<script lang="ts">
</script>
<style scoped>
.custom-radio-card {
  padding: 10px 16px;
  border: 1px solid var(--color-border-2);
  border-radius: 4px;
  width: 250px;
  box-sizing: border-box;
}

.custom-radio-card-mask {
  height: 14px;
  width: 14px;
  display: inline-flex;
  align-items: center;
  justify-content: center;
  border-radius: 100%;
  border: 1px solid var(--color-border-2);
  box-sizing: border-box;
}

.custom-radio-card-mask-dot {
  width: 8px;
  height: 8px;
  border-radius: 100%;
}

.custom-radio-card-title {
  color: var(--color-text-1);
  font-size: 14px;
  font-weight: bold;
  margin-bottom: 8px;
}

.custom-radio-card:hover,
.custom-radio-card-checked,
.custom-radio-card:hover .custom-radio-card-mask,
.custom-radio-card-checked .custom-radio-card-mask {
  border-color: rgb(var(--primary-6));
}

.custom-radio-card-checked {
  background-color: var(--color-primary-light-1);
}

.custom-radio-card:hover .custom-radio-card-title,
.custom-radio-card-checked .custom-radio-card-title {
  color: rgb(var(--primary-6));
}

.custom-radio-card-checked .custom-radio-card-mask-dot {
  background-color: rgb(var(--primary-6));
}
</style>
```

## 异步选项

### 异步选项

开启“手动返回”后使用真实本地Promise，不走默认定时器。连续加载两次，分别按新旧或旧新顺序返回：只有当前请求版本可替换选项、结束加载。移除选项使在途版本失效但保留业务选值；旧任务仍可手动返回。Applied/Ignored/Pending显示应用、忽略及等待数，加载/返回不增加用户变更次数。版本保护和等待清理由示例业务加载器负责，不代表Radio自动解决网络竞争，也不访问外部服务。

选项载入、移除和外部值更新均不会反向触发值变化；未载入的已选值不会自动清理。重复选择当前值不再触发 change，false、0、空字符串按实际值比较。

示例以 800ms 本地延迟模拟加载。等待期间可设为设备 A 或清空选择，选项到达后按最新模型反显；这些外部操作不会增加用户变更次数。加载中移除选项会取消待完成任务，避免旧选项重新显示。

等待期间仍可用方向键选择已加载的选项；同值选项重新加载后保留当前焦点。加载提示保持稳定节点，避免提示显隐导致分组重新挂载；重复激活当前值不会增加 change 次数。

Example source: src/radio/__demos__/async-options.vue

```vue
<script setup>
import { onDeactivated, onUnmounted, ref, shallowRef } from "vue";

const value = ref("remote");
const options = ref([]);
const loading = ref(false);
const changeCount = ref(0);
let pendingTimer;
const manual = ref(false);
const waiting = shallowRef([]);
const applied = ref(0);
const ignored = ref(0);
let version = 0;
let sequence = 0;

function cancelPending() {
  version++;
  if (pendingTimer !== undefined) {
    clearTimeout(pendingTimer);
  }
  pendingTimer = undefined;
  loading.value = false;
}

function load() {
  cancelPending();
  loading.value = true;
  const ticket = version;
  const id = ++sequence;
  const complete = () => {
    if (ticket !== version) {
      ignored.value++;
      return;
    }
    applied.value = id;
    options.value = [
      { label: "异步设备", value: "remote" },
      { label: "设备 A", value: "a" },
      { label: "停用设备", value: "locked", disabled: true },
    ];
    pendingTimer = undefined;
    loading.value = false;
  };
  if (manual.value) {
    new Promise((resolve) => {
      waiting.value = [...waiting.value, { id, resolve }];
    }).then(complete);
  } else {
    pendingTimer = setTimeout(complete, 800);
  }
}

function settle(latest) {
  const jobs = [...waiting.value];
  const job = latest ? jobs.pop() : jobs.shift();
  waiting.value = jobs;
  job?.resolve();
}

function cleanup() {
  cancelPending();
  const jobs = waiting.value;
  waiting.value = [];
  jobs.forEach((job) => job.resolve());
}

function remove() {
  cancelPending();
  options.value = [];
}

onDeactivated(cleanup);
onUnmounted(cleanup);
</script>

<template>
  <c-space class="radio-async-demo" direction="column">
    <p>业务值独立于当前选项，加载或移除选项不会清空已选值：{{ value }}</p>
    <c-checkbox v-model="manual" edit-mode="direct" @change="remove"
      >Manual responses / 手动返回</c-checkbox
    >
    <c-space wrap>
      <c-button size="sm" @click="load">加载选项</c-button>
      <c-button size="sm" @click="remove">移除选项</c-button>
      <c-button size="sm" @click="value = 'a'">设为设备 A</c-button>
      <c-button size="sm" @click="value = null">清空选择</c-button>
      <c-button
        size="sm"
        :disabled="waiting.length === 0"
        @click="settle(false)"
        >返回最早加载</c-button
      >
      <c-button size="sm" :disabled="waiting.length === 0" @click="settle(true)"
        >返回最新加载</c-button
      >
    </c-space>
    <p aria-live="polite">
      {{
        loading
          ? "加载中，可在完成前移除选项以取消本次加载。"
          : "加载完成后保留当前选值和键盘焦点。"
      }}
    </p>
    <c-radio-group
      v-model="value"
      edit-mode="direct"
      :options="options"
      @change="changeCount++"
    />
    <p>用户变更次数：{{ changeCount }}</p>
    <p role="status">
      Applied: {{ applied }} · Ignored: {{ ignored }} · Pending:
      {{ waiting.length }}
    </p>
  </c-space>
</template>
```

## API

### 空值识别与阅读空文案

`empty-values` 用于空值识别，`empty-value` 保留原清空输出；`empty-text` 仅在 `read-pretty` 空内容下展示，默认 `'-'`，字段 > FormItem > Form，自定义 read 插槽优先。显式配置 empty-values 后，内置 required 接入该策略，自定义校验仍收到原值。详见[统一说明](llms/zh-CN/guide/empty-values.md)。

| 参数         | 类型               | 缺省与范围                                            |
| ------------ | ------------------ | ----------------------------------------------------- |
| empty-values | readonly unknown[] | 字段 > FormItem > Form > 组件族默认；完整覆盖，不合并 |
| empty-text   | string             | 字段 > FormItem > Form > '-'；显式 '' 有效            |

以上是字段展示层 API；纯面板不因此新增阅读模式。Form 与 FormItem 提供继承配置。empty-value 的现有类型与默认输出仍按该组件原 API 执行。

`ChoiceValue = string | number | boolean`；`CheckboxModel = boolean | ChoiceValue[]`；`RadioModel = ChoiceValue | null`。

### Radio Props

| 属性                  | 说明                            | 类型                      | 默认值    |
| --------------------- | ------------------------------- | ------------------------- | --------- |
| model-value (v-model) | 受控值                          | ChoiceValue \| null       | undefined |
| default-value         | 非受控初始值                    | ChoiceValue \| null       | null      |
| value                 | 选项的`value`                   | `string\|number\|boolean` | `true`    |
| variant               | 单选的类型                      | `'radio'\|'button'`       | `'radio'` |
| disabled              | 是否禁用；未设置时继承表单/分组 | boolean                   | undefined |
| readonly              | 是否只读；未设置时继承表单/分组 | boolean                   | undefined |
| error                 | 错误态；未设置时继承表单/分组   | boolean                   | undefined |

### Radio Events

| 事件名             | 说明     | 参数                              |
| ------------------ | -------- | --------------------------------- |
| update:model-value | 提议新值 | value: ChoiceValue                |
| change             | 值变化   | value: ChoiceValue, event?: Event |
| focus              | 聚焦     | event: FocusEvent                 |
| blur               | 失焦     | event: FocusEvent                 |

### Radio Methods

| 方法   | 参数                   | 返回值 |
| ------ | ---------------------- | ------ |
| select | -                      | void   |
| focus  | options?: FocusOptions | void   |
| blur   | -                      | void   |

### Radio Slots

| 插槽名 | 说明         | 参数                                     |
| ------ | ------------ | ---------------------------------------- |
| radio  | 自定义单选框 | `checked:boolean`<br/>`disabled:boolean` |

### RadioGroup Props

| 属性                  | 说明                                                        | 类型                                                                                                    | 默认值         |
| --------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | -------------- |
| model-value (v-model) | 受控值                                                      | RadioModel                                                                                              | undefined      |
| default-value         | 非受控初始值                                                | RadioModel                                                                                              | null           |
| variant               | 单选框组的类型                                              | `'radio'\|'button'`                                                                                     | `'radio'`      |
| size                  | 单选框组的尺寸                                              | `'xs'\|'sm'\|'md'\|'lg'\|'xl'`                                                                          | `-`            |
| options               | 选项；传入时替代默认插槽                                    | Array<ChoiceValue \| RadioOption \| Record<string, unknown>> / `(query, { signal }) => Array / Promise` | `undefined`    |
| orientation           | 单选组内选项的横纵排列，默认 horizontal；不表示文字阅读方向 | `'horizontal'\|'vertical'`                                                                              | `'horizontal'` |
| disabled              | 是否禁用；未设置时继承表单/分组                             | boolean                                                                                                 | undefined      |
| readonly              | 是否只读；未设置时继承表单/分组                             | boolean                                                                                                 | undefined      |
| error                 | 错误态；未设置时继承表单/分组                               | boolean                                                                                                 | undefined      |
| field-names           | 选项字段映射                                                | ChoiceFieldNames                                                                                        | undefined      |
| aria-label            | 分组的无障碍名称                                            | string                                                                                                  | ''             |

### RadioGroup Events

| 事件名             | 说明                        | 参数                                           |
| ------------------ | --------------------------- | ---------------------------------------------- |
| update:model-value | 提议新值                    | value: string \| number \| boolean             |
| change             | 值变化，只由 Group 通知一次 | value: string \| number \| boolean, ev?: Event |

### RadioGroup Slots

| 插槽名 | 说明          | 参数                                     |
| ------ | ------------- | ---------------------------------------- |
| radio  | 自定义单选框  | `checked:boolean`<br/>`disabled:boolean` |
| label  | radio文案内容 | `data: RadioOption, checked: boolean`    |

### RadioOption

| 字段     | 说明           | 类型                                                              |
| -------- | -------------- | ----------------------------------------------------------------- |
| value    | 选项标识       | ChoiceValue                                                       |
| label    | 标签或渲染函数 | VNodeChild \| (data: RadioOption, checked: boolean) => VNodeChild |
| disabled | 禁用           | boolean                                                           |
| readonly | 只读           | boolean                                                           |

## 类型定义

组件导出以下类型定义

```ts
import type { RadioProps } from "@cedar-design/ui";
```

### ChoiceFieldNames

`{ label?: string; value?: string; disabled?: string; readonly?: string; indeterminate?: string }`

公开导出类型：`RadioOption`、`ChoiceFieldNames`。

### 原生属性与外观补齐

| 组件               | 属性                            | 说明                                       | 类型                | 默认值    |
| ------------------ | ------------------------------- | ------------------------------------------ | ------------------- | --------- |
| Radio / RadioGroup | name                            | 原生字段名，子项覆盖分组                   | string              | undefined |
| Radio              | aria-label                      | 原生控件的无障碍名称                       | string              | undefined |
| Radio              | input-attrs                     | 原生 input 属性                            | InputHTMLAttributes | undefined |
| Radio              | checked-color / unchecked-color | 实例选中/未选中色；错误/禁用状态优先       | string              | undefined |
| Radio              | icon-size                       | 图标长度，number 为 px；string 为 CSS 长度 | number \| string    | undefined |
| Radio              | ripple                          | 触控水波纹                                 | boolean             | true      |

### 图标与默认插槽

checked-icon、unchecked-icon 在两端都可用。default 接收 { checked, disabled }；radio 接收 { checked, disabled }。click 只发出一次原始 MouseEvent；disabled 不发 click，只读可发 click，但不改变值。

### Form 字段展示与确认

本组件支持 `edit-mode`，字段 > FormItem > Form 逐层继承；未指定时为 `direct`，保留原有交互。支持值：`direct / click / dblclick`。非 direct 编辑模式通过字段值入口打开编辑面板，并维护单份草稿；确认后才更新 v-model，取消、重置或启用 readPretty 时丢弃草稿。

Cedar 使用 edit-mode="click" / "dblclick" 在字段附近打开编辑浮层，Enter/F2 也可进入；取消/Escape 丢弃草稿，确认后提交。readPretty 为独立阅读属性，与 readonly、disabled 分开。

`before-commit(value, { previousValue, signal })` 可拦截弹层保存；FormItem 先校验候选值，失败保持编辑。`open / default-open / update:open` 控制编辑层。`#read="{ value, text }"` 可自定义阅读内容。集中示例见 Form 的“各类字段统一展示”。

`read-pretty` 为独立布尔属性，与 `readonly`、`disabled` 同级；字段 > FormItem > Form 继承，显式 `false` 覆盖父级。默认 `false`。纯阅读不显示编辑器。

`empty-value` 可显式设为 `null`（或 `() => null`），清空时原样提交 null；省略时保留组件原默认值。界面把 null 显示为空，不会把普通输入的空字符串自动转成 null。支持弹出编辑的字段中，清空先修改草稿，确认后提交，取消则保留原值。

候选属性 `options` 支持数组或 `(query, { signal }) => 数组/Promise`。加载、取消、过期结果隔离由组件内部处理，失败触发 load-error。单选/多选分组初始化以空字符串查询，搜索型字段在查询变化时调用；树形字段根数据与原有 load-more 子节点懒加载独立。

---

Document: llms/zh-CN/components/rate.md

<!-- Source: src/rate/README.md; locale: zh-CN; page: /components/rate/ -->

# Rate

用于评分或打星的组件。

## 基础示例

### 基础用法

评分组件基本用法。

Example source: src/rate/__demos__/basic.vue

```vue
<template>
  <c-rate  />
</template>

<script lang="ts" setup>
</script>
```

## 外观与状态

### 只读模式

<!-- demo-config-notes:start -->

#### 本组配置对照

| 配置            | 作用                                     | 相关示例   |
| --------------- | ---------------------------------------- | ---------- |
| `default-value` | 非受控初值，只初始化一次                 | 只读模式   |
| `readonly`      | 只读且可聚焦；缺省继承表单               | 只读模式   |
| `color`         | 选中颜色，或按每个图标分值的递增阈值映射 | 自定义颜色 |

<!-- demo-config-notes:end -->

通过设置 `readonly` 属性让评分组件为只读状态。

Example source: src/rate/__demos__/readonly.vue

```vue
<template>
  <c-rate :default-value="4" readonly />
</template>

<script lang="ts" setup>
</script>
```

### 自定义颜色

通过 color 可以自定义颜色。另外可以通过对象形式自定义不同分值时的颜色。

Example source: src/rate/__demos__/color.vue

```vue
<template>
  <c-space direction="column">
    <c-rate color="red" />
    <c-rate :color="color" />
  </c-space>
</template>

<script lang="ts" setup>
const color = {
  2: 'red',
  4: 'green',
  5: 'blue',
}
</script>
```

## 内容与展示

### 尺寸与符号

<!-- demo-config-notes:start -->

#### 本组配置对照

| 配置            | 作用                                              | 相关示例                         |
| --------------- | ------------------------------------------------- | -------------------------------- |
| `default-value` | 非受控初值，只初始化一次                          | 尺寸与符号、半选、评分总数与清除 |
| `allow-half`    | 半分步长                                          | 尺寸与符号、半选                 |
| `grading`       | 固定五级表情评分，优先于插槽和图标                | 尺寸与符号、笑脸分级             |
| `size`          | 图标尺寸；数字/数字字符串为 px，带单位为 CSS 长度 | 尺寸与符号                       |
| `aria-label`    | 评分的业务无障碍名称                              | 尺寸与符号                       |
| `gap`           | 图标间距；数字/数字字符串为 px，带单位为 CSS 长度 | 尺寸与符号                       |

<!-- demo-config-notes:end -->

Example source: src/rate/__demos__/sizes-and-symbols.vue

```vue
<template>
  <c-space direction="column">
    <c-rate :default-value="3" :size="20" aria-label="20 像素评分" />
    <c-rate :default-value="3.5" size="2rem" gap="0.5rem" allow-half aria-label="自定义尺寸评分" />
    <c-rate :default-value="4" grading aria-label="表情评分" />
    <c-rate :default-value="3" aria-label="自定义字符评分">
      <template #character="{ value, active }"><span>{{ active ? '♥' : '♡' }}{{ value }}</span></template>
    </c-rate>
  </c-space>
</template>
```

### 半选

指定 `allow-half` 来开启半选。

Example source: src/rate/__demos__/half.vue

```vue
<template>
  <c-rate :default-value="2.5" allow-half />
</template>

<script lang="ts" setup>
</script>
```

### 评分总数与清除

比较评分上限和重复选择时的清除行为；半星精度、键盘输入与受控值保持独立。

<details>
<summary>配置说明与使用限制</summary>

#### 支持清除

通过设置 `clearable` 来允许清除评分。

#### 任意长度的评分

通过指定 `count` 来指定任意长度的评分组件。

</details>

Example source: src/rate/__demos__/value-rules-comparison.vue

```vue
<script setup lang="ts">


</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="clear">
    <h4><span lang="zh-CN">支持清除</span><span lang="en-US">clear</span></h4>
    <c-rate :default-value="3" clearable />
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="count">
    <h4><span lang="zh-CN">任意长度的评分</span><span lang="en-US">count</span></h4>
    <c-rate :count="10" />
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

### 笑脸分级

通过 `grading` 使用笑脸分级。

Example source: src/rate/__demos__/grading.vue

```vue
<template>
  <c-rate grading />
</template>

<script lang="ts" setup>
</script>
```

## 自定义与插槽

### 自定义评分字符

可以将星星替换为其他字符，比如表情、字母，数字，字体图标甚至中文。

Example source: src/rate/__demos__/character.vue

```vue
<template>
  <c-rate :default-value="2">
    <template #character="index">
      <c-icon-check v-if="index < 3" />
      <c-icon-close v-else />
    </template>
  </c-rate>
</template>

<script lang="ts" setup>
</script>
```

## 交互与控制

### 交互状态切换

<!-- demo-config-notes:start -->

#### 本组配置对照

| 配置            | 作用                                   | 相关示例                 |
| --------------- | -------------------------------------- | ------------------------ |
| `disabled`      | 禁用；缺省继承表单，显式 false 覆盖    | 交互状态切换、键盘与状态 |
| `readonly`      | 只读且可聚焦；缺省继承表单             | 交互状态切换、键盘与状态 |
| `allow-half`    | 半分步长                               | 键盘与状态               |
| `clearable`     | 重复点击当前分数清空；键盘边界不会清空 | 键盘与状态               |
| `aria-label`    | 评分的业务无障碍名称                   | 键盘与状态               |
| `default-value` | 非受控初值，只初始化一次               | 键盘与状态               |

<!-- demo-config-notes:end -->

适用于评分反馈。调整禁用、只读，用相同数据观察变化。控制区始终可用，可以随时恢复编辑；错误外观本身不会触发表单校验。

Example source: src/rate/__demos__/state-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref(3);
const __demoState = __demoReactive({ disabled: false, readonly: false });
</script>
<template>
  <c-space direction="column" :size="16">
    <c-space wrap>
      <c-checkbox v-model="__demoState['disabled']">disabled</c-checkbox>
      <c-checkbox v-model="__demoState['readonly']">readonly</c-checkbox>
    </c-space>
    <c-rate v-model="value" v-bind="__demoState"></c-rate>
  </c-space>
</template>
```

### 键盘与状态

Example source: src/rate/__demos__/keyboard.vue

```vue
<script setup>
import { ref } from 'vue'
const score = ref(2.5)
</script>

<template>
  <c-space direction="column">
    <p>Tab 聚焦；方向键按半分调整；Home 清零，End 满分。重复点击当前分数可清空。</p>
    <c-rate v-model="score" allow-half clearable aria-label="服务评分" />
    <span>当前评分：{{ score }}</span>
    <c-rate :default-value="3" readonly aria-label="只读评分" />
    <c-rate :default-value="3" disabled aria-label="禁用评分" />
  </c-space>
</template>
```

## API

### 空值识别与阅读空文案

`empty-values` 用于空值识别，`empty-value` 保留原清空输出；`empty-text` 仅在 `read-pretty` 空内容下展示，默认 `'-'`，字段 > FormItem > Form，自定义 read 插槽优先。显式配置 empty-values 后，内置 required 接入该策略，自定义校验仍收到原值。详见[统一说明](llms/zh-CN/guide/empty-values.md)。

| 参数         | 类型               | 缺省与范围                                            |
| ------------ | ------------------ | ----------------------------------------------------- |
| empty-values | readonly unknown[] | 字段 > FormItem > Form > 组件族默认；完整覆盖，不合并 |
| empty-text   | string             | 字段 > FormItem > Form > '-'；显式 '' 有效            |

以上是字段展示层 API；纯面板不因此新增阅读模式。Form 与 FormItem 提供继承配置。empty-value 的现有类型与默认输出仍按该组件原 API 执行。

### Props

| 属性           | 说明                                              | 类型                             | 默认值     |
| -------------- | ------------------------------------------------- | -------------------------------- | ---------- |
| model-value    | 受控评分，配合 v-model；外部更新不发事件          | number                           | undefined  |
| default-value  | 非受控初值，只初始化一次                          | number                           | 0          |
| count          | 正有限数向下取整；非法值回退 5                    | number \| string                 | 5          |
| allow-half     | 半分步长                                          | boolean                          | false      |
| clearable      | 重复点击当前分数清空；键盘边界不会清空            | boolean                          | false      |
| grading        | 固定五级表情评分，优先于插槽和图标                | boolean                          | false      |
| disabled       | 禁用；缺省继承表单，显式 false 覆盖               | boolean                          | undefined  |
| readonly       | 只读且可聚焦；缺省继承表单                        | boolean                          | undefined  |
| aria-label     | 评分的业务无障碍名称                              | string                           | undefined  |
| size           | 图标尺寸；数字/数字字符串为 px，带单位为 CSS 长度 | number \| string                 | 样式默认值 |
| gap            | 图标间距；数字/数字字符串为 px，带单位为 CSS 长度 | number \| string                 | 样式默认值 |
| color          | 选中颜色，或按每个图标分值的递增阈值映射          | string \| Record<string, string> | undefined  |
| empty-color    | 未选中颜色                                        | string                           | undefined  |
| disabled-color | 禁用时覆盖选中/未选中颜色                         | string                           | undefined  |
| icon           | 选中图标                                          | string \| Component              | 星形       |
| half-icon      | 半选图标                                          | string \| Component              | 半星       |
| empty-icon     | 未选中图标                                        | string \| Component              | 空星       |
| ripple         | 点击水波纹                                        | boolean                          | true       |

size/gap 不接受 xs/sm/md/lg/xl 档位；省略、非法或非正数保留样式默认值。CSS var/calc/min/max/clamp 长度可用。评分按 1 或 0.5 步长归一至 0～count；非有限评分显示 0，不反向改写外部值。

### Events

| 事件               | 参数          | 说明                                      |
| ------------------ | ------------- | ----------------------------------------- |
| update:model-value | value: number | 用户产生新值                              |
| change             | value: number | 新值确认；相同值不重复通知                |
| hover-change       | value: number | 鼠标预览改变；离开/失焦/禁用/只读重置为 0 |

### Slots

| 插槽      | 参数                     | 说明                                           |
| --------- | ------------------------ | ---------------------------------------------- |
| character | { index, value, active } | index 从 0 开始，value 从 1 开始；替换评分符号 |

优先级：grading > character > icon/half-icon/empty-icon > 默认图标。字符串图标需要全局注册；组件值无需注册。

### Methods

focus() 聚焦评分，blur() 移除焦点。只读仍可聚焦，禁用移出 Tab 序列。方向键增减、Home 清零、End 满分；子控件键盘事件和 Alt/Ctrl/Meta 组合键不被接管。触屏点击与鼠标点击遵循相同半选、清空规则。

### 类型定义

导出 RateProps、RateColor、RateIcon、RateInstance、RateExpose、RateEmits、RateCharacterSlotProps。

### 样式变量

| Token                                 | Default                                        |
| ------------------------------------- | ---------------------------------------------- |
| `--c-rate-disabled-color`             | `var(--c-sys-color-content-disabled)`          |
| `--c-rate-error-color`                | `var(--c-sys-color-content-danger)`            |
| `--c-rate-active-scale`               | `1.2`                                          |
| `--c-rate-focus-color`                | `var(--c-sys-color-content-brand)`             |
| `--c-rate-focus-width`                | `2px`                                          |
| `--c-rate-focus-offset`               | `2px`                                          |
| `--c-rate-size`                       | `var(--c-font-size-title-3)`                   |
| `--c-rate-gap`                        | `var(--c-spacing-4)`                           |
| `--c-rate-min-height`                 | `var(--c-size-md)`                             |
| `--c-rate-action-padding`             | `0px`                                          |
| `--c-rate-empty-color`                | `var(--c-color-fill-3)`                        |
| `--c-rate-active-color`               | `rgb(var(--c-gold-6))`                         |
| `--c-rate-transition-duration`        | `var(--c-transition-duration-2)`               |
| `--c-rate-scale-duration`             | `var(--c-transition-duration-4)`               |
| `--c-rate-transition-timing-function` | `var(--c-transition-timing-function-standard)` |

两端公开 Token 后缀及含义一致；Cedar 保留金色星形和紧凑间距，Maple 保留主色星形与触控内边距，默认值差异已登记主题契约。源码各自维护，不共享运行时。

`transition-duration` 控制 hover/颜色过渡，`scale-duration` 控制选中动画，`transition-timing-function` 控制缓动。低动态偏好下关闭非必要动画；`size` / `gap` Prop 会覆盖当前实例的对应 Token。

### Form 字段展示与确认

本组件支持 `edit-mode`，字段 > FormItem > Form 逐层继承；未指定时为 `direct`，保留原有交互。支持值：`direct / click / dblclick`。非 direct 编辑模式通过字段值入口打开编辑面板，并维护单份草稿；确认后才更新 v-model，取消、重置或启用 readPretty 时丢弃草稿。

Cedar 使用 edit-mode="click" / "dblclick" 在字段附近打开编辑浮层，Enter/F2 也可进入；取消/Escape 丢弃草稿，确认后提交。readPretty 为独立阅读属性，与 readonly、disabled 分开。

`before-commit(value, { previousValue, signal })` 可拦截弹层保存；FormItem 先校验候选值，失败保持编辑。`open / default-open / update:open` 控制编辑层。`#read="{ value, text }"` 可自定义阅读内容。集中示例见 Form 的“各类字段统一展示”。

`read-pretty` 为独立布尔属性，与 `readonly`、`disabled` 同级；字段 > FormItem > Form 继承，显式 `false` 覆盖父级。默认 `false`。纯阅读不显示编辑器。

## 配置清空后的值

`empty-value` 指定当前组件已有清空动作的输出；省略时采用该组件默认返回。具体类型以组件 API 为准。它不改变 empty-values 的识别规则，也不改变 Form reset 的初始值。

`empty-value` 可显式设为 `null`（或 `() => null`），清空时原样提交 null；省略时保留组件原默认值。界面把 null 显示为空，不会把普通输入的空字符串自动转成 null。支持弹出编辑的字段中，清空先修改草稿，确认后提交，取消则保留原值。

---

Document: llms/zh-CN/components/resize-box.md

<!-- Source: src/resize-box/README.md; locale: zh-CN; page: /components/resize-box/ -->

# ResizeBox

## 基础示例

### 基础用法

`ResizeBox` 伸缩框组件的基础使用。通过设置 `directions`，可以指定四条边中的哪几条边可以进行伸缩。

Example source: src/resize-box/__demos__/basic.vue

```vue
<template>
  <div>
    <c-resize-box
      :directions="['right', 'bottom']"
      :style="{ width: '500px', minWidth: '100px', maxWidth: '100%', height: '200px', textAlign: 'center' }"
    >
      <c-typography-paragraph>We are building the future of content discovery and creation.</c-typography-paragraph>
      <c-divider  />
      <c-typography-paragraph>
        ByteDance's content platforms enable people to enjoy content powered by AI technology. We inform, entertain, and
        inspire people across language, culture and geography.
      </c-typography-paragraph>
      <c-divider>ByteDance</c-divider>
      <c-typography-paragraph>Yiming Zhang is the founder and CEO of ByteDance.</c-typography-paragraph>
    </c-resize-box>
  </div>
</template>

<script lang="ts" setup>
</script>
```

## 布局与排列

### 在布局中使用

[Layout](react/components/ResizeBox) 组件中集成了 `ResizeBox` 组件，可以在 Layout 中使用可伸缩的侧边栏。

Example source: src/resize-box/__demos__/layout.vue

```vue
<template>
  <div class="layout-demo">
    <c-layout>
      <c-layout-header>Header</c-layout-header>
      <c-layout>
        <c-layout-sider :resize-directions="['right']"> Sider </c-layout-sider>
        <c-layout-content>Content</c-layout-content>
      </c-layout>
      <c-layout-footer>Footer</c-layout-footer>
    </c-layout>
  </div>
</template>

<script lang="ts" setup>
</script>

<style scoped>
.layout-demo :deep(.c-layout-header),
.layout-demo :deep(.c-layout-footer),
.layout-demo :deep(.c-layout-sider-children),
.layout-demo :deep(.c-layout-content) {
  display: flex;
  flex-direction: column;
  justify-content: center;
  color: var(--color-white);
  font-size: 16px;
  font-stretch: condensed;
  text-align: center;
}

.layout-demo :deep(.c-layout-header),
.layout-demo :deep(.c-layout-footer) {
  height: 64px;
  background-color: var(--color-primary-light-4);
}

.layout-demo :deep(.c-layout-sider) {
  width: 206px;
  background-color: var(--color-primary-light-3);
  min-width: 150px;
  max-width: 500px;
  height: 200px;
}

.layout-demo :deep(.c-layout-content) {
  background-color: rgb(var(--brand-6));
}
</style>
```

## 交互与控制

### 受控的高宽

`ResizeBox` 的 `width` 和 `height` 都支持 `v-model`。

Example source: src/resize-box/__demos__/controlled.vue

```vue
<template>
  <div>
    <c-resize-box
      :directions="['right', 'bottom']"
      :style="{ minWidth: '100px', maxWidth: '100%', textAlign: 'center' }"
      v-model:width="width"
      v-model:height="height"
    >
      <c-typography-paragraph>We are building the future of content discovery and creation.</c-typography-paragraph>
      <c-divider  />
      <c-typography-paragraph>
        ByteDance's content platforms enable people to enjoy content powered by AI technology. We inform, entertain, and
        inspire people across language, culture and geography.
      </c-typography-paragraph>
      <c-divider>ByteDance</c-divider>
      <c-typography-paragraph>Yiming Zhang is the founder and CEO of ByteDance.</c-typography-paragraph>
    </c-resize-box>
  </div>
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const width = ref(500)
const height = ref(200)
</script>
```

### 定制伸缩杆内容

可通过插槽 `resize-trigger` 定制各个方向的伸缩杆的内容。

Example source: src/resize-box/__demos__/custom-triggers.vue

```vue
<template>
  <c-resize-box
    :directions="['right', 'bottom']"
    style="width: 500px; min-width: 100px; max-width: 100%; height: 200px; text-align: center"
  >
    <template #resize-trigger="{ direction }">
      <div :class="[`resizebox-demo`, `resizebox-demo-${direction === 'right' ? 'vertical' : 'horizontal'}`]">
        <div class="resizebox-demo-line" />
      </div>
    </template>
    <c-typography-paragraph>We are building the future of content discovery and creation.</c-typography-paragraph>
    <c-divider  />
    <c-typography-paragraph>
      ByteDance's content platforms enable people to enjoy content powered by AI technology. We inform, entertain, and
      inspire people across language, culture and geography.
    </c-typography-paragraph>
    <c-divider>ByteDance</c-divider>
    <c-typography-paragraph>Yiming Zhang is the founder and CEO of ByteDance.</c-typography-paragraph>
  </c-resize-box>
</template>

<script lang="ts" setup>
</script>

<style scoped>
.resizebox-demo {
  position: relative;
  display: flex;
  align-items: center;
  justify-content: center;
  width: 100%;
  height: 100%;
  background-color: var(--c-color-bg-white);
}

.resizebox-demo::before,
.resizebox-demo::after {
  width: 6px;
  height: 6px;
  border: 1px solid rgb(var(--brand-6));
  content: '';
}

.resizebox-demo-line {
  flex: 1;
  background-color: rgb(var(--brand-6));
}

.resizebox-demo-vertical {
  flex-direction: column;
}

.resizebox-demo-vertical .resizebox-demo-line {
  width: 1px;
  height: 100%;
}

.resizebox-demo-horizontal .resizebox-demo-line {
  height: 1px;
}
</style>
```

## API

### `<resize-box>` Props

| 参数名               | 描述                                       | 类型                                         |   默认值    |
| -------------------- | ------------------------------------------ | -------------------------------------------- | :---------: |
| width **(v-model)**  | 宽度                                       | `number`                                     |     `-`     |
| height **(v-model)** | 高度                                       | `number`                                     |     `-`     |
| component            | 伸缩框的 html 标签                         | `string`                                     |   `'div'`   |
| directions           | 启用尺寸调整手柄的边，默认仅 right；可选 top/right/bottom/left，可组合；不是鼠标移动方向，也不是浮层方位 | `('left' \| 'right' \| 'top' \| 'bottom')[]` | `['right']` |

### `<resize-box>` Events

| 事件名       | 描述           | 参数                                                           |
| ------------ | -------------- | -------------------------------------------------------------- |
| moving-start | 拖拽开始时触发 | ev: `MouseEvent`                                               |
| moving       | 拖拽时触发     | size: `{ width: number; height: number; }`<br>ev: `MouseEvent` |
| moving-end   | 拖拽结束时触发 | ev: `MouseEvent`                                               |

### `<resize-box>` Slots

| 插槽名              |     描述     | 参数                                                |
| ------------------- | :----------: | --------------------------------------------------- |
| resize-trigger      | 伸缩杆的内容 | direction: `'left' \| 'right' \| 'top' \| 'bottom'` |
| resize-trigger-icon | 伸缩杆的图标 | direction: `'left' \| 'right' \| 'top' \| 'bottom'` |

### 类型定义

组件导出以下类型定义

```ts
import type { ResizeBoxInstance } from '@cedar-design/ui'
```


### 方位语义与配置入口

directions 指启用调整手柄的边，保留现有名称；默认仅右边，可组合多边。它不是 orientation 横纵轴，也不是 placement 弹层方位。从零设计时 edges 更直接，但本次未进行 API 改名。


## 阅读方向与交互

ResizeBox 的 `directions` 使用物理边：left 始终在左、right 始终在右，RTL 不交换手柄，也不反转宽高含义。左手柄向左、右手柄向右增大宽度；上手柄向上、下手柄向下增大高度，尺寸下限为 0。

手柄可聚焦并使用对应轴的方向键，步长 10px，Shift 为 50px；支持鼠标和触摸指针。文字继承原生阅读方向。方向切换、移除活动手柄、组件停用或卸载会释放手势监听和临时光标。

---

Document: llms/zh-CN/components/result.md

<!-- Source: src/result/README.md; locale: zh-CN; page: /components/result/ -->

# Result

用于反馈一系列操作任务的处理结果，当有重要操作需告知用户处理结果，且反馈内容较为复杂时使用。

## 基础示例

### 基础用法

Next status 循环六种本地结果状态并更新标题/图形，Reset status 恢复 info；按钮不发请求或导航。Result 只展示传入的 status，不根据标题文字推断成功/失败。

展示结果状态。

Example source: src/result/__demos__/basic.vue

```vue
<script setup lang="ts">
import { computed, ref } from 'vue'
const statuses = ['info', 'success', 'warning', 'danger', 'question', 'empty'] as const
const index = ref(0)
const status = computed(() => statuses[index.value])
</script>

<template>
  <c-result data-demo-result :status="status" :title="'Result: ' + status" subtitle="Local state preview">
    <template #extra>
      <c-space wrap>
        <c-button status="primary" @click="index = (index + 1) % statuses.length">Next status</c-button>
        <c-button @click="index = 0">Reset status</c-button>
      </c-space>
      <p aria-live="polite">Current status: {{ status }}</p>
    </template>
  </c-result>
</template>
```

## 内容与展示

### 成功、警告与失败

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `status` | 结果页显示的状态 | 成功、警告与失败、HTTP 结果状态对比、完整功能 |
| `title` | 标题内容 | 成功、警告与失败、完整功能 |
| `subtitle` | 子标题内容 | HTTP 结果状态对比 |
<!-- demo-config-notes:end -->

对比语义状态如何影响图形、标题和操作区；HTTP 状态与自定义图形另行展示。

<details>
<summary>配置说明与使用限制</summary>

#### 成功状态

展示成功状态。

#### 警告状态

展示警告状态。

#### 错误状态

展示错误状态。

</details>

Example source: src/result/__demos__/status-comparison.vue

```vue
<script setup lang="ts">


</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="success">
    <h4><span lang="zh-CN">成功状态</span><span lang="en-US">success</span></h4>
    <c-result status="success" title="This is title content">
        <template #subtitle> This is subtitle content </template>
        <template #extra>
          <c-space>
            <c-button status="primary">Back</c-button>
          </c-space>
        </template>
      </c-result>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="warning">
    <h4><span lang="zh-CN">警告状态</span><span lang="en-US">warning</span></h4>
    <c-result status="warning" title="This is title content">
        <template #subtitle> This is subtitle content </template>
    
        <template #extra>
          <c-space>
            <c-button status="primary">Back</c-button>
          </c-space>
        </template>
      </c-result>
  </section>

  <section class="demo-comparison-case demo-comparison-case--3" data-comparison-scene="error">
    <h4><span lang="zh-CN">错误状态</span><span lang="en-US">error</span></h4>
    <c-result status="danger" title="This is title content">
        <template #subtitle> This is subtitle content </template>
    
        <template #extra>
          <c-space>
            <c-button status="primary">Back</c-button>
          </c-space>
        </template>
      </c-result>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

### HTTP 结果状态对比

比较无权限、资源不存在和服务器错误的内容层级，按业务恢复路径选择操作文案。

<details>
<summary>配置说明与使用限制</summary>

#### HTTP状态码 403

没有当前页面的访问权限。

#### HTTP状态码 404

页面未找到

#### HTTP状态码 500

通常表示服务器错误

</details>

Example source: src/result/__demos__/http-status-comparison.vue

```vue
<script setup lang="ts">


</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="403">
    <h4><span lang="zh-CN">HTTP状态码 403</span><span lang="en-US">403</span></h4>
    <c-result status="403" subtitle="Access to this resource on the server is denied.">
        <template #extra>
          <c-space>
            <c-button status="primary">Back</c-button>
          </c-space>
        </template>
      </c-result>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="404">
    <h4><span lang="zh-CN">HTTP状态码 404</span><span lang="en-US">404</span></h4>
    <c-result status="404" subtitle="Whoops, that page is gone.">
        <template #extra>
          <c-space>
            <c-button status="primary">Back</c-button>
          </c-space>
        </template>
      </c-result>
  </section>

  <section class="demo-comparison-case demo-comparison-case--3" data-comparison-scene="500">
    <h4><span lang="zh-CN">HTTP状态码 500</span><span lang="en-US">500</span></h4>
    <c-result status="500" subtitle="This page isn’t working.">
        <template #extra>
          <c-space>
            <c-button status="primary">Back</c-button>
          </c-space>
        </template>
      </c-result>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

### 完整功能

完整功能

Example source: src/result/__demos__/all.vue

```vue
<template>
  <c-result status="danger" title="No internet ">
    <template #icon>
      <c-icon-face-frown-fill />
    </template>
    <template #subtitle> DNS_PROBE_FINISHED_NO_INTERNET</template>

    <template #extra>
      <c-button status="primary">Refresh</c-button>
    </template>
    <c-typography style="background: var(--color-fill-2); padding: 24px">
      <c-typography-paragraph>Try:</c-typography-paragraph>
      <ul>
        <li>Checking the network cables, modem, and router</li>
        <li>Reconnecting to Wi-Fi</li>
      </ul>
    </c-typography>
  </c-result>
</template>

<script lang="ts" setup>
</script>
```

## 自定义与插槽

### 自定义状态

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `title` | 标题内容 | 自定义状态 |
| `subtitle` | 子标题内容 | 自定义状态 |
<!-- demo-config-notes:end -->

自定义状态。需要传入指定的图标

Example source: src/result/__demos__/custom.vue

```vue
<template>
  <c-result title="This is title content" subtitle="This is subtitle content">
    <template #icon>
      <c-icon-face-smile-fill />
    </template>
    <template #extra>
      <c-space>
        <c-button status="secondary">Again</c-button>
        <c-button status="primary">Back</c-button>
      </c-space>
    </template>
  </c-result>
</template>

<script lang="ts" setup>
</script>
```

## API

### `<result>` Props

| 参数名   | 描述             | 类型                                                                             |  默认值  |
| -------- | ---------------- | -------------------------------------------------------------------------------- | :------: |
| status   | 结果页显示的状态 | `'info' \| 'success' \| 'warning' \| 'danger' \| 'question' \| 'empty' \| '403' \| '404' \| '500'` | `'info'` |
| title    | 标题内容         | `string`                                                                         |   `-`    |
| subtitle | 子标题内容       | `string`                                                                         |   `-`    |
| image-size | 状态图形尺寸，数字表示 px | `string \| number` | `-` |
| animation | 是否启用状态图形动画 | `boolean` | `true` |

### `<result>` Slots

| 插槽名   |   描述   | 参数 | 版本  |
| -------- | :------: | ---- | :---- |
| icon     |   自定义状态图形   | `{ size?: string }` |       |
| title    |   标题   | -    |       |
| subtitle |  副标题  | -    |       |
| extra    |  操作区  | -    | 2.8.0 |
| default  | 默认插槽 | -    | 2.8.0 |

### 类型定义

组件导出以下类型定义

```ts
import type { ResultInstance } from '@cedar-design/ui'
```

---

Document: llms/zh-CN/components/ripple.md

<!-- Source: src/ripple/README.md; locale: zh-CN; page: /components/ripple/ -->

# Ripple 水波指令

在元素上添加点击、触摸或键盘水波效果。指令主体与 Maple 独立复制同源，不共享实例或运行时；本地包依赖、命名空间与 Token 默认值独立维护。

## 基础示例

### 基本使用

支持触摸、鼠标主键和宿主 Enter/Space；鼠标从实际按下位置扩散，在所属 document 松开或窗口失焦时释放。忽略非主键与触摸产生的兼容鼠标事件；缺少 sourceCapabilities 时采用触摸后 800ms 去重窗口。键盘从中心扩散，请使用原生按钮。移动模拟站的点击不等同真实触屏验收。

Example source: src/ripple/__demos__/basic.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import { Ripple } from "@cedar-design/ui";
import "@cedar-design/ui/ripple/style";

const vRipple = Ripple;
const disabled = ref(false);
</script>

<template>
  <c-space wrap>
    <div role="button" tabindex="0" v-ripple="{ disabled }" class="ripple-demo"
      >Ripple</div
    >
    <div
      role="button" tabindex="0"
      v-ripple="{ disabled }"
      class="ripple-demo ripple-demo--long"
      >600ms 扩散／800ms 消退</div
    >
    <c-button @click="disabled = !disabled">{{
      disabled ? "启用水波" : "禁用水波"
    }}</c-button>
  </c-space>
</template>

<style scoped>
.ripple-demo--long {
  --c-ripple-expand-duration: 600ms;
  --c-ripple-fade-duration: 800ms;
}
.ripple-demo {
  position: relative;
  overflow: hidden;
  padding: 8px 20px;
  border: 1px solid var(--c-sys-color-border-default);
  border-radius: var(--c-sys-radius-sm);
  color: var(--c-sys-color-action-primary);
  background: var(--c-sys-color-surface-overlay);
  cursor: pointer;
}
</style>
```

## 选项

| 选项 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| color | 水波颜色 | `string` | `currentColor` |
| disabled | 禁止产生水波，并取消待执行动画 | `boolean` | `false` |

使用 `v-ripple="{ color, disabled }"`。组件卸载会取消动画与定时器并移除事件监听；键盘状态由每个元素独立维护。

## 样式

直接注册指令时，引入 `@cedar-design/ui/ripple/style`；运行时代码不导入 CSS，以支持 SSR 包导入。样式名使用 `--c-ripple-*`，声明见 `style/token.less`。主题默认值无需强行与移动端同值，动画规则与消费协议保持一致。

| 变量 | 默认值 | 职责 |
| --- | --- | --- |
| --c-ripple-color | currentColor | 波纹背景；color 选项优先 |
| --c-ripple-cubic-bezier | cubic-bezier(0.68, 0.01, 0.62, 0.6) | transform 扩散曲线 |
| --c-ripple-expand-duration | 200ms | transform 扩散时长 |
| --c-ripple-fade-duration | 140ms | opacity 显现／消退时长，线性 |

变量设置在实际指令宿主，由波纹继承；以上默认值目前两端一致。250ms 分别为节点创建后的最小展示和开始淡出后的最小移除等待，不是视觉时长或总生命周期。运行时读取实际波纹的 computed transition duration/delay；淡出等待创建+250ms 或激活+扩散时长的较晚者，删除等待 max(250ms, 消退时长)。长时长覆写不再截断，0ms／无样式仍保留清理下限。reduce 隐藏装饰波纹；扩散在创建／激活、消退在开始淡出时采样，不保证任意中途 CSS 改动或 animation。

重复释放只排队一次；禁用／卸载清理所属定时器与直接子波纹，不误删嵌套实例。文档事件绑定／移除使用挂载时 ownerDocument，不承诺跨文档搬迁自动重绑。仅本宿主 Enter／Space 与对应 keyup 或 blur 参与；指令不为普通 div 提供按钮语义、可访问名称或点击业务能力。真实触摸设备／OS 偏好另行验收。

---

Document: llms/zh-CN/components/row.md

<!-- Source: src/row/README.md; locale: zh-CN; page: /components/row/ -->

# Row

24 栏 Flex 栅格。Row 管理间距与对齐，Col 管理列宽、偏移、排序与响应式配置。需要 CSS Grid 折叠与后缀时使用 Grid。

> **布局怎么选**
>
> - Grid + GridItem：适合表单分栏、卡片网格，需要统一列宽、跨列、响应式列数或折叠行与后缀时使用。
> - Row + Col：适合 24 栏 Flex 布局，需要水平/垂直对齐、控制换行、固定宽度与自适应宽度组合，或响应式排序时使用。Row 控制整行，Col 控制列宽、偏移和排序。
> - Space：适合按钮、标签、文字等简单排列，只需要间距、方向和对齐时使用；更自由的宽度分配可使用原生 Flex。

## 基础示例

### 24 栏基础布局

Example source: src/row/__demos__/basic.vue

```vue
<template><div>
  <c-row :gutter="12"><c-col :span="12"><div class="cell">12</div></c-col><c-col :span="12"><div class="cell soft">12</div></c-col></c-row>
  <c-row :gutter="12"><c-col v-for="i in 3" :key="i" :span="8"><div class="cell">8</div></c-col></c-row>
</div></template>

<style scoped>
.controls { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; }
.cell { box-sizing: border-box; padding: 12px; min-width: 0; border-radius: 4px; background: var(--c-color-primary); color: var(--c-color-white); text-align: center; overflow-wrap: anywhere; }
.soft { opacity: .7; }
</style>
```

## 布局与排列

### 双向间距与响应式间距

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `gutter` | 间距：数值、响应式对象或 [水平, 垂直] | 双向间距与响应式间距、水平与垂直对齐、换行与普通容器模式 |
| `justify` | 水平对齐 | 水平与垂直对齐、布局与对齐 |
| `align` | 垂直对齐 | 水平与垂直对齐、布局与对齐 |
| `wrap` | 是否换行 | 换行与普通容器模式 |
| `div` | Row 与 Col 均作为普通容器，移除全部布局样式 | 换行与普通容器模式 |
<!-- demo-config-notes:end -->

Example source: src/row/__demos__/gutter.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const gap = ref(16)
const vertical = ref(true)
</script>
<template><div>
  <div class="controls"><c-radio-group v-model="gap"><c-radio v-for="value in [0, 8, 16, 24]" :key="value" :value="value">{{ value }}px</c-radio></c-radio-group><c-switch v-model="vertical" aria-label="Vertical gutter" />Vertical gap</div>
  <c-row :gutter="[gap, vertical ? gap : 0]"><c-col v-for="i in 6" :key="i" :span="8"><div class="cell">{{ i }}</div></c-col></c-row>
  <c-row :gutter="[{ xs: 8, md: 24 }, { xs: 8, md: 16 }]"><c-col v-for="i in 4" :key="i" :span="12"><div class="cell soft">Responsive gap</div></c-col></c-row>
</div></template>

<style scoped>
.controls { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; }
.cell { box-sizing: border-box; padding: 12px; min-width: 0; border-radius: 4px; background: var(--c-color-primary); color: var(--c-color-white); text-align: center; overflow-wrap: anywhere; }
.soft { opacity: .7; }
</style>
```

### 水平与垂直对齐

Example source: src/row/__demos__/alignment.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const justifies = ['start', 'center', 'end', 'space-around', 'space-between'] as const
const aligns = ['start', 'center', 'end', 'stretch'] as const
const justify = ref<typeof justifies[number]>('space-between')
const align = ref<typeof aligns[number]>('center')
</script>
<template><div>
  <c-radio-group v-model="justify"><c-radio v-for="value in justifies" :key="value" :value="value">{{ value }}</c-radio></c-radio-group>
  <c-radio-group v-model="align"><c-radio v-for="value in aligns" :key="value" :value="value">{{ value }}</c-radio></c-radio-group>
  <c-row :gutter="12" :justify="justify" :align="align"><c-col v-for="i in 3" :key="i" :span="6"><div class="cell" :style="{ minHeight: `${36 + i * 24}px`, height: '100%' }">{{ i }}</div></c-col></c-row>
</div></template>

<style scoped>
.controls { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; }
.cell { box-sizing: border-box; padding: 12px; min-width: 0; border-radius: 4px; background: var(--c-color-primary); color: var(--c-color-white); text-align: center; overflow-wrap: anywhere; }
.soft { opacity: .7; }
</style>
```

### 换行与普通容器模式

Example source: src/row/__demos__/wrap.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const wrap = ref(true)
const div = ref(false)
</script>
<template><div>
  <div class="controls"><c-switch v-model="wrap" aria-label="Wrap" />Wrap<c-switch v-model="div" aria-label="Plain div" />Plain div</div>
  <div style="overflow: auto; padding: 8px"><c-row :gutter="12" :wrap="wrap" :div="div"><c-col v-for="i in 3" :key="i" :span="12"><div class="cell">{{ i }}</div></c-col></c-row></div>
</div></template>

<style scoped>
.controls { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; }
.cell { box-sizing: border-box; padding: 12px; min-width: 0; border-radius: 4px; background: var(--c-color-primary); color: var(--c-color-white); text-align: center; overflow-wrap: anywhere; }
.soft { opacity: .7; }
</style>
```

### 嵌套与间距隔离

Example source: src/row/__demos__/nested.vue

```vue
<template><div><c-row :gutter="24"><c-col :span="16"><c-row :gutter="8"><c-col :span="12"><div class="cell">Inner 12</div></c-col><c-col :span="12"><div class="cell soft">Inner 12</div></c-col></c-row></c-col><c-col :span="8"><div class="cell">Outer 8</div></c-col></c-row></div></template>

<style scoped>
.controls { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; }
.cell { box-sizing: border-box; padding: 12px; min-width: 0; border-radius: 4px; background: var(--c-color-primary); color: var(--c-color-white); text-align: center; overflow-wrap: anywhere; }
.soft { opacity: .7; }
</style>
```

### 布局与对齐

适用于row。调整交叉轴对齐、主轴分配，用相同数据观察变化。内容保持一致，便于比较不同设置的实际效果。

Example source: src/row/__demos__/layout-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";

const __demoLayout = __demoReactive({ align: "start", justify: "start" });
</script>
<template>
  <c-space direction="column" :size="16">
    <c-form layout="vertical">
      <c-form-item layout="vertical" size="sm" label="align">
        <c-radio-group
          v-model="__demoLayout['align']"
          aria-label="align"
          :options="[
            { label: 'start', value: 'start' },
            { label: 'center', value: 'center' },
            { label: 'end', value: 'end' },
            { label: 'stretch', value: 'stretch' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
      <c-form-item layout="vertical" size="sm" label="justify">
        <c-radio-group
          v-model="__demoLayout['justify']"
          aria-label="justify"
          :options="[
            { label: 'start', value: 'start' },
            { label: 'center', value: 'center' },
            { label: 'end', value: 'end' },
            { label: 'space-around', value: 'space-around' },
            { label: 'space-between', value: 'space-between' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
    </c-form>
    <c-row :gutter="12" v-bind="__demoLayout"
      ><c-col v-for="i in 3" :key="i" :span="8"
        ><div class="cell">8</div></c-col
      ></c-row
    >
  </c-space>
</template>
<style scoped>
.controls {
  display: flex;
  flex-wrap: wrap;
  align-items: center;
  gap: 12px;
}
.cell {
  box-sizing: border-box;
  padding: 12px;
  min-width: 0;
  border-radius: 4px;
  background: var(--c-color-primary);
  color: var(--c-color-white);
  text-align: center;
  overflow-wrap: anywhere;
}
.soft {
  opacity: 0.7;
}
</style>
```

## API

<!-- same-source-api:start -->
### Props

| 属性 | 说明 | Type | Default |
| --- | --- | --- | --- |
| gutter | 间距：数值、响应式对象或 [水平, 垂直] | `RowGutter` | `0` |
| justify | 水平对齐 | `start / center / end / space-around / space-between` | `start` |
| align | 垂直对齐 | `start / center / end / stretch` | `start` |
| wrap | 是否换行 | `boolean` | `true` |
| div | Row 与 Col 均作为普通容器，移除全部布局样式 | `boolean` | `false` |

### Events

| Event | Description |
| --- | --- |
| click | 原生 MouseEvent，每次点击一次 |

### Slots

| Slot | Description |
| --- | --- |
| default | 布局内容 |

### Methods

| Method | Description |
| --- | --- |
<!-- same-source-api:end -->

换行示例分别切换换行与普通 `div` 模式。普通模式移除 Row 布局样式及子 Col 间距；间距示例区分水平与垂直间距。Row 使用 Flex，不依赖 CSS Grid。

## 响应式与可访问性

断点基于浏览器视口：xs 为基础值，sm ≥576、md ≥768、lg ≥992、xl ≥1200、xxl ≥1600px；从最大匹配断点向下取已配置值。SSR 首屏使用 xs，挂载后响应视口；Grid 折叠和动态排序在挂载后计算。组件为布局容器，不增加键盘快捷键；内容语义及可聚焦元素由调用者提供。没有公开方法和专用主题 Token。

## 导入

Grid 仅包含 Grid.Item；Row、Col 是独立组件，拥有独立源码、样式、菜单、文档和 Demo。已移除 Grid.Row/Grid.Col、Grid 入口的 Row/Col 转导出以及 GridRowInstance/GridColInstance。请从库根入口或独立 row/col 入口导入；安装 Grid 不再自动注册 Row/Col。

---

Document: llms/zh-CN/components/scheduler.md

<!-- Source: src/scheduler/README.md; locale: zh-CN; page: /components/scheduler/ -->

# Scheduler 日程调度

原生 Vue 日程调度组件。资源是可选关联，可表示人员、设备、会议室，也可完全不使用。内置 Cedar 编辑器与资源筛选，日期计算、重叠布局、分配和校验独立于 Vue。现有 Calendar 继续负责轻量日期展示与选择。

| 目标 | 从这里开始 |
| --- | --- |
| 只展示或编辑日期与时间 | 基础用法，不关联资源的计划 |
| 给人员或设备排期 | 资源视图与分配 |
| 加载后端日程、保存修改 | 按范围远程加载，保存与自定义 |
| 设置休假、重复与可用时间 | 日历体验与可用时间，重复日程与日历数据 |
| 大规模排期、事务和完整业务 | 大规模资源、批量操作、最后的业务组合示例 |

## 基础示例

### 基础用法

先从一个日程开始：切换日/周/月视图，点击空白时间创建日程，点击已有日程编辑。只需 v-model 和初始日期，不需要准备资源、远程接口或保存钩子。

Example source: src/scheduler/__demos__/basic.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
import type { SchedulerEvent } from '@cedar-design/ui'
const events = ref<SchedulerEvent[]>([
  { id: 'meeting', title: '项目同步', start: '2026-09-09T09:00:00', end: '2026-09-09T10:00:00' },
])
</script>
<template>
  <c-scheduler v-model="events" default-date="2026-09-09" />
</template>
```

## 阅读方向

继承页面、局部容器或 ConfigProvider 的 `dir`，可沿用文档导航的 LTR/RTL 按钮实时切换。月/周/资源列和横向时间轴从阅读起点排列；纵向时间仍从上向下。切换方向保留日期、日程数据、选择和横向阅读距离，并取消正在进行的拖动或拉伸。

小时级资源时间线支持日程移动和开始/结束两端拉伸，遵守 `snapDuration`、只读状态、里程碑和日程的 `resizable` 限制。时间轴缩放保留可视时间区域中心的日期；资源标签固定在阅读起点，虚拟行与表头同步滚动。

默认重叠布局使用逻辑起点；自定义 `eventLayout` 返回的 `left` 保持屏幕物理左侧语义，由调用方按业务需要提供几何位置。日期、时区、依赖关系和资源顺序不会因 RTL 而反转。

## 视图与布局

### 布局分组与自定义宽度

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `default-date` | 初始定位日期 | 布局分组与自定义宽度、不关联资源的计划、资源周计划 |
| `default-mode` | 非受控默认视图 | 布局分组与自定义宽度、资源时间线、隐藏周末与指定星期 |
| `resources` | 当前可见资源行/列及本地选项，不要求全量目录 | 资源周计划、资源时间线、现在时间线 |
| `start-hour` | 时间网格起始小时，0–23 | 布局分组与自定义宽度、现在时间线、重叠日程错位叠放 |
| `end-hour` | 时间网格结束小时，必须大于起始，最多 24 | 布局分组与自定义宽度、现在时间线、重叠日程错位叠放 |
| `modes` | 允许切换的视图 | 不关联资源的计划、隐藏周末与指定星期、现在时间线 |
<!-- demo-config-notes:end -->

固定时长日程可设置 `resizable: false`，隐藏拉伸手柄但保留移动；它不限制应用通过表单或接口重新设置时间，最终时长仍由业务保存规则校验。

`layoutGroupId` 只用于日、周、资源日程时间网格的横向布局：同一日期和资源列内，同组时间相接或重叠的块共享列、宽度和聚焦层级；有空隙时分为独立布局单元。每个块保留自己的起止时间，分组不触发联动编辑、批量拖拽或保存。完全重合的同组块会互相遮挡，业务可拆分组或使用自定义详情。月、全天、议程和资源时间线不使用此字段。

`event-layout` 保留 `stack` / `columns`，也可传入 `(item: Readonly<SchedulerLayoutItem>) => { left, width }`。回调只定制横向几何，数值为单列宽度的 0–1 比例，必须满足 `left >= 0`、`width > 0`、`left + width <= 1`；非法结果回退默认叠放。纵向位置由时间决定，自定义布局支持聚焦前置。相同布局单元应返回相同几何，回调应保持纯函数，不修改 `item.event`。

Example source: src/scheduler/__demos__/layout-groups.vue

```vue
<template>
  <c-space direction="column" block>
    <c-alert
      >分组仅共享布局位置。业务关联保存在
      metadata，修改单块不会自动修改整组。</c-alert
    >
    <c-space>
      <c-checkbox v-model="grouped">连续日程组成布局组</c-checkbox>
      <c-checkbox v-model="custom">自定义横向留白</c-checkbox>
    </c-space>
    <c-scheduler
      v-model="displayEvents"
      :default-date="today"
      default-mode="day"
      :event-layout="custom ? layout : 'stack'"
      :show-sidebar="false"
      :start-hour="8"
      :end-hour="17"
    >
      <template #event="{ event }">
        <strong>{{ event.title }}</strong>
        <div v-if="event.metadata?.reference">
          关联：{{ event.metadata.reference }}
        </div>
      </template>
    </c-scheduler>
  </c-space>
</template>
<script setup lang="ts">
import { computed, ref } from "vue";
import type { SchedulerEvent, SchedulerEventLayout } from "../core";
const today = new Date();
const grouped = ref(true);
const custom = ref(false);
const at = (hour: number) => {
  const date = new Date(today);
  date.setHours(hour, 0, 0, 0);
  return date;
};
const events = ref<SchedulerEvent[]>([
  {
    id: "a",
    title: "阶段一",
    start: at(9),
    end: at(11),
    metadata: { reference: "A" },
  },
  {
    id: "b",
    title: "阶段二",
    start: at(11),
    end: at(13),
    metadata: { reference: "A" },
  },
  { id: "c", title: "独立日程", start: at(10), end: at(12) },
  {
    id: "d",
    title: "间隔后的阶段",
    start: at(15),
    end: at(16),
    metadata: { reference: "A" },
  },
]);
// Only the application interprets metadata and chooses which blocks share layout.
const displayEvents = computed({
  get: () =>
    events.value.map((event) => ({
      ...event,
      layoutGroupId:
        grouped.value && typeof event.metadata?.reference === "string"
          ? event.metadata.reference
          : undefined,
    })),
  set: (value: SchedulerEvent[]) => {
    events.value = value;
  },
});
// Product-specific percentages stay in the demo. Fractions are relative to one date/resource column.
const layout: SchedulerEventLayout = ({ column, columns }) => {
  const left = (column * 0.9) / columns;
  return {
    left,
    width: Math.min(Math.max(0.45, 1 - 0.1 * columns), 0.9 - left),
  };
};
</script>
```

组件只认识日程、资源、时间和通用展示属性。出勤单、任务类型、休息状态、业务权限、表单和服务端 DTO 映射放在 Demo/应用中，通过 `metadata`、插槽、`before-change`、`before-transaction` 接入。复制日程不继承 `layoutGroupId`，避免意外加入原布局组。

本次 API 调整：移除 Event/Template 的 `taskId`，改为 `metadata.taskId`；`createSchedulerTaskEvents`、`SchedulerTask`、`SchedulerTaskAssignment` 移至 Demo，不再从核心导出。`layoutGroupId` 不是任务 ID 的替代字段，只在需要分组布局时由应用映射。

### 不关联资源的计划

只管理日期与时间，不需要准备人员列表；没有资源、查询回调或关联 ID 时，侧栏和编辑器自动隐藏资源选择。

Example source: src/scheduler/__demos__/without-resources.vue

```vue
<template>
  <p>仅管理发布时间与工作计划，不传人员或设备列表。编辑器不显示资源字段。</p>
  <c-scheduler
    v-model="events"
    :modes="['day', 'week', 'month', 'agenda']"
    default-date="2026-09-09"
  />
</template>
<script setup lang="ts">
import { ref } from "vue";
import type { SchedulerEvent } from "@cedar-design/ui";
const events = ref<SchedulerEvent[]>([
  {
    id: "release",
    title: "产品发布",
    start: "2026-09-09T10:00:00",
    end: "2026-09-09T11:00:00",
    description: "检查发布清单",
  },
  {
    id: "campaign",
    title: "专题活动",
    start: "2026-09-10",
    end: "2026-09-13",
    allDay: true,
  },
  { id: "draft", title: "下期内容选题", description: "未排期，可拖入时间格" },
]);
</script>
```

### 资源周计划

在基础日历上增加资源列表，观察同一份日程的资源关联。再继续查看多人分配和远程目录。

Example source: src/scheduler/__demos__/resource-week.vue

```vue
<template>
  <c-scheduler
    v-model="events"
    default-date="2026-09-09"
    :resources="resources"
  />
</template>
<script setup lang="ts">
import { ref } from "vue";
import { createEvents, resources } from "./data";
const events = ref(createEvents());
</script>
```

### 资源时间线

按资源显示一周排期，按占用日期展示日程，跨天日程连续展示，同一天的日程分层排列；精确时分请看资源日程视图。拖放到日期格保留原开始时分。

Example source: src/scheduler/__demos__/timeline.vue

```vue
<template>
  <c-scheduler
    v-model="events"
    default-date="2026-09-09"
    default-mode="resource-timeline"
    :resources="resources"
  />
</template>
<script setup lang="ts">
import { ref } from "vue";
import { createEvents, resources } from "./data";
const events = ref(createEvents());
</script>
```

### 隐藏周末与指定星期

Example source: src/scheduler/__demos__/hidden-days.vue

```vue
<template>
  <c-space direction="column" block>
    <c-alert
      >隐藏日期只影响展示，原日程仍保留，并参与容量和冲突校验。跨周末任务会出现在周五及下周一；拖动到周一会按周一的实际日期保存。可切换周、月和议程检查同一份数据。</c-alert
    >
    <c-space wrap>
      <c-checkbox v-model="weekends">隐藏周末</c-checkbox>
      <c-checkbox v-model="wednesday">隐藏周三</c-checkbox>
      <c-tag>完整数据：{{ events.length }} 条</c-tag>
    </c-space>
    <c-scheduler
      key="hidden-days"
      v-model="events"
      default-date="2026-09-18"
      default-mode="month"
      :modes="['week', 'month', 'agenda']"
      :hidden-days="hidden"
      :first-day-of-week="0"
      history
    />
  </c-space>
</template>
<script setup lang="ts">
import { computed, ref } from "vue";
import type { SchedulerEvent } from "../core";
const weekends = ref(true);
const wednesday = ref(false);
const hidden = computed(() => [
  ...(weekends.value ? [0, 6] : []),
  ...(wednesday.value ? [3] : []),
]);
const events = ref<SchedulerEvent[]>([
  {
    id: "cross-weekend",
    title: "跨周末项目",
    start: "2026-09-18",
    end: "2026-09-22",
    allDay: true,
  },
  {
    id: "weekend",
    title: "周末值班",
    start: "2026-09-19T10:00:00",
    end: "2026-09-19T11:00:00",
  },
  {
    id: "wednesday",
    title: "周三评审",
    start: "2026-09-16T14:00:00",
    end: "2026-09-16T15:00:00",
  },
]);
</script>
```

`hidden-days` 接受星期数组，`0` 表示周日，`6` 表示周六；默认 `[]`，例如 `[0, 6]` 显示工作周。作用于周、月和议程视图，月表头与列数同步缩减，`first-day-of-week` 决定星期顺序。重复星期只计算一次。非法星期或隐藏全部七天会触发 Vue prop 校验警告，组件回退显示全部日期。

这是展示过滤：不会修改日程、重复规则、排期权限或完整的 `range-change` 查询范围；导航仍按原周/月跨度。跨隐藏日期的任务在可见日期上显示，持续时长不压缩；拖动使用目标格子的实际日期。更改隐藏配置会取消当前拖动预览。隐藏日期仍参与容量/冲突校验，表单和外部命令仍可排期；需要禁止预约请使用工作时间或禁用时段。

单日、资源日程和资源时间线目前保留原来的完整日期/时间轴。纯核心 `getSchedulerVisibleDays(range, hiddenDays)` 返回独立的可见日期数组，非法隐藏配置或范围会抛出 `RangeError`。

### 现在时间线

时间网格的日期头与全天行共同固定，纵向滚动时保持可见；今天的日期头高亮。启用 `show-now-indicator` 后，时间轴同时显示与红线对齐的当前时间文字，红线处于卡片上方。

Example source: src/scheduler/__demos__/now-indicator.vue

```vue
<template>
  <c-space direction="column" block>
    <c-alert
      >红线标出当前本地时间，每 30
      秒刷新。可以切换日、周和资源日程；日和资源日程查看明天时红线消失。标线不影响新建和拖动。</c-alert
    >
    <c-space wrap>
      <c-checkbox v-model="enabled">显示现在时间线</c-checkbox>
      <c-button @click="date = new Date()">查看今天</c-button>
      <c-button @click="date = addSchedulerDays(new Date(), 1)"
        >查看明天</c-button
      >
    </c-space>
    <c-scheduler
      key="now-indicator"
      v-model:date="date"
      :show-now-indicator="enabled"
      default-mode="resource-day"
      :modes="['day', 'week', 'resource-day']"
      :start-hour="0"
      :end-hour="24"
      :resources="resources"
    />
  </c-space>
</template>
<script setup lang="ts">
import { ref } from "vue";
import { addSchedulerDays } from "../core";
const date = ref(new Date());
const enabled = ref(true);
const resources = [
  { id: "a", label: "今日值班 A" },
  { id: "b", label: "今日值班 B" },
];
</script>
```

设置 `show-now-indicator` 在日、周和资源日程中显示当前本地时间标线，默认关闭。只在当天列且当前时间位于 `[start-hour, end-hour)` 内显示；资源日程中的当天资源列各显示一条。月、议程和资源时间线暂不显示。

标线每 30 秒刷新，浏览器标签页隐藏时暂停计时，返回时立即刷新；关闭功能、切换不支持的视图或卸载后停止计时。服务端渲染不读取实时钟、不启动计时器，客户端挂载后显示。标线不会拦截鼠标或触摸操作，提供“当前时间”的可访问名称，但不会持续播报。

纯核心 `getSchedulerNowPosition(now, day, startHour = 0, endHour = 24)` 返回本地时间在网格中的百分比；不在当天/时间范围或输入无效时返回 `undefined`。该函数不读取系统时间，与现有本地时间布局保持一致；不代表已实现任意 IANA 显示时区。

可通过 `--c-scheduler-now-color`、`--c-scheduler-now-width`、`--c-scheduler-now-z-index` 调整标线样式。

### 时间线缩放与资源分组

小时刻度显示定位日，天刻度显示一周。切换刻度保留定位日期，上一页/下一页跟随刻度按日或按周导航。资源分组仅影响时间线展示，不修改日程分配。

Example source: src/scheduler/__demos__/timeline-groups.vue

```vue
<template>
  <c-space direction="column" block>
    <c-alert
      >按部门折叠资源；切换小时刻度可查看定位日的精确排期。资源名称在横向滚动时保持可见。</c-alert
    >
    <c-scheduler
      v-model="events"
      v-model:scale="scale"
      v-model:expanded-keys="expanded"
      default-date="2026-09-09"
      default-mode="resource-timeline"
      :resources="resources"
      :resource-group-by="groupBy"
    />
  </c-space>
</template>
<script setup lang="ts">
import { ref } from "vue";
import type { SchedulerResource, SchedulerScale } from "../core";
import { createEvents, resources } from "./data";
const events = ref(createEvents());
const scale = ref<SchedulerScale>("hour");
const expanded = ref(["产品与设计", "研发"]);
const groupBy = (resource: SchedulerResource) =>
  resource.id === resources[0].id ? "产品与设计" : "研发";
</script>
```

| 属性                                  | 说明                                                      | 默认值   |
| ------------------------------------- | --------------------------------------------------------- | -------- |
| scale / default-scale                 | `hour` 或 `day`，支持 `v-model:scale`                     | `day`    |
| virtual-list-props                    | 资源时间线虚拟列表配置 `SchedulerVirtualListProps`        | —        |
| resource-group-dimensions             | 交叉分组维度顺序，资源时间线有效                          | []       |
| resource-group-by                     | `(resource: SchedulerResource) => string`，返回稳定分组键 | —        |
| expanded-keys / default-expanded-keys | 展开的分组键，支持 `v-model:expanded-keys`                | 全部展开 |

资源较多时可先折叠不关注的分组。小时刻度按真实经过小时构建，夏令时切换日可能有 23 或 25 个小时；表头带时区缩写用于辨别重复小时。当前运行环境时区仍决定显示日期。

### 重叠日程错位叠放

Example source: src/scheduler/__demos__/stacked-events.vue

```vue
<template>
  <c-space direction="column" block>
    <c-alert
      >重叠卡片按数量等分起点并延伸到最右侧。本例最多直接显示 3
      张，更多日程通过“还有 N
      项”Popover查看。Tab聚焦前置，失焦恢复；单击或Enter打开详情。</c-alert
    >
    <c-space>
      <c-button @click="layout = layout === 'stack' ? 'columns' : 'stack'">{{
        layout === "stack" ? "切换并排布局" : "切换叠放布局"
      }}</c-button>
      <c-checkbox v-model="readonly">只读查看</c-checkbox>
    </c-space>
    <c-scheduler
      v-model="events"
      default-date="2026-09-22"
      default-mode="week"
      :event-layout="layout"
      :overlap-event-limit="3"
      :readonly="readonly"
      selectable
      :show-sidebar="false"
      :start-hour="8"
      :end-hour="16"
    />
  </c-space>
</template>
<script setup lang="ts">
import { ref } from "vue";
import type { SchedulerEvent } from "../core";
const layout = ref<"stack" | "columns">("stack");
const readonly = ref(false);
const events = ref<SchedulerEvent[]>([
  {
    id: "a",
    title: "站点巡检",
    start: "2026-09-22T09:00:00",
    end: "2026-09-22T12:00:00",
  },
  {
    id: "b",
    title: "设备维护",
    start: "2026-09-22T09:30:00",
    end: "2026-09-22T11:30:00",
  },
  {
    id: "c",
    title: "人员培训",
    start: "2026-09-22T10:00:00",
    end: "2026-09-22T12:30:00",
  },
  {
    id: "e",
    title: "安全检查",
    start: "2026-09-22T09:15:00",
    end: "2026-09-22T11:00:00",
  },
  {
    id: "f",
    title: "临时工单",
    start: "2026-09-22T09:45:00",
    end: "2026-09-22T12:00:00",
  },
  {
    id: "d",
    title: "独立任务",
    start: "2026-09-23T13:00:00",
    end: "2026-09-23T14:00:00",
  },
]);
</script>
```

周视图默认使用 `event-layout="stack"`：重叠组按并发列数等分卡片起点，每张卡片延伸到该日期列的最右侧。例如 3 张同时重叠的日程，起点分别为 0%、33.33%、66.67%，宽度分别为 100%、66.67%、33.33%。单击前置并直接打开详情，Tab 聚焦同样前置，Enter 打开详情；焦点离开卡片后恢复原层级。非重叠日程仍单击打开，多选模式仍单击选择。

可通过 `event-layout="columns"` 恢复旧并排布局。日与资源日程默认并排，也可显式启用 stack；全天、月历、时间线布局不受影响。设置 `overlap-event-limit` 后，一个相连重叠组超过该数量时隐藏后续列并显示“还有 N 项”，点击 Popover 查看该组全部日程；省略时不收敛。选择 Popover 项继续触发正常详情，筛选、数据和冲突校验不受影响。

前置仅改变焦点层级，不修改数组、选中模型或事件时间。只读允许查看，disabled 阻止查看操作。布局方式与 `allow-overlap` 的业务冲突校验相互独立。

## 资源与任务分配

### 多人分配

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `default-date` | 初始定位日期 | 多人分配、交叉分组：站下展开人员、多资源维度：站与人 |
| `default-mode` | 非受控默认视图 | 多人分配、交叉分组：站下展开人员、多资源维度：站与人 |
| `resources` | 当前可见资源行/列及本地选项，不要求全量目录 | 多人分配、交叉分组：站下展开人员、多资源维度：站与人 |
| `resource-dimensions` | 维度定义 `{ id, label }[]` | 交叉分组：站下展开人员、多资源维度：站与人、独立任务分配 |
| `resource-filters` | 跨维度组合筛选，支持 v-model:resource-filters | 交叉分组：站下展开人员、多资源维度：站与人、大量资源与虚拟滚动 |
| `show-assignment-details` | 编辑资源占用量与角色 | 独立任务分配、占用量与资源负载 |
<!-- demo-config-notes:end -->

一条日程可关联多人。拖到另一人员列时只替换拖出列的人员，其他参与者保留；时间变更影响这条日程的所有参与者。需要每个人独立时间时，创建不同 id 的日程，在 `metadata.taskId` 中保存关联。

Example source: src/scheduler/__demos__/resources.vue

```vue
<template>
  <c-scheduler
    v-model="events"
    default-date="2026-09-09"
    default-mode="resource-day"
    :resources="resources"
    :start-hour="8"
    :end-hour="18"
  />
</template>
<script setup lang="ts">
import { ref } from "vue";
import { createEvents, resources } from "./data";
const events = ref(createEvents());
</script>
```

### 交叉分组：站下展开人员

Example source: src/scheduler/__demos__/resource-cross-groups.vue

```vue
<template>
  <c-space direction="column" block>
    <c-alert
      >按站展开人员，也可切换为按人展开站。联合验收在两个人员行显示，但数据只有一条；拖动会修改整条任务的时间和对应资源。点击空白行可创建同时关联站与人的任务。</c-alert
    >
    <c-space wrap>
      <c-button
        @click="
          filters = { station: ['station:north'], person: ['person:lin'] }
        "
        >北站 + 小林</c-button
      >
      <c-button
        @click="
          filters = {
            station: ['station:north', 'station:south'],
            person: ['person:chen'],
          }
        "
        >两站 + 小陈</c-button
      >
      <c-button @click="filters = {}">清空维度筛选</c-button>
      <c-button @click="groupDimensions = ['station', 'person']"
        >站 → 人</c-button
      >
      <c-button @click="groupDimensions = ['person', 'station']"
        >人 → 站</c-button
      >
      <c-tag>匹配 {{ matching.length }} / {{ events.length }} 条任务</c-tag>
    </c-space>
    <c-scheduler
      data-cross-groups-demo
      key="resource-cross-groups"
      v-model="events"
      v-model:resource-filters="filters"
      :resource-group-dimensions="groupDimensions"
      default-date="2026-09-22"
      default-mode="resource-timeline"
      default-scale="hour"
      :resources="resources"
      :resource-dimensions="dimensions"
      history
    />
  </c-space>
</template>
<script setup lang="ts">
import { computed, ref } from "vue";
import { filterSchedulerEventsByResources } from "../core";
import type {
  SchedulerEvent,
  SchedulerResource,
  SchedulerResourceFilters,
} from "../core";
const dimensions = [
  { id: "station", label: "站" },
  { id: "person", label: "人" },
];
const resources: SchedulerResource[] = [
  { id: "station:north", label: "北站", dimensionId: "station", capacity: 2 },
  { id: "station:south", label: "南站", dimensionId: "station", capacity: 2 },
  { id: "person:lin", label: "小林", dimensionId: "person", capacity: 1 },
  { id: "person:chen", label: "小陈", dimensionId: "person", capacity: 1 },
];
const filters = ref<SchedulerResourceFilters>({});
const groupDimensions = ref(["station", "person"]);
const events = ref<SchedulerEvent[]>([
  {
    id: "north-lin",
    title: "北站巡检",
    start: "2026-09-22T09:00:00",
    end: "2026-09-22T10:00:00",
    resourceIds: ["station:north", "person:lin"],
  },
  {
    id: "north-chen",
    title: "北站检修",
    start: "2026-09-22T10:00:00",
    end: "2026-09-22T11:00:00",
    resourceIds: ["station:north", "person:chen"],
  },
  {
    id: "south-lin",
    title: "南站巡检",
    start: "2026-09-22T11:00:00",
    end: "2026-09-22T12:00:00",
    resourceIds: ["station:south", "person:lin"],
  },
  {
    id: "south-chen",
    title: "南站检修",
    start: "2026-09-22T13:00:00",
    end: "2026-09-22T14:00:00",
    resourceIds: ["station:south", "person:chen"],
  },
  {
    id: "joint",
    title: "北站联合验收",
    start: "2026-09-22T14:00:00",
    end: "2026-09-22T15:00:00",
    resourceIds: ["station:north", "person:lin", "person:chen"],
  },
]);
const matching = computed(() =>
  filterSchedulerEventsByResources(events.value, resources, filters.value),
);
</script>
```

资源时间线设置 `:resource-group-dimensions="['station', 'person']"`，按站分组并在每站下面展示人员行；顺序反转后按人分组。支持两个以上维度，最后一个维度作为行，前面的资源路径作为分组。此设置优先于 `resource-group-by` 和 `resource-dimension`，其他视图继续使用原有单维度轴。

- 行是筛选后各维度资源的笛卡尔积，包含空排期组合，便于直接新建任务。缺少任一维度资源时没有组合行；不满足完整组合的任务可在日程列表或单维度视图中查看。
- 点击组合行自动填入各维度真实资源 ID。`cell-click` 提供 `resourceIds`，组合行的 `resourceId` 为 undefined；展示行键不会进入日程数据。
- 一个任务关联多人或多站时显示在全部匹配组合中，底层仍只有一条任务。拖动修改整条任务的时间，并将来源行的资源替换为目标行资源，其他参与者保留；调整时长不改变资源。它不表示把共享任务拆成独立分配关系。
- 所有资源的容量、工作时间和禁用状态共同约束操作，筛选隐藏的任务仍参与保存校验。空白格可用时间提示同时考虑各维度；容量在提交时校验。
- 复用 `expanded-keys` 控制折叠。分组键为父资源 ID 数组的 `JSON.stringify`，例如 `'["station:north"]'`，不依赖显示名称。`resource-header` 插槽的 `resource` 是末级真实资源，`resources` 为完整资源路径。
- 空数组默认关闭；重复、少于两个或未声明的维度配置回退到普通资源行。纯函数 `createSchedulerResourceRows(resources, dimensionIds)` 对少于两个、重复或空维度 ID 抛出 RangeError，并返回 `SchedulerResourceRow[]`；`moveSchedulerResourceRow(ids, from, to)` 只计算资源替换，可独立于 Vue 使用。

组合行可通过 `virtual-list-props` 开启虚拟滚动，不自动截断组合目录；极大目录应先通过维度筛选缩小范围。资源目录以传入的 `resources` 为准；远程选择结果需由业务合并到资源目录后才生成新行。

### 多资源维度：站与人

Example source: src/scheduler/__demos__/resource-dimensions.vue

```vue
<template>
  <c-space direction="column" block>
    <c-alert
      >一条任务同时关联站和人。左侧同一维度可多选，站与人之间组合筛选；上方“展示维度”切换资源行。打开任务详情可分别修改站和人，其他维度的关联会保留。</c-alert
    >
    <c-space wrap>
      <c-button
        @click="
          filters = { station: ['station:north'], person: ['person:lin'] }
        "
        >北站 + 小林</c-button
      >
      <c-button
        @click="
          filters = {
            station: ['station:north', 'station:south'],
            person: ['person:chen'],
          }
        "
        >两站 + 小陈</c-button
      >
      <c-button @click="filters = {}">清空维度筛选</c-button>
      <c-button @click="axis = 'station'">按站展示</c-button>
      <c-button @click="axis = 'person'">按人展示</c-button>
      <c-tag>匹配 {{ matching.length }} / {{ events.length }} 条任务</c-tag>
    </c-space>
    <c-scheduler
      data-dimensions-demo
      key="resource-dimensions"
      v-model="events"
      v-model:resource-filters="filters"
      v-model:resource-dimension="axis"
      default-date="2026-09-22"
      default-mode="resource-timeline"
      default-scale="hour"
      :resources="resources"
      :resource-dimensions="dimensions"
      history
    />
  </c-space>
</template>
<script setup lang="ts">
import { computed, ref } from "vue";
import { filterSchedulerEventsByResources } from "../core";
import type {
  SchedulerEvent,
  SchedulerResource,
  SchedulerResourceFilters,
} from "../core";
const dimensions = [
  { id: "station", label: "站" },
  { id: "person", label: "人" },
];
const resources: SchedulerResource[] = [
  { id: "station:north", label: "北站", dimensionId: "station", capacity: 2 },
  { id: "station:south", label: "南站", dimensionId: "station", capacity: 2 },
  { id: "person:lin", label: "小林", dimensionId: "person", capacity: 1 },
  { id: "person:chen", label: "小陈", dimensionId: "person", capacity: 1 },
];
const filters = ref<SchedulerResourceFilters>({
  station: ["station:north"],
  person: ["person:lin"],
});
const axis = ref("station");
const events = ref<SchedulerEvent[]>([
  {
    id: "north-lin",
    title: "北站巡检",
    start: "2026-09-22T09:00:00",
    end: "2026-09-22T10:00:00",
    resourceIds: ["station:north", "person:lin"],
  },
  {
    id: "north-chen",
    title: "北站检修",
    start: "2026-09-22T10:00:00",
    end: "2026-09-22T11:00:00",
    resourceIds: ["station:north", "person:chen"],
  },
  {
    id: "south-lin",
    title: "南站巡检",
    start: "2026-09-22T11:00:00",
    end: "2026-09-22T12:00:00",
    resourceIds: ["station:south", "person:lin"],
  },
  {
    id: "south-chen",
    title: "南站检修",
    start: "2026-09-22T13:00:00",
    end: "2026-09-22T14:00:00",
    resourceIds: ["station:south", "person:chen"],
  },
  {
    id: "joint",
    title: "北站联合验收",
    start: "2026-09-22T14:00:00",
    end: "2026-09-22T15:00:00",
    resourceIds: ["station:north", "person:lin", "person:chen"],
  },
]);
const matching = computed(() =>
  filterSchedulerEventsByResources(events.value, resources, filters.value),
);
</script>
```

通过 `resource-dimensions` 定义资源维度，例如 `[{ id: 'station', label: '站' }, { id: 'person', label: '人' }]`，每个资源使用 `dimensionId` 归属一个维度。维度 ID 应非空且唯一；资源 ID 必须在全部维度之间唯一，可使用 `station:north`、`person:lin` 这样的业务前缀。同一日程继续使用一份 `resourceIds`，可同时关联多个站、多个人，所有关联资源共同参与可用时间、容量和冲突校验。

```ts
const resources = [
  { id: "station:north", label: "北站", dimensionId: "station", capacity: 2 },
  { id: "person:lin", label: "小林", dimensionId: "person", capacity: 1 },
];
const event = {
  id: "inspection",
  title: "北站巡检",
  start: "2026-09-22T09:00:00",
  end: "2026-09-22T10:00:00",
  resourceIds: ["station:north", "person:lin"],
};
const resourceFilters = { station: ["station:north"], person: ["person:lin"] };
```

- **同维度“或”、跨维度“且”**：选多个站和多个人时，日程需匹配任一所选站，并匹配任一所选人。空数组或缺省维度不限制该维度；共享日程按 ID 保持一份数据。
- `v-model:resource-filters` 控制筛选，`default-resource-filters` 提供非受控初值；侧栏每个维度独立多选，更新一个维度保留其他维度。
- `v-model:resource-dimension` 决定资源日程/时间线的列或行，`default-resource-dimension` 提供初值，默认空字符串显示所有维度资源。切换展示维度不修改日程和其他筛选。
- 编辑器按维度选择。更新“人”保留原“站”及尚未解析的资源 ID；未归入已配置维度的现有关联显示在“其他资源”。筛选不会自动成为新日程的默认分配；从资源格新建只预填该格资源。
- 拖动到同维度另一资源，只替换对应资源，其他维度关联保持；跨维度资源间拖动被阻止。过滤不会减少事务校验数据：被筛掉的日程仍可导致人员冲突或容量不足。

纯核心工具：`filterSchedulerEventsByResources(events, resources, filters)` 返回匹配事件数组（事件对象保留原引用，不修改输入）；`setSchedulerResourceDimension(resourceIds, dimensionId, selectedIds, resources)` 返回替换一个维度后的独立 ID 数组，其他维度和未知 ID 保留，新选择的 ID 必须存在且归属该维度。

远程查询 `requestResources` 新增可选 `dimensionId`，每个维度独立查询/分页/取消；服务端应按维度查询并在返回资源上提供 `dimensionId`。客户端还会过滤不属于该维度的候选。`resolveResources` 仍按全局 ID 回显，返回维度后自动参与分组。未知资源在解析完成前不能满足维度筛选，不会被猜测归类；筛选键不会因暂时缺少目录记录而被隐式忽略。

未配置 `resource-dimensions` 时原有单组资源筛选和编辑继续工作。完整日程范围仍由原来的加载接口提供；这些筛选是本地展示条件，服务端保存仍应校验全部相关数据。

### 独立任务分配

Example source: src/scheduler/__demos__/independent-assignments.vue

```vue
<template>
  <c-space direction="column" block>
    <c-alert
      >同一业务任务有两个独立分配：北站小林 09:00–10:00、南站小陈
      13:00–15:00。它们共用
      metadata.taskId，各自拥有时间与占用量；修改一个分配不会移动另一个。</c-alert
    >
    <c-scheduler
      v-model="events"
      :resources="resources"
      :resource-dimensions="dimensions"
      :resource-group-dimensions="['station', 'person']"
      default-date="2026-09-22"
      default-mode="resource-timeline"
      default-scale="hour"
      show-assignment-details
      history
    />
  </c-space>
</template>
<script setup lang="ts">
import { ref } from "vue";
import { createSchedulerTaskEvents } from "./task-assignments";
const dimensions = [
  { id: "station", label: "站" },
  { id: "person", label: "人" },
];
const resources = [
  { id: "north", label: "北站", dimensionId: "station" },
  { id: "south", label: "南站", dimensionId: "station" },
  { id: "lin", label: "小林", dimensionId: "person", capacity: 1 },
  { id: "chen", label: "小陈", dimensionId: "person", capacity: 1 },
];
const events = ref(
  createSchedulerTaskEvents({ id: "inspection", title: "联合巡检" }, [
    {
      id: "north-lin",
      start: "2026-09-22T09:00:00",
      end: "2026-09-22T10:00:00",
      resourceIds: ["north", "lin"],
      resourceDetails: { lin: { units: 1, role: "负责" } },
    },
    {
      id: "south-chen",
      start: "2026-09-22T13:00:00",
      end: "2026-09-22T15:00:00",
      resourceIds: ["south", "chen"],
      resourceDetails: { chen: { units: 0.5, role: "负责" } },
    },
  ]),
);
</script>
```

Demo 内的 `createSchedulerTaskEvents(task, assignments)` 适配器将独立的站/人分配转换为共享 `metadata.taskId` 的不同日程块，各块可有不同时间、资源及占用量。分配 ID 在一个任务内唯一，生成事件 ID 为 `JSON.stringify([task.id, assignment.id])`。多个资源共享同一时间块时仍使用单个 Event；两种语义由业务明确选择，不自动拆分共享事件。

### 占用量与资源负载

Example source: src/scheduler/__demos__/assignment-load.vue

```vue
<template>
  <c-space direction="column" block>
    <c-alert
      >每条日程可配置资源占用量和角色。两条各占 0.5 的日程恰好占满容量
      1；尝试新增一条可验证阻止或提醒策略。详情中可直接修改分配信息，资源表头显示本日峰值负载。</c-alert
    >
    <c-space
      ><c-button @click="policy = {}">超载时阻止</c-button
      ><c-button @click="policy = { capacity: 'warn' }">超载时提醒</c-button
      ><c-button @click="add">新增 0.5 占用</c-button></c-space
    >
    <c-scheduler
      ref="scheduler"
      v-model="events"
      default-date="2026-09-22"
      default-mode="resource-timeline"
      default-scale="hour"
      :resources="resources"
      :rule-policy="policy"
      show-assignment-details
      show-resource-load
      history
    />
  </c-space>
</template>
<script setup lang="ts">
import { ref } from "vue";
import type { SchedulerInstance } from "../index";
import type { SchedulerEvent, SchedulerRulePolicy } from "../core";
const scheduler = ref<SchedulerInstance>();
const resources = [{ id: "device", label: "实验设备", capacity: 1 }];
const policy = ref<SchedulerRulePolicy>({});
let sequence = 2;
const events = ref<SchedulerEvent[]>(
  [0, 1].map((i) => ({
    id: `load${i}`,
    title: `任务 ${i + 1}`,
    start: "2026-09-22T09:00:00",
    end: "2026-09-22T10:00:00",
    resourceIds: ["device"],
    resourceDetails: { device: { units: 0.5, role: i ? "协作" : "负责" } },
  })),
);
function add() {
  const id = sequence++;
  return scheduler.value?.change({
    type: "create",
    event: { ...events.value[0], id: `load${id}`, title: `任务 ${id + 1}` },
  });
}
</script>
```

Event 新增 `resourceDetails?: Record<string, { units?: number; role?: string }>`，以 `resourceIds` 为唯一资源关联来源；详情仅补充已关联资源的占用量和角色。units 是有限非负数，省略为 1，支持 0.5；0 表示不占容量。未关联 ID 的详情不参与负载。复制深拷贝详情，同维度拖动携带来源详情，目标已关联时保留目标原详情。

`show-assignment-details` 在内置编辑器显示占用量和角色，`show-resource-load` 在资源时间线表头显示当前日期范围的峰值负载/容量、峰值占用条和范围利用率。利用率分母为完整可见范围的经过分钟数 × 容量，不仅限于工作时间；容量为零或未配置时不计算百分比。`getSchedulerResourceSummary` 同时返回 peakLoad、unitMinutes 与 utilization。峰值包含筛选隐藏的已加载日程，超载标红；服务端仍需检查未加载数据。

`rule-policy` 可分别配置 capacity、unavailable、conflict 为 `allow | warn | block`，默认 block。warn 在成功提交后显示警告并触发 `rule-warning`（SchedulerError[]）；allow 忽略该类规则。conflict 仍以 `allow-overlap=false` 为启用前提。无效配置、无效事件、只读、禁用资源和过期版本不能降级为提醒；保存钩子仍可否决。灰色背景始终表示可用时间约束，即使其提交策略为提醒。

### 大量资源与虚拟滚动

Example source: src/scheduler/__demos__/virtual-resources.vue

```vue
<template>
  <c-space direction="column" block>
    <c-alert
      >100 个站 × 20 位人员，共 2000
      个组合行。滚动时只挂载附近的行；点击空白格新建，或在当前可见行之间拖动任务。编辑后保留滚动位置；拖到边缘可自动滚动到其他组合行。</c-alert
    >
    <c-space wrap>
      <c-button @click="filters = {}">全部 2000 行</c-button>
      <c-button @click="filters = { station: ['s0', 's1', 's2'] }"
        >前 3 个站</c-button
      >
      <c-button @click="filters = { person: ['p0'] }">仅人员 001</c-button>
      <c-tag>{{ events.length }} 条日程</c-tag>
    </c-space>
    <c-scheduler
      key="virtual-resources"
      data-virtual-resources-demo
      v-model="events"
      v-model:resource-filters="filters"
      :resources="resources"
      :resource-dimensions="dimensions"
      :resource-group-dimensions="['station', 'person']"
      :virtual-list-props="{ height: 480, buffer: 10, estimatedSize: 80 }"
      default-date="2026-09-22"
      default-mode="resource-timeline"
      default-scale="hour"
      history
    />
  </c-space>
</template>
<script setup lang="ts">
import { ref } from "vue";
import type {
  SchedulerResource,
  SchedulerEvent,
  SchedulerResourceFilters,
} from "../core";
const dimensions = [
  { id: "station", label: "站" },
  { id: "person", label: "人" },
];
const resources: SchedulerResource[] = [
  ...Array.from({ length: 100 }, (_, i) => ({
    id: `s${i}`,
    label: `站点 ${String(i + 1).padStart(3, "0")}`,
    dimensionId: "station",
  })),
  ...Array.from({ length: 20 }, (_, i) => ({
    id: `p${i}`,
    label: `人员 ${String(i + 1).padStart(3, "0")}`,
    dimensionId: "person",
  })),
];
const filters = ref<SchedulerResourceFilters>({});
const events = ref<SchedulerEvent[]>(
  Array.from({ length: 100 }, (_, i) => ({
    id: `task${i}`,
    title: `巡检 ${String(i + 1).padStart(3, "0")}`,
    start: "2026-09-22T09:00:00",
    end: "2026-09-22T10:00:00",
    resourceIds: [`s${i}`, `p${i % 20}`],
  })),
);
</script>
```

设置 `:virtual-list-props="{ height: 480, estimatedSize: 80, buffer: 10 }"` 开启资源时间线虚拟滚动，配置命名与 Table、Select 一致。普通资源行和交叉分组均可使用；未配置时保持完整渲染。分组标题与资源行一起进入滚动窗口，顶部时间刻度跟随横向滚动。

| 配置          | 说明                                                       | 默认值                                       |
| ------------- | ---------------------------------------------------------- | -------------------------------------------- |
| height        | 视口高度，数字为 px，也支持 CSS 高度字符串                 | `var(--c-scheduler-virtual-height)`（480px） |
| estimatedSize | 未测量行的预估高度，正数 px；实际高度按内容测量            | 80                                           |
| buffer        | 预渲染窗口参数，正整数；内部列表最多挂载约 `buffer × 3` 项 | 10                                           |

行布局按需计算并缓存；滚动不改变事件数据或真实资源 ID。筛选、分组展开、日程内容或刻度变化后重置测量缓存，按原可见行键恢复行内偏移与横向位置；原行消失时回退到邻近有效行。更高的视口或更紧凑的行高应增大 `buffer`，确保窗口能够覆盖视口。

资源时间线指针手势由 Scheduler 持有，源卡片卸载后仍可继续；靠近容器边缘会自动滚动并重新计算目标。Escape、失焦、取消和卸载清理手势。虚拟滚动减少 DOM 和布局计算，组合资源目录仍在内存中生成；极大规模的笛卡尔积仍需先筛选或在业务侧限制目录范围。

边缘自动横滚会改变指针下的实际时间格，因此拖动时即使指针横坐标不变，也可能同时更改资源与开始时间；保存后可打开详情核对，或使用撤销/重做恢复。此资源时间线的紧凑卡片支持移动，不显示时间网格的起止拉伸手柄；调整时长可通过详情编辑。非首屏空白格新建使用实际组合行的资源，取消草稿不增加日程。

撤销/重做恢复的是日程数据，不会强制滚动到历史日程的位置。若恢复后的卡片不在当前视口内，先滚动使其可见，再点击查看详情；也可以聚焦日程按钮后使用 Enter 打开。

## 工作时间与容量

### 周期与指定日期可用时段

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `default-date` | 初始定位日期 | 周期与指定日期可用时段、维护禁用时段、资源并发容量 |
| `default-mode` | 非受控默认视图 | 周期与指定日期可用时段、维护禁用时段、资源并发容量 |
| `resources` | 当前可见资源行/列及本地选项，不要求全量目录 | 周期与指定日期可用时段、维护禁用时段、资源并发容量 |
| `resource-label` | 资源字段名称，如设备、会议室 | 周期与指定日期可用时段、维护禁用时段 |
| `allow-overlap` | 允许同资源时间重叠 | 周期与指定日期可用时段 |
<!-- demo-config-notes:end -->

对照工作日规则与指定日期覆盖；在允许和禁止的时段分别尝试创建或编辑任务，观察完整时长的校验边界。

<details>
<summary>配置说明与使用限制</summary>

#### 指定日期工作时间

`date-working-hours` 接受 `SchedulerDateWorkingHours[]`，每项包含本地日期 `date: "YYYY-MM-DD"`、`intervals: { startMinute, endMinute }[]` 和可选 `resourceIds`。分钟范围为 0–1440，结束必须晚于开始；可配置多个时段，空 `intervals` 关闭当天。

优先级为：资源指定日期 > 公共指定日期 > 资源每周规则 > 公共每周规则。指定日期替换当天的周规则，可开放原本关闭的补班日；未匹配的日期沿用每周规则。相同日期不能重复配置公共规则或同一资源，可将分段时段合并到一条规则。非法日期、分钟或重复作用域会使校验返回 `invalid-config`。

全天日程跳过小时限制；维护和企业日历产生的 `disabled-ranges` 始终有效。多人日程必须满足每个人的规则。规则切换不会自动修改已有任务，保存、拖动和跨日期编辑均按完整日程校验；异步保存期间规则变化会拒绝旧结果。

纯逻辑调用：`getSchedulerAvailabilityIssues(event, { workingHours, dateWorkingHours, disabledRanges })`，无需 Vue 或 DOM。

</details>

Example source: src/scheduler/__demos__/working-hours-comparison.vue

```vue
<script setup lang="ts">
import { ref } from "vue"
import type { SchedulerEvent } from "../core"
import type { SchedulerWorkingHours } from "../core"
import type { SchedulerDateWorkingHours } from "../core"
import { proxyRefs as demoProxyRefs } from 'vue'

const scene1 = demoProxyRefs((() => {

const rooms = [
  { id: "room-a", label: "会议室 A" },
  { id: "room-b", label: "会议室 B" },
];

const hours: SchedulerWorkingHours[] = [
  { daysOfWeek: [1, 2, 3, 4, 5], startMinute: 540, endMinute: 720 },
  { daysOfWeek: [1, 2, 3, 4, 5], startMinute: 780, endMinute: 1080 },
];

const events = ref<SchedulerEvent[]>([
  {
    id: "meeting",
    title: "产品评审",
    start: "2026-09-09T10:00:00",
    end: "2026-09-09T11:00:00",
    resourceIds: ["room-a"],
  },
]);
return { rooms, hours, events }
})())

const scene2 = demoProxyRefs((() => {

const enabled = ref(true);

const resources = [
  { id: "lin", label: "小林" },
  { id: "chen", label: "小陈" },
  { id: "device", label: "设备" },
];

const hours = [
  { daysOfWeek: [1, 2, 3, 4, 5], startMinute: 540, endMinute: 1080 },
];

const overrides: SchedulerDateWorkingHours[] = [
  { date: "2026-09-12", intervals: [{ startMinute: 540, endMinute: 720 }] },
  {
    date: "2026-09-12",
    resourceIds: ["lin"],
    intervals: [
      { startMinute: 600, endMinute: 720 },
      { startMinute: 780, endMinute: 900 },
    ],
  },
  { date: "2026-09-12", resourceIds: ["device"], intervals: [] },
  { date: "2026-09-30", intervals: [{ startMinute: 540, endMinute: 720 }] },
];

const events = ref<SchedulerEvent[]>([
  {
    id: "makeup",
    title: "补班协作任务",
    start: "2026-09-12T10:00:00",
    end: "2026-09-12T11:00:00",
    resourceIds: ["lin", "chen"],
  },
]);
return { enabled, resources, hours, overrides, events }
})())
</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="working-hours">
    <h4><span lang="zh-CN">工作时间与维护时段</span><span lang="en-US">working hours</span></h4>
    <c-space direction="column" block>
        <c-alert
          >会议室工作日 09:00–12:00、13:00–18:00
          可预约。灰色时段包含午休和非工作时间；新建、拖动和编辑均会校验完整时长。</c-alert
        >
        <c-scheduler
          v-model="scene1.events"
          default-date="2026-09-09"
          default-mode="resource-day"
          resource-label="会议室"
          :resources="scene1.rooms"
          :working-hours="scene1.hours"
          :allow-overlap="false"
        />
      </c-space>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="date-working-hours">
    <h4><span lang="zh-CN">指定日期工作时间</span><span lang="en-US">date working hours</span></h4>
    <c-space direction="column" block>
        <c-alert
          >模拟周六补班：公共时段 09:00–12:00；小林改为
          10:00–12:00、13:00–15:00；设备全天关闭。关闭开关后恢复周一至周五规则。已有任务保留，再次保存时重新校验。</c-alert
        >
        <c-checkbox v-model="scene2.enabled">启用指定日期时段</c-checkbox>
        <c-scheduler
          key="date-hours"
          v-model="scene2.events"
          default-date="2026-09-12"
          default-mode="resource-day"
          :resources="scene2.resources"
          :working-hours="scene2.hours"
          :date-working-hours="scene2.enabled ? scene2.overrides : []"
        />
      </c-space>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

### 维护禁用时段

Example source: src/scheduler/__demos__/maintenance.vue

```vue
<template>
  <c-space direction="column" block>
    <c-alert
      >设备 A 在 10:00–12:00 维护，设备 B
      不受影响。可关闭维护规则，对比可用时段及拖动保存结果。</c-alert
    >
    <c-checkbox v-model="maintenance">启用设备 A 维护时段</c-checkbox>
    <c-scheduler
      v-model="events"
      default-date="2026-09-09"
      default-mode="resource-timeline"
      default-scale="hour"
      resource-label="设备"
      :resources="equipment"
      :disabled-ranges="maintenance ? ranges : []"
    />
  </c-space>
</template>
<script setup lang="ts">
import { ref } from "vue";
import type { SchedulerEvent, SchedulerDisabledRange } from "../core";
const maintenance = ref(true);
const equipment = [
  { id: "a", label: "设备 A" },
  { id: "b", label: "设备 B" },
];
const ranges: SchedulerDisabledRange[] = [
  {
    id: "maintenance-a",
    start: "2026-09-09T10:00:00",
    end: "2026-09-09T12:00:00",
    resourceIds: ["a"],
    label: "设备 A 定期维护",
  },
];
const events = ref<SchedulerEvent[]>([
  {
    id: "inspection",
    title: "样品检测",
    start: "2026-09-09T09:00:00",
    end: "2026-09-09T10:00:00",
    resourceIds: ["a"],
  },
]);
</script>
```

| 属性               | 类型                          | 说明                                                   |
| ------------------ | ----------------------------- | ------------------------------------------------------ |
| date-working-hours | `SchedulerDateWorkingHours[]` | 指定日期时段覆盖，默认 `[]`；详见上文优先级            |
| working-hours      | `SchedulerWorkingHours[]`     | 未传不限制，空数组禁止定时日程；按运行环境本地周历解释 |
| disabled-ranges    | `SchedulerDisabledRange[]`    | 维护、停用等绝对时间区间，默认空数组                   |

```ts
import type {
  SchedulerWorkingHours,
  SchedulerDisabledRange,
} from "@cedar-design/ui";
const workingHours: SchedulerWorkingHours[] = [
  { daysOfWeek: [1, 2, 3, 4, 5], startMinute: 540, endMinute: 720 },
  { daysOfWeek: [1, 2, 3, 4, 5], startMinute: 780, endMinute: 1080 },
];
const disabledRanges: SchedulerDisabledRange[] = [
  {
    id: "maintenance",
    start: "2026-09-09T10:00:00",
    end: "2026-09-09T12:00:00",
    resourceIds: ["equipment-a"],
    label: "定期维护",
  },
];
```

工作时间的起止分钟为当天 0–1440，结束必须晚于开始；跨午夜请拆成两天配置。多个窗口取并集，可以表达午休。存在某资源专用工作窗口时，该资源使用专用周计划覆盖全局周计划；没有适用规则的资源不受限制。多人共享日程必须同时满足每个资源的规则。

禁用区间采用 `[start, end)`，首尾相接不冲突。未指定或空 `resourceIds` 表示全局。全天日程作为日期事项不校验工作小时，但仍校验维护区间。未排期任务和删除不受可用时间规则限制。现有数据仍正常展示，更新时重新校验。

日/周时间网格及小时资源时间线以灰色标记含不可用部分的单元格，可悬停查看提示。格子仍能打开编辑器以调整时间；日/月汇总格不表达整天可用性。规则失败触发 `change-error`，错误码为 `unavailable`；错误的 `issues` 给出资源 ID、维护区间 ID、标签或 `invalid-config`。校验先于 `before-change`，失败不会调用保存钩子。异步等待期间规则变化会以 `stale` 拒绝旧提案。

纯核心入口导出 `getSchedulerAvailabilityIssues(event, options)`，应用可在预检查或服务端复用。时区采用当前运行环境，前后端必须统一日期语义；数据库仍应原子校验实际资源占用。

### 资源并发容量

时间线示例可把容量降至1后，将样品甲移出与样品乙的重叠时段，再拖入冲突区观察容量拒绝；拒绝保留原排期，下一次合法移动仍可保存。结束恰等于另一项开始的相邻区间不重叠。当前资源时间线卡片没有拉伸手柄，不能把移动路径当作水平拉伸验收；持按取消、触屏和其他视图需分别验证。

Example source: src/scheduler/__demos__/resource-capacity.vue

```vue
<template>
  <c-space direction="column" block>
    <c-alert
      >检测设备默认可并行处理 2 个任务。09:00–11:00 与 10:00–12:00 的两单已占满
      10:00–11:00；尝试追加第三单，或提高容量后重试。降低容量保留已有日程，并在下方标出超额时段。</c-alert
    >
    <c-space wrap>
      <c-button @click="capacity = 1">容量设为 1</c-button>
      <c-button @click="capacity = 2">容量设为 2</c-button>
      <c-button @click="capacity = 3">容量设为 3</c-button>
      <c-button status="primary" @click="addThird">尝试追加第三单</c-button>
      <c-button @click="reset">重置容量示例</c-button>
      <c-tag>当前容量：{{ capacity }}</c-tag>
      <c-tag v-if="result">{{ result }}</c-tag>
    </c-space>
    <c-space direction="column" block>
      <c-tag
        v-for="span in load"
        :key="+span.start"
        :status="span.exceeded ? 'danger' : 'success'"
      >
        {{ format(span.start) }}–{{ format(span.end) }}：{{ span.load }}/{{
          span.capacity
        }}
        {{ span.exceeded ? "超出容量" : "容量内" }}
      </c-tag>
      <c-tag v-if="!load.length">当前可见范围没有占用</c-tag>
    </c-space>
    <c-scheduler
      key="resource-capacity"
      ref="scheduler"
      v-model="events"
      default-date="2026-09-15"
      default-mode="resource-timeline"
      default-scale="hour"
      :resources="resources"
      history
      @range-change="range = $event"
    >
      <template #resource-header="{ resource }">
        <c-space
          ><span>{{ resource?.label }}</span
          ><c-tag>容量 {{ resource?.capacity }}</c-tag></c-space
        >
      </template>
    </c-scheduler>
  </c-space>
</template>
<script setup lang="ts">
import { computed, ref } from "vue";
import type { SchedulerInstance } from "../index";
import type { SchedulerEvent } from "../core";
import {
  getSchedulerResourceLoad,
  getSchedulerRange,
  schedulerDateKey,
} from "../core";
const scheduler = ref<SchedulerInstance>();
const capacity = ref(2);
const resources = computed(() => [
  { id: "lab", label: "检测设备", capacity: capacity.value },
]);
const initial: SchedulerEvent[] = [
  {
    id: "sample-a",
    title: "样品甲",
    start: "2026-09-15T09:00:00",
    end: "2026-09-15T11:00:00",
    resourceIds: ["lab"],
  },
  {
    id: "sample-b",
    title: "样品乙",
    start: "2026-09-15T10:00:00",
    end: "2026-09-15T12:00:00",
    resourceIds: ["lab"],
  },
];
const events = ref<SchedulerEvent[]>([...initial]);
const range = ref(getSchedulerRange("2026-09-15", "day"));
const load = computed(() =>
  getSchedulerResourceLoad(events.value, resources.value[0], range.value),
);
const result = ref("");
const format = (date: Date) =>
  `${schedulerDateKey(date)} ${String(date.getHours()).padStart(2, "0")}:${String(date.getMinutes()).padStart(2, "0")}`;
async function addThird() {
  if (events.value.some((event) => event.id === "sample-c")) {
    result.value = "第三单已存在，可撤销或重置后重试";
    return;
  }
  const saved = await scheduler.value?.change({
    type: "create",
    event: {
      id: "sample-c",
      title: "样品丙",
      start: "2026-09-15T10:30:00",
      end: "2026-09-15T11:00:00",
      resourceIds: ["lab"],
    },
  });
  result.value = saved ? "第三单已保存" : "第三单未保存：超出容量";
}
function reset() {
  events.value = [...initial];
  capacity.value = 2;
  result.value = "";
  scheduler.value?.goToDate(new Date(2026, 8, 15));
}
</script>
```

资源可设置 `capacity`，表示非负安全整数的并发日程上限；省略表示不限制，`0` 表示不能安排定时或全天日程。每条已排期日程对每个关联资源默认占用 1 份，可通过 resourceDetails.units 调整，重复的资源 ID 只计一次；未排期任务不占容量。相邻的 `[start, end)` 日程不重叠。多人任务需同时满足所有关联资源的容量。

默认允许重叠时，显式容量仍生效；`allow-overlap="false"` 更严格，继续禁止任何资源冲突。维护和工作时间校验也继续生效。新建、编辑、拖动、批量事务、撤销重做均校验最终排期；超额返回 `SchedulerError.code === 'capacity'`，`capacityIssues` 提供 `resourceId/start/end/load/capacity/eventIds/exceeded`。纯删除允许释放容量，外部降低容量不会自动修改已有日程。

- `getSchedulerResourceLoad(events, resource, range?)` 返回有占用的分段负载，`range` 可裁剪统计范围；同一时段事件集合变化时分段，未配置容量的资源也可统计。
- `getSchedulerCapacityIssues(event, events, resources)` 按 ID 替换候选日程，只检查候选时间和关联资源，返回超额时段。两项工具均可从 `@cedar-design/ui/scheduler/core` 导入，无 Vue/DOM 依赖。

容量使用已知资源目录（包括远程回显）和当前已加载日程。未知资源无法推断容量，未加载日程也不会被计入；服务端应在保存事务中校验完整数据和并发版本。`resourceDetails` 补充占用量，`resourceIds` 仍是唯一分配来源。网格的灰色时段仍表示工作时间/维护，负载由纯工具输出，可通过资源表头插槽和 Cedar 组件展示。

## 重复日程与日历

### 重复日程与本次例外

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `default-mode` | 非受控默认视图 | 重复日程与本次例外、每月、每年重复、企业休假与补班日历 |
| `default-date` | 初始定位日期 | 重复日程与本次例外、企业休假与补班日历、修改本次及以后 |
| `model-value` | 日程数据，支持 v-model；传入时受控 | 每月、每年重复、修改本次及以后、RRULE、时区与夏令时 |
| `readonly` | 可查看和导航，不能修改 | 每月、每年重复、修改本次及以后、RRULE、时区与夏令时 |
| `resources` | 当前可见资源行/列及本地选项，不要求全量目录 | 重复日程与本次例外 |
| `date` | 定位日期，支持 v-model:date | 每月、每年重复 |
<!-- demo-config-notes:end -->

Example source: src/scheduler/__demos__/recurring-events.vue

```vue
<template>
  <c-space direction="column" block>
    <c-alert
      >重复会议按可见范围展开。编辑、拖动或删除卡片只影响这一次；新建日程是独立安排。修改上方规则会重建系列并清除本例中的例外。</c-alert
    >
    <c-space wrap>
      <c-select
        v-model="frequency"
        :options="frequencies"
        aria-label="重复频率"
      />
      <c-input-number
        v-model="interval"
        :min="1"
        :max="12"
        aria-label="重复间隔"
      />
      <c-tag>{{
        frequency === "daily" ? "天一次" : "周一次（周一、三、五）"
      }}</c-tag>
      <c-input-number
        v-model="count"
        :min="1"
        :max="60"
        aria-label="重复次数"
      />
      <c-tag>次后结束</c-tag>
      <c-button :disabled="!exceptions.length" @click="exceptions = []"
        >恢复全部例外</c-button
      >
    </c-space>
    <c-tag
      >{{ exceptions.length }} 条本次例外 ·
      {{ standalone.length }} 条独立安排</c-tag
    >
    <c-scheduler
      v-model="events"
      default-date="2026-09-09"
      default-mode="week"
      :resources="resources"
      :before-transaction="validateChange"
      @range-change="range = $event"
    >
      <template #event="{ event }">
        {{ event.title }}
        <c-tag v-if="occurrenceIds.has(event.id)" size="small"
          >重复 · 仅本次</c-tag
        >
      </template>
    </c-scheduler>
  </c-space>
</template>
<script setup lang="ts">
import { computed, ref, watch } from "vue";
import {
  SchedulerError,
  applySchedulerChange,
  diffSchedulerEvents,
  expandSchedulerRecurrences,
  getSchedulerRange,
  setSchedulerRecurrenceException,
} from "../core";
import type {
  SchedulerEvent,
  SchedulerRecurrenceException,
  SchedulerRecurrenceRule,
  SchedulerRecurringEvent,
} from "../core";
import type { SchedulerBeforeTransaction } from "../props";
const validateChange: SchedulerBeforeTransaction = ({ changes }) => {
  if (
    changes.some(
      (change) =>
        occurrenceIds.value.has(change.event.id) &&
        change.type !== "remove" &&
        change.event.start == null,
    )
  ) {
    throw new SchedulerError(
      "invalid-event",
      "重复实例必须保留排期；取消本次请使用删除",
    );
  }
};
const frequencies = [
  { label: "每天", value: "daily" },
  { label: "每周", value: "weekly" },
];
const frequency = ref<SchedulerRecurrenceRule["frequency"]>("weekly");
const interval = ref(1);
const count = ref(12);
const range = ref(getSchedulerRange("2026-09-09", "week"));
const resources = [
  { id: "design", label: "林夏 · 设计" },
  { id: "dev", label: "陈舟 · 前端" },
];
const exceptions = ref<SchedulerRecurrenceException[]>([]);
const standalone = ref<SchedulerEvent[]>([]);
const series = computed<SchedulerRecurringEvent[]>(() => [
  {
    event: {
      id: "weekly-review",
      title: "项目同步会",
      start: "2026-09-07T09:00:00",
      end: "2026-09-07T10:00:00",
      resourceIds: ["design", "dev"],
    },
    rule: {
      frequency: frequency.value,
      interval: interval.value || 1,
      count: count.value || 1,
      daysOfWeek: frequency.value === "weekly" ? [1, 3, 5] : undefined,
    },
  },
]);
watch([frequency, interval, count], () => {
  exceptions.value = [];
});
const occurrences = computed(() =>
  expandSchedulerRecurrences(series.value, range.value, {
    exceptions: exceptions.value,
  }),
);
const occurrenceIds = computed(
  () => new Set(occurrences.value.map((event) => event.id)),
);
const events = computed<SchedulerEvent[]>({
  get: () => [...occurrences.value, ...standalone.value],
  set: (next) => {
    const previous = [...occurrences.value, ...standalone.value];
    const originals = new Map(
      occurrences.value.map((event) => [event.id, event]),
    );
    let nextExceptions = exceptions.value;
    let nextStandalone = standalone.value;
    for (const change of diffSchedulerEvents(previous, next)) {
      const original = originals.get(change.event.id);
      if (original)
        nextExceptions = setSchedulerRecurrenceException(
          nextExceptions,
          original,
          change.type === "remove" ? undefined : change.event,
        );
      else nextStandalone = applySchedulerChange(nextStandalone, change);
    }
    // A real backend saves these series/exception records atomically, not expanded instances.
    exceptions.value = nextExceptions;
    standalone.value = nextStandalone;
  },
});
</script>
```

系列与例外由业务保存，`expandSchedulerRecurrences` 按可见范围生成普通日程，传给现有 `v-model`。本例将编辑、拖动、拉伸和删除映射为“仅本次”的例外，新建仍是独立日程。“恢复全部例外”会撤销本例中的本次修改与取消；调整规则会清除本例的例外，不代表库替业务迁移系列。

```ts
import {
  expandSchedulerRecurrences,
  setSchedulerRecurrenceException,
} from "@cedar-design/ui/scheduler/core";
import type {
  SchedulerRecurringEvent,
  SchedulerRecurrenceException,
} from "@cedar-design/ui/scheduler/core";

const series: SchedulerRecurringEvent[] = [
  {
    event: {
      id: "sync",
      title: "项目同步",
      start: "2026-09-07T09:00:00",
      end: "2026-09-07T10:00:00",
    },
    rule: {
      frequency: "weekly",
      interval: 1,
      daysOfWeek: [1, 3, 5],
      count: 12,
    },
  },
];
let exceptions: SchedulerRecurrenceException[] = [];
const occurrences = expandSchedulerRecurrences(
  series,
  {
    start: new Date("2026-09-07T00:00:00"),
    end: new Date("2026-09-14T00:00:00"),
  },
  { exceptions },
);
// 保存完整的替换日程；省略第三个参数表示取消本次。
exceptions = setSchedulerRecurrenceException(exceptions, occurrences[0], {
  ...occurrences[0],
  title: "仅修改本次标题",
});
```

| 类型 / 方法                                                           | 说明                                                                                                                            |
| --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| SchedulerRecurringEvent                                               | `{ event, rule }`；event 为已排期的系列起点，id 是系列唯一标识                                                                  |
| SchedulerRecurrenceRule                                               | frequency 为 daily / weekly / monthly / yearly；interval 默认 1；weekly 的 daysOfWeek 默认起点星期，0 表示周日；一周从周一开始  |
| count / until                                                         | count 为原规则总发生次数（取消仍占次数）；until 为包含的最晚开始时间；同时配置则先到者结束                                      |
| SchedulerOccurrence                                                   | 普通日程加 seriesId、originalStart（全天为日期字符串，定时为 ISO 时间点字符串）；生成的 id 是不透明实例标识，不应解析或自行拼接 |
| SchedulerRecurrenceException                                          | `{ seriesId, originalStart, event? }`；event 省略表示取消；提供时必须保持排期                                                   |
| expandSchedulerRecurrences(series, range, options?)                   | 返回与范围相交的完整实例，按开始时间排序；options 可传 exceptions、maxOccurrences（默认 10000）、maxIterations（默认 100000）   |
| setSchedulerRecurrenceException(exceptions, occurrence, replacement?) | 不修改输入，返回替换该实例例外后的新数组                                                                                        |

开始日期只作为下界：每周所选星期不含起点星期时，第一次是之后的第一个匹配日。count 不会因为翻页或取消重新计数。until 表示时间点；日期字符串代表当地零点，定时会议若要包含当天需传入相应开始时刻。

全天系列保留日期字符串与日历天数；定时系列在运行环境本地日历上重复，保持原始时分及实际经过时长。夏令时不存在的时刻遵循 JavaScript Date 的归一化，随后日期恢复起点时分。本轮不支持任意 IANA 时区或完整 RRULE；前后端须统一时区，不能依赖实例 ID 跨时区不变。

例外始终引用原始发生时间，移动后仍可继续修改同一次。移出当前窗口的实例不再显示，移入窗口的例外正常出现。孤立例外或已不属于当前规则的发生时间不会生成实例；修改系列规则时，业务须明确保留、迁移或清理策略。

展开函数遇到非法规则、重复标识或计算/数量上限会抛错，不返回截断数据。上限针对一次展开调用的全部系列；长期系列会从起点扫描，较大数据建议由服务端按范围展开，并配合上方远程加载器处理错误。

本例不启用本地撤销历史；恢复例外是系列层操作。接入后端时由 `before-transaction` 原子保存系列/例外变更，再接受 `v-model` 提案。“本次及以后”拆分见下方示例；全系列冲突检查、专用整系列编辑尚未提供，当前窗口的冲突检查不能代替全系列校验。

### 每月、每年重复

Example source: src/scheduler/__demos__/calendar-recurrence.vue

```vue
<template>
  <c-space direction="column" block>
    <c-alert
      >按月、按年安排任务。无效日期可选择跳过或落到月底；“最后一个工作日”仅按周一至周五计算，不包含节假日调休。</c-alert
    >
    <c-space direction="column" align="stretch" wrap>
      <c-form-item layout="vertical" size="sm" label="月年重复规则">
        <c-radio-group
          v-model="preset"
          aria-label="月年重复规则"
          :options="presets"
          variant="button"
          size="sm"
        />
      </c-form-item>
      <c-input-number
        v-model="interval"
        :min="1"
        :max="12"
        aria-label="月年重复间隔"
      />
      <c-tag>{{ preset === "leap" ? "年一次" : "个月一次" }}</c-tag>
      <c-input-number
        v-model="count"
        :min="1"
        :max="10"
        aria-label="月年重复次数"
      />
      <c-tag>次后结束</c-tag>
      <c-checkbox
        v-if="preset === 'day31' || preset === 'leap'"
        v-model="lastDay"
        >缺少该日期时落到月底</c-checkbox
      >
    </c-space>
    <c-tag>未来 40 年内的前 {{ preview.length }} 次安排（点日期定位）</c-tag>
    <c-space wrap>
      <c-button
        v-for="item in preview"
        :key="item.id"
        @click="date = schedulerDate(item.start!)"
        >{{ schedulerDateKey(item.start!) }}</c-button
      >
    </c-space>
    <c-scheduler
      key="calendar-recurrence-preview"
      v-model:date="date"
      :model-value="events"
      default-mode="month"
      readonly
      @range-change="range = $event"
    />
  </c-space>
</template>
<script setup lang="ts">
import { computed, ref, watch } from "vue";
import {
  expandSchedulerRecurrences,
  getSchedulerRange,
  schedulerDate,
  schedulerDateKey,
} from "../core";
import type { SchedulerDate, SchedulerRecurringEvent } from "../core";
const preset = ref("day31");
const interval = ref(1);
const count = ref(6);
const lastDay = ref(false);
const presets = [
  { label: "每月 31 日", value: "day31" },
  { label: "每月最后一个工作日", value: "weekday" },
  { label: "每月第二个星期一", value: "monday" },
  { label: "每年 2 月 29 日", value: "leap" },
];
const date = ref<SchedulerDate>("2026-01-31");
const range = ref(getSchedulerRange(date.value, "month"));
watch(preset, () => {
  date.value = preset.value === "leap" ? "2024-02-29" : "2026-01-01";
});
const series = computed<SchedulerRecurringEvent[]>(() => {
  const start =
    preset.value === "leap"
      ? "2024-02-29"
      : preset.value === "day31"
        ? "2026-01-31"
        : "2026-01-01";
  return [
    {
      event: {
        id: "calendar-plan",
        title: presets.find((item) => item.value === preset.value)!.label,
        start: `${start}T09:00:00`,
        end: `${start}T10:00:00`,
      },
      rule: {
        frequency: preset.value === "leap" ? "yearly" : "monthly",
        interval: interval.value || 1,
        count: count.value || 1,
        ...(preset.value === "weekday"
          ? { weekOfMonth: -1, daysOfWeek: [1, 2, 3, 4, 5] }
          : preset.value === "monday"
            ? { weekOfMonth: 2, daysOfWeek: [1] }
            : {
                overflow: lastDay.value
                  ? ("last-day" as const)
                  : ("skip" as const),
              }),
      },
    },
  ];
});
const events = computed(() =>
  expandSchedulerRecurrences(series.value, range.value),
);
const preview = computed(() => {
  const start = schedulerDate(series.value[0].event.start!);
  const end = new Date(start);
  end.setFullYear(end.getFullYear() + 40);
  return expandSchedulerRecurrences(series.value, { start, end }).slice(0, 10);
});
</script>
```

月/年规则继续使用 `SchedulerRecurrenceRule`，共享单次例外、次数、截止时间及“本次及以后”拆分。

| 字段        | 说明                                                                                             |
| ----------- | ------------------------------------------------------------------------------------------------ |
| frequency   | monthly / yearly；interval 分别按起点月份 / 年份计数                                             |
| dayOfMonth  | 1–31，或 -1 表示最后一天；默认起点日期                                                           |
| weekOfMonth | 1–5 或 -1（最后一个）；从当月符合 daysOfWeek 的日期集合中选择第几个匹配日                        |
| daysOfWeek  | 月/年规则须搭配 weekOfMonth；默认起点星期；0 周日到 6 周六                                       |
| monthOfYear | 仅 yearly，1–12；默认起点月份                                                                    |
| overflow    | skip（默认）跳过不存在的日期，last-day 落到月底；只用于数字日期规则，不能与 weekOfMonth 同时使用 |

```ts
import type { SchedulerRecurrenceRule } from "@cedar-design/ui/scheduler/core";

const rules = [
  { frequency: "monthly", dayOfMonth: 31, overflow: "skip" },
  { frequency: "monthly", dayOfMonth: -1 },
  { frequency: "monthly", weekOfMonth: -1, daysOfWeek: [1, 2, 3, 4, 5] },
  { frequency: "monthly", weekOfMonth: 2, daysOfWeek: [1] },
  { frequency: "yearly", monthOfYear: 2, dayOfMonth: 29, overflow: "last-day" },
] satisfies SchedulerRecurrenceRule[];
```

每月 31 日默认跳过二月、四月等月份；落到月底时，之后有 31 日的月份会恢复到 31 日。每年 2 月 29 日同理，遵循公历闰年规则。第五个星期一不存在时直接跳过；被跳过的日期不消耗 count，取消例外仍消耗原次数。

`weekOfMonth` 选择的是整个星期集合中的第 N 个匹配日：`daysOfWeek: [1]` 配合 2 是第二个星期一；`[1,2,3,4,5]` 配合 -1 是最后一个周一至周五日期。后者不包含法定节假日、调休或企业工作日历。数字日期和星期顺序规则不能混用。

展开只从系列起点开始，不补出起点之前的匹配日。分拆继承规则时会固化原始月日/星期默认值，避免从二月 28 日拆分后把“31 日落到月底”改成“每月 28 日”。仍使用运行环境本地时区与计算上限，不承诺完整 RRULE 或任意 IANA 时区。

### 企业休假与补班日历

Example source: src/scheduler/__demos__/business-calendar.vue

```vue
<template>
  <c-space direction="column" block>
    <c-alert
      >以下日期均为模拟企业日历，不是官方放假通知。示例包含模拟春节休假、周末补班和月末企业休假；同一配置用于月末工作日计算和预约校验。</c-alert
    >
    <c-checkbox v-model="enabled">启用模拟休假与补班</c-checkbox>
    <c-space wrap
      ><c-tag v-for="item in settlements" :key="item.id"
        >结算日：{{ schedulerDateKey(item.start!) }}</c-tag
      ></c-space
    >
    <c-tag
      >2 月 27 日企业休假、28
      日周六补班。可尝试新增或移动任务，对比开关前后的保存结果。</c-tag
    >
    <c-scheduler
      key="business-calendar-bookings"
      v-model="bookings"
      default-date="2026-02-26"
      default-mode="week"
      :working-hours="hours"
      :disabled-ranges="blocked"
      :before-transaction="validateCalendar"
      @range-change="range = $event"
    />
  </c-space>
</template>
<script setup lang="ts">
import { computed, ref } from "vue";
import {
  expandSchedulerRecurrences,
  getSchedulerAvailabilityIssues,
  getSchedulerRange,
  schedulerDate,
  schedulerDateKey,
  SchedulerError,
} from "../core";
import { getSchedulerCalendarDisabledRanges } from "../core/business-calendar";
import type { SchedulerBusinessCalendar, SchedulerEvent } from "../core";
import type { SchedulerBeforeTransaction } from "../props";
const enabled = ref(true);
const range = ref(getSchedulerRange("2026-02-26", "week"));
const overrides: NonNullable<SchedulerBusinessCalendar["overrides"]> = [
  ...[16, 17, 18, 19, 20].map((day) => ({
    date: `2026-02-${day}`,
    working: false,
    label: "模拟春节休假",
  })),
  { date: "2026-02-14", working: true, label: "模拟补班" },
  { date: "2026-02-27", working: false, label: "企业休假" },
  { date: "2026-02-28", working: true, label: "模拟补班" },
];
const calendar = computed<SchedulerBusinessCalendar>(() => ({
  overrides: enabled.value ? overrides : [],
}));
// Calendar decides which dates work; hours separately decide when those dates work.
const hours = [
  { daysOfWeek: [0, 1, 2, 3, 4, 5, 6], startMinute: 540, endMinute: 1080 },
];
const blocked = computed(() =>
  getSchedulerCalendarDisabledRanges(calendar.value, range.value),
);
const bookings = ref<SchedulerEvent[]>([
  {
    id: "regular-job",
    title: "常规工作日任务",
    start: "2026-02-26T10:00:00",
    end: "2026-02-26T11:00:00",
  },
]);
const settlements = computed(() =>
  expandSchedulerRecurrences(
    [
      {
        event: {
          id: "settlement",
          title: "月末结算",
          start: "2026-02-01T09:00:00",
          end: "2026-02-01T10:00:00",
        },
        rule: {
          frequency: "monthly",
          weekOfMonth: -1,
          businessCalendar: calendar.value,
          count: 3,
        },
      },
    ],
    { start: new Date(2026, 1, 1), end: new Date(2026, 4, 1) },
  ),
);
const validateCalendar: SchedulerBeforeTransaction = ({ changes }) => {
  for (const change of changes) {
    if (
      change.type === "remove" ||
      change.event.start == null ||
      change.event.end == null
    )
      continue;
    // Editor changes can extend outside the visible window: validate the full proposal.
    const disabledRanges = getSchedulerCalendarDisabledRanges(calendar.value, {
      start: schedulerDate(change.event.start),
      end: schedulerDate(change.event.end),
    });
    const issues = getSchedulerAvailabilityIssues(change.event, {
      disabledRanges,
    });
    if (issues.length)
      throw new SchedulerError("unavailable", "日程包含非工作日", issues);
  }
};
</script>
```

`SchedulerBusinessCalendar` 共用“常规工作星期 + 指定日期覆盖”的数据模型；不内置官方节假日。上方纯星期示例继续保持原语义，需要企业日历时显式传入 businessCalendar。

```ts
import {
  isSchedulerWorkingDate,
  getSchedulerCalendarDisabledRanges,
} from "@cedar-design/ui/scheduler/core";
import type {
  SchedulerBusinessCalendar,
  SchedulerRecurrenceRule,
} from "@cedar-design/ui/scheduler/core";

const businessCalendar: SchedulerBusinessCalendar = {
  workingDays: [1, 2, 3, 4, 5],
  overrides: [
    { date: "2026-02-27", working: false, label: "模拟企业休假" },
    { date: "2026-02-28", working: true, label: "模拟补班" },
  ],
};
const rule: SchedulerRecurrenceRule = {
  frequency: "monthly",
  weekOfMonth: -1,
  businessCalendar,
};
isSchedulerWorkingDate("2026-02-28", businessCalendar); // true
```

| API / 字段                                                    | 说明                                                                                                   |
| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| workingDays                                                   | 0 周日至 6 周六，默认周一至周五；空数组表示没有常规工作日                                              |
| overrides                                                     | `{ date: 'YYYY-MM-DD', working: boolean, label?: string }[]`；指定日期优先于星期，重复或非法日期会抛错 |
| rule.businessCalendar                                         | 仅 monthly / yearly 搭配 weekOfMonth；按实际工作日选择第 N 个或最后一个，不能同时传 daysOfWeek         |
| isSchedulerWorkingDate(date, calendar)                        | 查询指定本地日期是否工作                                                                               |
| getSchedulerCalendarDisabledRanges(calendar, range, maxDays?) | 把范围内的非工作日期转换为现有 disabledRanges；默认最多扫描 3660 天，超出抛错                          |

日期范围遵循 `[start, end)`，输出是相交的完整非工作日区间，不裁剪日期两端。将结果绑定 `disabled-ranges` 后，原有拖动、编辑、批量操作会复用可用时间校验。多日任务中的任意休息日也会被拦截。

工作日期和每日小时分别约束：补班日不会自动覆盖 `working-hours` 中禁止周末的配置。本例把每日 09:00–18:00 应用到全部星期，再由工作日历决定哪些日期开放。额外的维护禁用区间仍然有效，补班不解除维护。现有预约不会因切换日历而自动移动或删除，再次编辑时重新校验。

可见范围生成的禁用区间只保证该范围；demo 还在 `before-transaction` 中为提案完整时间段生成区间，避免编辑至视图外漏校验。生产接口仍需按完整资源、时区、权限和版本做服务端校验。日历没有配置的日期继续按 workingDays 判断，因此业务需提供所需年份的休假/补班数据。

修改工作日历可能改变“最后工作日”的原始发生时间，已有例外不能自动迁移；请沿用系列规则变更的显式清理或迁移策略。本轮不包含地区节假日下载、调休规则推算、按资源选择多个企业日历或工作小时的日期级覆盖。

### 修改本次及以后

Example source: src/scheduler/__demos__/recurrence-following.vue

```vue
<template>
  <c-space direction="column" block>
    <c-alert
      >点击会议选择“仅本次”或“本次及以后”。周五预设了一条“客户参会”例外：默认保护它，明确选择清除后才允许拆分。修改日期时需保留原规则的星期。</c-alert
    >
    <c-space wrap>
      <c-button @click="reset">重置示例</c-button>
      <c-checkbox v-model="reject">模拟保存失败</c-checkbox>
      <c-tag
        >{{ state.series.length }} 个系列 ·
        {{ state.exceptions.length }} 条例外</c-tag
      >
    </c-space>
    <c-space wrap>
      <c-tag v-for="item in state.series" :key="item.event.id"
        >{{ item.event.title }} · {{ item.rule.count ?? "不限" }} 次</c-tag
      >
    </c-space>
    <c-tag>{{ status }}</c-tag>
    <c-scheduler
      key="recurrence-following-calendar"
      :model-value="events"
      default-date="2026-09-09"
      default-mode="week"
      readonly
      :editable="false"
      @range-change="range = $event"
      @event-click="openEditor"
    />
    <c-dialog v-model:open="open" title="调整重复安排" :footer="false">
      <c-form
        v-if="draft"
        :model="draft"
        layout="vertical"
        @submit="save(false)"
      >
        <c-form-item label="修改范围">
          <c-select v-model="scope" :options="scopes" aria-label="修改范围" />
        </c-form-item>
        <c-form-item v-if="scope === 'following'" label="后续例外">
          <c-select
            v-model="policy"
            :options="policies"
            aria-label="后续例外处理"
          />
        </c-form-item>
        <c-form-item label="会议标题"
          ><c-input v-model="draft.title" aria-label="会议标题"
        /></c-form-item>
        <c-form-item label="开始时间"
          ><c-date
            v-model="draft.start"
            show-time
            value-format="Date"
            aria-label="会议开始"
        /></c-form-item>
        <c-form-item label="结束时间"
          ><c-date
            v-model="draft.end"
            show-time
            value-format="Date"
            aria-label="会议结束"
        /></c-form-item>
        <c-alert v-if="error" status="danger">{{ error }}</c-alert>
        <c-space wrap>
          <c-button status="primary" @click="save(false)">保存修改</c-button>
          <c-button @click="save(true)">取消所选安排</c-button>
          <c-button @click="open = false">返回</c-button>
        </c-space>
      </c-form>
    </c-dialog>
  </c-space>
</template>
<script setup lang="ts">
import { computed, ref, shallowRef } from "vue";
import {
  cloneSchedulerEvent,
  expandSchedulerRecurrences,
  getSchedulerRange,
  schedulerDate,
  setSchedulerRecurrenceException,
  splitSchedulerRecurrence,
} from "../core";
import type {
  SchedulerEvent,
  SchedulerOccurrence,
  SchedulerRecurringEvent,
  SchedulerRecurrenceException,
} from "../core";
const range = ref(getSchedulerRange("2026-09-09", "week"));
function initialState(): {
  series: SchedulerRecurringEvent[];
  exceptions: SchedulerRecurrenceException[];
} {
  const series: SchedulerRecurringEvent[] = [
    {
      event: {
        id: "team-sync",
        title: "团队同步会",
        start: "2026-09-07T09:00:00",
        end: "2026-09-07T10:00:00",
      },
      rule: { frequency: "weekly", daysOfWeek: [1, 3, 5], count: 9 },
    },
  ];
  const friday = expandSchedulerRecurrences(
    series,
    getSchedulerRange("2026-09-09", "week"),
  )[2];
  return {
    series,
    exceptions: setSchedulerRecurrenceException([], friday, {
      ...friday,
      title: "客户参会",
    }),
  };
}
const state = shallowRef(initialState());
const events = computed(() =>
  expandSchedulerRecurrences(state.value.series, range.value, {
    exceptions: state.value.exceptions,
  }),
);
const open = ref(false);
const reject = ref(false);
const scope = ref<"single" | "following">("single");
const policy = ref<"reject" | "discard">("reject");
const scopes = [
  { label: "仅本次", value: "single" },
  { label: "本次及以后", value: "following" },
];
const policies = [
  { label: "保护已有例外", value: "reject" },
  { label: "清除后续例外", value: "discard" },
];
const selected = shallowRef<SchedulerOccurrence>();
const draft = ref<{ title: string; start: Date; end: Date }>();
const error = ref("");
const status = ref("点击日程调整安排");
let baseline = state.value;
let nextId = 0;
function openEditor(event: SchedulerEvent) {
  const occurrence = events.value.find((item) => item.id === event.id);
  if (!occurrence) return;
  selected.value = { ...occurrence };
  draft.value = {
    title: occurrence.title,
    start: schedulerDate(occurrence.start!),
    end: schedulerDate(occurrence.end!),
  };
  scope.value = "single";
  policy.value = "reject";
  error.value = "";
  baseline = state.value;
  open.value = true;
}
function save(remove: boolean) {
  if (!selected.value || !draft.value) return;
  error.value = "";
  try {
    if (state.value !== baseline)
      throw new Error("安排已变化，请关闭后重新打开。");
    const replacement = {
      ...cloneSchedulerEvent(selected.value),
      ...draft.value,
    };
    let proposal: typeof state.value;
    let discarded = 0;
    if (scope.value === "following") {
      const affected = state.value.exceptions.filter(
        (item) =>
          item.seriesId === selected.value!.seriesId &&
          +schedulerDate(item.originalStart) >=
            +schedulerDate(selected.value!.originalStart),
      );
      if (affected.length && policy.value === "reject")
        throw new Error(
          `后续有 ${affected.length} 条例外，请选择清除后续例外或仅修改本次。`,
        );
      const result = splitSchedulerRecurrence(
        state.value.series,
        state.value.exceptions,
        selected.value,
        {
          nextEvent: remove
            ? undefined
            : { ...replacement, id: `team-sync-part-${nextId + 1}` },
          exceptionPolicy: policy.value,
        },
      );
      proposal = { series: result.series, exceptions: result.exceptions };
      discarded = result.removedExceptions.length;
    } else
      proposal = {
        series: state.value.series,
        exceptions: setSchedulerRecurrenceException(
          state.value.exceptions,
          selected.value,
          remove ? undefined : replacement,
        ),
      };
    // Save this complete canonical proposal atomically before publishing the projection.
    if (reject.value) throw new Error("模拟保存失败，原系列和例外均保留。");
    state.value = proposal;
    nextId++;
    status.value = `${remove ? "已取消" : "已修改"}${scope.value === "following" ? "本次及以后" : "本次"}；清除 ${discarded} 条后续例外`;
    open.value = false;
  } catch (cause) {
    error.value = cause instanceof Error ? cause.message : "保存失败";
  }
}
function reset() {
  state.value = initialState();
  open.value = false;
  status.value = "点击日程调整安排";
  reject.value = false;
}
</script>
```

`splitSchedulerRecurrence` 生成系列层提案，不直接修改日历或调用服务端。示例使用外部 Cedar Dialog 选择“仅本次 / 本次及以后”，将系列与例外一起保存成功后再发布到日历。模拟保存失败会保留原数据与表单。

```ts
import { splitSchedulerRecurrence } from "@cedar-design/ui/scheduler/core";

const proposal = splitSchedulerRecurrence(
  series,
  exceptions,
  selectedOccurrence,
  {
    nextEvent: { ...editedOccurrence, id: "new-series-id" },
    exceptionPolicy: "discard", // 明确清除本次及以后的例外；默认 reject
  },
);
// 先原子保存 proposal.series / proposal.exceptions，再更新业务状态。
// proposal.removedExceptions 可用于展示清除内容或审计。
```

| 选项 / 返回值       | 说明                                                                                                       |
| ------------------- | ---------------------------------------------------------------------------------------------------------- |
| nextEvent           | 新系列的完整已排期起点，id 必须与全部已有系列不同；省略表示取消本次及以后                                  |
| rule                | 可选完整新规则；省略继承原频率、间隔、星期、截止时间，并扣除之前已发生的次数；传入时完整替换，包括终止条件 |
| exceptionPolicy     | reject（默认）保护后续例外，discard 明确清除；不会自动把旧例外映射到新系列                                 |
| maxIterations       | 校验扫描上限，默认 100000；超出抛错，不返回部分提案                                                        |
| series / exceptions | 可一起原子保存的新系列与保留例外，不修改输入                                                               |
| removedExceptions   | 本次及以后被清除的例外副本                                                                                 |

切分点用 `originalStart`，即使某次会议已经被移到其他日期，也不会改变它在系列里的位置。之前的系列和实例 ID 保持不变；后续实例获得新系列 ID。此前发生但移动到未来的例外继续保留，未来发生但移动到过去的例外仍属于后续范围。

从第一次拆分会直接替换原系列；取消第一次及以后会删除整个系列。默认继承规则时，取消记录仍占原始次数；until 保持原截止时间。如果更改起点日期，新起点必须匹配继承或显式传入的新规则。需要改变星期、次数或截止时间时，请传完整 rule；不传 count / until 的新规则会持续重复。

本例默认保护已有例外，选择“清除后续例外”后才允许删除它们。该选择同样适用于取消后续安排。完整 RRULE、自动迁移后续例外、跨时区系列和多人并发版本合并不包含在此 API 中。服务端仍需检查版本、权限与所有后续冲突，并原子保存整个提案；仅检查当前可见窗口不足以确认系列有效。

### RRULE、时区与夏令时

Example source: src/scheduler/__demos__/zoned-recurrence.vue

```vue
<template>
  <c-space direction="column" block>
    <c-alert
      >每周一纽约时间 09:00，跨越夏令时切换后 UTC 时间会变化。RRULE
      由独立适配器解析，结果保留真实时间点；议程卡片同时展示所选时区时间。</c-alert
    >
    <c-space
      ><c-button @click="zone = 'America/New_York'">纽约时间</c-button
      ><c-button @click="zone = 'Asia/Shanghai'">上海时间</c-button
      ><c-tag>{{ zone }}</c-tag></c-space
    >
    <c-scheduler
      :model-value="events"
      default-date="2026-03-09"
      default-mode="agenda"
      readonly
    >
      <template #event="{ event }"
        >{{ event.title }} ·
        {{ formatSchedulerZonedDate(event.start, zone) }}</template
      >
    </c-scheduler>
  </c-space>
</template>
<script setup lang="ts">
import { ref } from "vue";
import { expandSchedulerRRule, formatSchedulerZonedDate } from "../adapters";
const zone = ref("America/New_York");
const events = expandSchedulerRRule(
  {
    event: {
      id: "ny",
      title: "纽约例会",
      start: "2026-03-02T14:00:00Z",
      end: "2026-03-02T15:00:00Z",
    },
    timeZone: "America/New_York",
    rule: "FREQ=WEEKLY;BYDAY=MO;COUNT=4",
  },
  { start: new Date("2026-03-01"), end: new Date("2026-04-01") },
);
</script>
```

高级引擎从 `@cedar-design/ui/scheduler/adapters` 导入，使用 [rrule](https://github.com/jkbrzt/rrule) 解析 RFC RRULE 字段、使用 [Temporal polyfill](https://github.com/js-temporal/temporal-polyfill) 转换 IANA 时区，未替换轻量 core 重复规则。

`expandSchedulerRRule({event, rule, timeZone?}, range, options?)` 接受定时种子和单个 RRULE 值（可带 RRULE: 前缀），DTSTART 由 event.start 唯一决定，不能在 rule 中再次指定。支持 BYDAY、BYSETPOS 等规则；options 提供 excludeDates/includeDates（真实时间点）、maxOccurrences、maxIterations。超出预算抛错，不静默截断。生成稳定的 seriesId/originalStart，供业务保存例外。

`schedulerZonedDate(localDateTime, timeZone, disambiguation?)` 将当地时间转换为 Date；不存在或重复时间默认 reject，可明确选择 earlier、later、compatible。`formatSchedulerZonedDate` 格式化真实时间点。RRULE 保持指定地区当地时刻、持续时间保持实际毫秒数。当前组件网格仍采用运行环境本地时间；时区 demo 通过卡片格式化展示指定时区，不将本地网格宣称为完整的多时区编辑器。

## 编辑与交互

### 拖拽虚影与实时拉伸

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `default-date` | 初始定位日期 | 拖拽虚影与实时拉伸、复制日程、自定义卡片拖入新增 |
| `default-mode` | 非受控默认视图 | 拖拽虚影与实时拉伸、复制日程、自定义日程与只读 |
| `resources` | 当前可见资源行/列及本地选项，不要求全量目录 | 拖拽虚影与实时拉伸、复制日程、自定义卡片拖入新增 |
| `before-change` | 返回 false 取消；异步拦截、保存接口 | 自定义日程与只读、自定义新建 / 编辑表单、完全自定义弹窗 / 页面 |
| `resource-label` | 资源字段名称，如设备、会议室 | 拖拽虚影与实时拉伸 |
| `start-hour` | 时间网格起始小时，0–23 | 拖拽虚影与实时拉伸 |
<!-- demo-config-notes:end -->

拖拽与拉伸预览不显示额外的虚线框，保留日程自身的主题样式、半透明反馈和动态尺寸变化。移动时鼠标旁显示紧凑的标题/时间摘要，不复制完整自定义卡片；摘要限制在屏幕边缘内，日历中的落点预览即时跟随吸附位置，按 Escape 取消且不保存。

时间格在普通悬停、拖拽及拉伸期间均不显示悬停背景，键盘焦点提示不受影响。

标题可留空：内置编辑器、自定义编辑器的 `save` 和实例 `change` 在保存时会将空标题或纯空格标题补为“无主题”（英文环境为 `Untitled`），然后再进行校验和调用 `before-change`。独立核心函数仍要求传入有效标题。

移动日程时显示保留标题、自定义插槽内容和主题色的半透明虚影，目标位置显示吸附预览及预计起止时间。日/周/资源日程视图的定时日程支持上边缘调整开始、下边缘调整结束；按 `step` 吸附，最短时长为一个步长。预览不改变原数据，松手后仍经过校验和 `before-change`，失败保留原值。

同一资源列内只移动时间时，保持原有 `resourceIds` 及其顺序；跨资源移动才替换来源资源，其他参与资源保持关联。

按 Escape、取消指针、窗口失焦或交互被禁用会撤销预览；动画遵循系统减少动态效果设置。月、全天行和资源时间线支持移动预览，精确起止拉伸仅在定时时间网格提供。

开始新的指针手势会取消残留的旧手势；自定义卡片内部阻止松手事件冒泡也不会导致其他日程跟随拉伸。拖拽只提交当前日程的数据，多资源列中的同一日程（相同 `id`）会同步显示；保存后若产生时间重叠，卡片会按重叠布局重新分列。

Example source: src/scheduler/__demos__/drag-feedback.vue

```vue
<template>
  <section class="scheduler-drag-demo">
    <p>
      拖动日程主体查看虚影和目标预览；拖上边缘调整开始，拖下边缘调整结束。按
      Escape 取消，松手才提交。
    </p>
    <c-scheduler
      v-model="events"
      default-date="2026-09-09"
      default-mode="resource-day"
      :resources="resources"
      resource-label="工作台"
      :start-hour="8"
      :end-hour="16"
      :step="15"
      :show-sidebar="false"
      style="--c-scheduler-max-height: 560px"
    >
      <template #event="{ event }">
        <strong>{{ event.title }}</strong
        ><br />
        <span>{{ event.description }}</span>
      </template>
    </c-scheduler>
    <c-button @click="events = createEvents()">重置日程</c-button>
    <ul aria-label="已提交日程">
      <li v-for="event in events" :key="event.id" :data-demo-event="event.id">
        {{ event.title }}：{{ event.start }} → {{ event.end }}；资源：{{
          event.resourceIds?.join(", ") || "无"
        }}
      </li>
    </ul>
  </section>
</template>
<script setup lang="ts">
import { ref } from "vue";
import type { SchedulerEvent, SchedulerResource } from "@cedar-design/ui";
const resources: SchedulerResource[] = [
  { id: "a", label: "工作台 A" },
  { id: "b", label: "工作台 B" },
];
function createEvents(): SchedulerEvent[] {
  return [
    {
      id: "design",
      title: "方案制作",
      description: "自定义卡片内容也会出现在虚影中",
      start: "2026-09-09T09:00:00",
      end: "2026-09-09T10:30:00",
      resourceIds: ["a"],
    },
    {
      id: "review",
      title: "验收检查",
      description: "试着拖动上边缘或下边缘",
      start: "2026-09-09T11:00:00",
      end: "2026-09-09T12:00:00",
      resourceIds: ["b"],
    },
  ];
}
const events = ref(createEvents());
</script>
```

下方“已提交日程”直接展示 v-model 的起止时间与资源 ID，便于核对只修改目标日程；预览不是提交值。可使用“重置日程”恢复两个独立 ID 的初始场景。

### 复制日程

Example source: src/scheduler/__demos__/duplicate-events.vue

```vue
<template>
  <c-space direction="column" block>
    <c-alert
      >点击日程详情中的“复制日程”，或使用下方按钮。副本取自已保存数据，生成新编号，尚未保存的表单修改不会带入。保存前可调整时间和人员；取消不创建日程。会议室容量为
      2，可体验第三条同时预约被拦截。</c-alert
    >
    <c-space wrap>
      <c-button @click="scheduler?.duplicateEvent('review')"
        >复制评审会议</c-button
      >
      <c-button @click="scheduler?.duplicateEvent('all-day')"
        >复制全天任务</c-button
      >
      <c-button @click="scheduler?.duplicateEvent('backlog')"
        >复制未排期任务</c-button
      >
      <c-checkbox v-model="reject">下一次副本保存失败</c-checkbox>
      <c-tag>已保存 {{ events.length }} 条日程</c-tag>
    </c-space>
    <c-scheduler
      key="duplicate-events"
      ref="scheduler"
      v-model="events"
      default-date="2026-09-16"
      default-mode="week"
      :resources="resources"
      :before-transaction="persist"
      history
    />
  </c-space>
</template>
<script setup lang="ts">
import { ref } from "vue";
import type { SchedulerInstance } from "../index";
import type { SchedulerEvent } from "../core";
import type { SchedulerBeforeTransaction } from "../props";
const scheduler = ref<SchedulerInstance>();
const reject = ref(false);
const resources = [{ id: "room", label: "协作会议室", capacity: 2 }];
const events = ref<SchedulerEvent[]>([
  {
    id: "review",
    title: "设计方案评审",
    start: "2026-09-16T10:00:00",
    end: "2026-09-16T11:00:00",
    resourceIds: ["room"],
    description: "讨论方案与任务分配",
    metadata: { taskId: "design" },
  },
  {
    id: "all-day",
    title: "资料整理日",
    start: "2026-09-17",
    end: "2026-09-18",
    allDay: true,
  },
  {
    id: "backlog",
    title: "待安排的用户访谈",
    description: "确认参与人员后安排时间",
  },
]);
const persist: SchedulerBeforeTransaction = async () => {
  const shouldReject = reject.value;
  if (shouldReject) reject.value = false;
  await new Promise((resolve) => setTimeout(resolve, 200));
  if (shouldReject) throw new Error("Simulated save failure");
};
</script>
```

详情中的“复制日程”使用当前已保存日程创建新草稿，未保存的表单修改不会带入。副本保持标题、日期、时长、全天状态、资源、描述、颜色、`metadata`，生成新 ID；取消不创建数据。定时、全天、未排期均支持。保存仍经过工作时间、维护、容量、冲突和保存钩子，成功后可以撤销重做。

示例中的“下一次副本保存失败”只拒绝下一次提交，并自动复位；失败时抽屉保留草稿，可直接点击保存重试，不需要先关闭抽屉操作外部开关。此开关仅模拟本地保存，不是组件属性。

保存被容量、可用时间或业务钩子拒绝时，编辑器保留草稿与错误以便修正重试；点击取消关闭编辑器后清除该次错误，不在日历外层残留过期提示，已保存模型不变。

实例方法 `duplicateEvent(id): boolean` 用于打开复制草稿；返回 `true` 只表示草稿已打开或编辑请求已发出，**不表示已保存**。日程不存在、只读或组件正在加载/保存、禁用时返回 `false`。`editable=false` 时发送 `editor-request`，其 `action='create'`、`source='duplicate'`。自定义 `editor` 插槽可调用 `duplicate()`；新建模式下该动作无效。

纯核心 `duplicateSchedulerEvent(event, newId)` 从 `@cedar-design/ui/scheduler/core` 导出，返回脱离原数据的标准 `SchedulerEvent`，不修改源数据，也不执行保存。调用者负责 ID 在数据集中的唯一性；空 ID、与源相同 ID、非法或只读源日程会抛错。复制重复实例不会保留 `seriesId/originalStart`，会成为独立普通日程。标准 `metadata` 会浅复制；未声明的对象扩展字段不会自动复制，需要应用在提交前按自身规则添加。

### 单击日程直接弹窗

Example source: src/scheduler/__demos__/event-dialog.vue

```vue
<template><EventDetailsExample /></template>
<script setup lang="ts">
import EventDetailsExample from "./event-details-example.vue";
</script>
```

通过 `editable=false` 与 `editor-request` 接入内部 Dialog，单击堆叠卡片即可编辑；新建也使用同一窗口。取消不提交，保存调用 Scheduler 的 `change`，复用只读、冲突与保存钩子校验。

### Popover 摘要与高级编辑

Example source: src/scheduler/__demos__/event-popover.vue

```vue
<template><EventDetailsExample preview /></template>
<script setup lang="ts">
import EventDetailsExample from "./event-details-example.vue";
</script>
```

通过 `event` 插槽放置受控 Popover，以日程卡片为锚点；`editor-request` 打开对应摘要。同一 Popover 模式也处理点击空白单元格新增：锚定该单元格，填写名称后可直接创建；“高级编辑”携带当前草稿打开完整 Dialog。工具栏“新建日程”等非单元格入口仍直接打开窗口，拖入和复制也不按单元格点击处理。只读时提供“查看完整详情”；点击外部、Escape、切换日期或开始指针操作关闭摘要。示例站点与负责人为演示字段，可替换为业务资源数据。

摘要锚定整张日程卡片：依次尝试右侧顶部、左侧顶部、右侧底部、左侧底部对齐；两侧够宽但上下都放不下时，尽量保留侧边并贴视口边界。两侧太窄则尝试卡片上方或下方，最终位置限制在视口内，保留 8px 边距。弹层默认宽 360px，超宽自动收窄，超高内部滚动；跟随页面/容器滚动、窗口和可视视口尺寸变化重新定位。

两个示例共享编辑实现，包含日期、标题、说明、删除、取消和失败重试。无需新增 Scheduler 公共 API，也可按相同方式接入业务弹窗。

日程的 `color` 用作文字、前景和图案颜色；`accentColor` 单独设置可操作日程左侧的强调线，省略时跟随 `color`；`backgroundColor` 设置卡片底色，`backgroundPattern` 可选 `solid`、`diagonal-stripes`、`dots`、`crosshatch`。全局只读、禁用、日程只读或当前不可拖拽时，卡片不显示左侧操作强调线。图案使用语义枚举，便于不同业务类型保持一致。

业务类型不是 Scheduler 的内置枚举。应用可把 `typeId` 等信息放入 `metadata`，再在自定义编辑器中映射为标题建议、外观和权限；Scheduler 不读取这些内容，只在新建、编辑、拖动和复制过程中保留一层独立副本。

### 自定义卡片拖入新增

左侧卡片通过 `sidebar-extra` 插槽自定义，不需要提前写入日程数据。绑定原生 `dragstart` 到 `startDrag(template, $event)`，`dragend` 到 `cancelDrag`。
拖入日/周/资源时间格识别准确时刻和目标资源；月格与全天行生成一天的全天日程；资源时间线识别日期和资源，以 `start-hour` 为开始时间。议程视图没有拖入目标。
落下后打开内置编辑弹层，确认才新增，取消不保存，模板可重复使用。`duration` 为正数分钟，省略时使用 `step`；全天落点忽略分钟时长。目标资源优先于模板的 `resourceIds`。
只读、禁用、加载、提交中或内置编辑器已打开时不可拖入。`editable=false` 时拖入改为触发 `editor-request`，交由外部页面确认。保存复用 `before-change`、冲突校验和受控更新逻辑。此示例使用桌面原生拖拽，触屏及键盘用户仍可用工具栏新增入口。

Example source: src/scheduler/__demos__/custom-cards.vue

```vue
<template>
  <c-scheduler
    v-model="events"
    default-date="2026-09-09"
    :resources="resources"
  >
    <template #sidebar-extra="{ startDrag, cancelDrag, disabled }">
      <strong>自定义卡片</strong>
      <p>拖到右侧日期或时间格，确认后新增。卡片可重复使用。</p>
      <c-button
        v-for="card in cards"
        :key="card.title"
        class="scheduler-template-card"
        :disabled="disabled"
        :draggable="!disabled"
        @dragstart="startDrag(card, $event)"
        @dragend="cancelDrag"
      >
        <strong>{{ card.title }}</strong>
        <span>{{ card.description }} · {{ card.duration }} 分钟</span>
      </c-button>
    </template>
  </c-scheduler>
</template>
<script setup lang="ts">
import { ref } from "vue";
import type { SchedulerEvent, SchedulerEventTemplate } from "@cedar-design/ui";
import { resources } from "./data";
const events = ref<SchedulerEvent[]>([]);
const cards: SchedulerEventTemplate[] = [
  {
    title: "需求评审",
    description: "确认目标和验收标准",
    duration: 60,
    metadata: { taskId: "review" },
  },
  {
    title: "客户沟通",
    description: "记录反馈与后续安排",
    duration: 30,
    metadata: { taskId: "call" },
  },
  {
    title: "专注工作",
    description: "预留不被打扰的时段",
    duration: 90,
    metadata: { taskId: "focus" },
  },
];
</script>
<style scoped>
.scheduler-template-card {
  display: flex;
  flex-direction: column;
  gap: 8px;
  padding: 12px;
  text-align: left;
  border: 1px solid var(--c-color-border);
  border-radius: 8px;
  color: var(--c-color-text-1);
  background: var(--c-color-bg-2);
  cursor: grab;
}
.scheduler-template-card:disabled {
  cursor: not-allowed;
  opacity: 0.5;
}
.scheduler-template-card span {
  color: var(--c-color-text-2);
}
</style>
```

### 自定义日程与只读

插槽提供展示内容；外层已经是可聚焦按钮，插槽内避免嵌套交互控件。只读仍能打开详情。

Example source: src/scheduler/__demos__/custom-event.vue

```vue
<template>
  <c-alert>
    这里的工作、会议、休息和不可用时段都是 Demo 自己定义的业务类型，并非
    Scheduler
    内置枚举。新增时可选择类型，由业务配置映射标题建议、外观和默认权限。
  </c-alert>
  <c-space>
    <c-checkbox v-model="rejectSave">模拟后端保存失败</c-checkbox>
    <span>{{ requestStatus }}</span>
  </c-space>
  <c-loading :loading="loading" style="display: block">
  <c-scheduler
    :readonly="loading"
    v-model="events"
    default-date="2026-09-09"
    default-mode="week"
    :resources="resources"
    :before-change="saveToMockServer"
  >
    <template #event="{ event }">
      <span>{{ event.title }}</span>
      <c-tag size="sm" :status="event.readonly ? 'neutral' : 'info'">
        {{ typeOf(event).label }} · {{ event.readonly ? "只读" : "可编辑" }}
      </c-tag>
    </template>

    <template
      #editor="{
        action,
        event,
        save,
        remove,
        close,
        readonly,
        pending,
        errorMessage,
      }"
    >
      <h3>{{ action === "create" ? "新增日程" : "编辑日程" }}</h3>
      <c-alert v-if="errorMessage" status="danger">
        {{ errorMessage }}
      </c-alert>
      <c-form
        :model="event"
        layout="vertical"
        @submit="prepareAndSave(event, save)"
      >
        <c-form-item label="日程类型">
          <c-select
            :model-value="typeOf(event).id"
            :disabled="readonly || pending"
            @update:model-value="applyType(event, $event)"
          >
            <c-option
              v-for="type in eventTypes"
              :key="type.id"
              :value="type.id"
            >
              {{ type.label }} · {{ type.readonly ? "默认只读" : "默认可编辑" }}
            </c-option>
          </c-select>
        </c-form-item>

        <div class="scheduler-type-preview" :style="previewStyle(event)">
          <strong>{{ typeOf(event).label }}</strong>
          <span>{{ typeOf(event).description }}</span>
        </div>

        <c-form-item label="标题">
          <c-input
            v-model="event.title"
            :disabled="readonly || pending"
            placeholder="请输入日程标题"
          />
        </c-form-item>
        <c-form-item label="开始时间">
          <c-date
            :model-value="
              event.start == null ? undefined : schedulerDate(event.start)
            "
            :disabled="readonly || pending"
            show-time
            value-format="Date"
            @update:model-value="event.start = $event"
          />
        </c-form-item>
        <c-form-item label="结束时间">
          <c-date
            :model-value="
              event.end == null ? undefined : schedulerDate(event.end)
            "
            :disabled="readonly || pending"
            show-time
            value-format="Date"
            @update:model-value="event.end = $event"
          />
        </c-form-item>
        <c-form-item>
          <c-checkbox
            :model-value="!event.readonly"
            :disabled="readonly || pending"
            @update:model-value="event.readonly = !$event"
          >
            创建后允许修改和拖拽
          </c-checkbox>
        </c-form-item>
        <c-space>
          <c-button :disabled="pending" @click="close">取消</c-button>
          <c-button
            v-if="action === 'edit' && !readonly"
            status="danger"
            :disabled="pending"
            @click="remove"
            >删除</c-button
          >
          <c-button
            v-if="!readonly"
            html-type="submit"
            status="primary"
            :loading="pending"
            >保存日程</c-button
          >
        </c-space>
      </c-form>
    </template>
  </c-scheduler>
  </c-loading>
  <c-collapse class="scheduler-mock-log">
    <c-collapse-item name="request" title="查看最近一次 Mock API 请求">
      <pre>{{ lastRequest || "尚未提交" }}</pre>
    </c-collapse-item>
  </c-collapse>
</template>

<script setup lang="ts">
import { onMounted, ref } from "vue";
import { resources } from "./data";
import { cloneSchedulerEvent, schedulerDate } from "../core";
import type {
  SchedulerBeforeChange,
  SchedulerEvent,
  SchedulerEventBackgroundPattern,
} from "../index";

type EventType = {
  id: string;
  label: string;
  description: string;
  title: string;
  color: string;
  backgroundColor: string;
  backgroundPattern: SchedulerEventBackgroundPattern;
  readonly: boolean;
};

const eventTypes: EventType[] = [
  {
    id: "work",
    label: "工作安排",
    description: "普通任务，可继续编辑和拖拽调整时间。",
    title: "工作安排",
    color: "#1677ff",
    backgroundColor: "#e6f4ff",
    backgroundPattern: "solid",
    readonly: false,
  },
  {
    id: "meeting",
    label: "会议",
    description: "用圆点背景区分协作和沟通类日程。",
    title: "会议",
    color: "#d48806",
    backgroundColor: "#fffbe6",
    backgroundPattern: "dots",
    readonly: false,
  },
  {
    id: "rest",
    label: "休息",
    description: "休息时段默认锁定，保存后不允许修改或拖拽。",
    title: "休息",
    color: "#00a854",
    backgroundColor: "#f0fff4",
    backgroundPattern: "diagonal-stripes",
    readonly: true,
  },
  {
    id: "blocked",
    label: "不可用时段",
    description: "用于停机、封场等占用，默认只读。",
    title: "不可用时段",
    color: "#722ed1",
    backgroundColor: "#f9f0ff",
    backgroundPattern: "crosshatch",
    readonly: true,
  },
];

const seedEvents: SchedulerEvent[] = [
  createEvent("work", "work-1", "需求评审", "09:00", "10:30"),
  createEvent("meeting", "meeting-1", "项目周会", "10:00", "11:30"),
  createEvent("rest", "rest-1", "张志强 休息", "13:00", "15:00"),
  createEvent("blocked", "blocked-1", "会议室维护", "15:30", "17:30"),
];
const events = ref<SchedulerEvent[]>([]);
const loading = ref(true);
const rejectSave = ref(false);
const requestStatus = ref("正在从 Mock API 加载…");
const lastRequest = ref("");
let mockDatabase = seedEvents.map(cloneSchedulerEvent);

const wait = (milliseconds: number) =>
  new Promise((resolve) => setTimeout(resolve, milliseconds));
const mockApi = {
  async list() {
    await wait(300);
    return mockDatabase.map(cloneSchedulerEvent);
  },
  async save(next: SchedulerEvent[]) {
    await wait(500);
    if (rejectSave.value) throw new Error("Mock API：保存被拒绝");
    mockDatabase = next.map(cloneSchedulerEvent);
    return {
      revision: Date.now(),
      events: mockDatabase.map(cloneSchedulerEvent),
    };
  },
};

onMounted(async () => {
  events.value = await mockApi.list();
  loading.value = false;
  requestStatus.value = `已加载 ${events.value.length} 条日程`;
});

const saveToMockServer: SchedulerBeforeChange = async (context) => {
  lastRequest.value = JSON.stringify(
    {
      method: "PUT",
      url: "/api/scheduler/events",
      change: context.type,
      event: context.event,
      events: context.value,
    },
    null,
    2,
  );
  requestStatus.value = "正在提交 metadata 和日程数据…";
  try {
    const response = await mockApi.save(context.value);
    requestStatus.value = `保存成功 · revision ${response.revision}`;
    return true;
  } catch (error) {
    requestStatus.value = error instanceof Error ? error.message : "保存失败";
    throw error;
  }
};

function createEvent(
  typeId: string,
  id: string,
  title: string,
  start: string,
  end: string,
): SchedulerEvent {
  const event: SchedulerEvent = {
    id,
    title,
    start: `2026-09-09T${start}:00`,
    end: `2026-09-09T${end}:00`,
    resourceIds: [],
  };
  applyType(event, typeId, false);
  return event;
}

function typeOf(event: SchedulerEvent): EventType {
  return (
    eventTypes.find((type) => type.id === event.metadata?.typeId) ??
    eventTypes[0]
  );
}

function applyType(event: SchedulerEvent, value: unknown, suggestTitle = true) {
  const previous = typeOf(event);
  const type = eventTypes.find((item) => item.id === value) ?? eventTypes[0];
  const replaceTitle =
    suggestTitle && (!event.title.trim() || event.title === previous.title);
  event.color = type.color;
  event.backgroundColor = type.backgroundColor;
  event.backgroundPattern = type.backgroundPattern;
  event.metadata = { ...event.metadata, typeId: type.id };
  event.readonly = type.readonly;
  if (replaceTitle) event.title = type.title;
}

function prepareAndSave(
  event: SchedulerEvent,
  save: (event?: SchedulerEvent) => void,
) {
  const type = typeOf(event);
  event.color ??= type.color;
  event.backgroundColor ??= type.backgroundColor;
  event.backgroundPattern ??= type.backgroundPattern;
  event.metadata = {
    ...event.metadata,
    typeId: type.id,
    clientRequestId: `demo-${Date.now()}`,
  };
  save(event);
}

function previewStyle(event: SchedulerEvent) {
  const color = event.color ?? "#1677ff";
  const background = event.backgroundColor ?? "#e6f4ff";
  const pattern = event.backgroundPattern;
  const images: Record<SchedulerEventBackgroundPattern, string> = {
    solid: `linear-gradient(${background}, ${background})`,
    "diagonal-stripes": `repeating-linear-gradient(135deg, transparent 0 8px, color-mix(in srgb, ${color} 18%, transparent) 8px 16px)`,
    dots: `radial-gradient(circle, color-mix(in srgb, ${color} 28%, transparent) 1.5px, transparent 1.5px)`,
    crosshatch: `repeating-linear-gradient(45deg, transparent 0 9px, color-mix(in srgb, ${color} 14%, transparent) 9px 11px), repeating-linear-gradient(-45deg, transparent 0 9px, color-mix(in srgb, ${color} 14%, transparent) 9px 11px)`,
  };
  return {
    color,
    backgroundColor: background,
    backgroundImage: images[pattern ?? "solid"],
    backgroundSize: pattern === "dots" ? "10px 10px" : undefined,
    borderColor: color,
  };
}
</script>

<style scoped>
.scheduler-type-preview {
  display: grid;
  gap: 4px;
  margin: 0 0 16px;
  padding: 12px 14px;
  border: 1px solid;
  border-radius: 8px;
}

.scheduler-type-preview span {
  font-size: 12px;
  opacity: 0.75;
}

.scheduler-mock-log {
  margin-top: 12px;
}

.scheduler-mock-log pre {
  max-height: 260px;
  overflow: auto;
  padding: 12px;
  border-radius: 8px;
  background: var(--c-color-fill-1);
  font-size: 12px;
}
</style>
```

### 自定义新建 / 编辑表单

`editor` 插槽替换内置 Drawer 的内容，`action` 区分 `create` / `edit`。`event` 是隔离草稿，可修改其字段；`save(event)` 提交完整日程，`save()` 提交当前自定义草稿。不得修改草稿 ID。二者都保留校验和 `before-change`，成功才自动关闭；取消不会写入数据。

`error` 是结构化 SchedulerError，`errorMessage` 是当前语言的显示文案，包含内置字段校验或保存失败。自定义内容负责显示错误并根据 `readonly` / `pending` 禁用控件。`save` 是触发提交的动作，不返回成功 Promise；需要等待结果请使用实例 `change()`。`remove()` 和 `duplicate()` 在新建模式下无效。

Example source: src/scheduler/__demos__/custom-editor.vue

```vue
<template>
  <c-checkbox v-model="reject">模拟接口拒绝保存</c-checkbox>
  <p>保留内置抽屉，替换全部表单内容；可看到新建/编辑标识及校验、接口错误。</p>
  <c-scheduler
    v-model="events"
    default-date="2026-09-09"
    default-mode="day"
    :before-change="beforeChange"
  >
    <template
      #editor="{
        action,
        event,
        save,
        remove,
        close,
        readonly,
        pending,
        errorMessage,
      }"
    >
      <h3>{{ action === "create" ? "新增工作计划" : "修改工作计划" }}</h3>
      <c-alert v-if="errorMessage" status="danger">{{ errorMessage }}</c-alert>
      <c-form :model="event" layout="vertical" @submit="save(event)">
        <c-form-item label="计划标题">
          <c-input v-model="event.title" :disabled="readonly || pending" />
        </c-form-item>
        <c-form-item label="开始时间">
          <c-date
            :model-value="event.start == null ? undefined : schedulerDate(event.start)"
            @update:model-value="event.start = $event"
            :show-time="!event.allDay"
            value-format="Date"
            :disabled="readonly || pending"
          />
        </c-form-item>
        <c-form-item label="结束时间（不含）">
          <c-date
            :model-value="event.end == null ? undefined : schedulerDate(event.end)"
            @update:model-value="event.end = $event"
            :show-time="!event.allDay"
            value-format="Date"
            :disabled="readonly || pending"
          />
        </c-form-item>
        <c-form-item label="验收说明">
          <c-textarea
            v-model="event.description"
            :disabled="readonly || pending"
          />
        </c-form-item>
        <c-space>
          <c-button :disabled="pending" @click="close">取消</c-button>
          <c-button
            v-if="action === 'edit' && !readonly"
            status="danger"
            :disabled="pending"
            @click="remove"
            >删除</c-button
          >
          <c-button
            v-if="!readonly"
            html-type="submit"
            status="primary"
            :loading="pending"
            >保存计划</c-button
          >
        </c-space>
      </c-form>
    </template>
  </c-scheduler>
</template>
<script setup lang="ts">
import { ref } from "vue";
import { schedulerDate } from "@cedar-design/ui/scheduler/core";
import type { SchedulerEvent, SchedulerBeforeChange } from "@cedar-design/ui";
const events = ref<SchedulerEvent[]>([
  {
    id: "plan",
    title: "交付验收",
    start: "2026-09-09T09:00:00",
    end: "2026-09-09T10:00:00",
    description: "确认验收清单",
  },
]);
const reject = ref(false);
const beforeChange: SchedulerBeforeChange = async () => {
  if (reject.value) throw new Error("模拟接口拒绝");
  return true;
};
</script>
```

### 完全自定义弹窗 / 页面

设置 `editable=false` 后，工具栏新增、空白格点击、卡片拖入和已有日程点击统一通过 `editor-request` 交给业务方。组件不打开内置 Drawer，也不自动保存。`request.event` 已带生成的 ID、日期/时间和资源；`source` 标明来源，`readonly` 用于只读详情。

Example source: src/scheduler/__demos__/external-editor.vue

```vue
<template>
  <p>
    关闭内置编辑器，统一接收工具栏、日期格、卡片拖入及已有日程请求，使用独立
    Dialog。取消不写入，保存失败保留表单。
  </p>
  <c-checkbox v-model="reject">下一次模拟接口提交失败</c-checkbox>
  <c-scheduler
    ref="scheduler"
    v-model="events"
    :editable="false"
    default-date="2026-09-09"
    default-mode="day"
    :before-change="beforeChange"
    @editor-request="openEditor"
    @change-error="showError"
  >
    <template #sidebar-extra="{ startDrag, cancelDrag, disabled }">
      <c-button
        :draggable="!disabled"
        :disabled="disabled"
        @dragstart="startDrag(card, $event)"
        @dragend="cancelDrag"
        >拖入：现场检查 · 60 分钟</c-button
      >
    </template>
  </c-scheduler>
  <c-dialog
    v-model:open="open"
    :title="request?.action === 'create' ? '业务新增窗口' : '业务详情窗口'"
    :footer="false"
    :closable="!saving"
    :overlay-closable="!saving"
    :esc-to-close="!saving"
  >
    <template v-if="draft">
      <p>请求来源：{{ request?.source }}；业务页面也可接收相同请求。</p>
      <c-alert v-if="errorMessage" status="danger">{{ errorMessage }}</c-alert>
      <c-form :model="draft" layout="vertical" @submit="submit()">
        <c-form-item label="任务名称"
          ><c-input
            v-model="draft.title"
            :disabled="request?.readonly || saving"
        /></c-form-item>
        <c-form-item label="开始"
          ><c-date
            :model-value="draft.start == null ? undefined : schedulerDate(draft.start)"
            @update:model-value="draft.start = $event"
            :show-time="!draft.allDay"
            value-format="Date"
            :disabled="request?.readonly || saving"
        /></c-form-item>
        <c-form-item label="结束（不含）"
          ><c-date
            :model-value="draft.end == null ? undefined : schedulerDate(draft.end)"
            @update:model-value="draft.end = $event"
            :show-time="!draft.allDay"
            value-format="Date"
            :disabled="request?.readonly || saving"
        /></c-form-item>
        <c-form-item label="工作说明"
          ><c-textarea
            v-model="draft.description"
            :disabled="request?.readonly || saving"
        /></c-form-item>
        <c-space>
          <c-button :disabled="saving" @click="open = false">取消</c-button>
          <c-button
            v-if="request?.action === 'edit' && !request.readonly"
            status="danger"
            :disabled="saving"
            @click="submit(true)"
            >删除</c-button
          >
          <c-button
            v-if="!request?.readonly"
            status="primary"
            html-type="submit"
            :loading="saving"
            >确认保存</c-button
          >
        </c-space>
      </c-form>
    </template>
  </c-dialog>
</template>
<script setup lang="ts">
import { ref } from "vue";
import { cloneSchedulerEvent, schedulerDate } from "@cedar-design/ui/scheduler/core";
import type {
  SchedulerInstance,
  SchedulerEvent,
  SchedulerEditorRequest,
  SchedulerEventTemplate,
  SchedulerBeforeChange,
} from "@cedar-design/ui";
const scheduler = ref<SchedulerInstance>();
const events = ref<SchedulerEvent[]>([
  {
    id: "inspection",
    title: "设备例行检查",
    start: "2026-09-09T10:00:00",
    end: "2026-09-09T11:00:00",
  },
]);
const card: SchedulerEventTemplate = {
  title: "现场检查",
  duration: 60,
  description: "核对运行参数",
};
const request = ref<SchedulerEditorRequest>();
const draft = ref<SchedulerEvent>();
const open = ref(false);
const saving = ref(false);
const reject = ref(false);
const errorMessage = ref("");
let snapshot: string | undefined;
function openEditor(value: SchedulerEditorRequest) {
  if (open.value || saving.value) return;
  request.value = value;
  draft.value = cloneSchedulerEvent(value.event);
  snapshot = JSON.stringify(
    events.value.find((item) => item.id === value.event.id),
  );
  errorMessage.value = "";
  open.value = true;
}
const beforeChange: SchedulerBeforeChange = async () => {
  if (reject.value) {
    reject.value = false;
    throw new Error("模拟接口提交失败，请保留草稿直接重试");
  }
  return true;
};
function showError(error: unknown) {
  errorMessage.value = error instanceof Error ? error.message : "保存失败";
}
async function submit(remove = false) {
  if (
    !draft.value ||
    !request.value ||
    request.value.readonly ||
    saving.value ||
    !scheduler.value
  )
    return;
  if (
    draft.value.id !== request.value.event.id ||
    JSON.stringify(events.value.find((item) => item.id === draft.value!.id)) !==
      snapshot
  ) {
    errorMessage.value = "原日程已变化，请关闭并重新打开。";
    return;
  }
  saving.value = true;
  errorMessage.value = "";
  try {
    const success = await scheduler.value.change({
      type: remove
        ? "remove"
        : request.value.action === "create"
          ? "create"
          : "update",
      event: cloneSchedulerEvent(draft.value),
    });
    if (success) open.value = false;
    else if (!errorMessage.value)
      errorMessage.value = "保存被取消或当前不可提交，请重试。";
  } finally {
    saving.value = false;
  }
}
</script>
```

示例中的“下一次模拟接口提交失败”只拒绝一次保存或删除，随后自动复位；失败时 Dialog 保留草稿，保存可直接再次确认，删除可再次点击删除，无需关闭窗口操作外部开关。取消则丢弃未保存草稿。

业务方可以使用 Dialog、独立路由或其他表单。确认时调用 `change({ type: request.action === 'create' ? 'create' : 'update', event })`，等待返回 `true` 后关闭；返回 `false` 时保留表单，可监听 `change-error` 显示错误。删除已有日程使用 `type: 'remove'`。

只绑定 `editor-request` 来打开外部表单，不要再通过 `cell-click` / `event-click` 打开一次。内置编辑模式不触发 `editor-request`。工具栏和拖入不是格子点击，不触发 `cell-click`。

外部页面自己管理取消、重复打开、提交中禁止关闭、卸载后的响应和编辑快照/版本。示例拒绝覆盖已打开的窗口，并在提交前比对打开时的数据；Scheduler 的 `change()` 只检查提交过程中的并发变化，不代替业务页面打开期间的版本校验。真正跨路由的表单还需自行持久化草稿并对接服务端，不能在 Scheduler 卸载后继续调用旧实例。

### 多选、批量操作与撤销重做

Example source: src/scheduler/__demos__/batch-history.vue

```vue
<template>
  <c-space direction="column" block>
    <c-alert
      >开启“多选”后点击日程卡片，可整批后移一天、添加资源或删除。共享日程在多个资源列中只计为一项；撤销和重做同样经过保存接口。</c-alert
    >
    <c-checkbox v-model="reject">模拟整批保存失败</c-checkbox>
    <c-scheduler
      v-model="events"
      v-model:selected-keys="selected"
      default-date="2026-09-09"
      default-mode="resource-timeline"
      :resources="resources"
      selectable
      history
      :before-transaction="persist"
    />
    <c-tag>{{ status }}</c-tag>
  </c-space>
</template>
<script setup lang="ts">
import { ref } from "vue";
import type { SchedulerBeforeTransaction } from "../props";
import { createEvents, resources } from "./data";
const events = ref(createEvents());
const selected = ref<string[]>([]);
const reject = ref(false);
const status = ref("尚未提交");
const persist: SchedulerBeforeTransaction = async (context) => {
  status.value = `正在提交 ${context.changes.length} 项变更…`;
  await new Promise((resolve) => setTimeout(resolve, 350));
  if (reject.value) {
    status.value = "整批保存失败，日程和历史均保留";
    throw new Error("Demo rejected");
  }
  status.value = `已提交 ${context.changes.length} 项变更（${context.action === "undo" ? "撤销" : context.action === "redo" ? "重做" : "修改"}）`;
};
</script>
```

### 原子事务交换

Example source: src/scheduler/__demos__/atomic-swap.vue

```vue
<template>
  <c-space direction="column" block>
    <c-alert
      >会议室禁止重叠。两条日程可以通过一次事务交换时间；整体校验最终结果，任一项失败都不会改变另一项。</c-alert
    >
    <c-button @click="swap">交换两个会议的时间</c-button>
    <c-scheduler
      ref="scheduler"
      v-model="events"
      default-date="2026-09-09"
      default-mode="resource-day"
      :resources="[{ id: 'room', label: '会议室 A' }]"
      :allow-overlap="false"
      history
    />
  </c-space>
</template>
<script setup lang="ts">
import { ref } from "vue";
import type { SchedulerEvent } from "../core";
import type { SchedulerInstance } from "../index";
const scheduler = ref<SchedulerInstance>();
const events = ref<SchedulerEvent[]>([
  {
    id: "a",
    title: "产品评审",
    start: "2026-09-09T09:00:00",
    end: "2026-09-09T10:00:00",
    resourceIds: ["room"],
  },
  {
    id: "b",
    title: "技术评审",
    start: "2026-09-09T10:00:00",
    end: "2026-09-09T11:00:00",
    resourceIds: ["room"],
  },
]);
async function swap() {
  const [a, b] = events.value;
  await scheduler.value?.transaction([
    { type: "move", event: { ...a, start: b.start, end: b.end } },
    { type: "move", event: { ...b, start: a.start, end: a.end } },
  ]);
}
</script>
```

### 批量与事务约定

| 属性                                  | 说明                                                        | 默认值 |
| ------------------------------------- | ----------------------------------------------------------- | ------ |
| selectable                            | 展示多选模式开关；开启模式后点击卡片切换选中，暂停卡片拖拽  | false  |
| selected-keys / default-selected-keys | 选中日程 ID，支持 `v-model:selected-keys`；共享日程只计一次 | 空数组 |
| history                               | 开启本地撤销/重做，展示工具栏                               | false  |
| history-limit                         | 最多保留历史条数，正整数                                    | 20     |
| before-transaction                    | 一次性校验或保存整笔事务；返回 false 取消，异常保留数据     | —      |

| 实例方法                                 | 说明                                                                |
| ---------------------------------------- | ------------------------------------------------------------------- |
| `transaction(changes): Promise<boolean>` | 原子提交多条 create/update/remove/move/resize；每个 ID 只能出现一次 |
| `undo(): Promise<boolean>`               | 撤销最近一次已接受变更，重新经过规则与保存钩子                      |
| `redo(): Promise<boolean>`               | 重做最近一次撤销                                                    |
| `canUndo` / `canRedo`                    | 当前是否允许撤销/重做                                               |

新增 `transaction(value, context)` 与 `transaction-error(error, context)` 事件；context 包含 `action`（change/undo/redo）、`changes`、`previousValue` 和 `value`。原单条 `change` / `change-error` 事件仅在事务含一条变更时触发，多条变更不会逐条触发这些事件。

**保存钩子约定：**设置 `before-transaction` 后，它统一接管单条、批量、撤销和重做，替代 `before-change`，避免同一操作保存两次。只有 `before-change` 的旧应用保持单条行为；执行多条事务会明确返回 `transaction-hook-required`，请迁移到一次性的原子保存接口。前端原子提交不能替代后端数据库事务。

```ts
import type { SchedulerBeforeTransaction } from "@cedar-design/ui";
const beforeTransaction: SchedulerBeforeTransaction = async (context) => {
  // 在这里向业务后端提交整个 context.changes；失败抛错或返回 false。
  // 后端应对整批变更校验版本、权限和最终资源占用，再原子保存。
};
```

批量后移保留本地时分；包含未排期任务时整批拒绝，避免静默遗漏。添加资源为追加去重，不替换其他参与人。只读成员、禁用资源、工作时间和维护冲突均会阻止整批操作。

受控模式中，父组件接受对应 `update:model-value` 后才记录历史；若父组件不接受，撤销不可用。父组件接受的数据若与提案不同（例如服务端重写字段），视为外部更新并清空本地历史。其他外部数据更新也会清空历史，避免覆盖别人或后端的修改。规则变更不会清空历史，但撤销必须通过当前规则。关闭 history 清空历史，新的成功变更清空重做分支。历史只属于当前组件实例，不是多人协作版本历史。

### 拖选、吸附间隔与月历更多日程

Example source: src/scheduler/__demos__/interaction-completion.vue

```vue
<template>
  <c-space direction="column" block>
    <c-alert
      >周视图空白处拖选创建，支持向上拖选；网格 60 分钟，指针吸附 15
      分钟，单击新建默认 45 分钟。月视图每天先显示 2
      条，可点击“更多日程”。</c-alert
    >
    <c-space
      ><c-button @click="mode = 'week'">拖选排期</c-button
      ><c-button @click="mode = 'month'">查看月历更多日程</c-button></c-space
    >
    <c-scheduler
      v-model="events"
      v-model:mode="mode"
      default-date="2026-09-22"
      :slot-duration="60"
      :snap-duration="15"
      :default-duration="45"
      :month-event-limit="2"
      drag-to-create
      history
    />
  </c-space>
</template>
<script setup lang="ts">
import { ref } from "vue";
import type { SchedulerEvent, SchedulerMode } from "../core";
const mode = ref<SchedulerMode>("week");
const events = ref<SchedulerEvent[]>(
  Array.from({ length: 5 }, (_, i) => ({
    id: `sample${i}`,
    title: `任务 ${i + 1}`,
    start: `2026-09-22T${String(i + 9).padStart(2, "0")}:00:00`,
    end: `2026-09-22T${String(i + 10).padStart(2, "0")}:00:00`,
  })),
);
</script>
```

`drag-to-create` 在日、周、资源日程的空白时段启用指针拖选，支持同一列内向前或向后选择。释放后打开创建表单；Escape、失焦或禁用取消。单击和键盘激活仍可创建日程。

触屏拖动日程、调整起止时间或拖选空白时段需要长按 350ms。长按生效前移动超过 8px 会取消排期手势，把操作留给页面滚动；鼠标仍保持 5px 移动阈值，无需等待。粗指针设备上的上下缩放热区扩大到至少 14px，视觉线条尺寸不变。

焦点位于日程、时间单元格、月视图日期或“还有 N 项”入口时，方向键会按屏幕中的上下左右位置移动到最近的可用日历控件。Enter/Space 沿用 Cedar Button 的原生激活行为；禁用项和不可见项会被跳过。导航只在日历内容区生效，不接管工具栏、编辑器及表单输入。关闭内置编辑器后焦点返回原触发控件；若该日程已删除或视图已变化，则定位到原位置附近的可用日历控件，最终回退到 Scheduler 容器。

`slot-duration` 控制网格分钟数，`snap-duration` 控制指针吸附，`default-duration` 控制单击新建时长，均省略时回退旧 `step`。例如 60 / 15 / 45 表示一小时格、15 分钟吸附、45 分钟默认任务。拖选使用选择区间；外部模板的 duration 优先。指针拖动时间线也按吸附间隔定位；吸附以当前单元格真实开始时间为锚点。

月视图默认每天直接显示 3 条日程，固定单元格高度；超出时显示“还有 N 项”。点击后使用 Cedar Popover 展示当天全部日程，选择其中一项可进入详情。`month-event-limit` 可调整直接展示数量；隐藏周末仍沿用真实日期。

### 依赖、里程碑与时间线缩放

Example source: src/scheduler/__demos__/advanced-planning.vue

```vue
<template>
  <c-space direction="column" block>
    <c-alert
      >准备 → 执行 →
      验收里程碑。依赖连线在时间线中展示；把执行拖到准备完成前会被阻止。里程碑使用相同起止时间，不占用资源容量。缩放按钮以视口中心为锚点调整刻度宽度。</c-alert
    >
    <c-scheduler
      v-model="events"
      default-date="2026-09-22"
      default-mode="resource-timeline"
      default-scale="hour"
      :resources="resources"
      :dependencies="dependencies"
      show-resource-load
      history
    />
  </c-space>
</template>
<script setup lang="ts">
import { ref } from "vue";
import type { SchedulerEvent, SchedulerDependency } from "../core";
const resources = [{ id: "team", label: "执行团队", capacity: 1 }];
const dependencies: SchedulerDependency[] = [
  { id: "prepare-run", fromId: "prepare", toId: "run" },
  { id: "run-accept", fromId: "run", toId: "accept" },
];
const events = ref<SchedulerEvent[]>([
  {
    id: "prepare",
    title: "准备",
    start: "2026-09-22T09:00:00",
    end: "2026-09-22T10:00:00",
    resourceIds: ["team"],
  },
  {
    id: "run",
    title: "执行",
    start: "2026-09-22T10:00:00",
    end: "2026-09-22T12:00:00",
    resourceIds: ["team"],
  },
  {
    id: "accept",
    title: "验收里程碑",
    start: "2026-09-22T12:00:00",
    end: "2026-09-22T12:00:00",
    milestone: true,
    resourceIds: ["team"],
  },
]);
</script>
```

`dependencies` 为 `{id, fromId, toId, type?, lag?}[]`，支持 finish-to-start（默认）、start-to-start、finish-to-finish、start-to-finish，lag 为实际经过分钟数，可为负。纯函数 `getSchedulerDependencyIssues` 返回无效配置、缺失端点、循环和时间顺序问题；提交使用最终事务状态校验，失败返回 dependency 错误。尚未排期的端点不检查时间顺序。删除事件前需先移除相关依赖。

资源时间线为当前已挂载的两端绘制依赖连线；虚拟列表中一端不在视口时不绘制。此功能不会自动重排其他任务。`milestone: true` 表示定时零时长里程碑，必须 start=end，不支持全天或未排期；以 ◆ 显示，不占容量，可移动而不能拉伸。

`zoom/default-zoom/update:zoom` 控制 0.5–4 倍时间线缩放，工具栏提供放大缩小；以当前视口中心的时间为锚调整横向位置。`show-date-header` 默认开启日期分组表头。资源名称在横向滚动时固定。

## 异步加载与保存

### 异步目录、分页与 ID 回显

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `default-mode` | 非受控默认视图 | 异步目录、分页与 ID 回显、按范围远程加载、异步保存 |
| `resources` | 当前可见资源行/列及本地选项，不要求全量目录 | 异步目录、分页与 ID 回显、异步保存 |
| `before-change` | 返回 false 取消；异步拦截、保存接口 | 异步目录、分页与 ID 回显、异步保存 |
| `default-date` | 初始定位日期 | 异步目录、分页与 ID 回显、异步保存 |
| `resource-label` | 资源字段名称，如设备、会议室 | 异步目录、分页与 ID 回显 |
| `request-resources` | 按关键词和游标查询候选资源 | 异步目录、分页与 ID 回显 |
<!-- demo-config-notes:end -->

示例可切换设备接口和人员接口。仅提供当前 4 条可见资源，而已有日程关联第 12 条，通过 `resolve-resources` 单独回显。打开资源下拉框后远程搜索、滚动或点击加载更多；搜索结果不会添加资源视图的行/列。可模拟搜索与回显失败，查看 ID 保留及重试。

示例状态文案按当前请求更新：回显或搜索失败后，成功重试会清除旧失败提示；切换设备/人员接口会重置示例反馈。失败和重试都不会将资源显示名称写进日程，关联仍只存稳定 ID。

Example source: src/scheduler/__demos__/async-resources.vue

```vue
<template>
  <c-space direction="column" align="stretch" wrap>
    <c-form-item layout="vertical" hide-label>
      <c-select
        v-model="kind"
        :options="[
          { value: 'device', label: '设备接口' },
          { value: 'person', label: '人员接口' },
        ]"
      />
    </c-form-item>
    <c-button @click="failNextSearch = true">下次搜索模拟失败</c-button>
    <c-button @click="retryHydration">模拟回显失败并重新加载</c-button>
    <c-button @click="useNextPage">切换可见资源页</c-button>
  </c-space>
  <p>
    当前仅提供 {{ visibleResources.length }} 条可见资源。已有日程关联第 12
    条，不在本页，仍通过 ID 接口回显名称。进入编辑器，搜索“12”或滚动加载更多。
  </p>
  <p role="status">{{ feedback }}</p>
  <c-scheduler
    :key="`${kind}-${revision}`"
    v-model="events"
    :resources="visibleResources"
    :resource-label="kind === 'device' ? '设备' : '人员'"
    :request-resources="requestResources"
    :resolve-resources="resolveResources"
    :before-change="beforeChange"
    default-mode="agenda"
    default-date="2026-09-09"
    @resource-error="resourceError"
  />
</template>
<script setup lang="ts">
import { computed, onScopeDispose, ref, watch } from "vue";
import type {
  SchedulerEvent,
  SchedulerRequestResources,
  SchedulerResolveResources,
  SchedulerBeforeChange,
  SchedulerResourceErrorContext,
} from "@cedar-design/ui";

const kind = ref<"device" | "person">("device");
// 业务接口字段在接入层适配，Scheduler 始终只认识 id / label。
const devices = Array.from({ length: 24 }, (_, index) => ({
  deviceId: `device-${index + 1}`,
  deviceName: `实验设备 ${index + 1}`,
}));
const people = Array.from({ length: 24 }, (_, index) => ({
  userId: `person-${index + 1}`,
  displayName: `工程师 ${index + 1}`,
}));
const directory = computed(() =>
  kind.value === "device"
    ? devices.map((item) => ({ id: item.deviceId, label: item.deviceName }))
    : people.map((item) => ({ id: item.userId, label: item.displayName })),
);
const page = ref(0);
const revision = ref(0);
const visibleResources = computed(() =>
  directory.value.slice(page.value * 4, page.value * 4 + 4),
);
const events = ref<SchedulerEvent[]>([]);
const feedback = ref("打开详情查看名称回显，或在资源下拉框搜索。");
const failNextSearch = ref(false);
const failNextResolve = ref(false);
const failedOperation = ref<"search" | "resolve">();
watch(
  kind,
  () => {
    failedOperation.value = undefined;
    feedback.value = "打开详情查看名称回显，或在资源下拉框搜索。";
    page.value = 0;
    events.value = [
      {
        id: `${kind.value}-job`,
        title: "已有排期：关联不在本页的资源",
        start: "2026-09-09T09:00:00",
        end: "2026-09-09T10:00:00",
        resourceIds: [`${kind.value}-12`],
      },
    ];
  },
  { immediate: true, flush: "sync" },
);

const lifetime = new AbortController();
onScopeDispose(() => lifetime.abort());
// 模拟接口延时；真实接入时直接 fetch(url, { signal })。
function delay(signal: AbortSignal) {
  return new Promise<void>((resolve, reject) => {
    if (signal.aborted) {
      reject(new Error("Aborted"));
      return;
    }
    const abort = () => {
      clearTimeout(timer);
      signal.removeEventListener("abort", abort);
      reject(new Error("Aborted"));
    };
    const timer = setTimeout(() => {
      signal.removeEventListener("abort", abort);
      resolve();
    }, 500);
    signal.addEventListener("abort", abort, { once: true });
  });
}
const requestResources: SchedulerRequestResources = async ({
  query,
  cursor,
  signal,
}) => {
  const data = directory.value;
  const fail = failNextSearch.value;
  failNextSearch.value = false;
  await delay(signal);
  if (fail) throw new Error("模拟搜索网络错误");
  const matches = data.filter(
    (item) => item.label.includes(query) || item.id.includes(query),
  );
  const offset = Number(cursor ?? 0);
  if (failedOperation.value === "search") {
    failedOperation.value = undefined;
    feedback.value = "搜索重试成功，可继续选择资源。";
  }
  return {
    items: matches.slice(offset, offset + 4),
    nextCursor: offset + 4 < matches.length ? String(offset + 4) : undefined,
  };
};
const resolveResources: SchedulerResolveResources = async (ids, { signal }) => {
  const data = directory.value;
  const fail = failNextResolve.value;
  failNextResolve.value = false;
  await delay(signal);
  if (fail) throw new Error("模拟回显网络错误");
  if (failedOperation.value === "resolve") {
    failedOperation.value = undefined;
    feedback.value = "资源名称回显成功，关联 ID 保持不变。";
  }
  return data.filter((item) => ids.includes(item.id));
};
const beforeChange: SchedulerBeforeChange = async ({ event, type }) => {
  const data = directory.value;
  await delay(lifetime.signal);
  // 演示服务端校验；生产环境还应验证权限、版本和全量时段冲突。
  if (
    type !== "remove" &&
    event.resourceIds?.some((id) => !data.some((item) => item.id === id))
  )
    throw new Error("资源不存在");
  feedback.value = "模拟接口保存成功，日程只保存 resourceIds，不保存显示名称。";
};
function resourceError(
  _error: unknown,
  context: SchedulerResourceErrorContext,
) {
  failedOperation.value = context.type;
  feedback.value =
    context.type === "resolve"
      ? "回显失败：ID 仍保留，点击日程内的重试按钮。"
      : "搜索失败：可在下拉框内重试。";
}
function retryHydration() {
  failNextResolve.value = true;
  revision.value++;
}
function useNextPage() {
  page.value = (page.value + 1) % 6;
}
</script>
```

日程只保存 `resourceIds`；`id` 是稳定标识，`label` 是显示名称。业务层把 `userId/displayName`、`deviceId/deviceName` 等接口字段映射为 `{ id, label }`。不要把名称当 ID，也不要为了回显把全量目录放进 `resources`。

| 数据入口          | 职责                                                                |
| ----------------- | ------------------------------------------------------------------- |
| resources         | 当前资源视图的行/列及本地候选项，可以是部分目录；同 ID 时优先于缓存 |
| request-resources | 远程搜索与游标分页，返回候选项，不修改可见行/列                     |
| resolve-resources | 根据已有 ID 批量加载名称，不依赖当前搜索页                          |
| before-change     | 对接服务端有效性、权限、全量冲突与保存校验                          |

```ts
import type {
  SchedulerRequestResources,
  SchedulerResolveResources,
} from "@cedar-design/ui";

const requestResources: SchedulerRequestResources = async ({
  query,
  cursor,
  signal,
}) => {
  const params = new URLSearchParams({ query });
  if (cursor !== undefined) params.set("cursor", cursor);
  const response = await fetch(`/api/devices?${params}`, { signal });
  if (!response.ok) throw new Error("设备查询失败");
  const page = await response.json();
  return {
    items: page.items.map((item) => ({
      id: String(item.deviceId),
      label: item.deviceName,
    })),
    nextCursor: page.nextCursor, // 没有下一页时省略；游标使用非空字符串
  };
};

const resolveResources: SchedulerResolveResources = async (ids, { signal }) => {
  const response = await fetch("/api/devices/by-ids", {
    method: "POST",
    signal,
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ ids }),
  });
  if (!response.ok) throw new Error("设备回显失败");
  const items = await response.json();
  return items.map((item) => ({
    id: String(item.deviceId),
    label: item.deviceName,
  }));
};
```

同一实例缓存回显结果，并合并请求中的重复 ID；不在实例之间共用数据。搜索更换关键词会取消旧请求，即使接口未响应取消信号也忽略过期结果。切换 `resolve-resources` 回调会清空回显缓存；切换租户/目录建议给 Scheduler 设置不同 `key`，隔离搜索结果、缓存和编辑草稿。

回显查不到或失败时保留原 ID 并用 ID 显示，不会清空日程关联或禁止保存。失败触发 `resource-error`；可通过提示按钮或重新打开选择器重试。远程请求只影响资源控件的加载状态，不锁住整个日程。

当前未加载的资源不等于无效资源。已知 `disabled` 的资源不能新增分配，已有关联可保留/移除；保存期间新增分配的资源变为禁用会阻止保存，但目录翻页、补全名称不会使保存过期。`allow-overlap=false` 仅检查已加载日程，全量冲突和权限必须由服务端校验。

### 按范围远程加载

Example source: src/scheduler/__demos__/remote-events.vue

```vue
<template>
  <c-space direction="column" block>
    <c-alert
      >翻页按可见范围请求；返回已访问日期命中 30
      秒缓存。可模拟失败后重试，也可连续切换日期，验证慢响应不会覆盖最新页面。</c-alert
    >
    <c-space wrap>
      <c-button @click="refresh()">刷新 / 重试</c-button>
      <c-button @click="jump(1)">下一天</c-button>
      <c-button @click="jump(-1)">上一天</c-button>
      <c-checkbox v-model="fail">模拟加载失败</c-checkbox>
      <c-checkbox v-model="outOfOrder">模拟乱序响应</c-checkbox>
    </c-space>
    <c-space wrap>
      <c-tag>请求 {{ requests }} 次</c-tag>
      <c-tag>{{
        loading
          ? "加载中"
          : error
            ? "加载失败，请重试"
            : `已加载 ${events.length} 项`
      }}</c-tag>
      <c-tag>{{ status }}</c-tag>
    </c-space>
    <c-scheduler
      v-model="events"
      v-model:date="date"
      default-mode="day"
      :readonly="loading || !!error"
      :before-transaction="persist"
      @range-change="range = $event"
    />
  </c-space>
</template>
<script setup lang="ts">
import { ref } from "vue";
import { useSchedulerDataSource } from "../use-data-source";
import {
  applySchedulerTransaction,
  cloneSchedulerEvent,
  isSchedulerEventInRange,
  schedulerDate,
} from "../core";
import type { SchedulerDate, SchedulerEvent, SchedulerRange } from "../core";
import type { SchedulerBeforeTransaction } from "../props";
const date = ref<SchedulerDate>("2026-09-09");
const range = ref<SchedulerRange>();
const fail = ref(false);
const outOfOrder = ref(false);
const requests = ref(0);
const status = ref("编辑日程会保存到模拟服务端");
let database: SchedulerEvent[] = Array.from({ length: 90 }, (_, index) => ({
  id: `remote-${index}`,
  title: `远程计划 ${index + 1}`,
  start: new Date(2026, 7, 15 + index, 9),
  end: new Date(2026, 7, 15 + index, 10),
}));
const { events, loading, error, refresh } = useSchedulerDataSource({
  range,
  requestEvents: async (query) => {
    const sequence = ++requests.value;
    const shouldFail = fail.value;
    const ignoreAbort = outOfOrder.value;
    const result = database
      .filter((event) => isSchedulerEventInRange(event, query))
      .map(cloneSchedulerEvent);
    await new Promise<void>((resolve, reject) => {
      const abort = () => {
        clearTimeout(timer);
        reject(new Error("Aborted"));
      };
      const timer = setTimeout(
        () => {
          query.signal.removeEventListener("abort", abort);
          resolve();
        },
        ignoreAbort ? (sequence % 2 ? 1800 : 200) : 450,
      );
      if (!ignoreAbort)
        query.signal.addEventListener("abort", abort, { once: true });
    });
    if (shouldFail) throw new Error("模拟接口失败");
    return result;
  },
});
function jump(offset: number) {
  const next = schedulerDate(date.value);
  next.setDate(next.getDate() + offset);
  date.value = next;
}
const persist: SchedulerBeforeTransaction = async (context) => {
  // Send the delta to the backend, never replace the full database with a loaded window.
  database = applySchedulerTransaction(database, context.changes);
  status.value = `已保存 ${context.changes.length} 项变更；查询缓存随 v-model 更新失效`;
};
</script>
```

`useSchedulerDataSource` 独立负责加载，不改变 Scheduler 的 `v-model` 数据所有权。将 `range-change` 写入范围 ref，将返回的 `events` 绑定到组件。需要避免在加载中或失败后编辑时，由业务设置 `readonly="loading || !!error"`；整块占位可在外层使用 Loading。

```ts
import { ref } from "vue";
import { useSchedulerDataSource } from "@cedar-design/ui";
import type { SchedulerRange } from "@cedar-design/ui";

const range = ref<SchedulerRange>();
const { events, loading, error, refresh } = useSchedulerDataSource({
  range,
  requestEvents: async ({ start, end, resourceIds, signal }) => {
    const params = new URLSearchParams({
      start: start.toISOString(),
      end: end.toISOString(),
      resourceIds: resourceIds.join(","),
    });
    const response = await fetch(`/api/events?${params}`, { signal });
    if (!response.ok) throw new Error("加载失败");
    return response.json();
  },
});
```

| 选项            | 说明                                                                                                  |
| --------------- | ----------------------------------------------------------------------------------------------------- |
| requestEvents   | 查询函数或其 ref，接收 start、end、resourceIds、AbortSignal，返回日程数组或 Promise；切换函数清空缓存 |
| range           | 范围、ref 或 getter；undefined 暂停并清空当前数据                                                     |
| resourceIds     | 可选数组、ref 或 getter；去重排序后作为查询条件，空数组表示不限资源                                   |
| enabled         | 可选 boolean、ref 或 getter，默认 true；false 取消加载并清空当前数据                                  |
| cacheTime       | 缓存有效毫秒数，默认 30000，0 禁用                                                                    |
| maxCacheEntries | LRU 缓存条数上限，默认 20，0 禁用                                                                     |

返回 `events`（可写 ref）、`loading`、`error`、`loadedRange`（最后成功发布的范围）、`refresh()`（绕过当前缓存并返回成功与否）、`cancel()`（保留已发布数据，终止当前请求）、`invalidate()`（仅清空全部缓存）。在组件 setup 或 effectScope 中调用；SSR 不自动请求。

范围为 `[start, end)`：接口应返回与范围相交的完整日程，不截断跨日事件，不返回仅第一页。资源筛选条件由业务同步传入；组件内部资源筛选不会自动改变加载器条件。未排期任务可由业务接口额外包含在返回数组中。

切换范围会清空旧窗口并取消旧请求，即使接口忽略 AbortSignal，过期响应也不会覆盖最新结果。失败通过 `error` 暴露，点击刷新重试。查询结果会整体校验，重复 ID 或无效日程不会部分发布。缓存以精确范围和资源条件区分；通过 `v-model` 替换或响应式原位编辑会取消在途加载并清空缓存。Date 的原生 set 方法不会触发 Vue 响应式，请替换日期值。

加载器不执行保存。继续使用 `before-transaction` 向服务端提交 `context.changes`；不要将当前窗口的 `context.value` 当作全库替换。全局冲突、权限及原子保存由服务端校验。切换窗口属于外部数据更新，会使组件本地撤销历史失效。

### 异步保存

before-change 返回 false 取消，抛错或拒绝 Promise 会触发 change-error 并保留原数据。期间组件禁止重复变更。如果外部数据或权限变化，旧提案失效。服务端仍需原子校验权限、版本和资源冲突。

Example source: src/scheduler/__demos__/async-change.vue

```vue
<template>
  <section class="scheduler-async-demo">
    <c-space direction="column" block>
      <c-space>
        <c-checkbox v-model="reject">下一次模拟保存失败</c-checkbox>
        <c-checkbox v-model="accept">父组件接受更新</c-checkbox>
        <c-button @click="reset">重置日程</c-button>
      </c-space>
      <p>
        本地模拟 600ms
        保存；失败开关在一次失败后自动复位，可直接重试。取消或父组件拒绝提案不改变已保存值。
      </p>
      <c-scheduler
        :model-value="events"
        default-date="2026-09-09"
        default-mode="resource-day"
        :resources="resources"
        :before-change="beforeChange"
        @update:model-value="update"
        @change="outcome = accept ? '父组件已接受' : '父组件未接受提案'"
        @change-error="outcome = '保存失败，原值不变'"
      />
      <p role="status">{{ outcome }}；活动请求：{{ pendingCount }}</p>
      <ul aria-label="异步已提交日程">
        <li v-for="event in events" :key="event.id" :data-demo-event="event.id">
          {{ event.title }}：{{ event.start ?? "未排期" }} →
          {{ event.end ?? "未排期" }}；资源：{{ event.resourceIds?.join(",") }}
        </li>
      </ul>
    </c-space>
  </section>
</template>
<script setup lang="ts">
import { onBeforeUnmount, onDeactivated, ref } from "vue";
import type { SchedulerBeforeChange } from "../props";
import type { SchedulerEvent } from "../core";
import { createEvents, resources } from "./data";
const events = ref(createEvents());
const reject = ref(false);
const accept = ref(true);
const outcome = ref("尚未操作");
const pendingCount = ref(0);
const pending = new Map<ReturnType<typeof setTimeout>, () => void>();
const beforeChange: SchedulerBeforeChange = () =>
  new Promise<boolean>((resolve, rejectRequest) => {
    const fail = reject.value;
    const timer = setTimeout(() => {
      pending.delete(timer);
      pendingCount.value = pending.size;
      if (fail) {
        reject.value = false;
        rejectRequest(new Error("模拟接口失败"));
      } else resolve(true);
    }, 600);
    pending.set(timer, () => resolve(false));
    pendingCount.value = pending.size;
  });
function update(value: SchedulerEvent[]) {
  if (accept.value) events.value = value;
}
function cancelPending() {
  pending.forEach((cancel, timer) => {
    clearTimeout(timer);
    cancel();
  });
  pending.clear();
  pendingCount.value = 0;
}
function reset() {
  cancelPending();
  events.value = createEvents();
  outcome.value = "已重置";
}
onBeforeUnmount(cancelPending);
onDeactivated(cancelPending);
</script>
```

示例只使用本地 600ms 模拟保存。“下一次模拟保存失败”仅失败一次后自动复位，可在保留草稿的编辑器中直接重试。“父组件接受更新”关闭后，验证通过仍只是提案，下方模型明细和卡片保持已保存值；取消编辑也不写入。卸载、停用或重置清理示例请求计时器。

## 业务组合与集成

### 设备排期与工单

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `resources` | 当前可见资源行/列及本地选项，不要求全量目录 | 设备排期与工单、出勤详情、打卡与关单、任务日历组合工作台 |
| `default-mode` | 非受控默认视图 | 设备排期与工单、外部日历、模拟协同、ICS 与打印、出勤详情、打卡与关单 |
| `default-date` | 初始定位日期 | 设备排期与工单、外部日历、模拟协同、ICS 与打印、出勤详情、打卡与关单 |
| `editable` | 启用内置编辑器；false 通过 editor-request 接管 | 出勤详情、打卡与关单、任务日历组合工作台 |
| `start-hour` | 时间网格起始小时，0–23 | 出勤详情、打卡与关单、任务日历组合工作台 |
| `end-hour` | 时间网格结束小时，必须大于起始，最多 24 | 出勤详情、打卡与关单、任务日历组合工作台 |
<!-- demo-config-notes:end -->

相同资源 API 用于设备，无人员字段依赖。示例包括工单拖入、双设备联合占用、全天维护、只读日程及本地重叠校验。`resource-label` 自定义显示名称，不改变存储字段。

Example source: src/scheduler/__demos__/equipment.vue

```vue
<template>
  <p>
    设备共享使用时段：拖入左侧任务后确认排期；维护中的设备禁止新增分配，同一设备的时间冲突会阻止保存。
  </p>
  <c-scheduler
    v-model="events"
    :resources="devices"
    resource-label="设备"
    default-mode="resource-day"
    default-date="2026-09-09"
    :allow-overlap="false"
  >
    <template #sidebar-extra="{ startDrag, cancelDrag, disabled }">
      <strong>待安排工单</strong>
      <c-button
        v-for="task in tasks"
        :key="String(task.metadata?.taskId)"
        :draggable="!disabled"
        :disabled="disabled"
        @dragstart="startDrag(task, $event)"
        @dragend="cancelDrag"
      >
        {{ task.title }} · {{ task.duration }} 分钟
      </c-button>
    </template>
    <template #resource-header="{ resource, date }">
      <strong>{{ resource?.label ?? date.toLocaleDateString() }}</strong>
      <small v-if="resource">
        · {{ resource.disabled ? "维护中" : "可预约" }}</small
      >
    </template>
    <template #event="{ event }">
      <strong>{{ event.title }}</strong
      ><span v-if="event.metadata?.taskId">
        · {{ event.metadata?.taskId }}</span
      >
    </template>
  </c-scheduler>
</template>
<script setup lang="ts">
import { ref } from "vue";
import type {
  SchedulerEvent,
  SchedulerResource,
  SchedulerEventTemplate,
} from "@cedar-design/ui";
const devices: SchedulerResource[] = [
  { id: "laser-01", label: "激光切割机 01" },
  { id: "printer-02", label: "3D 打印机 02" },
  { id: "scanner-03", label: "扫描仪 03", disabled: true },
];
const tasks: SchedulerEventTemplate[] = [
  {
    title: "样件加工",
    duration: 90,
    metadata: { taskId: "JOB-201" },
    description: "安排加工设备并确认材料",
  },
  {
    title: "设备校准",
    duration: 30,
    metadata: { taskId: "JOB-202" },
    description: "校准完成后记录结果",
  },
];
const events = ref<SchedulerEvent[]>([
  {
    id: "run-1",
    title: "批次 A 加工",
    start: "2026-09-09T09:00:00",
    end: "2026-09-09T11:00:00",
    resourceIds: ["laser-01"],
    metadata: { taskId: "JOB-100" },
  },
  {
    id: "run-2",
    title: "联合验收（共用两台设备）",
    start: "2026-09-09T14:00:00",
    end: "2026-09-09T15:00:00",
    resourceIds: ["laser-01", "printer-02"],
    metadata: { taskId: "JOB-101" },
  },
  {
    id: "maintenance",
    title: "停机维护",
    start: "2026-09-09",
    end: "2026-09-10",
    allDay: true,
    resourceIds: ["scanner-03"],
    readonly: true,
  },
]);
</script>
```

### 外部日历、模拟协同、ICS 与打印

Example source: src/scheduler/__demos__/calendar-integration.vue

```vue
<template>
  <c-space direction="column" block>
    <c-alert
      >模拟服务端持有版本号：编辑保存延迟
      300ms，期间模拟远端更新会触发过期保护。导入/导出使用真实 ICS
      文本；打印生成独立文档，不打印整页组件文档。</c-alert
    >
    <c-space
      ><c-button @click="remote">模拟远端更新</c-button
      ><c-button @click="exportIcs">导出 ICS 文本</c-button
      ><c-button @click="importIcs">导入 ICS 文本</c-button
      ><c-button @click="print">打印日程</c-button
      ><c-tag>版本 {{ revision }}</c-tag></c-space
    >
    <c-alert v-if="error" status="danger">{{ error }}</c-alert>
    <c-textarea v-model="ical" placeholder="ICS 文本" :rows="4" />
    <c-scheduler
      v-model="events"
      default-date="2026-09-22"
      default-mode="week"
      :before-transaction="save"
      history
    />
  </c-space>
</template>
<script setup lang="ts">
import { ref, onBeforeUnmount } from "vue";
import {
  createSchedulerMemoryProvider,
  exportSchedulerICalendar,
  importSchedulerICalendar,
  createSchedulerPrintHtml,
} from "../adapters";
import type { SchedulerEvent, SchedulerTransactionContext } from "../core";
const events = ref<SchedulerEvent[]>([
  {
    id: "meeting",
    title: "团队会议",
    start: "2026-09-22T09:00:00",
    end: "2026-09-22T10:00:00",
  },
]);
const source = createSchedulerMemoryProvider(events.value),
  revision = ref(0),
  ical = ref(""),
  error = ref("");
const stop = source.subscribe!((snapshot, origin) => {
  if (origin === "editor") return;
  revision.value = snapshot.revision;
  events.value = snapshot.events;
});
onBeforeUnmount(stop);
async function save(context: SchedulerTransactionContext) {
  const expected = revision.value;
  await new Promise((resolve) => setTimeout(resolve, 300));
  const next = await source.commit(context.changes, expected, "editor");
  revision.value = next.revision;
}
async function remote() {
  try {
    await source.commit(
      [
        {
          type: "update",
          event: {
            ...events.value[0],
            title: `远端更新 ${revision.value + 1}`,
          },
        },
      ],
      revision.value,
      "remote",
    );
  } catch (cause) {
    error.value = String(cause);
  }
}
function exportIcs() {
  try {
    ical.value = exportSchedulerICalendar(events.value, {
      stamp: new Date(),
      name: "Cedar demo",
    });
    error.value = "";
  } catch (cause) {
    error.value = String(cause);
  }
}
async function importIcs() {
  try {
    const parsed = importSchedulerICalendar(ical.value, {
      timeZone: "Asia/Shanghai",
    });
    if (parsed.series.length)
      throw new Error("含重复系列，请先通过 RRULE 适配器展开");
    const existing = new Set(events.value.map((event) => event.id));
    await source.commit(
      parsed.events.map((event) => ({
        type: existing.has(event.id) ? "update" : "create",
        event,
      })),
      revision.value,
      "import",
    );
    error.value = "";
  } catch (cause) {
    error.value = String(cause);
  }
}
function print() {
  const page = window.open("", "_blank");
  if (!page) return;
  page.document.open();
  page.document.write(
    createSchedulerPrintHtml(events.value, { title: "团队日程" }),
  );
  page.document.close();
  page.focus();
  page.print();
}
</script>
```

`SchedulerCalendarProvider` 定义 load(range, signal)、commit(changes, expectedRevision, origin?) 与可选 subscribe。`createSchedulerMemoryProvider` 为离线示例实现：校验递增版本、发布分离快照、可注销订阅。真实服务需实现认证、持久化、权限与完整业务校验。示例用 origin 忽略自己的回声，外部更新仍触发 Scheduler 的过期保护；内部事务用本地单调版本检测等待期间数据变化。

`exportSchedulerICalendar(events, {stamp, name?})` 导出 UTC 定时事件和 DATE 全天事件，正确转义文本并按 UTF-8 75 字节折行；未排期事件明确拒绝。`importSchedulerICalendar(text, {timeZone?, disambiguation?})` 返回普通 events 与 RRULE 种子 series；要求 UID/DTSTART/DTEND。支持 UTC/IANA TZID/指定时区的浮动时间。全天 RRULE、自定义 VTIMEZONE、RECURRENCE-ID、RDATE/EXDATE/EXRULE、DURATION 及重复 UID 会明确拒绝，交由专用提供方适配，避免导入后语义丢失。

`createSchedulerPrintHtml(events, options?)` 返回独立可打印 HTML，含完整转义、重复表头及跨页设置。调用方决定打开、保存或打印；示例的打印按钮只打印此文档。

### 出勤详情、打卡与关单

Example source: src/scheduler/__demos__/task-calendar-details.vue

```vue
<template>
  <c-alert>
    点击日程先查看业务摘要，再进入高级详情。完整出勤单、任务与打卡记录由页面按
    metadata ID 查询，Scheduler 只保存展示字段和业务 ID。
  </c-alert>
  <c-scheduler
    v-model="events"
    :editable="false"
    :resources="resources"
    default-date="2026-09-09"
    default-mode="resource-day"
    :start-hour="0"
    :end-hour="24"
    :initial-scroll-minute="420"
    :modes="['resource-day']"
    :show-sidebar="false"
    @editor-request="activate"
  >
    <template #event="{ event }">
      <EventSummaryPopover
        :open="previewId === event.id"
        :title="event.title"
        @update:open="!$event && (previewId = undefined)"
        @click-outside="previewId = undefined"
      >
        <span :class="{ 'completed-event': event.readonly }">
          {{ event.title }} · {{ personLabel(event) }}
        </span>
        <template #content>
          <c-space v-if="orderOf(event)" direction="column" block>
            <c-space>
              <c-tag>{{ statusLabel(orderOf(event)!) }}</c-tag>
              <c-tag>{{ orderOf(event)!.source }}</c-tag>
            </c-space>
            <strong>{{ timeRange(event) }}</strong>
            <span>
              {{ orderOf(event)!.tasks.length }} 项任务 ·
              {{ totalMinutes(orderOf(event)!) }} 分钟 · 1 人
            </span>
            <span>设备：{{ deviceLabels(orderOf(event)!) }}</span>
            <span>最近打卡：{{ latestPunch(orderOf(event)!) }}</span>
            <c-space>
              <c-button status="primary" @click.stop="openDetails(event)">
                高级详情
              </c-button>
              <c-button @click.stop="previewId = undefined">关闭</c-button>
            </c-space>
          </c-space>
        </template>
      </EventSummaryPopover>
    </template>
  </c-scheduler>

  <c-dialog v-model:open="detailsOpen" title="出勤单高级详情" :footer="false">
    <template v-if="activeOrder">
      <c-space direction="column" block>
        <c-space>
          <c-tag>{{ statusLabel(activeOrder) }}</c-tag>
          <c-tag>{{ activeOrder.source }}</c-tag>
        </c-space>
        <p>执行人：{{ resourceLabel(activeOrder.personId) }} · 人数：1</p>
        <p>
          计划时间：{{ displayTime(activeOrder.plannedStart) }} –
          {{ displayTime(activeOrder.plannedEnd) }}
        </p>
        <p v-if="activeOrder.actualStart">
          实际时间：{{ displayTime(activeOrder.actualStart) }} –
          {{ displayTime(activeOrder.actualEnd) }}
        </p>
        <c-divider />
        <strong>任务与工单</strong>
        <div v-for="task in activeOrder.tasks" :key="task.id">
          <c-link :href="`#work-order-${task.id}`">{{ task.title }}</c-link>
          · 技能 {{ skillLabel(task.skill) }} · {{ task.standardMinutes }} 分钟
        </div>
        <p>总标准工时：{{ totalMinutes(activeOrder) }} 分钟</p>
        <c-divider />
        <strong>打卡记录</strong>
        <div v-for="record in activeOrder.punchRecords" :key="record.id">
          {{ resourceLabel(record.deviceId) }}：
          {{ displayTime(record.checkedInAt) }} –
          {{ displayTime(record.checkedOutAt) }}
        </div>
        <c-empty
          v-if="!activeOrder.punchRecords.length"
          description="暂无打卡记录"
        />
        <c-space>
          <c-button @click="detailsOpen = false">关闭</c-button>
          <c-button
            v-if="
              activeOrder.status !== 'closed' && activeOrder.kind !== 'rest'
            "
            status="primary"
            @click="closeOrder(activeOrder)"
          >
            按实际打卡时间关单
          </c-button>
        </c-space>
      </c-space>
    </template>
  </c-dialog>
</template>

<script setup lang="ts">
import { computed, ref } from "vue";
import type {
  SchedulerEditorRequest,
  SchedulerEvent,
  SchedulerResource,
} from "@cedar-design/ui";
import EventSummaryPopover from "./event-summary-popover.vue";
import {
  toTaskCalendarEvent,
  type TaskCalendarOrder,
} from "./task-calendar-model";

const resources: SchedulerResource[] = [
  { id: "person-li", label: "李卫东" },
  { id: "person-zhang", label: "张志强" },
  { id: "device-a", label: "月检站 A" },
  { id: "device-c", label: "预警处理台 C" },
];
const orders = ref<TaskCalendarOrder[]>([
  {
    id: "detail-101",
    kind: "work",
    status: "review",
    source: "设备待办",
    personId: "person-li",
    plannedStart: "2026-09-09T09:00:00",
    plannedEnd: "2026-09-09T11:00:00",
    tasks: [
      {
        id: "WO-301",
        title: "月检与运行参数复核",
        deviceId: "device-a",
        skill: "inspection",
        standardMinutes: 120,
      },
    ],
    punchRecords: [
      {
        id: "punch-1",
        deviceId: "device-a",
        checkedInAt: "2026-09-09T09:12:00",
        checkedOutAt: "2026-09-09T10:48:00",
      },
    ],
    color: "#1677ff",
  },
  {
    id: "detail-102",
    kind: "work",
    status: "closed",
    source: "站长负责范围",
    personId: "person-zhang",
    plannedStart: "2026-09-09T13:00:00",
    plannedEnd: "2026-09-09T14:00:00",
    actualStart: "2026-09-09T13:08:00",
    actualEnd: "2026-09-09T13:52:00",
    tasks: [
      {
        id: "WO-302",
        title: "预警处理",
        deviceId: "device-c",
        skill: "warning",
        standardMinutes: 60,
      },
    ],
    punchRecords: [
      {
        id: "punch-2",
        deviceId: "device-c",
        checkedInAt: "2026-09-09T13:08:00",
        checkedOutAt: "2026-09-09T13:52:00",
      },
    ],
    color: "#86909c",
  },
  {
    id: "detail-rest",
    kind: "rest",
    status: "planned",
    source: "个人安排",
    personId: "person-li",
    plannedStart: "2026-09-09T12:00:00",
    plannedEnd: "2026-09-09T13:00:00",
    tasks: [],
    punchRecords: [],
    color: "#00a854",
  },
]);
const events = ref<SchedulerEvent[]>(orders.value.map(toTaskCalendarEvent));
const previewId = ref<string>();
const activeOrderId = ref<string>();
const detailsOpen = ref(false);
const activeOrder = computed(() =>
  orders.value.find((order) => order.id === activeOrderId.value),
);

function activate(request: SchedulerEditorRequest) {
  if (request.action !== "edit") return;
  previewId.value = request.event.id;
  activeOrderId.value = businessId(request.event);
}
function openDetails(event: SchedulerEvent) {
  activeOrderId.value = businessId(event);
  previewId.value = undefined;
  detailsOpen.value = true;
}
function closeOrder(order: TaskCalendarOrder) {
  const punches = order.punchRecords;
  const first = punches[0]?.checkedInAt;
  const last = punches.at(-1)?.checkedOutAt;
  if (!first || !last) return;
  orders.value = orders.value.map((item) =>
    item.id === order.id
      ? { ...item, status: "closed", actualStart: first, actualEnd: last }
      : item,
  );
  events.value = orders.value.map(toTaskCalendarEvent);
}
function businessId(event: SchedulerEvent) {
  return String(event.metadata?.attendanceOrderId ?? event.id);
}
function orderOf(event: SchedulerEvent) {
  return orders.value.find((order) => order.id === businessId(event));
}
function totalMinutes(order: TaskCalendarOrder) {
  return order.tasks.reduce((total, task) => total + task.standardMinutes, 0);
}
function deviceLabels(order: TaskCalendarOrder) {
  return (
    [...new Set(order.tasks.map((task) => resourceLabel(task.deviceId)))].join(
      "、",
    ) || "无"
  );
}
function personLabel(event: SchedulerEvent) {
  return resourceLabel(orderOf(event)?.personId);
}
function resourceLabel(id?: string) {
  return resources.find((resource) => resource.id === id)?.label ?? "未知";
}
function skillLabel(skill: string) {
  return { inspection: "巡检", warning: "预警处理" }[skill] ?? skill;
}
function statusLabel(order: TaskCalendarOrder) {
  if (order.kind === "rest") return "休息";
  return {
    planned: "计划中",
    active: "执行中",
    review: "待关单",
    closed: "已完成",
  }[order.status];
}
function latestPunch(order: TaskCalendarOrder) {
  const record = order.punchRecords.at(-1);
  return record
    ? `${displayTime(record.checkedInAt)} – ${displayTime(record.checkedOutAt)}`
    : "暂无";
}
function timeRange(event: SchedulerEvent) {
  return `${displayTime(event.start)} – ${displayTime(event.end)}`;
}
function displayTime(value?: string | number | Date) {
  return value == null
    ? "未记录"
    : new Date(value).toLocaleString("zh-CN", {
        month: "numeric",
        day: "numeric",
        hour: "2-digit",
        minute: "2-digit",
        hour12: false,
      });
}
</script>

<style scoped>
.completed-event {
  opacity: 0.55;
}
</style>
```

点击日程先打开 Popover 摘要，再通过“高级详情”查看工单、任务技能、人员、设备、标准工时、来源和打卡记录。页面用 `metadata.attendanceOrderId` 查询完整业务对象；关单后保留业务对象中的计划时间，只把 Scheduler Event 映射为实际打卡时间和只读外观。完成、休息和来源都是 Demo 业务配置。

### 任务日历组合工作台

Example source: src/scheduler/__demos__/task-calendar-workbench.vue

```vue
<template>
  <div
    ref="host"
    class="workbench-shell"
    @pointerdown.capture="captureDrag"
    @dragend="endDrag"
  >
    <nav v-if="navigationOpen" class="workbench-nav" aria-label="应用导航">
      <c-button variant="text">任务日历</c-button>
      <c-button variant="text" @click="navigationOpen = false"
        >收起导航</c-button
      >
    </nav>
    <c-scheduler
      ref="scheduler"
      class="task-calendar-workbench"
      :model-value="events"
      v-model:date="date"
      mode="week"
      show-now-indicator
      :snap-duration="1"
      :modes="['week']"
      :step="60"
      :start-hour="0"
      :end-hour="24"
      :initial-scroll-minute="420"
      :resources="data.resources"
      :event-layout="workbenchLayout"
      :editable="false"
      :readonly="role === 'viewer'"
      :disabled="saving"
      :preview-event="preview"
      :before-change="prepareMove"
      @change="finishMove"
      @change-error="moveError"
      @editor-request="openEditor"
    >
      <template #toolbar="{ navigate, create }">
        <c-space wrap>
          <c-button
            :aria-expanded="navigationOpen"
            @click="navigationOpen = !navigationOpen"
            >导航</c-button
          >
          <c-button aria-label="上一周" :disabled="saving" @click="navigate(-1)"
            >‹</c-button
          >
          <c-popover
            trigger="click"
            placement="bottom-start"
            :open="datePickerOpen"
            @update:open="datePickerOpen = $event"
          >
            <c-button :disabled="saving">{{ weekLabel(date) }}</c-button>
            <template #content
              ><c-date-picker
                :model-value="date"
                value-format="Date"
                @update:model-value="chooseDate"
            /></template>
          </c-popover>
          <c-button aria-label="下一周" :disabled="saving" @click="navigate(1)"
            >›</c-button
          >
          <c-button :disabled="saving" @click="goToday">今天</c-button>
        </c-space>
        <c-button
          status="primary"
          :disabled="saving || role === 'viewer'"
          @click="create"
          >新增出勤单</c-button
        >
      </template>
      <template #sidebar="{ startDrag, cancelDrag, disabled }">
        <div class="workbench-panels">
          <section class="source-panel" aria-label="人员设备选择">
            <strong class="panel-title">人员与设备</strong>
            <c-input
              v-model="query"
              placeholder="搜索人员、账号或设备"
              clearable
              :disabled="saving"
            />
            <div class="panel-scroll source-scroll">
              <c-tree
                :data="sourceTree"
                :checked-values="sourceKeys"
                :expanded-values="expandedSources"
                checkable
                only-check-leaf
                block-node
                :selectable="false"
                :disabled="saving"
                @update:expanded-values="expandedSources = $event"
                @check="checkSources"
              >
                <template #label="node">
                  <span
                    v-if="node.resourceId"
                    class="source-object"
                    :data-owner="node.resourceId"
                  >
                    {{ resource(node.resourceId)?.label }}
                    <small v-if="resource(node.resourceId)?.account">{{
                      resource(node.resourceId)?.account
                    }}</small>
                    <span
                      v-if="resource(node.resourceId)?.managers"
                      class="quick-actions"
                    >
                      <c-button
                        v-for="id in resource(node.resourceId)?.managers"
                        :key="id"
                        size="xs"
                        :disabled="saving"
                        :aria-pressed="selected.includes(id)"
                        @click.stop="toggleResource(id)"
                        >{{ resource(id)?.label }}
                        {{ selected.includes(id) ? "−" : "+" }}</c-button
                      >
                    </span>
                  </span>
                  <span v-else>{{ node.label }}</span>
                </template>
              </c-tree>
            </div>
          </section>
          <section class="pending-panel" aria-label="待分配任务">
            <strong
              >待分配任务 <c-tag>{{ pending.length }}</c-tag></strong
            >
            <div class="panel-scroll">
              <c-tree
                :data="pendingTree"
                :checked-values="pendingKeys"
                :expanded-values="expandedPending"
                checkable
                only-check-leaf
                block-node
                :selectable="false"
                :disabled="disabled"
                @update:expanded-values="expandedPending = $event"
                @check="checkPending"
              >
                <template #label="node">
                  <div
                    v-if="node.taskId"
                    class="pending-task"
                    :class="deadlineClass(task(node.taskId))"
                    :draggable="!disabled"
                    @dragstart="beginPending(node.taskId, startDrag, $event)"
                    @dragend="
                      cancelDrag();
                      endDrag();
                    "
                  >
                    <strong>{{ task(node.taskId)?.title }}</strong>
                    <span>{{
                      resource(task(node.taskId)?.deviceId)?.label
                    }}</span>
                    <span>{{ deadlineText(task(node.taskId)) }}</span>
                    <span
                      >{{ task(node.taskId)?.skill }} /
                      {{ task(node.taskId)?.people }} 人 /
                      {{ task(node.taskId)?.minutes }} 分钟</span
                    >
                    <small>{{ task(node.taskId)?.source }}</small>
                  </div>
                  <span v-else>{{ node.label }}</span>
                </template>
              </c-tree>
              <c-empty
                v-if="!pendingTree.length"
                description="暂无待分配任务"
              />
            </div>
          </section>
        </div>
      </template>
      <template #resource-header="{ date: day }">
        {{ day.toLocaleDateString("zh-CN", { weekday: "short" }) }}
        {{ day.getDate() }}
      </template>
      <template #column-background="{ date: day }">
        <div
          v-if="dragDeadline && schedulerDateKey(day) > dragDeadline"
          class="deadline-mask"
          aria-label="晚于任务截止日期"
        />
      </template>
      <template #event="{ event }">
        <div
          class="task-card"
          :data-order-id="event.metadata?.orderId"
          :data-edge="event.metadata?.edge"
          :class="{
            linked: activeOrder === event.metadata?.orderId,
            closed: event.metadata?.closed,
            rest: event.metadata?.kind === 'rest',
          }"
          @mouseenter="hoverOrder = String(event.metadata?.orderId ?? '')"
          @mouseleave="hoverOrder = ''"
          @dragover="allowMerge($event, event)"
          @drop="dropMerge($event, event)"
        >
          <strong>{{ event.title }}</strong>
          <span v-if="event.metadata?.kind !== 'rest'">{{
            event.metadata?.counterpart
          }}</span>
          <span v-if="!event.allDay"
            >{{ time(event.start) }}–{{ time(event.end) }}</span
          >
        </div>
      </template>
    </c-scheduler>
  </div>
  <c-alert
    v-if="notice"
    :status="noticeError ? 'danger' : 'warning'"
    class="workbench-notice"
    role="status"
    >{{ notice }}</c-alert
  >
  <c-space wrap class="workbench-test-controls">
    <span>联调演示</span>
    <c-select
      v-model="role"
      :options="roles"
      :disabled="saving"
      style="width: 170px"
    />
    <c-checkbox v-model="rejectSave" :disabled="saving"
      >模拟保存失败</c-checkbox
    >
    <c-checkbox v-model="conflict" :disabled="saving">模拟版本冲突</c-checkbox>
    <c-button :disabled="saving" @click="reload">重新加载</c-button>
    <c-popover trigger="click" title="最近提交的业务 DTO" placement="top">
      <c-button>提交数据</c-button>
      <template #content>
        <pre class="payload">{{ lastPayload || "尚未提交" }}</pre>
      </template>
    </c-popover>
  </c-space>
  <c-dialog
    v-model:open="editorOpen"
    :title="
      draft?.kind === 'rest'
        ? '休息安排'
        : draft?.version
          ? '出勤单详情'
          : '创建出勤单'
    "
    :footer="false"
    :closable="!saving"
    :overlay-closable="!saving"
    :esc-to-close="!saving"
    @update:open="onEditorVisibility"
  >
    <template v-if="draft">
      <c-alert v-if="editorError" status="danger">{{ editorError }}</c-alert>
      <template v-if="draft.kind === 'rest'">
        <p>{{ resource(draft.personId)?.label }}</p>
        <p>{{ format(draft.start) }} – {{ format(draft.end) }}</p>
        <c-button @click="closeEditor">关闭</c-button>
      </template>
      <c-form v-else :model="draft" layout="vertical" @submit="saveDraft()">
        <c-space
          ><c-tag>{{ statuses[draft.status] }}</c-tag
          ><span>{{ draft.id }}</span></c-space
        >
        <c-form-item label="执行人"
          ><c-select
            v-model="draft.personId"
            :options="personOptions"
            :disabled="readOnly || saving"
        /></c-form-item>
        <c-form-item label="开始"
          ><c-date
            :model-value="new Date(draft.start)"
            value-format="Date"
            :show-time="!draft.allDay"
            :disabled="readOnly || saving"
            @update:model-value="setStart"
        /></c-form-item>
        <c-form-item v-if="draft.allDay" label="结束日期（不含）"
          ><c-date
            :model-value="new Date(draft.end)"
            value-format="Date"
            :disabled="readOnly || saving"
            @update:model-value="setAllDayEnd"
        /></c-form-item>
        <p v-else>计划结束：{{ format(calculatedEnd) }}</p>
        <c-form-item label="任务">
          <div class="detail-task-list">
            <div
              v-for="(entry, index) in draftTasks"
              :key="entry.id"
              class="detail-task"
              :data-task-id="entry.id"
            >
              <WorkbenchPunches
                :data="data"
                :task="entry"
                :start="taskStart(index)"
              />
              <div>
                <c-tag>{{ entry.source }}</c-tag> ·
                {{ resource(entry.deviceId)?.label }}
              </div>
              <c-button variant="text" @click="workOrderTask = entry"
                >工单详情</c-button
              >
              <c-button
                v-if="!readOnly"
                variant="text"
                :disabled="saving"
                @click="removeDraftTask(entry.id)"
                >移出任务</c-button
              >
            </div>
            <c-select
              v-if="!readOnly"
              v-model="addTaskId"
              :options="availableTaskOptions"
              placeholder="选择同设备待办任务"
              :disabled="saving"
              @update:model-value="addTask"
            />
            <c-button
              v-if="!readOnly"
              :disabled="saving || !selectedTasks.length"
              @click="addSelected"
              >加入已勾选任务（{{ selectedTasks.length }}）</c-button
            >
          </div>
        </c-form-item>
        <template v-if="draft.status === 'closed'">
          <p v-for="record in linkedPunches" :key="record.id">
            实际：{{ format(record.start) }} – {{ format(record.end) }}
          </p>
        </template>
        <template v-if="closing && !readOnly">
          <c-divider />
          <c-form-item label="关联打卡">
            <div class="detail-task-list">
              <c-checkbox
                v-for="record in eligiblePunches"
                :key="record.id"
                :model-value="draft.punchIds.includes(record.id)"
                :disabled="saving"
                @update:model-value="togglePunch(record.id, $event)"
                >{{ format(record.start) }} – {{ time(record.end) }}</c-checkbox
              >
              <c-empty
                v-if="!eligiblePunches.length"
                description="暂无匹配打卡，可手动补录"
              />
            </div>
          </c-form-item>
          <c-checkbox v-model="manualPunch" :disabled="saving"
            >手动补录打卡</c-checkbox
          >
          <c-form-item v-if="manualPunch" label="登录"
            ><c-date
              v-model="punchStart"
              value-format="Date"
              show-time
              :disabled="saving"
          /></c-form-item>
          <c-form-item v-if="manualPunch" label="注销"
            ><c-date
              v-model="punchEnd"
              value-format="Date"
              show-time
              :disabled="saving"
          /></c-form-item>
        </template>
        <c-space wrap>
          <c-button
            v-if="!readOnly"
            html-type="submit"
            status="primary"
            :loading="saving"
            >{{ closing ? "确认关单" : "保存" }}</c-button
          >
          <c-button
            v-if="!readOnly && draft.version && !closing"
            :disabled="saving || !draft.taskIds.length"
            @click="closing = true"
            >关联打卡并关单</c-button
          >
          <c-button
            v-if="!readOnly && draft.version"
            status="danger"
            :disabled="saving"
            @click="saveDraft(true)"
            >删除出勤单</c-button
          >
          <c-button :disabled="saving" @click="closeEditor">{{
            readOnly ? "关闭" : "取消"
          }}</c-button>
        </c-space>
      </c-form>
    </template>
  </c-dialog>
  <c-dialog
    :open="!!workOrderTask"
    title="工单详情"
    :footer="false"
    @update:open="!$event && (workOrderTask = undefined)"
  >
    <template v-if="workOrderTask"
      ><h3>{{ workOrderTask.id }} · {{ workOrderTask.title }}</h3>
      <p>{{ resource(workOrderTask.deviceId)?.label }}</p>
      <p>
        {{ workOrderTask.skill }} / {{ workOrderTask.people }} 人 /
        {{ workOrderTask.minutes }} 分钟
      </p>
      <p>
        来源：{{ workOrderTask.source }}；截止：{{ workOrderTask.deadline }}
      </p></template
    >
  </c-dialog>
</template>
<script setup lang="ts">
import {
  computed,
  nextTick,
  onBeforeUnmount,
  onMounted,
  ref,
  watch,
} from "vue";
import type {
  SchedulerEvent,
  SchedulerEventTemplate,
  SchedulerEditorRequest,
  SchedulerChangeContext,
} from "../index";
import { schedulerDateKey } from "../core";
import type { TreeNodeData } from "../../tree";
import WorkbenchPunches from "./workbench-punches.vue";
import {
  createWorkbenchApi,
  createWorkbenchMock,
  copyData,
  moveWorkbenchOrder,
  orderEnd,
  orderTasks,
  pendingWorkbenchTasks,
  projectWorkbench,
  remainingDays,
  weekLabel,
  workbenchLayout,
  type WorkbenchOrder,
  type WorkbenchTask,
  type WorkbenchPunch,
  type SaveResult,
} from "./workbench-model";

const today = new Date();
const api = createWorkbenchApi(createWorkbenchMock(today));
const data = ref(api.load());
const date = ref(new Date(today));
const role = ref<"dispatcher" | "viewer">("dispatcher");
const roles = [
  { value: "dispatcher", label: "调度员（可编辑）" },
  { value: "viewer", label: "查看者（只读）" },
];
const statuses = {
  planned: "待出发",
  active: "进行中",
  submit: "待提交",
  review: "待审核",
  closed: "已完成",
};
const rejectSave = ref(false),
  conflict = ref(false),
  saving = ref(false),
  navigationOpen = ref(false),
  datePickerOpen = ref(false);
const query = ref(""),
  recent = ref<string[]>(["li", "station-a"]),
  selected = ref<string[]>(["me"]);
const selectedTasks = ref<string[]>([]),
  draggingTasks = ref<string[]>([]),
  dragDeadline = ref<string>();
const notice = ref(""),
  noticeError = ref(false),
  editorError = ref(""),
  lastPayload = ref("");
const editorOpen = ref(false),
  draft = ref<WorkbenchOrder>(),
  hoverOrder = ref("");
const closing = ref(false),
  manualPunch = ref(false),
  punchStart = ref<Date>(),
  punchEnd = ref<Date>();
const addTaskId = ref<string>(),
  workOrderTask = ref<WorkbenchTask>();
const host = ref<HTMLElement>();
const scheduler = ref();
let opener: HTMLElement | undefined;
let sequence = 0;
let staged: (() => SaveResult) | undefined;
const events = computed(() => projectWorkbench(data.value, selected.value));
const pending = computed(() => pendingWorkbenchTasks(data.value, today));
const resource = (id: unknown) =>
  data.value.resources.find((item) => item.id === id);
const task = (id: unknown) => data.value.tasks.find((item) => item.id === id);
const draftTasks = computed(() =>
  draft.value ? orderTasks(draft.value, data.value) : [],
);
const calculatedEnd = computed(() =>
  draft.value ? orderEnd(draft.value.start, draftTasks.value) : "",
);
const readOnly = computed(
  () =>
    role.value === "viewer" ||
    draft.value?.kind === "rest" ||
    draft.value?.status === "closed",
);
const activeOrder = computed(() =>
  editorOpen.value ? draft.value?.id : hoverOrder.value,
);
const personOptions = computed(() =>
  data.value.resources
    .filter((r) => r.dimensionId === "person")
    .map((r) => ({ value: r.id, label: r.label })),
);
const availableTaskOptions = computed(() =>
  pending.value
    .filter(
      (entry) =>
        !draft.value?.taskIds.includes(entry.id) &&
        (!draftTasks.value.length ||
          entry.deviceId === draftTasks.value[0].deviceId),
    )
    .map((entry) => ({
      value: entry.id,
      label: `${entry.title} · ${resource(entry.deviceId)?.label}`,
    })),
);
const eligiblePunches = computed(() =>
  data.value.punches.filter(
    (record) =>
      record.personId === draft.value?.personId &&
      record.deviceId === draftTasks.value[0]?.deviceId,
  ),
);
const linkedPunches = computed(() =>
  data.value.punches.filter((record) =>
    draft.value?.punchIds.includes(record.id),
  ),
);
const preview = computed<SchedulerEvent | undefined>(() =>
  editorOpen.value && draft.value?.version === 0
    ? {
        id: "workbench-draft",
        title:
          draftTasks.value.map((entry) => entry.title).join("、") || "新出勤单",
        start: draft.value.start,
        end: draft.value.allDay
          ? draft.value.end
          : draft.value.taskIds.length
            ? calculatedEnd.value
            : new Date(+new Date(draft.value.start) + 3600000).toISOString(),
        allDay: draft.value.allDay,
        color: resource(draft.value.personId)?.color,
        backgroundColor: resource(draft.value.personId)?.background,
      }
    : undefined,
);

interface Node extends TreeNodeData {
  resourceId?: string;
  taskId?: string;
  children?: Node[];
}
const group = (key: string, title: string, ids: string[]): Node => ({
  value: key,
  label: title,
  children: ids.map((id) => ({
    value: `${key}/${id}`,
    label: resource(id)?.label,
    resourceId: id,
  })),
});
const sourceTree = computed<Node[]>(() => [
  ...(query.value.trim()
    ? [
        group(
          "search",
          "搜索结果",
          data.value.resources
            .filter((r) =>
              `${r.label} ${r.account ?? ""}`
                .toLowerCase()
                .includes(query.value.trim().toLowerCase()),
            )
            .map((r) => r.id),
        ),
      ]
    : []),
  group("self", "自己", ["me"]),
  group("stations", "我的站", ["station-a", "station-b"]),
  group("favorites", "收藏", ["station-a", "station-c"]),
  group("recent", "最近使用", recent.value),
]);
const expandedSources = ref<Array<string | number>>([
  "self",
  "stations",
  "favorites",
  "recent",
  "search",
]);
const sourceKeys = computed(() =>
  sourceTree.value
    .flatMap((node) => node.children ?? [])
    .filter((node) => selected.value.includes(node.resourceId!))
    .map((node) => node.value!),
);
function checkSources(
  _keys: Array<string | number>,
  context: { checked?: boolean; node?: Node },
) {
  if (saving.value || !context.node) return;
  const ids = context.node.resourceId
    ? [context.node.resourceId]
    : (context.node.children ?? []).map((node) => node.resourceId!);
  selected.value = context.checked
    ? [...new Set([...selected.value, ...ids])]
    : selected.value.filter((id) => !ids.includes(id));
  if (context.checked)
    recent.value = [...new Set([...ids, ...recent.value])].slice(0, 12);
}
function toggleResource(id: string) {
  selected.value = selected.value.includes(id)
    ? selected.value.filter((value) => value !== id)
    : [...selected.value, id];
  recent.value = [...new Set([id, ...recent.value])].slice(0, 12);
}
const pendingTree = computed<Node[]>(() =>
  selected.value.flatMap((id) => {
    const owner = resource(id);
    const ids =
      owner?.dimensionId === "device"
        ? [id]
        : data.value.resources
            .filter((r) => r.managers?.includes(id))
            .map((r) => r.id);
    const tasks = pending.value.filter((entry) => ids.includes(entry.deviceId));
    return tasks.length
      ? [
          {
            value: `pending/${id}`,
            label: owner?.label,
            children: tasks.map((entry) => ({
              value: `pending/${id}/${entry.id}`,
              label: entry.title,
              taskId: entry.id,
            })),
          },
        ]
      : [];
  }),
);
const expandedPending = ref<Array<string | number>>(
  data.value.resources.map((r) => `pending/${r.id}`),
);
const pendingKeys = computed(() =>
  pendingTree.value
    .flatMap((node) => node.children ?? [])
    .filter((node) => selectedTasks.value.includes(node.taskId!))
    .map((node) => node.value!),
);
function checkPending(
  _keys: Array<string | number>,
  context: { checked?: boolean; node?: Node },
) {
  if (!context.node) return;
  const ids = context.node.taskId
    ? [context.node.taskId]
    : (context.node.children ?? []).map((node) => node.taskId!);
  const next = context.checked
    ? [...new Set([...selectedTasks.value, ...ids])]
    : selectedTasks.value.filter((id) => !ids.includes(id));
  if (new Set(next.map((id) => task(id)?.deviceId)).size > 1)
    return showNotice("请勾选同一设备的任务", true);
  selectedTasks.value = next;
}
const deadlineClass = (entry?: WorkbenchTask) => ({
  overdue: entry && remainingDays(entry, today) < 0,
  urgent:
    entry &&
    remainingDays(entry, today) >= 0 &&
    remainingDays(entry, today) <= 3,
});
const deadlineText = (entry?: WorkbenchTask) => {
  if (!entry) return "";
  const days = remainingDays(entry, today);
  return days < 0
    ? `逾期 ${-days} 天`
    : days === 0
      ? "今天截止"
      : `剩 ${days} 天`;
};
function beginPending(
  id: string,
  startDrag: (template: SchedulerEventTemplate, event: DragEvent) => void,
  event: DragEvent,
) {
  const ids = selectedTasks.value.includes(id)
    ? [...selectedTasks.value]
    : [id];
  draggingTasks.value = ids;
  dragDeadline.value = ids
    .map((key) => task(key)?.deadline ?? "")
    .filter(Boolean)
    .sort()[0];
  startDrag(
    {
      title: ids.map((key) => task(key)?.title).join("、"),
      duration: ids.reduce((sum, key) => sum + (task(key)?.minutes ?? 0), 0),
      metadata: { taskIds: ids },
    },
    event,
  );
}
function captureDrag(event: PointerEvent) {
  const node = (event.target as HTMLElement).closest<HTMLElement>(
    "[data-order-id]",
  );
  const order = data.value.orders.find(
    (item) => item.id === node?.dataset.orderId,
  );
  if (
    order &&
    order.kind === "work" &&
    order.status !== "closed" &&
    role.value !== "viewer"
  )
    dragDeadline.value = orderTasks(order, data.value)
      .map((entry) => entry.deadline)
      .sort()[0];
}
function endDrag() {
  dragDeadline.value = undefined;
  draggingTasks.value = [];
}
function allowMerge(event: DragEvent, target: SchedulerEvent) {
  if (
    draggingTasks.value.length &&
    !target.readonly &&
    !saving.value &&
    role.value !== "viewer"
  )
    event.preventDefault();
}
async function dropMerge(event: DragEvent, target: SchedulerEvent) {
  if (!draggingTasks.value.length) return;
  event.preventDefault();
  event.stopPropagation();
  const ids = [...draggingTasks.value];
  endDrag();
  const current = data.value.orders.find(
    (order) => order.id === target.metadata?.orderId,
  );
  if (!current || target.readonly || saving.value || role.value === "viewer")
    return showNotice("当前记录不可合并", true);
  const next = copyData(current);
  next.taskIds = [...new Set([...next.taskIds, ...ids])];
  if (!next.allDay)
    next.end = orderEnd(next.start, orderTasks(next, data.value));
  await persist(next);
}
function openEditor(request: SchedulerEditorRequest) {
  editorError.value = "";
  closing.value = false;
  manualPunch.value = false;
  addTaskId.value = undefined;
  opener =
    document.activeElement instanceof HTMLElement
      ? document.activeElement
      : undefined;
  if (request.action === "edit") {
    const order = data.value.orders.find(
      (item) => item.id === request.event.metadata?.orderId,
    );
    if (!order) return;
    draft.value = copyData(order);
  } else {
    const templateIds = request.event.metadata?.taskIds;
    const ids = Array.isArray(templateIds)
      ? templateIds.filter((id): id is string => typeof id === "string")
      : [...selectedTasks.value];
    const start = new Date(request.event.start ?? date.value);
    if (request.source === "toolbar") start.setHours(9, 0, 0, 0);
    else if (request.source === "cell") start.setMinutes(0, 0, 0);
    draft.value = {
      id: `ATT-${Date.now()}-${++sequence}`,
      version: 0,
      personId:
        selected.value.find((id) => resource(id)?.dimensionId === "person") ??
        "me",
      taskIds: ids,
      start: start.toISOString(),
      end: request.event.allDay
        ? new Date(request.event.end!).toISOString()
        : orderEnd(
            start.toISOString(),
            ids.map(task).filter((entry): entry is WorkbenchTask => !!entry),
          ),
      allDay: request.event.allDay,
      kind: "work",
      status: "planned",
      punchIds: [],
    };
  }
  punchStart.value = new Date(draft.value.start);
  punchEnd.value = new Date(draft.value.end);
  editorOpen.value = true;
  endDrag();
}
function setStart(value: Date | undefined) {
  if (draft.value && value && Number.isFinite(+value))
    draft.value.start = value.toISOString();
}
function setAllDayEnd(value: Date | undefined) {
  if (draft.value && value && Number.isFinite(+value))
    draft.value.end = value.toISOString();
}
function addTask(id: string) {
  if (draft.value && id)
    draft.value.taskIds = [...new Set([...draft.value.taskIds, id])];
  addTaskId.value = undefined;
}
function addSelected() {
  if (!draft.value) return;
  const ids = [...new Set([...draft.value.taskIds, ...selectedTasks.value])];
  if (new Set(ids.map((id) => task(id)?.deviceId)).size > 1) {
    editorError.value = "一张出勤单只能安排同一设备的任务";
    return;
  }
  draft.value.taskIds = ids;
}
function removeDraftTask(id: string) {
  if (draft.value)
    draft.value.taskIds = draft.value.taskIds.filter((value) => value !== id);
}
function taskStart(index: number) {
  return draft.value
    ? orderEnd(draft.value.start, draftTasks.value.slice(0, index))
    : "";
}
function togglePunch(id: string, checked: boolean) {
  if (draft.value)
    draft.value.punchIds = checked
      ? [...new Set([...draft.value.punchIds, id])]
      : draft.value.punchIds.filter((key) => key !== id);
}
function options() {
  const value = {
    role: role.value,
    fail: rejectSave.value,
    conflict: conflict.value,
  };
  conflict.value = false;
  return value;
}
function accept(result: SaveResult) {
  data.value = result.data;
  selectedTasks.value = selectedTasks.value.filter((id) =>
    pending.value.some((entry) => entry.id === id),
  );
  showNotice(result.warnings.join("；") || "已保存", false);
}
async function persist(
  value: WorkbenchOrder,
  remove = false,
  manual?: WorkbenchPunch,
) {
  saving.value = true;
  editorError.value = "";
  lastPayload.value = JSON.stringify(
    {
      operation: remove ? "remove" : "save",
      order: value,
      manualPunch: manual,
    },
    null,
    2,
  );
  try {
    accept(await api.save(value, options(), remove, manual));
    return true;
  } catch (error) {
    editorError.value = error instanceof Error ? error.message : "保存失败";
    showNotice(editorError.value, true);
    return false;
  } finally {
    saving.value = false;
  }
}
async function saveDraft(remove = false) {
  if (!draft.value || saving.value || readOnly.value) return;
  const value = copyData(draft.value);
  const dissolve = !!value.version && !value.taskIds.length;
  if (!value.allDay && value.taskIds.length)
    value.end = orderEnd(value.start, orderTasks(value, data.value));
  let manual: WorkbenchPunch | undefined;
  if (closing.value && !remove && !dissolve) {
    value.status = "closed";
    if (manualPunch.value) {
      if (
        !punchStart.value ||
        !punchEnd.value ||
        !Number.isFinite(+punchStart.value) ||
        !Number.isFinite(+punchEnd.value)
      ) {
        editorError.value = "请填写登录和注销时间";
        return;
      }
      manual = {
        id: `punch-${Date.now()}-${++sequence}`,
        personId: value.personId,
        deviceId: draftTasks.value[0]?.deviceId ?? "",
        start: punchStart.value.toISOString(),
        end: punchEnd.value.toISOString(),
      };
      value.punchIds = [...value.punchIds, manual.id];
    }
  }
  if (await persist(value, remove || dissolve, manual)) closeEditor();
}
async function prepareMove(context: SchedulerChangeContext) {
  if (!context.previous || context.type !== "move")
    throw new Error("请在出勤单详情中修改");
  if (context.event.allDay !== context.previous.allDay)
    throw new Error("请在详情中调整全天安排");
  const next = moveWorkbenchOrder(data.value, context.event, context.previous);
  lastPayload.value = JSON.stringify(
    { operation: "move", order: next },
    null,
    2,
  );
  staged = await api.prepare(next, options());
  return true;
}
function finishMove() {
  try {
    if (staged) accept(staged());
  } catch (error) {
    moveError(error);
  } finally {
    staged = undefined;
    endDrag();
  }
}
function moveError(error: unknown) {
  staged = undefined;
  showNotice(error instanceof Error ? error.message : "保存失败", true);
  endDrag();
}
function showNotice(message: string, error: boolean) {
  notice.value = message;
  noticeError.value = error;
}
function reload() {
  data.value = api.load();
  if (draft.value?.version)
    draft.value = copyData(
      data.value.orders.find((item) => item.id === draft.value?.id) ??
        draft.value,
    );
  editorError.value = "";
  showNotice("已重新加载", false);
}
async function onEditorVisibility(open: boolean) {
  if (open) return;
  hoverOrder.value = "";
  await nextTick();
  if (opener?.isConnected) opener.focus({ preventScroll: true });
}
function closeEditor() {
  editorOpen.value = false;
  void onEditorVisibility(false);
}
async function chooseDate(value: Date | undefined) {
  if (value && Number.isFinite(+value)) date.value = value;
  datePickerOpen.value = false;
}
async function goToday() {
  date.value = new Date();
  await nextTick();
  const container =
    host.value?.querySelector<HTMLElement>(".c-scheduler__main");
  const heading = [
    ...(host.value?.querySelectorAll<HTMLElement>(
      "[data-scheduler-heading-date]",
    ) ?? []),
  ].find(
    (element) =>
      schedulerDateKey(element.dataset.schedulerHeadingDate!) ===
      schedulerDateKey(new Date()),
  );
  const cell = host.value?.querySelector<HTMLElement>(
    ".c-scheduler__time-cell",
  );
  if (container && cell) {
    container.scrollTop = (cell.getBoundingClientRect().height || 36) * 7;
    if (heading) container.scrollLeft = Math.max(0, heading.offsetLeft - 64);
  }
}
const time = (value: SchedulerEvent["start"]) =>
  value == null
    ? ""
    : new Date(value).toLocaleTimeString("zh-CN", {
        hour: "2-digit",
        minute: "2-digit",
        hour12: false,
      });
const format = (value: string) =>
  new Date(value).toLocaleString("zh-CN", {
    month: "numeric",
    day: "numeric",
    hour: "2-digit",
    minute: "2-digit",
    hour12: false,
  });
const cancelWithEscape = (event: KeyboardEvent) => {
  if (event.key === "Escape") endDrag();
};
onMounted(() => {
  window.addEventListener("pointerup", endDrag);
  window.addEventListener("pointercancel", endDrag);
  window.addEventListener("blur", endDrag);
  window.addEventListener("keydown", cancelWithEscape);
});
onBeforeUnmount(() => {
  window.removeEventListener("pointerup", endDrag);
  window.removeEventListener("pointercancel", endDrag);
  window.removeEventListener("blur", endDrag);
  window.removeEventListener("keydown", cancelWithEscape);
});
watch(query, () => {
  if (!expandedSources.value.includes("search"))
    expandedSources.value.push("search");
});
</script>
<style scoped>
.workbench-shell {
  display: flex;
  min-width: 0;
}
.workbench-nav {
  flex: 0 0 88px;
  display: flex;
  flex-direction: column;
  border: 1px solid var(--c-color-border);
}
.task-calendar-workbench {
  min-width: 0;
  flex: 1;
  --c-scheduler-sidebar-width: 420px;
  --c-scheduler-max-height: 650px;
  --c-scheduler-min-height: 650px;
  --c-scheduler-column-min-width: 110px;
  --c-scheduler-gap: 8px;
  --c-scheduler-padding: 10px;
}
.task-calendar-workbench :deep(.c-scheduler__sidebar) {
  padding: 0;
  overflow: hidden;
}
.workbench-panels {
  display: grid;
  grid-template-columns: 190px minmax(0, 1fr);
  grid-template-rows: minmax(0, 1fr);
  height: 650px;
  min-height: 0;
}
.source-panel,
.pending-panel {
  min-width: 0;
  min-height: 0;
  display: flex;
  flex-direction: column;
  padding: 12px;
  gap: 12px;
}
.source-panel {
  border-right: 1px solid var(--c-color-border);
}
.panel-scroll {
  min-height: 0;
  flex: 1;
  overflow-y: auto;
  overflow-x: hidden;
}
.source-object {
  color: var(--c-color-text-1);
  position: relative;
  display: block;
  white-space: nowrap;
}
.source-object small {
  display: block;
  font-size: 11px;
  color: var(--c-color-text-3);
}
.quick-actions {
  display: none;
  position: absolute;
  right: 0;
  bottom: 100%;
  z-index: 5;
  background: var(--c-color-bg-2);
  box-shadow: 0 2px 8px #0002;
}
.source-object:hover .quick-actions,
.source-object:focus-within .quick-actions,
.source-scroll :deep(.c-tree-node:focus-within) .quick-actions {
  display: flex;
}
.source-scroll :deep(.c-tree-node:has([data-owner="me"])) {
  --c-checkbox-control-color-checked: #466caa;
}
.source-scroll :deep(.c-tree-node:has([data-owner="li"])) {
  --c-checkbox-control-color-checked: #ad813c;
}
.source-scroll :deep(.c-tree-node:has([data-owner="zhang"])) {
  --c-checkbox-control-color-checked: #4b8d70;
}
.source-scroll :deep(.c-tree-node:has([data-owner="station-a"])) {
  --c-checkbox-control-color-checked: #8670ac;
}
.source-scroll :deep(.c-tree-node:has([data-owner="station-b"])) {
  --c-checkbox-control-color-checked: #a1657e;
}
.source-scroll :deep(.c-tree-node:has([data-owner="station-c"])) {
  --c-checkbox-control-color-checked: #458c98;
}
.pending-task {
  color: var(--c-color-text-2);
  display: flex;
  flex-direction: column;
  white-space: normal;
  font-size: 12px;
  line-height: 1.5;
  padding: 8px 0;
  cursor: grab;
}
.pending-task.overdue {
  color: #b8434b;
}
.pending-task.urgent {
  color: #a7782d;
}
.task-card {
  color: var(--c-scheduler-event-color);
  width: 100%;
  height: 100%;
  min-height: 0;
  display: flex;
  flex-direction: column;
  overflow: hidden;
  text-align: left;
}
.task-card > * {
  white-space: nowrap;
  overflow: hidden;
  text-overflow: clip;
  flex-shrink: 0;
  line-height: 16px;
}
.task-card.closed::after {
  content: "";
  position: absolute;
  inset: 0;
  background: #ffffff66;
  pointer-events: none;
}
.task-calendar-workbench :deep(.c-scheduler__event) {
  border: 1px solid var(--c-scheduler-event-color);
  border-left-width: 4px;
  color: var(--c-scheduler-event-color);
  margin-bottom: 0;
}
.task-calendar-workbench :deep(.c-scheduler__event--static) {
  border-left-width: 1px;
}
.task-calendar-workbench :deep(.c-scheduler__positioned-event) {
  padding-top: 0;
  padding-bottom: 0;
}
.task-calendar-workbench :deep(.c-scheduler__event:has([data-edge="first"])) {
  border-bottom: 0;
  border-bottom-left-radius: 0;
  border-bottom-right-radius: 0;
}
.task-calendar-workbench :deep(.c-scheduler__event:has([data-edge="middle"])) {
  border-block: 0;
  border-radius: 0;
}
.task-calendar-workbench :deep(.c-scheduler__event:has([data-edge="last"])) {
  border-top: 0;
  border-top-left-radius: 0;
  border-top-right-radius: 0;
}
.task-calendar-workbench :deep(.c-scheduler__event:has(.linked)) {
  box-shadow: inset 0 0 0 2px currentColor;
}
.task-calendar-workbench :deep(.c-scheduler__event:has(.rest)) {
  border-style: dashed;
}
.task-calendar-workbench :deep(.c-scheduler__event-button) {
  height: 100%;
  align-items: flex-start;
  padding-block: 0;
}
.deadline-mask {
  position: absolute;
  inset: 0;
  background: #66708526;
  pointer-events: none;
}
.detail-task-list {
  display: flex;
  flex-direction: column;
  gap: 12px;
  width: 100%;
}
.detail-task {
  padding: 8px 0;
  border-bottom: 1px solid var(--c-color-border);
}
.workbench-test-controls,
.workbench-notice {
  margin-top: 12px;
}
.payload {
  max-width: 480px;
  max-height: 300px;
  overflow: auto;
}

.task-calendar-workbench :deep(.c-scheduler__toolbar) {
  padding: 14px 16px;
}
.task-calendar-workbench :deep(.c-scheduler__toolbar .c-button) {
  box-shadow: none;
}
.task-calendar-workbench :deep(.c-scheduler__time-heading) {
  font-weight: 500;
}
.panel-title {
  font-size: 13px;
  font-weight: 600;
  color: var(--c-color-text-1);
}
.panel-scroll {
  scrollbar-width: thin;
  scrollbar-color: var(--c-color-border) transparent;
}
.source-scroll :deep(.c-tree-node-title-text),
.pending-panel :deep(.c-tree-node-title-text) {
  color: var(--c-color-text-2);
}
.pending-task {
  border-bottom: 1px solid var(--c-color-border);
}
.pending-task > small {
  color: var(--c-color-text-3);
}
.pending-task:active {
  cursor: grabbing;
}
.task-card > :first-child {
  font-weight: 600;
}
.task-card > :not(:first-child) {
  opacity: 0.85;
}
.quick-actions {
  border: 1px solid var(--c-color-border);
  border-radius: 6px;
  padding: 4px;
}
.workbench-test-controls {
  padding: 12px 16px;
  background: var(--c-color-fill-1);
  border-radius: 8px;
}
</style>
```

[打开宽屏工作台](llms/zh-CN/examples/task-calendar.md)。所有日期以打开页面时的本周一和今天动态生成，包含本周/下周、逾期/临期、已关闭记录与工作日轮休。

工作台将出勤单、任务、打卡保存为独立业务 DTO，再通过 `workbench-model.ts` 投影为 SchedulerEvent：一个任务一块，同单连续任务共享 `layoutGroupId`；同时勾选人员与设备时，各生成稳定视图 ID，点击/悬停关联高亮。跨天与全天单按出勤单投影到全天区。对象色、闭单白蒙版、休息斜纹和边框都由 Demo 映射，不添加组件业务状态。

人员/设备与待办分别使用 Cedar Tree，来源搜索固定在顶部。父节点勾选由 Tree 提供，重复资源条目的选中状态由资源 ID 同步；站点快捷按钮支持再次反选。待办按设备或选中人员负责的站点聚合，逾期优先、截止日期较早优先。待办可拖空白建单、拖到已有可编辑任务块合并，也可在详情中加入已勾选任务。一次打包限制同一设备。移出任务在保存后回池，最后一项移出后解散出勤单；取消或保存失败均不修改已保存数据。

详情支持按标准工时计算计划结束、查看工单、任务 hover/focus 显示该设备打卡并定位最近记录、关联已有打卡或手动补录后关单。已关闭、休息和查看者都不可编辑。时间重叠、每日超过 8 小时及超截止日只提示；技能、数据完整性、权限和版本冲突拒绝保存。拖动期间的截止日背景通过 `column-background` 插槽显示，空白仍允许落入。

保存使用独立内存 Mock API，`重新加载` 读取该 API 当前数据，刷新浏览器会重建 Mock。`提交数据` 可查看真实提交给 Mock 的业务 DTO，未把视图投影数组当成后端主表。移动通过 `before-change` 异步准备、`change` 成功后版本比较并提交，取消或过期手势不写入服务端；表单直接调用同一业务 API。保存失败保留草稿和勾选。生产接入只替换 API，不需要修改 Scheduler。

交互取舍：详情统一用 Dialog；全天表单允许填写日期范围；任务级实际打卡时间尚无独立来源时，闭单后的任务块按标准工时比例分布在整单真实打卡区间，详情保留原始记录。原生拖放合并的目标为任务卡片内容区，键盘操作使用“加入已勾选任务”；不向核心增加出勤单 drop-target 协议。

## API

### `<c-scheduler>` Props

| 属性                       | 说明                                                                    | 类型                                            | 默认值       |
| -------------------------- | ----------------------------------------------------------------------- | ----------------------------------------------- | ------------ |
| model-value                | 日程数据，支持 v-model；传入时受控                                      | SchedulerEvent[]                                | —            |
| preview-event              | 尚未保存的新增日程占位，只参与视觉展示                                  | SchedulerEvent                                  | —            |
| default-value              | 非受控初始数据                                                          | SchedulerEvent[]                                | []           |
| mode                       | 当前视图，支持 v-model:mode                                             | SchedulerMode                                   | —            |
| default-mode               | 非受控默认视图                                                          | SchedulerMode                                   | week         |
| date                       | 定位日期，支持 v-model:date                                             | Date / string / number                          | —            |
| default-date               | 初始定位日期                                                            | Date / string / number                          | 当前日期     |
| resource-dimensions        | 维度定义 `{ id, label }[]`                                              | SchedulerResourceDimension[]                    | []           |
| resource-filters           | 跨维度组合筛选，支持 v-model:resource-filters                           | SchedulerResourceFilters                        | —            |
| default-resource-filters   | 非受控筛选初值                                                          | SchedulerResourceFilters                        | {}           |
| resource-dimension         | 资源行/列展示维度，空字符串显示全部                                     | string                                          | —            |
| default-resource-dimension | 非受控展示维度初值                                                      | string                                          | ''           |
| resources                  | 当前可见资源行/列及本地选项，不要求全量目录                             | SchedulerResource[]                             | []           |
| resource-label             | 资源字段名称，如设备、会议室                                            | string                                          | 语言包“资源” |
| request-resources          | 按关键词和游标查询候选资源                                              | SchedulerRequestResources                       | —            |
| resolve-resources          | 按 ID 批量补全名称                                                      | SchedulerResolveResources                       | —            |
| modes                      | 允许切换的视图                                                          | SchedulerMode[]                                 | 全部六种     |
| first-day-of-week          | 周起始，0 周日至 6 周六                                                 | number                                          | 1            |
| start-hour                 | 时间网格起始小时，0–23                                                  | number                                          | 8            |
| end-hour                   | 时间网格结束小时，必须大于起始，最多 24                                 | number                                          | 20           |
| initial-scroll-minute      | 时间网格首次显示时定位的当天分钟数，后续保留用户滚动位置                | number                                          | —            |
| step                       | 时间格及吸附分钟，正整数且整除 60                                       | number                                          | 30           |
| slot-duration              | 网格分钟数，正整数                                                      | number                                          | step         |
| snap-duration              | 指针吸附分钟数，正整数                                                  | number                                          | step         |
| default-duration           | 单击新建默认分钟数，正整数                                              | number                                          | step         |
| drag-to-create             | 日/周/资源日程空白时段拖选                                              | boolean                                         | false        |
| month-event-limit          | 月视图每日直接展示上限，超出通过 Popover 查看                           | number                                          | 3            |
| overlap-event-limit        | 时间网格重叠组直接展示上限，超出通过 Popover 查看                       | number                                          | —            |
| zoom / default-zoom        | 时间线缩放，0.5–4                                                       | number                                          | 1            |
| show-date-header           | 时间线日期分层表头                                                      | boolean                                         | true         |
| show-assignment-details    | 编辑资源占用量与角色                                                    | boolean                                         | false        |
| show-resource-load         | 资源峰值、容量及范围利用率                                              | boolean                                         | false        |
| rule-policy                | capacity/unavailable/conflict 的 allow/warn/block 策略                  | SchedulerRulePolicy                             | {}（block）  |
| dependencies               | 任务依赖关系                                                            | SchedulerDependency[]                           | []           |
| event-layout               | 时间网格布局 stack / columns / 几何回调；默认周视图 stack、其他 columns | SchedulerEventLayout                            | 按视图       |
| readonly                   | 可查看和导航，不能修改                                                  | boolean                                         | false        |
| disabled                   | 禁用交互                                                                | boolean                                         | false        |
| hidden-days                | 周、月、议程隐藏指定星期，0–6，不可全部隐藏                             | number[]                                        | []           |
| show-now-indicator         | 日、周、资源日程显示当前本地时间标线                                    | boolean                                         | false        |
| show-sidebar               | 显示筛选和未排期列表                                                    | boolean                                         | true         |
| allow-overlap              | 允许同资源时间重叠                                                      | boolean                                         | true         |
| editable                   | 启用内置编辑器；false 通过 editor-request 接管                          | boolean                                         | true         |
| before-change              | 返回 false 取消；异步拦截、保存接口                                     | SchedulerBeforeChange / SchedulerBeforeChange[] | —            |

mode 为 `day | week | month | agenda | resource-day | resource-timeline`。agenda 与资源时间线按周导航。超出时间网格小时范围的日程仍可在月/议程/时间线查看。

model-value 受控时，组件只提出新值，由父组件接受后更新界面；不会在接口失败后先移动再回滚。组件不修改输入数组或对象。before-change 得到分离副本，修改副本不会修改提交值。

### `<c-scheduler>` Events

| 事件                     | 说明                                                             | 参数                                 |
| ------------------------ | ---------------------------------------------------------------- | ------------------------------------ |
| update:model-value       | 提出新主值                                                       | SchedulerEvent[]                     |
| update:resourceFilters   | 维度组合筛选变更，受控时等待父组件接受                           | SchedulerResourceFilters             |
| update:resourceDimension | 资源行/列展示维度变更                                            | string                               |
| update:mode              | 视图切换                                                         | SchedulerMode                        |
| update:zoom              | 时间线缩放值变化                                                 | number                               |
| rule-warning             | 提案通过时的提醒型规则问题                                       | SchedulerError[]                     |
| update:date              | 定位日期变更                                                     | Date                                 |
| change                   | 校验和钩子完成；受控时表示已提出通过的值                         | value, SchedulerChangeContext        |
| change-error             | 校验、冲突、保存或过期提案错误                                   | error, SchedulerChange               |
| event-click              | 激活日程（传出副本）；叠放重叠项同样通过单击或 Enter，多选不触发 | SchedulerEvent                       |
| cell-click               | 点击空白时段                                                     | SchedulerCell                        |
| range-change             | 首次与实际可见日期范围变化                                       | SchedulerRange                       |
| resource-error           | 资源搜索或回显失败，不修改日程数据                               | error, SchedulerResourceErrorContext |
| editor-request           | 仅 editable=false：请求外部新建或查看/编辑                       | SchedulerEditorRequest               |

### `<c-scheduler>` Slots

| 插槽              | 参数                                             | 说明                                                                                                               |
| ----------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ |
| event             | { event }                                        | 日程按钮内容                                                                                                       |
| sidebar           | { startDrag, cancelDrag, disabled, unscheduled } | 替换整个侧栏；适合业务资源树与待排任务池，show-sidebar=false 时不显示                                              |
| sidebar-extra     | { startDrag, cancelDrag, disabled }              | 默认侧栏顶部自定义内容；startDrag(template: SchedulerEventTemplate, event: DragEvent)，show-sidebar=false 时不显示 |
| resource-header   | { resource?, resources?, date }                  | 资源标题或日期标题                                                                                                 |
| toolbar           | { date, mode, navigate, create }                 | 替换工具栏；navigate(-1/1) 切换范围，create() 走工具栏新增流程                                                     |
| column-background | { date, resource? }                              | 日/周/资源日程列背景，不接管指针；用于业务软提示、热力背景等                                                       |
| toolbar-extra     | { date, mode }                                   | 工具栏扩展                                                                                                         |
| editor            | SchedulerEditorSlotProps                         | 自定义抽屉内容：action、event、error、errorMessage、save、remove、close、readonly、pending                         |
| empty             | —                                                | 空状态                                                                                                             |

### 实例方法

| 方法                               | 说明                                                           |
| ---------------------------------- | -------------------------------------------------------------- |
| `change(change): Promise<boolean>` | 执行 create/update/remove/move/resize，复用全部校验与钩子      |
| duplicateEvent(id: string)         | 打开独立复制草稿或发出自定义创建请求，返回 boolean，不自动保存 |
| goToDate(date: Date)               | 定位日期；遵循受控模型                                         |

## 类型定义

```ts
import type {
  SchedulerProps,
  SchedulerInstance,
  SchedulerMode,
  SchedulerEvent,
  SchedulerResource,
  SchedulerChange,
  SchedulerChangeContext,
  SchedulerBeforeChange,
  SchedulerEventTemplate,
  SchedulerRequestResources,
  SchedulerResolveResources,
  SchedulerResourcePage,
  SchedulerResourceQuery,
  SchedulerResourceErrorContext,
  SchedulerEditorRequest,
  SchedulerEditorAction,
  SchedulerEditorSlotProps,
} from "@cedar-design/ui";

interface SchedulerEvent {
  id: string;
  title: string;
  start?: Date | string | number;
  end?: Date | string | number;
  allDay?: boolean;
  resourceIds?: string[];
  resourceDetails?: Record<string, { units?: number; role?: string }>;
  milestone?: boolean;
  layoutGroupId?: string;
  description?: string;
  color?: string;
  accentColor?: string;
  backgroundColor?: string;
  backgroundPattern?: "solid" | "diagonal-stripes" | "dots" | "crosshatch";
  metadata?: Record<string, unknown>;
  readonly?: boolean;
  resizable?: boolean; // false 禁用时间网格拉伸，仍可移动/查看
}
type SchedulerEventTemplate = Pick<
  SchedulerEvent,
  | "title"
  | "description"
  | "color"
  | "accentColor"
  | "backgroundColor"
  | "backgroundPattern"
  | "metadata"
  | "resourceIds"
> & {
  duration?: number; // 正数分钟，默认 default-duration 或 step
};
interface SchedulerResource {
  id: string;
  dimensionId?: string;
  label: string;
  color?: string;
  disabled?: boolean;
  capacity?: number; // 非负安全整数，省略不限制并发日程数
}
interface SchedulerResourceQuery {
  dimensionId?: string;
  query: string;
  cursor?: string;
  signal: AbortSignal;
}
interface SchedulerResourcePage {
  items: SchedulerResource[];
  nextCursor?: string;
}
type SchedulerRequestResources = (
  query: SchedulerResourceQuery,
) => SchedulerResourcePage | Promise<SchedulerResourcePage>;
type SchedulerResolveResources = (
  ids: string[],
  context: { signal: AbortSignal },
) => SchedulerResource[] | Promise<SchedulerResource[]>;
type SchedulerResourceErrorContext =
  | { type: "search"; query: string; cursor?: string }
  | { type: "resolve"; ids: string[] };

type SchedulerEditorAction = "create" | "edit";
type SchedulerEditorRequest = { event: SchedulerEvent; readonly: boolean } & (
  | { action: "create"; source: "toolbar" | "cell" | "drop" }
  | { action: "edit"; source: "event" }
);
interface SchedulerEditorSlotProps {
  action: SchedulerEditorAction;
  event: SchedulerEvent;
  error?: SchedulerError;
  errorMessage?: string;
  readonly: boolean;
  pending: boolean;
  save: (event?: SchedulerEvent) => void;
  remove: () => void;
  close: () => void;
}
```

每条日程 id 必须唯一。start/end 同时省略表示未排期；否则 end 必须晚于 start；定时 milestone 例外，要求 start=end。所有区间为 `[start, end)`，前后相邻不冲突。allDay 为 true 时使用 `YYYY-MM-DD` 字符串，end 是不包含的结束日期（一天事项如 9 月 9 日至 9 月 10 日）。

当前按运行环境本地时区显示，定时日程建议传 ISO 时间点；没有任意 IANA 显示时区的承诺。跨时区 RRULE、ICS 与版本同步从独立 adapters 入口提供，真实外部账号连接需业务实现；虚拟资源行通过 virtual-list-props 配置。本地历史撤销与按范围远程加载见上方示例。指针拖拽支持移动与拉伸，Escape 取消；键盘与触屏也可通过编辑表单完成排期/分配修改。资源选项的 disabled 禁止新增分配与拖入，已存在的关联可保留或移除。

## 独立核心

源码 `src/scheduler/core` 不导入 Vue、DOM 或外部日历库，可单独测试及后续提取为 scheduler-core 包。发布后可直接使用纯核心子入口，避免导入组件运行时：

```ts
import {
  applySchedulerChange,
  getSchedulerConflicts,
  layoutSchedulerEvents,
} from "@cedar-design/ui/scheduler/core";
```

其余日期与时间线工具也从该入口导出。核心提供计算与不可变变更，不承担网络、权限认证或数据库事务。

### 样式变量

所有变量集中于 `style/token.less`，支持亮暗主题覆盖。

| 变量名                           | 默认值                         |
| -------------------------------- | ------------------------------ |
| --c-scheduler-background         | var(--c-color-bg-2)            |
| --c-scheduler-color              | var(--c-color-text-1)          |
| --c-scheduler-border-color       | var(--c-color-border)          |
| --c-scheduler-sidebar-width      | 220px                          |
| --c-scheduler-slot-height        | 36px                           |
| --c-scheduler-column-min-width   | 120px                          |
| --c-scheduler-max-height         | 720px                          |
| --c-scheduler-event-color        | rgb(var(--c-primary-6))        |
| --c-scheduler-event-accent-color | var(--c-scheduler-event-color) |
| --c-scheduler-event-background   | var(--c-color-primary-light-1) |
| --c-scheduler-lane-height        | 38px                           |
| --c-scheduler-ghost-opacity      | 0.75                           |
| --c-scheduler-preview-opacity    | 0.85                           |
| --c-scheduler-preview-duration   | 100ms                          |
| --c-scheduler-ghost-z-index      | 2000                           |

### 守卫等待反馈

before-* 等待期间显示加载反馈并标记 aria-busy；拒绝或失败后恢复，重复提交不再启动同一操作。普通事件返回的 Promise 不参与加载。

---

Document: llms/zh-CN/components/scrollbar.md

<!-- Source: src/scrollbar/README.md; locale: zh-CN; page: /components/scrollbar/ -->

# Scrollbar

## 基础示例

### 基础用法

滚动条组件基本用法。scrollbar 的默认插槽需要唯一的子元素。

Example source: src/scrollbar/__demos__/basic.vue

```vue
<template>
  <c-scrollbar style="height: 200px; overflow: auto">
    <div style="height: 2000px; width: 2000px; background-color: var(--c-color-primary-light-1)">Content</div>
  </c-scrollbar>
</template>

<script lang="ts" setup>
</script>
```

## 外观与状态

### 滚动条类型

设置 `type` 属性改变滚动条类型，`track` 类型会显示滚动条轨道。

Example source: src/scrollbar/__demos__/type.vue

```vue
<template>
  <c-scrollbar type="track" style="height: 200px; overflow: auto">
    <div style="height: 2000px; width: 2000px; background-color: var(--color-primary-light-4)">Content</div>
  </c-scrollbar>
</template>

<script lang="ts" setup>
</script>
```

## 生命周期与边界

### Thumb drag lifecycle / 滑块拖动生命周期

方向、max、thumbSize、ratio的有效值变化取消当前手势；仅替换等值data对象不取消连续拖动。最终偏移仍由父级新测量／setOffset结算。几何读取与响应式写入后重新核对会话，防止同步卸载后绑定或通知。停用／卸载保留按下／轨道点击／setOffset入口无效且不preventDefault；非左键不启动／跳转。当前setOffset夹取、拖动期间忽略外部setOffset和轨道一thumb-size步进保持。没有Pointer／touch拖动协议迁移或原生滚动回滚承诺。

Example source: src/scrollbar/__demos__/thumb-lifecycle.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const active = ref(true)
const mounted = ref(true)
const scrolls = ref(0)
</script>
<template>
  <div>
    <c-button @click="active = !active">Activate / 停用与激活</c-button>
    <c-button @click="mounted = !mounted">Mount / 卸载与挂载</c-button>
    <c-button @mouseenter="active = false">Hover while dragging to deactivate / 拖动时移入停用</c-button>
    <p>Scroll notifications / 滚动通知: {{ scrolls }}. Drag a thumb, release, open context menu or blur the window; later movement must not replay. Fresh activation requires a fresh press.</p>
    <KeepAlive v-if="mounted">
      <c-scrollbar v-if="active" style="height: 160px; width: 260px; overflow: auto" @scroll="scrolls++">
        <div style="height: 800px; width: 700px">Drag the horizontal/vertical thumb / 拖动横向或纵向滑块</div>
      </c-scrollbar>
    </KeepAlive>
  </div>
</template>
```

### Scrollbar consumer lifecycle / 滚动条消费者生命周期

scrollTo(0,0)／单轴0是合法坐标，不用真值判断；恢复零位置也同步thumb，不保留上次偏移。水平测量使用水平比例（旧代码误用了垂直比例）。零／无效视口用有限、非负thumb数据，不显示该零尺寸轴；正常最小thumb20px与track15px布局策略不变。禁用／隐藏轴的旧thumb命令无效，但禁用条不等于禁止内容或公开原生滚动。对象选项直接透传、不模拟JS动画；公开方法签名／样式变量不变。

Example source: src/scrollbar/__demos__/lifecycle.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
import type { ScrollbarInstance } from '@cedar-design/ui'
const active = ref(true)
const mounted = ref(true)
const bar = ref<ScrollbarInstance>()
let retained: ScrollbarInstance | undefined
function remember() { retained = bar.value }
function scrollRetained() { retained?.scrollTo(100, 100) }
</script>
<template>
  <div>
    <c-button @click="remember">Remember handle / 保留句柄</c-button>
    <c-button @click="active = !active">Activate / 停用与激活</c-button>
    <c-button @click="mounted = !mounted">Mount / 卸载与挂载</c-button>
    <c-button @click="scrollRetained">Retained scroll / 调用保留滚动</c-button>
    <c-button @click="bar?.scrollTo(0, 0)">Origin / 回到原点</c-button>
    <p>Remember the handle, deactivate or unmount, then call it. It must be inert. Activate for fresh commands; zero coordinates must work.</p>
    <KeepAlive v-if="mounted">
      <c-scrollbar v-if="active" ref="bar" style="height: 160px; width: 260px; overflow: auto">
        <div style="height: 800px; width: 700px">Scrollable content / 可滚动内容</div>
      </c-scrollbar>
    </KeepAlive>
  </div>
</template>
```

## API

### `<scrollbar>` Props

| 参数名      | 描述       | 类型                    |  默认值   |
| ----------- | ---------- | ----------------------- | :-------: |
| type        | 类型       | `'track' \| 'embed'`    | `'embed'` |
| outer-class | 外层的类名 | `string\|object\|array` |    `-`    |
| outer-style | 外层的样式 | `StyleValue`            |    `-`    |

### `<scrollbar>` Events

| 事件名 | 描述       | 参数 |
| ------ | ---------- | ---- |
| scroll | 滚动时触发 | -    |

### `<scrollbar>` Methods

| 方法名     | 描述     | 参数                                                             | 返回值 | 版本   |
| ---------- | -------- | ---------------------------------------------------------------- | ------ | :----- |
| scrollTo   | 滚动     | options: `number \| {left?: number;top?: number}`<br>y: `number` | -      |        |
| scrollTop  | 纵向滚动 | top: `number`                                                    | -      | 2.40.0 |
| scrollLeft | 横向滚动 | left: `number`                                                   | -      | 2.40.0 |

### 类型定义

组件导出以下类型定义

```ts
import type { ScrollbarBoxInstance } from '@cedar-design/ui'
```

---

Document: llms/zh-CN/components/search.md

<!-- Source: src/search/README.md; locale: zh-CN; page: /components/search/ -->

# Search

搜索组件，支持基础搜索、按钮搜索、字段搜索和受控的最近搜索记录。组件内部不持久化搜索历史；开发者可以根据 `search` 事件返回的 `recentSearches` 自行缓存到本地、服务端或状态管理中，再通过 `recent-searches` 回传给组件。

先看关键词与提交，再看字段模型，最后接入受控历史和自定义展示。组件不发业务请求，外部在 search 事件中处理异步任务并控制 loading。

## 基础示例

### 基础用法

输入关键词后按 Enter 提交；本例只展示一个关键词和提交结果。字段模型与历史记录在后续独立案例中说明。

Example source: src/search/__demos__/basic.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
import type { SearchResult } from '@cedar-design/ui'
const keyword = ref('')
const submitted = ref('')
function onSearch(result: SearchResult) { submitted.value = result.modelValue }
</script>
<template>
  <c-search v-model="keyword" placeholder="输入关键词后按 Enter" @search="onSearch" />
  <p role="status">已提交：{{ submitted || '尚未搜索' }}</p>
</template>
```

## 数据与选项

### 搜索按钮

<!-- demo-config-notes:start -->

#### 本组配置对照

| 配置              | 作用                 | 相关示例                                   |
| ----------------- | -------------------- | ------------------------------------------ |
| `placeholder`     | 占位符               | 搜索按钮、带下拉字段选择、本地缓存搜索历史 |
| `search-button`   | 是否显示公共搜索按钮 | 搜索按钮、带下拉字段选择                   |
| `recent-searches` | 受控搜索历史         | 带下拉字段选择、本地缓存搜索历史           |
| `button-text`     | 公共搜索按钮文字     | 搜索按钮                                   |
| `fields`          | 搜索字段可选项       | 带下拉字段选择                             |
| `select-style`    | 字段选择器样式       | 带下拉字段选择                             |

<!-- demo-config-notes:end -->

点击按钮提交与按 Enter 使用相同的 search 事件。

Example source: src/search/__demos__/search-button.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
import type { SearchResult } from '@cedar-design/ui'
const keyword = ref('')
const submitted = ref('')
function onSearch(result: SearchResult) { submitted.value = result.modelValue }
</script>
<template>
  <c-search v-model="keyword" search-button button-text="查询" placeholder="点击查询按钮提交" @search="onSearch" />
  <p role="status">已提交：{{ submitted || '尚未搜索' }}</p>
</template>
```

### 带下拉字段选择

Example source: src/search/__demos__/with-fields.vue

```vue
<template>
  <c-space direction="column">
    <c-search
      v-model="keyword"
      v-model:model-field="modelField"
      v-model:model="model"
      :style="inputStyle"
      :fields="fields"
      :recent-searches="recentSearches"
      :select-style="{ minWidth: '140px' }"
      default-field="name"
      placeholder="请输入搜索内容"
      search-button
      @change="handleChange"
      @search="handleSearch"
    />
    <c-button @click="resetModel">Reset Model</c-button>
    <div>最近提交：{{ latestChange || "-" }}</div>
    <pre v-if="latestResult">{{ JSON.stringify(latestResult, null, 2) }}</pre>
  </c-space>
</template>

<script lang="ts" setup>
import { ref } from "vue";
import type { SearchResult, SearchField } from "@cedar-design/ui";

const inputStyle = { width: "420px" };
const keyword = ref("");
const modelField = ref("name");
const model = ref<Record<string, unknown>>({});
const recentSearches = ref<string[]>(["设备 A", "设备 B", "设备 C"]);
const latestChange = ref("");
const latestResult = ref<SearchResult>();

const fields: SearchField[] = [
  {
    value: "id",
    label: "设备 ID",
    placeholder: "请输入设备 ID",
  },
  {
    value: "name",
    label: "设备名称",
    placeholder: "请输入设备名称",
  },
  {
    value: "desc",
    label: "设备描述",
    placeholder: "请输入设备描述",
  },
];

function handleSearch(data: SearchResult) {
  recentSearches.value = data.recentSearches;
  latestResult.value = data;
}

function handleChange(value: string) {
  latestChange.value = value;
}

function resetModel() {
  model.value = {};
  keyword.value = "";
}
</script>
```

### 本地缓存搜索历史

Example source: src/search/__demos__/local-storage.vue

```vue
<template>
  <c-space direction="column">
    <c-search
      v-model="keyword"
      :style="inputStyle"
      placeholder="业务侧使用 localStorage 保存搜索历史"
      :recent-searches="recentSearches"
      @search="handleSearch"
    />
    <c-button @click="clearRecentSearches">Clear History</c-button>
  </c-space>
</template>

<script lang="ts" setup>
import { ref } from "vue";
import type { SearchResult } from "@cedar-design/ui";

const inputStyle = { width: "360px" };
const storageKey = "__cedar_search_history__";

const keyword = ref("");
const recentSearches = ref<string[]>(loadRecentSearches());

function loadRecentSearches() {
  try {
    return JSON.parse(localStorage.getItem(storageKey) || "[]");
  } catch {
    return [];
  }
}

function saveRecentSearches(list: string[]) {
  localStorage.setItem(storageKey, JSON.stringify(list));
  recentSearches.value = list;
}

function handleSearch(data: SearchResult) {
  saveRecentSearches(data.recentSearches);
}

function clearRecentSearches() {
  saveRecentSearches([]);
}
</script>
```

## 自定义与插槽

### 历史展示与插槽

<!-- demo-config-notes:start -->

#### 本组配置对照

| 配置              | 作用                                              | 相关示例       |
| ----------------- | ------------------------------------------------- | -------------- |
| `edit-mode`       | 搜索编辑方式：direct 为直接搜索，popup 为弹层搜索 | 历史展示与插槽 |
| `recent-searches` | 受控搜索历史                                      | 历史展示与插槽 |
| `label`           | 搜索框左侧文本                                    | 历史展示与插槽 |
| `placeholder`     | 占位符                                            | 历史展示与插槽 |
| `clearable`       | 是否可清除                                        | 历史展示与插槽 |
| `show-action`     | 是否显示操作按钮                                  | 历史展示与插槽 |

<!-- demo-config-notes:end -->

Example source: src/search/__demos__/presentation.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import type { SearchResult } from "@cedar-design/ui";
const keyword = ref("");
const popup = ref(false);
const history = ref(["项目 A", "设备 B"]);
const lastAction = ref("尚未搜索");
function recordSearch(result: SearchResult) {
  history.value = result.recentSearches;
  lastAction.value = result.modelValue;
}
function recordAction(result: SearchResult) {
  lastAction.value = result.modelValue;
}
</script>
<template>
  <div class="search-demo">
    <c-checkbox v-model="popup">popup 全屏搜索（关闭后为 direct）</c-checkbox>
    <c-search
      v-model="keyword"
      :edit-mode="popup ? 'popup' : 'direct'"
      :recent-searches="history"
      label="资源"
      placeholder="输入资源名称"
      clearable
      show-action
      action-text="取消"
      @cancel="lastAction = '已取消'"
      @search="recordSearch"
    />
    <c-search
      v-model="keyword"
      search-button
      :button-props="{ variant: 'outline' }"
      placeholder="自定义按钮插槽"
      @search="recordAction"
    >
      <template #button-icon><span aria-hidden="true">⌕</span></template>
      <template #button-default>查找</template>
    </c-search>
    <div>最近操作：{{ lastAction }}</div>
  </div>
</template>
<style scoped>
.search-demo {
  display: flex;
  flex-direction: column;
  gap: 12px;
  max-width: 100%;
}
</style>
```

## 交互与控制

### 交互状态切换

<!-- demo-config-notes:start -->

#### 本组配置对照

| 配置            | 作用                             | 相关示例             |
| --------------- | -------------------------------- | -------------------- |
| `placeholder`   | 占位符                           | 交互状态切换、加载中 |
| `loading`       | 是否处于加载状态；加载时禁止提交 | 交互状态切换、加载中 |
| `readonly`      | 是否只读                         | 交互状态切换、加载中 |
| `search-button` | 是否显示公共搜索按钮             | 加载中、受控字段模型 |
| `disabled`      | 是否禁用                         | 交互状态切换         |
| `default-value` | 非受控默认关键词                 | 加载中               |

<!-- demo-config-notes:end -->

适用于关键词输入与搜索提交。调整禁用、只读，用相同数据观察变化。控制区始终可用，可以随时恢复编辑；错误外观本身不会触发表单校验。

Example source: src/search/__demos__/state-lab.vue

```vue
<script setup lang="ts">
import { reactive as __demoReactive } from "vue";
const inputStyle = { width: "360px" };
const __demoState = __demoReactive({ disabled: false, readonly: false });
</script>
<template>
  <c-space direction="column" :size="16">
    <c-space wrap>
      <c-checkbox v-model="__demoState['disabled']">disabled</c-checkbox>
      <c-checkbox v-model="__demoState['readonly']">readonly</c-checkbox>
    </c-space>
    <c-search
      :style="inputStyle"
      placeholder="加载中"
      loading
      v-bind="__demoState"
    />
  </c-space>
</template>
```

### 加载中

Example source: src/search/__demos__/loading.vue

```vue
<template>
  <c-space direction="column">
    <c-search :style="inputStyle" placeholder="加载中" loading />
    <c-search
      :style="inputStyle"
      placeholder="按钮加载中"
      search-button
      loading
    />
    <c-search :style="inputStyle" default-value="只读内容" readonly />
  </c-space>
</template>

<script lang="ts" setup>
const inputStyle = { width: "360px" };
</script>
```

### 受控字段模型

Example source: src/search/__demos__/controlled-fields.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import type { SearchResult } from "@cedar-design/ui";

const field = ref("name");
const model = ref<Record<string, unknown>>({ name: "设备 A", tenant: "demo" });
const accepted = ref(true);
const history = ref(["设备 A", "42"]);
const result = ref<SearchResult>();
const fields = [
  { value: "name", label: "设备名称", placeholder: "输入名称" },
  { value: "id", label: "设备 ID", placeholder: "输入 ID" },
];
function updateModel(proposal: Record<string, unknown>) {
  if (accepted.value) model.value = proposal;
}
function updateField(proposal: string) {
  if (accepted.value) field.value = proposal;
}
function search(next: SearchResult) {
  result.value = next;
  history.value = next.recentSearches;
}
</script>
<template>
  <div class="search-demo">
    <c-checkbox v-model="accepted"
      >接受输入与清空（关闭后父级拒绝更新）</c-checkbox
    >
    <c-search
      :model="model"
      :model-field="field"
      :fields="fields"
      :recent-searches="history"
      edit-mode="direct"
      search-button
      button-text="搜索"
      clearable
      @update:model="updateModel"
      @update:model-field="updateField"
      @search="search"
    />
    <c-button
      variant="text"
      @click="model = { name: '外部替换', tenant: 'demo' }"
      >外部替换模型</c-button
    >
    <div>已接受模型：{{ model }}</div>
    <p v-if="!accepted" role="status">
      父级正在拒绝输入和清空；打开上方开关后恢复。
    </p>
    <pre v-if="result">{{ JSON.stringify(result, null, 2) }}</pre>
  </div>
</template>
<style scoped>
.search-demo {
  display: flex;
  flex-direction: column;
  gap: 12px;
  max-width: 100%;
}
.search-demo pre {
  white-space: pre-wrap;
  overflow-wrap: anywhere;
}
</style>
```

## API

### 空值识别与阅读空文案

`empty-values` 用于空值识别，`empty-value` 保留原清空输出；`empty-text` 仅在 `read-pretty` 空内容下展示，默认 `'-'`，字段 > FormItem > Form，自定义 read 插槽优先。显式配置 empty-values 后，内置 required 接入该策略，自定义校验仍收到原值。详见[统一说明](llms/zh-CN/guide/empty-values.md)。

| 参数         | 类型               | 缺省与范围                                            |
| ------------ | ------------------ | ----------------------------------------------------- |
| empty-values | readonly unknown[] | 字段 > FormItem > Form > 组件族默认；完整覆盖，不合并 |
| empty-text   | string             | 字段 > FormItem > Form > '-'；显式 '' 有效            |

以上是字段展示层 API；纯面板不因此新增阅读模式。Form 与 FormItem 提供继承配置。empty-value 的现有类型与默认输出仍按该组件原 API 执行。

### 属性

| 参数                       | 说明                                              | 类型                      | 默认值                     |
| -------------------------- | ------------------------------------------------- | ------------------------- | -------------------------- |
| `v-model`                  | 搜索关键词                                        | _string_                  | `-`                        |
| `default-value`            | 非受控默认关键词                                  | _string_                  | `''`                       |
| `v-model:model-field`      | 当前搜索字段                                      | _string_                  | `-`                        |
| `default-field`            | 非受控默认字段                                    | _string_                  | `-`                        |
| `v-model:model`            | 字段搜索模式下按字段写入的对象                    | _Record<string, unknown>_ | `-`                        |
| `fields`                   | 搜索字段可选项                                    | _SearchField[]_           | `[]`                       |
| `select-style`             | 字段选择器样式                                    | _StyleValue_              | `-`                        |
| `recent-searches`          | 受控搜索历史                                      | _string[]_                | `[]`                       |
| `max-search-history-count` | 生成下一份历史时保留的最大数量                    | _number_                  | `5`                        |
| `edit-mode`                | 搜索编辑方式：direct 为直接搜索，popup 为弹层搜索 | `'direct' \| 'popup'`     | `'direct'`                 |
| `search-button`            | 是否显示公共搜索按钮                              | _boolean_                 | `false`                    |
| `button-text`              | 公共搜索按钮文字                                  | _string_                  | `-`                        |
| `button-props`             | 公共搜索按钮属性                                  | _ButtonProps_             | `-`                        |
| `loading`                  | 是否处于加载状态；加载时禁止提交                  | _boolean_                 | `false`                    |
| `clearable`                | 是否可清除                                        | _boolean_                 | `false`                    |
| `variant`                  | 输入框风格，可选 `filled` `outline` `standard`    | _string_                  | `outline`                  |
| `size`                     | 输入尺寸，继承 Form / ConfigProvider              | `xs / sm / md / lg / xl`  | `md`                       |
| `placeholder`              | 占位符                                            | _string_                  | `-`                        |
| `disabled`                 | 是否禁用                                          | _boolean_                 | `false`                    |
| `readonly`                 | 是否只读                                          | _boolean_                 | `false`                    |
| `label`                    | 搜索框左侧文本                                    | _string_                  | `-`                        |
| `shape`                    | 内层搜索框形状，可选 `round` `square`             | _string_                  | `square`                   |
| `background`               | 外层背景色                                        | _string_                  | `-`                        |
| `input-background`         | 内层搜索框背景色                                  | _string_                  | `-`                        |
| `show-action`              | 是否显示操作按钮                                  | _boolean_                 | `false`                    |
| `action-text`              | 操作按钮文字                                      | `string`                  | 跟随全局语言与 action-type |
| `action-type`              | 操作类型，可选 `cancel` `search`                  | _string_                  | `cancel`                   |
| `search-icon`              | 搜索图标名称                                      | _string_                  | `magnify`                  |
| `max-length`               | 最大长度                                          | _string \| number_        | `-`                        |
| `enterkeyhint`             | 虚拟键盘回车键提示                                | _string_                  | `search`                   |

### 事件

| 事件名              | 说明                                     | 回调参数                             |
| ------------------- | ---------------------------------------- | ------------------------------------ |
| `update:modelValue` | 关键词更新时触发                         | `value: string`                      |
| `update:modelField` | 字段更新时触发                           | `field: string`                      |
| `update:model`      | 字段表单更新时触发                       | `model: Record<string, unknown>`     |
| `input`             | 输入期间触发                             | `value: string, event: Event`        |
| `change`            | 失焦、Enter 提交或切换字段时触发         | `value: string, event: Event`        |
| `clear`             | 清除时触发                               | `event: Event`                       |
| `search`            | 点击图标/按钮、按 Enter 或选择历史时触发 | `result: SearchResult, event: Event` |
| `focus`             | 聚焦时触发                               | `event: FocusEvent`                  |
| `blur`              | 失焦时触发                               | `event: FocusEvent`                  |
| `cancel`            | 点击移动端取消按钮时触发                 | `event: Event`                       |

### 插槽

| 名称             | 说明                                 | 参数        |
| ---------------- | ------------------------------------ | ----------- |
| `prefix`         | 输入框前缀；提供后将替换默认搜索图标 | `-`         |
| `suffix`         | 输入框后缀                           | `-`         |
| `clear-icon`     | 清除图标                             | `{ clear }` |
| `button-default` | 公共搜索按钮内容                     | `-`         |
| `button-icon`    | 公共搜索按钮图标                     | `-`         |
| `label`          | 左侧标签                             | `-`         |
| `action`         | 操作按钮内容                         | `-`         |

### 方法

| 方法名  | 说明 | 参数 | 返回值 |
| ------- | ---- | ---- | ------ |
| `focus` | 聚焦 | `-`  | `-`    |
| `blur`  | 失焦 | `-`  | `-`    |

### SearchField

| 参数          | 说明                                       | 类型     |
| ------------- | ------------------------------------------ | -------- |
| `label`       | 字段文案                                   | _string_ |
| `value`       | 字段值                                     | _string_ |
| `placeholder` | 字段占位符，优先于 Search 的 `placeholder` | _string_ |

### SearchResult

| 参数             | 说明           | 类型                                   |
| ---------------- | -------------- | -------------------------------------- |
| `modelField`     | 搜索字段       | _string \| undefined_                  |
| `modelValue`     | 原始搜索关键词 | _string_                               |
| `model`          | 字段表单对象   | _Record<string, unknown> \| undefined_ |
| `recentSearches` | 下一份搜索历史 | _string[]_                             |

输入事件约定：编辑时先 `input`、再 `update:modelValue`；失焦提交仅在值变化时触发 `change`。清空依次触发 `clear → input → update:modelValue → change`，各一次，同时只更新一次搜索字段模型，不自动执行搜索。

输入事件先于模型更新。Enter 会等待 Input 提交及受控模型回填后生成搜索结果；父级拒绝 trim 提议时，搜索仍使用实际受控值。清空按 clear → input → update:modelValue → change 通知，不自动执行搜索。

## 受控模型协议

值优先级为 `modelValue` > `model[当前字段]` > 非受控 `defaultValue`。传入 `model` 且存在当前字段时，缺失/null 字段显示空字符串；同时绑定多个模型时，应在父级保持它们一致。`modelField` 优先于 `defaultField` 和第一项字段；受控值不会被内部强制覆盖。

`model` **不会被原地修改**。每次逻辑更新发出一份 `update:model` 新对象，清空已声明的其他字段、保留未声明属性；请使用 `v-model:model` 或显式接受提议。字段切换只产生一次 `update:modelField → update:modelValue → update:model → change`。父级可拒绝提议，Enter、按钮、历史项搜索均等待一轮更新后读取实际接受的字段、关键词和模型。

历史不按输入过滤，也不内部持久化；`search` 返回的新历史统一 trim、去空、去重并截取最大数量。空关键词不添加记录，非有限/负数最大数量按 0 处理。清空不执行搜索；取消提议空字符串并发出 cancel/change，不提交搜索。

输入编辑发出 `input → update:modelValue`；提交值变化时才发出 `change`。清空为 `clear → input → update:modelValue → change`，仅一次。只读、禁用、loading 会阻止搜索/取消/历史/字段操作；禁用和只读可继承 Form / FormItem / InputGroup。失活或卸载会取消未完成的异步搜索。

### 跨端边界

双方控制器、公开 API 和历史内容独立同源。两端默认 `presentation=inline`；Cedar 默认 `shape=square`，Maple 默认 `shape=round`；显式开启后分别使用本地 Drawer / Popup，不共享实例。Cedar 保留 InputGroup，Maple 保留移动搜索条布局和触控间距。Input 支持 `xs/sm/md/lg/xl`，外层条高度/间距仍由 Search token 控制，并非整个条随 size 等比例缩放。

### 公开类型

`SearchPresentation`、`SearchProps`, `SearchEmits`, `SearchSlots`, `SearchExpose`, `SearchField`, `SearchResult`.

### Input 属性透传

显式支持 `modelModifiers`、`type`、`ariaLabel`、`placeholder`、`maxLength`、`readonly`、`disabled`、`autofocus`、`enterkeyhint`、`textColor`、`focusColor`、`blurColor`、`size`、`variant`、`clearable`、`inputAttrs`、`error`。`inputAttrs` 将原生 name/autocomplete/ARIA 等属性传给外侧和全屏内输入框；`error` 可覆盖继承的错误状态。搜索、弹层取消和弹层标签沿用全局多语言系统。取消、字段、历史程序更新各通知一次 Form change，原生编辑沿用 Input 事件链。

## 配置清空后的值

`empty-value` 指定当前组件已有清空动作的输出；省略时采用该组件默认返回。具体类型以组件 API 为准。它不改变 empty-values 的识别规则，也不改变 Form reset 的初始值。

### 共享字段加载

`loading-mode="line"` 使用 FieldDecorator 的共享加载线；默认模式保留本组件已有的加载展示。加载状态本身不隐式设置 disabled 或 readonly。

---

Document: llms/zh-CN/components/segmented.md

<!-- Source: src/segmented/README.md; locale: zh-CN; page: /components/segmented/ -->

# Segmented 分段控制器

用于在少数互斥选项之间快速切换。

## 基础示例

### 基础用法

Example source: src/segmented/__demos__/basic.vue

```vue
<template>
  <c-segmented v-model="value" :options="['Daily', 'Weekly', 'Monthly']" />
</template>

<script setup>
import { ref } from 'vue'

const value = ref('Daily')
</script>
```

## 外观与状态

### 分段尺寸与禁用状态

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `size` | 尺寸 | 分段尺寸与禁用状态 |
| `options` | 选项列表 | 分段尺寸与禁用状态 |
| `disabled` | 禁用 | 分段尺寸与禁用状态 |
| `default-value` | 非受控默认值 | 分段尺寸与禁用状态 |
<!-- demo-config-notes:end -->

比较不同尺寸的密度与禁用选项的行为；受控值和块级布局保持独立。

Example source: src/segmented/__demos__/appearance-state-comparison.vue

```vue
<script setup lang="ts">
import { ref } from "vue"
import { proxyRefs as demoProxyRefs } from 'vue'

const scene1 = demoProxyRefs((() => {


const value = ref('md')

const options = ['xs', 'sm', 'md', 'lg', 'xl']
return { value, options }
})())

const scene2 = demoProxyRefs((() => {


const value = ref('on')
return { value }
})())
</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="size">
    <h4><span lang="zh-CN">尺寸</span><span lang="en-US">size</span></h4>
    <c-space direction="column">
        <c-segmented v-model="scene1.value" size="xs" :options="scene1.options" />
        <c-segmented v-model="scene1.value" size="sm" :options="scene1.options" />
        <c-segmented v-model="scene1.value" size="md" :options="scene1.options" />
        <c-segmented v-model="scene1.value" size="lg" :options="scene1.options" />
        <c-segmented v-model="scene1.value" size="xl" :options="scene1.options" />
      </c-space>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="disabled">
    <h4><span lang="zh-CN">禁用</span><span lang="en-US">disabled</span></h4>
    <c-space wrap>
        <c-segmented disabled :options="['A', 'B', 'C']" default-value="A" />
        <c-segmented
          v-model="scene2.value"
          :options="[{
      label: '可用',
      value: 'on'
    }, {
      label: '禁用',
      value: 'off',
      disabled: true
    }]"
        />
      </c-space>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

## 布局与排列

### 块级撑满

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `block` | 撑满父宽度 | 块级撑满 |
| `options` | 选项列表 | 块级撑满 |
<!-- demo-config-notes:end -->

Example source: src/segmented/__demos__/block.vue

```vue
<template>
  <div style="width: 360px">
    <c-segmented v-model="value" block :options="['列表', '看板', '日历']" />
  </div>
</template>

<script setup>
import { ref } from 'vue'

const value = ref('列表')
</script>
```

## 交互与控制

### 受控

Example source: src/segmented/__demos__/controlled.vue

```vue
<template>
  <c-space direction="column">
    <c-segmented :model-value="value" :options="options" @change="onChange" />
    <div>当前值：{{ value }}</div>
  </c-space>
</template>

<script setup>
import { ref } from 'vue'

const value = ref('a')
const options = [
  { label: '选项 A', value: 'a' },
  { label: '选项 B', value: 'b' },
  { label: '选项 C', value: 'c', disabled: true },
]

const onChange = (next) => {
  value.value = next
}
</script>
```

## 可访问性

- 根节点使用 `role="radiogroup"`，选项为原生 `radio`，支持键盘切换。
- 可通过 `name` 绑定表单字段名。
- 整体禁用时设置 `aria-disabled`。

## API

### Segmented Props

| 参数 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| model-value / v-model | 当前值 | `string \| number` | — |
| default-value | 非受控默认值 | `string \| number` | — |
| options | 选项列表 | `(string \| number \| SegmentedOption)[]` | `[]` |
| size | 尺寸 | `xs \| sm \| md \| lg \| xl` | `md` |
| disabled | 禁用 | `boolean` | `false` |
| block | 撑满父宽度 | `boolean` | `false` |
| orientation | 分段选项的横纵排列，默认 horizontal；不表示文字阅读方向 | `horizontal \| vertical` | `horizontal` |
| name | 原生 name | `string` | — |

### SegmentedOption

| 字段 | 说明 | 类型 |
| --- | --- | --- |
| label | 文案 | `string \| () => VNodeChild` |
| value | 值 | `string \| number` |
| disabled | 禁用该项 | `boolean` |

### Segmented Events

| 事件名 | 说明 | 参数 |
| --- | --- | --- |
| change | 值变化 | `(value, event)` |
| update:model-value | v-model | `(value)` |

### Segmented Slots

| 插槽名 | 说明 | 参数 |
| --- | --- | --- |
| label | 自定义选项内容 | `{ data: SegmentedOption }` |

---

Document: llms/zh-CN/components/select.md

<!-- Source: src/select/README.md; locale: zh-CN; page: /components/select/ -->

# Select

多选时，`inline` 下拉只显示选项；已选内容、单项移除和清空由输入框承担。确认式编辑面板保留“已选／清空”，选择为草稿，确认后提交。

当用户需要从一组同类数据中选择一个或多个时，可以使用下拉选择器，点击后选择对应项。

## 阅读方向

选择框继承来源 `dir`；独立使用时默认按阅读起点对齐，在 FormItem 内继续继承其 content-align。显式 left/right 保持物理对齐；标签保持业务数组顺序，空搜索时 Backspace 删除最后一个可关闭值。下拉与选择面板携带来源方向，自定义 popup-container 不覆盖该方向。

## 基础示例

### 基础用法

点击展开选项，选中后回填并收起；清除后可重新选择。本例只演示单选。

Example source: src/select/__demos__/basic.vue

```vue
<template>
  <c-space direction="column">
    <c-select v-model="value" :style="{ width: '240px' }" placeholder="Please select ..." aria-label="基础单选示例" clearable>
      <c-option>Beijing</c-option>
      <c-option>Shanghai</c-option>
      <c-option>Guangzhou</c-option>
      <c-option disabled>Disabled</c-option>
    </c-select>
  </c-space>
</template>

<script lang="ts">
import { defineComponent, ref } from 'vue'
export default defineComponent({
  setup() {
    const value = ref('Shanghai')
    return {
      value,
    }
  },
})
</script>
```

## 外观与状态

### 外观配置对比

<!-- demo-config-notes:start -->

#### 本组配置对照

| 配置          | 作用                                                | 相关示例                       |
| ------------- | --------------------------------------------------- | ------------------------------ |
| `options`     | 原始值、对象、分组均支持；三种展示使用同一数据源    | 外观配置对比、表单控件尺寸对照 |
| `clearable`   | 允许清除，保留禁用的已选项                          | 外观配置对比、表单控件尺寸对照 |
| `size`        | 完整支持 xs、sm、md、lg、xl，未设置时继承分组与表单 | 表单控件尺寸对照               |
| `variant`     | filled、outline、standard；未设置时继承 InputGroup  | 表单控件尺寸对照               |
| `placeholder` | 占位文本                                            | 表单控件尺寸对照               |
| `multiple`    | 多选；默认启用搜索                                  | 表单控件尺寸对照               |

<!-- demo-config-notes:end -->

选择一个对比维度后，同屏展示它的全部可选值；其余配置和内容保持一致。可切换其他配置检查组合效果；输入类预览共享一个值。

<details>
<summary>配置说明与使用限制</summary>

#### 变体

设置`variant="outline"`开启变体模式，常用于沉浸式使用。

#### 选择框大小

支持 xs、sm、md、lg、xl 五档尺寸。未设置时依次继承 InputGroup、FormItem、ConfigProvider，最终默认 md。

#### 外观组合

适用于选项数据明确的单选输入。调整变体、尺寸，用相同数据观察变化。内容保持一致，便于比较不同设置的实际效果。

</details>

Example source: src/select/__demos__/appearance-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref("design");
const options = [
  { label: "研发", value: "dev" },
  { label: "设计", value: "design" },
  { label: "运营", value: "ops", disabled: true },
];
const __demoAppearance = __demoReactive({ variant: "filled", size: "md" });

import { computed as demoComputed, ref as demoRef } from 'vue'
const demoCompareFields = [{"name":"variant","values":["filled","outline","standard"]},{"name":"size","values":["xs","sm","md","lg","xl"]}]
const demoCompareAxis = demoRef("variant")
const demoComparedOptions = demoComputed(() => demoCompareFields.find(field => field.name === demoCompareAxis.value)?.values ?? [])
</script>
<template>
  <c-space direction="column" :size="16">
    <c-form layout="vertical">
      <c-form-item layout="vertical" size="sm" label="variant">
        <c-radio-group
          v-model="__demoAppearance['variant']"
          aria-label="variant"
          :options="[
            { label: 'filled', value: 'filled' },
            { label: 'outline', value: 'outline' },
            { label: 'standard', value: 'standard' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
      <c-form-item layout="vertical" size="sm" label="size">
        <c-radio-group
          v-model="__demoAppearance['size']"
          aria-label="size"
          :options="[
            { label: 'xs', value: 'xs' },
            { label: 'sm', value: 'sm' },
            { label: 'md', value: 'md' },
            { label: 'lg', value: 'lg' },
            { label: 'xl', value: 'xl' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
    </c-form>
    <p class="demo-config-comparison-hint"><span lang="zh-CN">选择一个对比维度；其他配置和内容保持一致。输入类示例共享同一个值，便于比较外观。</span><span lang="en-US">Compare one dimension while keeping the other settings and content identical. Input specimens share the same value.</span></p>
<c-radio-group v-model="demoCompareAxis" aria-label="Compare configuration" :options="demoCompareFields.map(field => ({ label: field.name, value: field.name }))" />
<div class="demo-config-comparison">
<section v-for="sample in demoComparedOptions" :key="String(sample)">
<p><code>{{ demoCompareAxis }}={{ sample }}</code></p>
<c-select
      v-model="value"
      :options="options"
      clearable
      v-bind="{ ...__demoAppearance, [demoCompareAxis]: sample }"
    ></c-select>
</section>
</div>
  </c-space>
</template>

<style scoped>
.demo-config-comparison { display: grid; grid-template-columns: repeat(auto-fit, minmax(min(100%, 220px), 1fr)); gap: 20px; min-width: 0; max-width: 100%; }
.demo-config-comparison > section { min-width: 0; }
.demo-config-comparison p { margin: 0 0 8px; }
html:not([lang='en-US']) .demo-config-comparison-hint > [lang='en-US'],
html[lang='en-US'] .demo-config-comparison-hint > [lang='zh-CN'] { display: none; }
</style>
```

### 表单控件尺寸对照

切换五档 size 和三种字段变体，比较 Input、Button、Select、日期时间及其他单行表单控件的高度。Button 在这里固定使用 outline。DatePicker/TimePicker 是面板，此处使用带输入框的 Date/Time 字段。示例同时展示有值、可清空、标签删除与长标签多选；Select/Cascader 设置 tag-nowrap 时保持同档高度，长标签文字省略、删除图标保留；标签行可横向滚动，清空按钮和箭头固定在外侧。被省略的标签正文支持悬停、键盘聚焦或点按查看完整文字，点外部或按 Esc 关闭，不改变选中值。可清空后恢复选中值重复比较。多行文本和允许换行的多选内容按内容撑高。

Example source: src/field-decorator/__demos__/control-sizes.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
const sizes = ["xs", "sm", "md", "lg", "xl"] as const;
const variants = ["outline", "filled", "standard"] as const;
const size = ref<(typeof sizes)[number]>("md");
const variant = ref<(typeof variants)[number]>("outline");
const options = [
  { value: "beijing", label: "Beijing" },
  { value: "shanghai", label: "Shanghai" },
];
const cascaderOptions = [{ value: "china", label: "China", children: options }];

const inputValue = ref("Beijing");
const selectValue = ref("beijing");
const cascaderValue = ref("beijing");
const selectMultiple = ref(["beijing", "shanghai"]);
const cascaderMultiple = ref(["beijing", "shanghai"]);
const selectOverflow = ref(["long", "beijing", "shanghai"]);
const cascaderOverflow = ref(["long", "beijing", "shanghai"]);
const selectedOptions = [
  ...options,
  {
    value: "long",
    label:
      "A very long selected option label for overflow comparison — full text preview keeps the selected value unchanged.",
  },
];
const selectedCascaderOptions = [
  { value: "china", label: "China", children: selectedOptions },
];
function resetSelections() {
  inputValue.value = "Beijing";
  selectValue.value = "beijing";
  cascaderValue.value = "beijing";
  selectMultiple.value = ["beijing", "shanghai"];
  cascaderMultiple.value = ["beijing", "shanghai"];
  selectOverflow.value = ["long", "beijing", "shanghai"];
  cascaderOverflow.value = ["long", "beijing", "shanghai"];
}
</script>
<template>
  <section
    aria-label="Form control size comparison"
    class="control-size-comparison"
  >
    <c-space wrap :size="12">
      <c-radio-group v-model="size" aria-label="Comparison size">
        <c-radio v-for="item in sizes" :key="item" :value="item">{{
          item
        }}</c-radio>
      </c-radio-group>
      <c-radio-group v-model="variant" aria-label="Comparison variant">
        <c-radio v-for="item in variants" :key="item" :value="item">{{
          item
        }}</c-radio>
      </c-radio-group>
    </c-space>
    <div class="control-size-comparison__grid">
      <div data-control="Input">
        <p>Input</p>
        <c-input :size="size" :variant="variant" placeholder="Input" />
      </div>
      <div data-control="Button">
        <p>Button</p>
        <c-button :size="size" variant="outline">Button</c-button>
      </div>
      <div data-control="Select">
        <p>Select</p>
        <c-select
          :size="size"
          :variant="variant"
          :options="options"
          placeholder="Select"
        />
      </div>
      <div data-control="Date">
        <p>Date</p>
        <c-date :size="size" :variant="variant" placeholder="Date" />
      </div>
      <div data-control="Time">
        <p>Time</p>
        <c-time :size="size" :variant="variant" placeholder="Time" />
      </div>
      <div data-control="InputNumber">
        <p>InputNumber</p>
        <c-input-number :size="size" :variant="variant" placeholder="Number" />
      </div>
      <div data-control="AutoComplete">
        <p>AutoComplete</p>
        <c-auto-complete
          :size="size"
          :variant="variant"
          :options="options"
          placeholder="AutoComplete"
        />
      </div>
      <div data-control="Cascader">
        <p>Cascader</p>
        <c-cascader
          :size="size"
          :variant="variant"
          :options="cascaderOptions"
          placeholder="Cascader"
        />
      </div>
      <div data-control="DateRange">
        <p>DateRange</p>
        <c-date-range
          :size="size"
          :variant="variant"
          :placeholder="['Start', 'End']"
        />
      </div>
      <div data-control="TimeRange">
        <p>TimeRange</p>
        <c-time-range
          :size="size"
          :variant="variant"
          :placeholder="['Start', 'End']"
        />
      </div>
    </div>

    <section
      aria-label="Selected control size comparison"
      class="control-size-comparison__states"
    >
      <c-space wrap align="center" :size="12">
        <span>Selected / Clearable / Multiple — 有值、可清空与多选不换行</span>
        <span
          >Hover or focus truncated text; tap on touch screens /
          悬停或聚焦省略正文查看全文；触屏点按查看，点外部关闭</span
        >
        <c-button size="sm" variant="outline" @click="resetSelections"
          >Reset / 恢复选中值</c-button
        >
      </c-space>
      <div class="control-size-comparison__grid">
        <div data-control="InputValue">
          <p>Input · clearable</p>
          <c-input
            v-model="inputValue"
            :size="size"
            :variant="variant"
            clearable
            placeholder="Input value"
          />
        </div>
        <div data-control="ButtonReference">
          <p>Button · reference</p>
          <c-button :size="size" variant="outline">Button</c-button>
        </div>
        <div data-control="SelectValue">
          <p>Select · clearable</p>
          <c-select
            v-model="selectValue"
            :size="size"
            :variant="variant"
            :options="selectedOptions"
            clearable
            placeholder="Select value"
          />
        </div>
        <div data-control="CascaderValue">
          <p>Cascader · clearable</p>
          <c-cascader
            v-model="cascaderValue"
            :size="size"
            :variant="variant"
            :options="selectedCascaderOptions"
            clearable
            placeholder="Cascader value"
          />
        </div>
        <div data-control="SelectMultiple">
          <p>Select · multiple / nowrap</p>
          <c-select
            v-model="selectMultiple"
            :size="size"
            :variant="variant"
            :options="selectedOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Select multiple"
          />
        </div>
        <div data-control="CascaderMultiple">
          <p>Cascader · multiple / nowrap</p>
          <c-cascader
            v-model="cascaderMultiple"
            :size="size"
            :variant="variant"
            :options="selectedCascaderOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Cascader multiple"
          />
        </div>
        <div data-control="SelectOverflow">
          <p>Select · long values / nowrap</p>
          <c-select
            v-model="selectOverflow"
            edit-mode="direct"
            :size="size"
            :variant="variant"
            :options="selectedOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Select long values"
          />
        </div>
        <div data-control="CascaderOverflow">
          <p>Cascader · long values / nowrap</p>
          <c-cascader
            v-model="cascaderOverflow"
            edit-mode="direct"
            :size="size"
            :variant="variant"
            :options="selectedCascaderOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Cascader long values"
          />
        </div>
      </div>
    </section>
  </section>
</template>
<style scoped>
.control-size-comparison,
.control-size-comparison__states {
  display: grid;
  gap: 24px;
}
.control-size-comparison__grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
  align-items: start;
  gap: 24px 16px;
}
.control-size-comparison__grid > div {
  min-width: 0;
}
.control-size-comparison__grid p {
  margin: 0 0 12px;
  font-size: 14px;
  line-height: 20px;
}
.control-size-comparison__grid :deep(.c-input-number),
.control-size-comparison__grid :deep(.c-auto-complete) {
  width: 100%;
}
</style>
```

## 选择模式与选项

### 多选选择器

<!-- demo-config-notes:start -->

#### 本组配置对照

| 配置          | 作用                                             | 相关示例                             |
| ------------- | ------------------------------------------------ | ------------------------------------ |
| `placeholder` | 占位文本                                         | 多选选择器、同名选项、分组           |
| `multiple`    | 多选；默认启用搜索                               | 多选选择器、同名选项、分组           |
| `clearable`   | 允许清除，保留禁用的已选项                       | 多选选择器、同名选项、子组件选项组合 |
| `filterable`  | 开启搜索，可设置 retainInputValue                | 同名选项、子组件选项组合             |
| `options`     | 原始值、对象、分组均支持；三种展示使用同一数据源 | 同名选项、分组间距                   |
| `scrollbar`   | Menu / List 滚动条配置                           | 多选选择器                           |

<!-- demo-config-notes:end -->

通过设置 multiple ，可以让选择器支持多选。此外通过 max-tag-count 可以设置最多显示的标签个数。

Example source: src/select/__demos__/multiple.vue

```vue
<template>
  <c-space direction="column" size="lg">
    <c-select
      :default-value="['Beijing', 'Shanghai']"
      :style="{ width: '360px' }"
      placeholder="Please select ..."
      multiple
      scrollbar
    >
      <c-option>Beijing</c-option>
      <c-option :tag-props="{ color: 'red' }">Shanghai</c-option>
      <c-option>Guangzhou</c-option>
      <c-option disabled>Disabled</c-option>
      <c-option>Shenzhen</c-option>
      <c-option>Wuhan</c-option>
    </c-select>
    <c-select
      :default-value="['Beijing', 'Shanghai', 'Guangzhou']"
      :style="{ width: '360px' }"
      placeholder="Please select ..."
      multiple
      :max-tag-count="2"
      clearable
      scrollbar
    >
      <c-option>Beijing</c-option>
      <c-option>Shanghai</c-option>
      <c-option>Guangzhou</c-option>
      <c-option disabled>Disabled</c-option>
      <c-option>Shenzhen</c-option>
      <c-option>Chengdu</c-option>
      <c-option>Wuhan</c-option>
    </c-select>
  </c-space>
</template>

<script lang="ts">
import { defineComponent, ref } from 'vue'
export default defineComponent({
  setup() {
    const value = ref('Shanghai')
    return {
      value,
    }
  },
})
</script>
```

### 同名选项

标签展示允许同名，但每个选项的值必须唯一。删除第二个“设备”只移除 ID 2，不会误删 ID 1；搜索文字与已选值分别管理。

Example source: src/select/__demos__/same-label.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'

const value = ref([1, 2])
const options = [
  { value: 1, label: '设备' },
  { value: 2, label: '设备' },
  { value: 3, label: '备用设备' },
]
</script>

<template>
  <c-space direction="column">
    <c-select v-model="value" multiple filterable clearable :options="options" placeholder="选择设备" />
    <span>已选 ID：{{ value.join(', ') || '无' }}</span>
  </c-space>
</template>
```

### 分组

使用 optgroup 组件添加分组选项。

Example source: src/select/__demos__/optgroup.vue

```vue
<template>
  <c-space direction="column" size="lg">
    <c-select :style="{ width: '320px' }" placeholder="Please select ...">
      <c-optgroup label="Group-1">
        <c-option>Beijing</c-option>
        <c-option>Shanghai</c-option>
      </c-optgroup>
      <c-optgroup label="Group-2">
        <c-option>Guangzhou</c-option>
        <c-option disabled>Disabled</c-option>
        <c-option>Shenzhen</c-option>
      </c-optgroup>
      <c-optgroup label="Group-3">
        <c-option>Chengdu</c-option>
        <c-option>Wuhan</c-option>
      </c-optgroup>
    </c-select>
    <c-select :style="{ width: '320px' }" placeholder="Please select ..." multiple>
      <c-optgroup label="Group-1">
        <c-option>Beijing</c-option>
        <c-option>Shanghai</c-option>
      </c-optgroup>
      <c-optgroup label="Group-2">
        <c-option>Guangzhou</c-option>
        <c-option disabled>Disabled</c-option>
        <c-option>Shenzhen</c-option>
      </c-optgroup>
      <c-optgroup label="Group-3">
        <c-option>Chengdu</c-option>
        <c-option>Wuhan</c-option>
      </c-optgroup>
    </c-select>
  </c-space>
</template>

<script lang="ts">
import { defineComponent, ref } from 'vue'
export default defineComponent({
  })
</script>
```

### 分组间距

Example source: src/select/__demos__/group-spacing.vue

```vue
<script setup lang="ts">
const options = [
  {
    isGroup: true,
    label: "华北",
    options: [
      { value: "beijing", label: "北京" },
      { value: "tianjin", label: "天津" },
    ],
  },
  {
    isGroup: true,
    label: "华东",
    options: [
      { value: "shanghai", label: "上海" },
      { value: "hangzhou", label: "杭州" },
    ],
  },
];
</script>

<template>
  <c-select
    :options="options"
    placeholder="分组候选"
    :style="{ width: '280px' }"
  />
</template>
```

### 管理已选项

确认式多选编辑面板顶部提供已选数量与清空。Cedar 在列表上方显示可删除标签；Maple 点击数量查看已选明细，支持逐项移除并返回可选项。popup/popover 与 dialog 共用该内容。移除和清空先修改草稿，关闭取消会恢复原值，确认后才提交；禁用项保留，异步确认期间禁用操作。面板的清空入口独立于字段清空图标。

### 子组件选项组合

Example source: src/select/__demos__/options-review.vue

```vue
<script setup lang="ts">
import { ref, watch } from 'vue'
const multiple = ref(true)
const filterable = ref(true)
const disabled = ref(false)
const value = ref<string | string[] | undefined>([])
watch(multiple, (next) => { value.value = next ? [] : undefined })
</script>
<template>
  <c-space direction="column">
    <c-space>
      <c-checkbox v-model="multiple">多选</c-checkbox>
      <c-checkbox v-model="filterable">允许搜索</c-checkbox>
      <c-checkbox v-model="disabled">禁用研发选项</c-checkbox>
      <c-button @click="value = multiple ? [] : undefined">清空选择</c-button>
    </c-space>
    <c-select v-model="value" :multiple="multiple" :filterable="filterable" clearable placeholder="子组件选项审查" :style="{ width: '280px' }">
      <c-optgroup label="研发组">
        <template #label><c-tag>研发组插槽</c-tag></template>
        <c-option value="dev" label="研发" :disabled="disabled" :tag-props="{ size: 'sm' }" :index="0">
          <template #default="{ selected }"><c-tag>{{ selected ? '已选研发' : '选择研发' }}</c-tag></template>
          <template #icon><c-tag>图标</c-tag></template>
          <template #suffix><c-tag>后缀</c-tag></template>
        </c-option>
      </c-optgroup>
    </c-select>
    <p role="status">当前值：{{ JSON.stringify(value) }}</p>
  </c-space>
</template>
```

### 允许创建

通过设置 creatable ，让选择器可以创建选项中不存在的条目。

Example source: src/select/__demos__/allow-create.vue

```vue
<template>
  <c-space direction="column" size="lg">
    <c-select :style="{ width: '320px' }" placeholder="Please select ..." creatable>
      <c-option>Beijing</c-option>
      <c-option>Shanghai</c-option>
      <c-option>Guangzhou</c-option>
      <c-option disabled>Disabled</c-option>
      <c-option>Shenzhen</c-option>
      <c-option>Chengdu</c-option>
      <c-option>Wuhan</c-option>
    </c-select>
    <c-select :style="{ width: '320px' }" placeholder="Please select ..." multiple creatable>
      <c-option>Beijing</c-option>
      <c-option>Shanghai</c-option>
      <c-option>Guangzhou</c-option>
      <c-option disabled>Disabled</c-option>
      <c-option>Shenzhen</c-option>
      <c-option>Chengdu</c-option>
      <c-option>Wuhan</c-option>
    </c-select>
  </c-space>
</template>

<script lang="ts">
import { defineComponent } from 'vue'
export default defineComponent({})
</script>
```

### 回退选项

使用 fallback-option 自定义选项中不存在的值，默认会在输入框中展示不存在的选项值。可能用于选项还没有获取完，或者远程搜索时选项改变了。

Example source: src/select/__demos__/fallback-option.vue

```vue
<template>
  <c-space direction="column" size="lg">
    <c-select
      default-value="Shanxi"
      :style="{ width: '320px' }"
      placeholder="Please select ..."
      :fallback-option="fallback"
    >
      <c-option>Beijing</c-option>
      <c-option>Shanghai</c-option>
      <c-option>Guangzhou</c-option>
      <c-option disabled>Disabled</c-option>
    </c-select>
    <c-select
      default-value="Shanxi"
      :style="{ width: '320px' }"
      placeholder="Please select ..."
      :fallback-option="fallback"
      :show-extr-options="false"
    >
      <c-option>Beijing</c-option>
      <c-option>Shanghai</c-option>
      <c-option>Guangzhou</c-option>
      <c-option disabled>Disabled</c-option>
    </c-select>
    <c-select
      :default-value="['Shanxi', 'Nanjing', 'Hangzhou']"
      :style="{ width: '320px' }"
      placeholder="Please select ..."
      multiple
      :fallback-option="fallback"
    >
      <c-option>Beijing</c-option>
      <c-option>Shanghai</c-option>
      <c-option>Guangzhou</c-option>
      <c-option disabled>Disabled</c-option>
      <c-option>Shenzhen</c-option>
      <c-option>Chengdu</c-option>
      <c-option>Wuhan</c-option>
    </c-select>
  </c-space>
</template>

<script lang="ts">
import { defineComponent, ref } from 'vue'
export default defineComponent({
  setup() {
    const fallback = (value: any) => {
      return {
        value,
        label: `++${value}++`,
      }
    }
    return {
      fallback,
    }
  },
})
</script>
```

## 搜索与过滤

### 允许搜索

<!-- demo-config-notes:start -->

#### 本组配置对照

| 配置             | 作用                                             | 相关示例                             |
| ---------------- | ------------------------------------------------ | ------------------------------------ |
| `placeholder`    | 占位文本                                         | 允许搜索、搜索匹配规则、下拉菜单滚动 |
| `options`        | 原始值、对象、分组均支持；三种展示使用同一数据源 | 允许搜索、搜索匹配规则、虚拟列表     |
| `filterable`     | 开启搜索，可设置 retainInputValue                | 允许搜索、搜索匹配规则               |
| `loading`        | 加载状态；禁止选择和确认                         | 允许搜索                             |
| `multiple`       | 多选；默认启用搜索                               | 允许搜索                             |
| `case-sensitive` | 内置本地过滤是否区分大小写，自定义过滤函数优先   | 搜索匹配规则                         |

<!-- demo-config-notes:end -->

通过设置 filterable ，可以让选择器支持对选项的搜索，配合 filter-option 可以自定义搜索。

Example source: src/select/__demos__/filterable.vue

```vue
<template>
  <c-space direction="column" size="lg">
    <c-select :style="{ width: '320px' }" placeholder="Please select ..." filterable>
      <c-option>Beijing</c-option>
      <c-option>Shanghai</c-option>
      <c-option>Guangzhou</c-option>
      <c-option disabled>Disabled</c-option>
      <c-option>Shenzhen</c-option>
      <c-option>Chengdu</c-option>
      <c-option>Wuhan</c-option>
    </c-select>
    <c-select :style="{ width: '320px' }" placeholder="Please select ..." :filterable="{ retainInputValue: true }">
      <c-option>Beijing</c-option>
      <c-option>Shanghai</c-option>
      <c-option>Guangzhou</c-option>
      <c-option disabled>Disabled</c-option>
      <c-option>Shenzhen</c-option>
      <c-option>Chengdu</c-option>
      <c-option>Wuhan</c-option>
    </c-select>
    <c-select
      :options="options"
      :style="{ width: '320px' }"
      :loading="loading"
      placeholder="Please select ..."
      multiple
      @search="handleSearch" />
  </c-space>
</template>

<script lang="ts">
import { defineComponent, ref } from 'vue'
export default defineComponent({
  setup() {
    const options = ref(['Option1', 'Option2', 'Option3'])
    const loading = ref(false)

    const handleSearch = (value: any) => {
      if (value) {
        loading.value = true
        window.setTimeout(() => {
          options.value = [`${value}-Option1`, `${value}-Option2`, `${value}-Option3`]
          loading.value = false
        }, 2000)
      } else {
        options.value = []
      }
    }

    return {
      options,
      loading,
      handleSearch,
    }
  },
})
</script>
```

### 搜索匹配规则

`case-sensitive` 默认 false，只控制内置本地匹配是否区分大小写；自定义过滤函数优先。远程结果可设置 `:filter-option="false"`，不再执行本地筛选。

同时匹配 value 和 label 可直接配置 `:search-fields="['value', 'label']"`；下面的示例不再需要自定义过滤函数。

Example source: src/select/__demos__/search-matching.vue

```vue
<script setup lang="ts">
import { computed, ref } from "vue";
const value = ref("");
const mode = ref("label");
const caseSensitive = ref(false);
const modes = [
  { value: "label", label: "默认：只匹配 label" },
  { value: "both", label: "配置：value 或 label" },
];
const options = [
  { value: "USER_A", label: "Apple" },
  { value: "USER_B", label: "Banana" },
];
const searchFields = computed<("label" | "value")[]>(() =>
  mode.value === "both" ? ["value", "label"] : ["label"],
);
</script>
<template>
  <c-space direction="column" align="stretch" fill>
    <c-form-item layout="vertical" size="sm" label="匹配字段">
      <c-radio-group
        v-model="mode"
        aria-label="匹配字段"
        :options="modes"
        variant="button"
        size="sm"
      />
    </c-form-item>
    <c-space
      ><c-switch v-model="caseSensitive" /><span>区分大小写</span></c-space
    >
    <c-select
      v-model="value"
      :options="options"
      :case-sensitive="caseSensitive"
      :search-fields="searchFields"
      :search-delay="0"
      filterable
      placeholder="输入 Apple、apple 或 USER_A"
    />
    <p>
      默认搜索 label，不区分大小写；配置两字段后，USER_A 和 Apple
      都能找到同一个选项。
    </p>
  </c-space>
</template>
```

### 下拉菜单滚动

可以通过`dropdown-scroll`监听下拉菜单的滚动事件，或者通过`dropdown-reach-bottom`监听下拉菜单滚动到底部的事件

Example source: src/select/__demos__/dropdown-scroll.vue

```vue
<template>
  <c-select
    :style="{ width: '320px' }"
    default-value="Beijing"
    placeholder="Please select ..."
    @dropdown-scroll="handleScroll"
    @dropdown-reach-bottom="handleReachBottom"
  >
    <c-option>Beijing</c-option>
    <c-option>Shanghai</c-option>
    <c-option>Guangzhou</c-option>
    <c-option disabled>Disabled</c-option>
    <c-option>Shenzhen</c-option>
    <c-option>Chengdu</c-option>
    <c-option>Wuhan</c-option>
  </c-select>
</template>

<script lang="ts">
import { defineComponent, ref } from 'vue'
export default defineComponent({
  setup() {
    const handleScroll = (ev) => {
      console.log('scroll', ev)
    }
    const handleReachBottom = (ev) => {
      console.log('reach the bottom', ev)
    }

    return {
      handleScroll,
      handleReachBottom,
    }
  },
})
</script>
```

### 虚拟列表

虚拟列表的使用方法

Example source: src/select/__demos__/virtual-list.vue

```vue
<template>
  <c-select
    :style="{ width: '320px' }"
    :options="options"
    placeholder="Please select ..."
    :virtual-list-props="{ height: 200 }" />
</template>

<script lang="ts">
import { defineComponent } from 'vue'
export default defineComponent({
  setup() {
    const options = Array(1000)
      .fill(null)
      .map((_, index) => `Option ${index}`)

    return {
      options,
    }
  },
})
</script>
```

选项分组与 Menu 使用一致的间距逻辑：标题行高 20px，上下各 4px 留白（总高 28px）；后续分组前额外留 8px，首组不添加组间距。标题与选项文字左对齐；AutoComplete 的标题缩进跟随其选项水平 padding 配置。

## 内容与下拉定制

### 已选 Tag 样式

<!-- demo-config-notes:start -->

#### 本组配置对照

| 配置          | 作用                                             | 相关示例                                      |
| ------------- | ------------------------------------------------ | --------------------------------------------- |
| `placeholder` | 占位文本                                         | 已选 Tag 样式、下拉菜单的页头、下拉菜单的页脚 |
| `multiple`    | 多选；默认启用搜索                               | 已选 Tag 样式、下拉菜单的页头、复杂插槽组合   |
| `options`     | 原始值、对象、分组均支持；三种展示使用同一数据源 | 已选 Tag 样式、复杂插槽组合                   |
| `filterable`  | 开启搜索，可设置 retainInputValue                | 下拉菜单的页脚、复杂插槽组合                  |
| `clearable`   | 允许清除，保留禁用的已选项                       | 复杂插槽组合                                  |

<!-- demo-config-notes:end -->

多选时，已选项在选择框中以 Tag 展示。通过选项上的 `tagProps`（或 `<c-option>` 的 `tag-props`）可以把属性透传给 [Tag](llms/zh-CN/components/tag.md)，用来改颜色、状态、变体等。Tag 没有单独的最大宽度属性，需要截断长文本时传入 `nowrap: true`，并用 `style.maxWidth` 限制宽度。

Example source: src/select/__demos__/tag-props.vue

```vue
<template>
  <c-space direction="column" size="lg">
    <c-select
      multiple
      :default-value="['urgent', 'high', 'medium', 'low', 'custom', 'outline']"
      :style="{ width: '520px' }"
      placeholder="Please select ..."
      :options="colorOptions"
    />
    <c-select
      multiple
      :default-value="['long']"
      :style="{ width: '320px' }"
      placeholder="Please select ..."
      :options="widthOptions"
    />
  </c-space>
</template>

<script lang="ts">
import { defineComponent } from 'vue'

export default defineComponent({
  setup() {
    const colorOptions = [
      { value: 'urgent', label: '紧急', tagProps: { color: 'red' } },
      { value: 'high', label: '高', tagProps: { status: 'danger' } },
      { value: 'medium', label: '中', tagProps: { status: 'warning' } },
      { value: 'low', label: '低', tagProps: { status: 'success' } },
      { value: 'custom', label: '自定义色', tagProps: { color: '#165DFF' } },
      {
        value: 'outline',
        label: '描边',
        tagProps: { variant: 'outline', status: 'primary' },
      },
    ]

    const widthOptions = [
      {
        value: 'long',
        label: '这是一段很长的选项文案，用来演示 Tag 最大宽度截断',
        tagProps: {
          nowrap: true,
          style: { maxWidth: '160px' },
        },
      },
      { value: 'short', label: '短标签' },
    ]

    return {
      colorOptions,
      widthOptions,
    }
  },
})
</script>
```

### 下拉菜单的页头

自定义下拉菜单的页头

Example source: src/select/__demos__/custom-header.vue

```vue
<template>
  <c-select :default-value="'Beijing'" :style="{ width: '360px' }" placeholder="Please select ..." multiple>
    <c-option>Beijing</c-option>
    <c-option>Shanghai</c-option>
    <c-option>Guangzhou</c-option>
    <c-option disabled>Disabled</c-option>
    <c-option>Shenzhen</c-option>
    <c-option>Wuhan</c-option>
    <template #header>
      <div style="padding: 6px 12px">
        <c-checkbox value="1">全选</c-checkbox>
      </div>
    </template>
  </c-select>
</template>

<script lang="ts">
import { defineComponent, ref } from 'vue'
export default defineComponent({
  })
</script>
```

### 下拉菜单的页脚

自定义下拉菜单的页脚

Example source: src/select/__demos__/custom-footer.vue

```vue
<template>
  <c-space>
    <c-select :default-value="'Beijing'" :style="{ width: '360px' }" placeholder="Please select ..." filterable>
      <c-option>Beijing</c-option>
      <c-option>Shanghai</c-option>
      <c-option>Guangzhou</c-option>
      <c-option disabled>Disabled</c-option>
      <c-option>Shenzhen</c-option>
      <c-option>Wuhan</c-option>
      <template #footer>
        <div style="padding: 6px 0; text-align: center">
          <c-button>Click Me</c-button>
        </div>
      </template>
    </c-select>
    <c-select
      :default-value="'Beijing'"
      :style="{ width: '360px' }"
      placeholder="Please select ..."
      filterable
      show-footer-on-empty
    >
      <c-option>Beijing</c-option>
      <c-option>Shanghai</c-option>
      <c-option>Guangzhou</c-option>
      <c-option disabled>Disabled</c-option>
      <c-option>Shenzhen</c-option>
      <c-option>Wuhan</c-option>
      <template #footer>
        <div style="padding: 6px 0; text-align: center">
          <c-button>Click Me</c-button>
        </div>
      </template>
    </c-select>
  </c-space>
</template>

<script lang="ts">
import { defineComponent, ref } from 'vue'
export default defineComponent({
  })
</script>
```

### 自定义选择框展示内容

通过`#label`插槽可以自定义选择框展示内容。

Example source: src/select/__demos__/custom-label.vue

```vue
<template>
  <c-select v-model:modelValue="value" :style="{ width: '320px' }" placeholder="Please select ...">
    <template #label="{ data }">
      <span> <c-icon-plus />{{ data?.label }}</span>
    </template>
    <c-option>Beijing</c-option>
    <c-option>Shanghai</c-option>
    <c-option>Guangzhou</c-option>
    <c-option disabled>Disabled</c-option>
  </c-select>
</template>

<script lang="ts">
import { defineComponent, ref } from 'vue'
export default defineComponent({
  setup() {
    const value = ref('Beijing')
    return { value }
  },
})
</script>
```

### 复杂插槽组合

Example source: src/select/__demos__/slots-review.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const value = ref<string[]>(['dev'])
const selectedSlot = ref(false)
const triggerSlot = ref(false)
const clears = ref(0)
const options = [{ value: 'dev', label: '研发' }, { value: 'design', label: '设计' }, { value: 'ops', label: '运营', disabled: true }]
function onClear(clear: (event: MouseEvent) => void, event: MouseEvent) {
  clears.value++
  clear(event)
}
</script>
<template>
  <c-space direction="column">
    <c-space>
      <c-checkbox v-model="selectedSlot">自定义已选区</c-checkbox>
      <c-checkbox v-model="triggerSlot">自定义触发器</c-checkbox>
    </c-space>
    <c-select v-model="value" :options="options" multiple filterable clearable placeholder="复杂插槽审查" :style="{ width: '320px' }">
      <template #prefix><c-tag>前缀</c-tag></template>
      <template #suffix><c-tag>后缀</c-tag></template>
      <template #header><c-tag>菜单页头</c-tag></template>
      <template #footer><c-tag>菜单页脚</c-tag></template>
      <template #option="{ data }"><c-tag>选项：{{ data.label }}</c-tag></template>
      <template #label="{ data }"><c-tag>已选：{{ data.label }}</c-tag></template>
      <template #clear-icon="{ clear }"><c-button size="xs" @mousedown.prevent @click.stop="onClear(clear, $event)">插槽清空</c-button></template>
      <template #arrow-icon><c-tag>展开</c-tag></template>
      <template #search-icon><c-tag>搜索</c-tag></template>
      <template #loading-icon><c-tag>加载</c-tag></template>
      <template #empty><c-tag>无匹配选项</c-tag></template>
      <template #read="{ text }"><c-tag>阅读：{{ text }}</c-tag></template>
      <template v-if="selectedSlot" #selected><c-tag>已选区域：{{ value.join(' / ') }}</c-tag></template>
      <template v-if="triggerSlot" #trigger><c-button>插槽打开选择器</c-button></template>
    </c-select>
    <p role="status">当前值：{{ JSON.stringify(value) }}；插槽清空：{{ clears }}</p>
  </c-space>
</template>
```

## 值模型与联动

### 候选高亮与表单数据流

<!-- demo-config-notes:start -->

#### 本组配置对照

| 配置                          | 作用                                                                                                                    | 相关示例                                             |
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| `options`                     | 原始值、对象、分组均支持；三种展示使用同一数据源                                                                        | 候选高亮与表单数据流、联动选择框、空值识别与清空输出 |
| `clearable`                   | 允许清除，保留禁用的已选项                                                                                              | 空值识别与清空输出、交互状态对比                     |
| `edit-mode`                   | 字段展示；未指定时继承 FormItem/Form                                                                                    | 候选高亮与表单数据流                                 |
| `default-active-first-option` | 打开选项列表时，无有效选中项则默认激活首个可用候选；仅高亮，不更新 modelValue 或触发 change。已有有效选中项优先激活该项 | 候选高亮与表单数据流                                 |
| `placeholder`                 | 占位文本                                                                                                                | 候选高亮与表单数据流                                 |
| `empty-value`                 | 清空输出覆盖；多选返回数组，保留不可清除项                                                                              | 空值识别与清空输出                                   |

<!-- demo-config-notes:end -->

初始 `form.city` 为 `undefined`。打开面板只激活候选行，不触发 `update:modelValue` 或 `change`，表单仍为空。inline 点击选项或按 Enter 后提交；click 在面板内选择只是草稿，确认后才提交，取消不改变表单。两个示例分别显示已提交值、更新次数和真实事件日志；日志按最新在前排列。

Example source: src/select/__demos__/selection-data-flow.vue

```vue
<script setup lang="ts">
import { computed, reactive, ref } from "vue";

const props = defineProps<{ english?: boolean }>();
const autoFirst = ref(true);
const generation = ref(0);
const form = reactive<{ city?: string; panelCity?: string }>({
  city: undefined,
  panelCity: undefined,
});
const logs = reactive<{ inline: string[]; panel: string[] }>({
  inline: [],
  panel: [],
});
const counts = reactive({ inline: 0, panel: 0 });
const options = computed(() => [
  { label: props.english ? "Hangzhou" : "杭州", value: "hangzhou" },
  { label: props.english ? "Shanghai" : "上海", value: "shanghai" },
  {
    label: props.english ? "Beijing (disabled)" : "北京（禁用）",
    value: "beijing",
    disabled: true,
  },
]);
function show(value: unknown) {
  return value === undefined ? "undefined" : JSON.stringify(value);
}
function record(kind: "inline" | "panel", event: string, value: unknown) {
  if (event === "update:modelValue") {
    counts[kind]++;
  }
  logs[kind].unshift(`${event}(${show(value)})`);
  logs[kind].splice(8);
}
function reset() {
  generation.value++;
  form.city = undefined;
  form.panelCity = undefined;
  counts.inline = counts.panel = 0;
  logs.inline = [];
  logs.panel = [];
}
</script>

<template>
  <div class="selection-data-flow">
    <c-checkbox v-model="autoFirst" @change="reset"
      >defaultActiveFirstOption = {{ autoFirst }}</c-checkbox
    >
    <c-button @click="reset">{{
      english ? "Reset both forms and logs" : "重置两组表单和日志"
    }}</c-button>
    <p>
      {{
        english
          ? "Each field starts empty. Open it and inspect the highlighted candidate: highlighting does not select a city. Change the switch to remount both fields."
          : "两组字段初始都没有值。打开后观察候选行的高亮：高亮不代表选中城市。切换开关会重建两组字段，便于从空值重新比较。"
      }}
    </p>

    <section>
      <h4>
        inline · {{ english ? "Selection commits immediately" : "选择即提交" }}
      </h4>
      <c-form-item layout="vertical" hide-label>
        <c-select
          :key="`inline-${generation}`"
          v-model="form.city"
          edit-mode="direct"
          :options="options"
          :default-active-first-option="autoFirst"
          :placeholder="english ? 'Choose a city' : '请选择城市'"
          @update:model-value="record('inline', 'update:modelValue', $event)"
          @change="record('inline', 'change', $event)"
          @open-change="record('inline', 'open-change', $event)"
        >
          <template #footer>
            <p class="panel-value">
              form.city = {{ show(form.city) }} · update:modelValue ×
              {{ counts.inline }}
            </p>
          </template>
        </c-select>
      </c-form-item>
      <p>
        {{
          english
            ? "Move with arrow keys, then press Enter, or click a city. Closing without selecting leaves the form unchanged."
            : "上下键移动后按 Enter，或点击城市，才更新表单。只打开、移动候选或关闭，不更新表单。"
        }}
      </p>
      <p role="status">
        form.city = <code>{{ show(form.city) }}</code> · update:modelValue ×
        {{ counts.inline }}
      </p>
      <ol v-if="logs.inline.length" aria-live="polite">
        <li v-for="(entry, index) in logs.inline" :key="index">
          <code>{{ entry }}</code>
        </li>
      </ol>
      <p v-else>
        {{ english ? "No component events yet." : "尚无组件事件。" }}
      </p>
    </section>

    <section>
      <h4>
        click · {{ english ? "Confirm commits the draft" : "确认后提交草稿" }}
      </h4>
      <c-form-item layout="vertical" hide-label>
        <c-select
          :key="`panel-${generation}`"
          v-model="form.panelCity"
          edit-mode="click"
          :options="options"
          :default-active-first-option="autoFirst"
          :placeholder="
            english ? 'Choose a city, then confirm' : '选择城市后确认'
          "
          @update:model-value="record('panel', 'update:modelValue', $event)"
          @change="record('panel', 'change', $event)"
          @open-change="record('panel', 'open-change', $event)"
        >
          <template #footer>
            <p class="panel-value">
              {{ english ? "Committed form value" : "已提交表单值" }}：{{
                show(form.panelCity)
              }}
              · update:modelValue × {{ counts.panel }}
            </p>
          </template>
        </c-select>
      </c-form-item>
      <p>
        {{
          english
            ? "Choose a city in the editor: the selection mark is a draft. Confirm saves it; cancel or Escape discards it. Highlighting a candidate alone is not a draft selection."
            : "在编辑面板选择城市后，勾选标记表示草稿；确认才保存，取消或 Escape 丢弃草稿。只有候选高亮、尚未选择，不算草稿选择。"
        }}
      </p>
      <p role="status">
        form.panelCity = <code>{{ show(form.panelCity) }}</code> ·
        update:modelValue × {{ counts.panel }}
      </p>
      <ol v-if="logs.panel.length" aria-live="polite">
        <li v-for="(entry, index) in logs.panel" :key="index">
          <code>{{ entry }}</code>
        </li>
      </ol>
      <p v-else>
        {{ english ? "No component events yet." : "尚无组件事件。" }}
      </p>
    </section>
    <p>
      {{
        english
          ? "Logs are newest first. open-change only changes panel visibility; update:modelValue is the event that writes the form value."
          : "日志按最新在前排列。open-change 只表示打开或关闭面板；update:modelValue 才对应表单值更新。"
      }}
    </p>
  </div>
</template>

<style scoped>
.selection-data-flow {
  display: grid;
  gap: 12px;
  min-width: 0;
}
.selection-data-flow section {
  display: grid;
  gap: 8px;
  min-width: 0;
}
.selection-data-flow p,
.selection-data-flow h4 {
  margin: 0;
}
.selection-data-flow code {
  overflow-wrap: anywhere;
}
.panel-value {
  padding: 8px;
}
</style>
```

### 联动选择框

展示联动选择框的实现方法

Example source: src/select/__demos__/linkage.vue

```vue
<template>
  <c-space>
    <c-select :style="{ width: '200px' }" v-model="province">
      <c-option v-for="value of Object.keys(data)" :key="value">{{ value }}</c-option>
    </c-select>
    <c-select :style="{ width: '200px' }" :options="data[province] || []" v-model="city" />
  </c-space>
</template>

<script lang="ts">
import { defineComponent, ref, watch } from 'vue'
export default defineComponent({
  setup() {
    const province = ref('Sichuan')
    const city = ref('Chengdu')
    const data = {
      Beijing: ['Haidian', 'Chaoyang', 'Changping'],
      Sichuan: ['Chengdu', 'Mianyang', 'Aba'],
      Guangdong: ['Guangzhou', 'Shenzhen', 'Shantou'],
    }

    watch(province, () => {
      city.value = ''
    })

    return {
      province,
      city,
      data,
    }
  },
})
</script>
```

### 自定义字段名

可以通过`field-names`属性定义`options`中数据的格式

### 空值识别与清空输出

本例把空字符串保留为合法的“全部”选项，清空按钮返回 null。先观察“全部”已选，再点击清空；两种状态在模型输出中分别是空字符串和 null。搜索框删空不会删除已选值。下方另列多选清空返回 []、单选用工厂明确返回 undefined 的情况，分别显示模型值。

Example source: src/select/__demos__/empty-value.vue

```vue
<script setup lang="ts">
import { reactive, ref } from "vue";
const model = reactive({ status: "" as string | null });
const multiple = ref(["active"]);
const optional = ref<string | undefined>("active");
const options = [
  { value: "", label: "全部" },
  { value: "active", label: "启用" },
];
</script>
<template>
  <c-space direction="column">
    <p>“全部”的值是空字符串，仍是有效选项；点击清空返回 null。</p>
    <c-form :model="model" layout="vertical">
      <c-form-item field="status" label="状态">
        <c-select
          v-model="model.status"
          :options="options"
          edit-mode="direct"
          clearable
          :empty-values="[null, undefined]"
          :empty-value="null"
        />
      </c-form-item>
    </c-form>
    <c-button @click="model.status = ''">选择“全部”</c-button>
    <p>
      当前模型: <output>{{ JSON.stringify(model.status) }}</output>
    </p>
    <c-form layout="vertical">
      <c-form-item label="多选：清空返回 []">
        <c-select
          v-model="multiple"
          :options="options"
          edit-mode="direct"
          multiple
          clearable
          :empty-value="() => []"
        />
        <output>{{ JSON.stringify(multiple) }}</output>
      </c-form-item>
      <c-form-item label="单选：清空返回 undefined">
        <c-select
          v-model="optional"
          :options="options"
          edit-mode="direct"
          clearable
          :empty-value="() => undefined"
        />
        <output>{{ String(optional) }}</output>
      </c-form-item>
    </c-form>
  </c-space>
</template>
```

### 交互状态对比

在同一实例上切换禁用、只读和错误状态后再操作控件，比较可编辑性和交互反馈。恢复开关位于目标控件外；错误外观本身不会执行校验。

<details>
<summary>配置说明与使用限制</summary>

#### 交互状态切换

适用于选项数据明确的单选输入。调整禁用、只读、错误反馈，用相同数据观察变化。控制区始终可用，可以随时恢复编辑；错误外观本身不会触发表单校验。

</details>

Example source: src/select/__demos__/state-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref("design");
const options = [
  { label: "研发", value: "dev" },
  { label: "设计", value: "design" },
  { label: "运营", value: "ops", disabled: true },
];
const __demoState = __demoReactive({
  disabled: false,
  readonly: false,
  error: false,
});
</script>
<template>
  <c-space direction="column" :size="16">
    <c-space wrap>
      <c-checkbox v-model="__demoState['disabled']">disabled</c-checkbox>
      <c-checkbox v-model="__demoState['readonly']">readonly</c-checkbox>
      <c-checkbox v-model="__demoState['error']">error</c-checkbox>
    </c-space>
    <c-select
      v-model="value"
      :options="options"
      clearable
      v-bind="__demoState"
    ></c-select>
  </c-space>
</template>
```

## 异步数据与搜索

### 加载中

<!-- demo-config-notes:start -->

#### 本组配置对照

| 配置            | 作用                                             | 相关示例                                                               |
| --------------- | ------------------------------------------------ | ---------------------------------------------------------------------- |
| `loading`       | 加载状态；禁止选择和确认                         | 加载中、远程搜索、异步设备与 ID 回显                                   |
| `options`       | 原始值、对象、分组均支持；三种展示使用同一数据源 | 远程搜索、异步设备与 ID 回显、共用异步数据源（进阶可选）               |
| `placeholder`   | 占位文本                                         | 加载中、远程搜索、异步设备与 ID 回显                                   |
| `filterable`    | 开启搜索，可设置 retainInputValue                | 异步设备与 ID 回显、共用异步数据源（进阶可选）、函数属性：初始化与搜索 |
| `multiple`      | 多选；默认启用搜索                               | 远程搜索、异步设备与 ID 回显                                           |
| `filter-option` | false 关闭本地过滤；函数接收搜索词和原始选项     | 远程搜索                                                               |

<!-- demo-config-notes:end -->

切换加载状态，对比默认指示器与底部加载线。加载期间保留已选值，暂停选择与确认；关闭加载后恢复。

Example source: src/select/__demos__/loading.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const busy = ref(true)
const value = ref('beijing')
const options = [{ label: '北京 / Beijing', value: 'beijing' }, { label: '上海 / Shanghai', value: 'shanghai' }, { label: '广州 / Guangzhou', value: 'guangzhou' }]
</script>
<template>
  <c-space direction="column" :size="16" style="width: 100%">
    <c-form layout="vertical">
      <c-form-item label="加载状态 / Loading"><c-switch v-model="busy" /></c-form-item>
      <c-form-item label="默认指示器 / Default"><c-select v-model="value" :loading="busy" :options="options" edit-mode="direct" loading-mode="default" /></c-form-item>
      <c-form-item label="底部加载线 / Line"><c-select v-model="value" :loading="busy" :options="options" edit-mode="direct" loading-mode="line" /></c-form-item>
    </c-form>
    <p>切换加载状态；加载期间保留已选值，暂停选择与确认，关闭加载后恢复。Loading preserves the selected value and pauses selection.</p>
  </c-space>
</template>
```

### 远程搜索

使用 search 事件进行远程搜索，并改变选项。

Example source: src/select/__demos__/search.vue

```vue
<template>
  <c-space direction="column" size="lg">
    <div>Show selections after search options</div>
    <c-select
      :style="{ width: '320px' }"
      :loading="loading"
      placeholder="Please select ..."
      multiple
      :filter-option="false"
      @search="handleSearch"
    >
      <c-option v-for="item of options" :key="item" :value="item">{{ item }}</c-option>
    </c-select>
    <div>Hide selections after search options</div>
    <c-select
      :options="options"
      :style="{ width: '320px' }"
      :loading="loading"
      placeholder="Please select ..."
      multiple
      :filter-option="false"
      :show-extr-options="false"
      @search="handleSearch" />
  </c-space>
</template>

<script lang="ts">
import { defineComponent, ref } from 'vue'
export default defineComponent({
  setup() {
    const options = ref(['Option1', 'Option2', 'Option3'])
    const loading = ref(false)

    const handleSearch = (value: any) => {
      if (value) {
        loading.value = true
        window.setTimeout(() => {
          options.value = [`${value}-Option1`, `${value}-Option2`, `${value}-Option3`]
          loading.value = false
        }, 2000)
      } else {
        options.value = []
      }
    }

    return {
      options,
      loading,
      handleSearch,
    }
  },
})
</script>
```

### 异步设备与 ID 回显

Example source: src/select/__demos__/async-devices.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const value = ref([2])
const options = ref<{ id: number; name: string; disabled?: boolean }[]>([])
const loading = ref(false)
async function load() {
  loading.value = true
  try {
    options.value = await Promise.resolve(Array.from({ length: 200 }, (_, index) => ({
      id: index + 1, name: `设备 ${index + 1}`, disabled: index === 3,
    })))
  } finally { loading.value = false }
}
</script>
<template>
  <c-space direction="column" :size="16">
    <c-button @click="load">加载设备列表</c-button>
    <c-select v-model="value" :options="options" :loading="loading"
      :field-names="{ label: 'name', value: 'id' }" :virtual-list-props="{ height: 180 }"
      :limit="3" multiple filterable clearable placeholder="最多选择三个设备" />
    <p>已提交 ID：{{ value }}。加载前显示 ID，加载后自动回显名称。</p>
  </c-space>
</template>
```

主体、控制器、选项算法与样式在两端独立维护；展示方式继承 Form/Item。完整对比示例集中在 Form 文档。

未设置 disabled / error 时继承表单状态；显式 false 可以覆盖继承值。FieldDecorator 和 SelectionField 不重复注入表单上下文，focus / blur 由 Select 向表单分发一次。

### 共用异步数据源（进阶可选）

常规使用给 options 直接传入加载函数，组件内部负责异步状态。只有需要多个组件共享同一份结果、或组合不同控件时，才在业务层选用公开 useAsyncData；这不是组件的必需接入步骤。options/data 同时支持数组和加载函数，组件不解析业务响应。

Example source: src/select/__demos__/async-source.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { useAsyncData } from '@cedar-design/use'
const value = ref('mengshuai')
// A shared business function can be imported and reused in other fields.
const loadPeople = async () => {
  await new Promise(resolve => setTimeout(resolve, 200))
  return [{ value: 'mengshuai', label: '孟帅' }, { value: 'wujiaming', label: '吴甲明' }]
}
const { data: options, loading, error, refresh } = useAsyncData(loadPeople, {
  initialData: [] as { value: string; label: string }[],
})
</script>
<template>
  <c-space direction="column">
    <c-select v-model="value" :options="options" :loading="loading" filterable />
    <p v-if="error" role="alert">加载失败，请重试。</p>
    <c-button @click="refresh()">重新加载</c-button>
  </c-space>
</template>
```

### 函数属性：初始化与搜索

Example source: src/select/__demos__/async-data.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const value = ref('')
// Replace this loader body with your API and response mapping.
async function request(query: string, { signal }: { signal: AbortSignal }) {
  await new Promise<void>((resolve, reject) => {
    const abort = () => { clearTimeout(timer); reject(new Error('Cancelled')) }
    const timer = setTimeout(() => { signal.removeEventListener('abort', abort); resolve() }, 300)
    if (signal.aborted) { abort(); return }
    signal.addEventListener('abort', abort, { once: true })
  })
  return [{ value: 'a', label: 'Alice' }, { value: 'b', label: 'Bob' }].filter(option => option.label.toLowerCase().includes(query.toLowerCase()))
}
const error = ref('')
</script>
<template>
  <c-space direction="column">
    <c-select v-model="value" :options="request" filterable @load-error="error = 'Load failed'" />
    <p role="alert">{{ error }}</p>
    <p>Selected: {{ value }}</p>
  </c-space>
</template>
```

## 配置与生命周期

### 透传配置边界与优先级

<!-- demo-config-notes:start -->

#### 本组配置对照

| 配置                  | 作用                                                                                                                 | 相关示例                                           |
| --------------------- | -------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| `options`             | 原始值、对象、分组均支持；三种展示使用同一数据源                                                                     | 透传配置边界与优先级、交互调度生命周期、复制与编辑 |
| `edit-mode`           | 字段展示；未指定时继承 FormItem/Form                                                                                 | 透传配置边界与优先级、复制与编辑                   |
| `trigger-props`       | 可选的下拉浮层 Trigger 配置；placement 默认 bottom-start，空间不足时自动调整；字段拥有展开状态，不提供顶层 placement | 透传配置边界与优先级                               |
| `open-trigger-target` | 打开面板的点击区域；field 为整个字段，icon 仅右侧选择按钮。不影响键盘展开及受控 open。                               | 复制与编辑                                         |
| `filterable`          | 开启搜索，可设置 retainInputValue                                                                                    | 复制与编辑                                         |

<!-- demo-config-notes:end -->

建议使用 `SelectTriggerOptions` 声明 trigger-props。open/defaultOpen、disabled 和展开更新归 Select 管理。popup-container 顶层明确传入时优先（包括 false），否则回退 triggerProps.popupContainer。其他属性保持现有顺序：Trigger 默认配置 → 顶层 auto-fit-popup-width / unmount-on-close → trigger-props；因此旧嵌套配置仍可覆盖后两项。此兼容阶段不改为“顶层永远优先”。内部展开监听继续执行，通知使用 Select 事件。

本次仅新增可主动选用的专用类型，不收窄已发布的宽属性类型，不增加运行时过滤、不改变覆盖顺序；旧业务写法继续可编译。若直接使用旧宽属性，内部托管字段仍可能通过类型检查，但不代表能控制内部状态。

```ts
import type { SelectTriggerOptions } from "@cedar-design/ui";
```

Example source: src/select/__demos__/passthrough-options.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import type { SelectTriggerOptions } from "@cedar-design/ui";
const open = ref(false);
const triggerOptions: SelectTriggerOptions = {
  placement: "top-start",
  popupOffset: 8,
  popupContainer: false,
};
const options = [
  { value: "USER_A", label: "Apple" },
  { value: "USER_B", label: "Banana" },
];
</script>
<template>
  <c-space direction="column" fill>
    <c-button @click="open = !open">{{
      open ? "关闭面板" : "打开面板"
    }}</c-button>
    <c-select
      edit-mode="direct"
      v-model:open="open"
      :options="options"
      :trigger-props="triggerOptions"
      aria-label="透传配置示例"
    />
    <p role="status">顶层 open：{{ open }}；嵌套配置：向上展开并调整偏移。</p>
  </c-space>
</template>
```

### 交互调度生命周期

Example source: src/select/__demos__/scheduler-lifecycle.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
const active = ref(true);
const open = ref(false);
const value = ref("Item 101");
const options = Array.from(
  { length: 200 },
  (_, index) => "Item " + (index + 1),
);
</script>
<template>
  <div>
    <c-button @click="open = !open">Open / close</c-button>
    <c-button @click="active = !active">Activate / deactivate</c-button>
    <p>
      Open the menu, navigate with Arrow keys, then close or deactivate. Old
      scrolling must not replay.
    </p>
    <KeepAlive>
      <c-select
        v-if="active"
        v-model="value"
        v-model:open="open"
        :options="options"
        style="width: 240px"
      />
    </KeepAlive>
  </div>
</template>
```

### 复制与编辑

open-trigger-target="icon" 时，输入区可以编辑或复制，只有右侧选择按钮响应点击打开。关闭手输或搜索后，已有文本仍可复制。

Example source: src/select/__demos__/open-trigger-target.vue

```vue
<template>
  <c-space direction="column" align="stretch">
    <c-radio-group
      v-model="target"
      :options="[
        { label: '整个字段', value: 'field' },
        { label: '仅右侧图标', value: 'icon' },
      ]"
    />
    <label><c-switch v-model="editable" /> 允许编辑 / 搜索</label>
    <c-form-item layout="vertical" hide-label>
      <c-select
        v-model="value"
        edit-mode="direct"
        :open-trigger-target="target"
        :filterable="editable"
        :options="[
          { value: 'a', label: 'Alpha' },
          { value: 'b', label: 'Beta' },
        ]"
      />
    </c-form-item>
    <p>关闭编辑后，可以复制已有文本；仅图标模式下编辑不会展开。</p>
  </c-space>
</template>
<script setup lang="ts">
import { ref } from "vue";
const target = ref<"field" | "icon">("icon");
const editable = ref(true);
const value = ref("a");
</script>
```

### 共享字段加载

`loading` 控制共享字段加载状态；`loading-mode` 为 `default`（指示器）或 `line`（底部不定进度线），默认 `default`。渲染统一由 FieldDecorator 负责；Select 原有 loading 语义仍会暂停选择和确认，允许搜索。

## API

### 空值识别与阅读空文案

`empty-values` 用于空值识别，`empty-value` 保留原清空输出；`empty-text` 仅在 `read-pretty` 空内容下展示，默认 `'-'`，字段 > FormItem > Form，自定义 read 插槽优先。显式配置 empty-values 后，内置 required 接入该策略，自定义校验仍收到原值。详见[统一说明](llms/zh-CN/guide/empty-values.md)。

| 参数         | 类型               | 缺省与范围                                            |
| ------------ | ------------------ | ----------------------------------------------------- |
| empty-values | readonly unknown[] | 字段 > FormItem > Form > 组件族默认；完整覆盖，不合并 |
| empty-text   | string             | 字段 > FormItem > Form > '-'；显式 '' 有效            |

以上是字段展示层 API；纯面板不因此新增阅读模式。Form 与 FormItem 提供继承配置。empty-value 的现有类型与默认输出仍按该组件原 API 执行。

单选和多选的已选行右侧均显示主色对勾；仅候选高亮时不显示对勾。click/dblclick 编辑面板内的对勾表示当前草稿选择，确认后才提交表单；禁用已选项保持禁用外观。

### 清空值与 1.x 兼容性

`SelectValue` 包含 `undefined`。默认单选清空发出 `''`；当前候选中有 `value: ''` 时发出 `undefined`，用于区分清空与选中空字符串选项。此已发布行为保持不变，`change` 和 `update:modelValue` 均使用 `SelectValue` 类型。

`empty-value` 指定清空输出；省略时保留原有默认值。单选可使用 `() => undefined` 明确返回 undefined；多选应返回符合模型形状的数组。存在不可清除的禁用选中项时，优先保留这些项，不执行清空覆盖。受控模式仍需父级接受更新。

根入口与组件入口均导出 `SelectValue`、`SelectEmptyValue`。

### Select 属性

分别使用 `v-model`、`v-model:open` 和 `v-model:input-value` 控制选中值、展开状态和搜索词。单选清空为 `''`，多选为 `[]`；Select 存在真实空字符串选项时，清空值为 `undefined`。

| 属性                                          | 说明                                                                                                                    | 类型                                                        | 默认值                       |
| --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | ---------------------------- |
| `open-trigger-target`                         | 打开面板的点击区域；field 为整个字段，icon 仅右侧选择按钮。不影响键盘展开及受控 open。                                  | `'field' \| 'icon'`                                         | `'field'`                    |
| `model-value / default-value`                 | 受控值 / 非受控初始值                                                                                                   | `Value`                                                     | `单选 ''，多选 []`           |
| `open / default-open`                         | 受控展开 / 默认展开                                                                                                     | `boolean`                                                   | `undefined / false`          |
| `input-value / default-input-value`           | 搜索文本，独立于选中值                                                                                                  | `string`                                                    | `undefined / ''`             |
| `multiple`                                    | 多选；默认启用搜索                                                                                                      | `boolean`                                                   | `false`                      |
| `size`                                        | 完整支持 xs、sm、md、lg、xl，未设置时继承分组与表单                                                                     | `ComponentSize`                                             | `md`                         |
| `variant`                                     | filled、outline、standard；未设置时继承 InputGroup                                                                      | `FormControlVariant`                                        | `filled`                     |
| `disabled / readonly / error`                 | 未设置时继承表单；显式 false 可覆盖                                                                                     | `boolean`                                                   | `undefined`                  |
| `placeholder`                                 | 占位文本                                                                                                                | `string`                                                    | `—`                          |
| `hint / line`                                 | 浮动提示 / standard 变体下划线                                                                                          | `boolean`                                                   | `true`                       |
| `text-color / focus-color / blur-color`       | 字段颜色                                                                                                                | `string`                                                    | `—`                          |
| `loading`                                     | 加载状态；禁止选择和确认                                                                                                | `boolean`                                                   | `false`                      |
| `loading-mode` | 加载布局：默认指示器或底部加载线 | `default / line` | `default` |
| `show-tags`                                   | 多选值以标签展示；false 改用分隔文本                                                                                    | `boolean`                                                   | `true`                       |
| `separator`                                   | show-tags=false 时的多选分隔符                                                                                          | `string`                                                    | `,`                          |
| `text-align`                                  | 文字对齐 left / center / right；未设置时继承 FormItem 的 content-align，独立使用默认阅读起点 start                               | `'left' \| 'center' \| 'right'`                             | `-`                          |
| `max-tag-count`                               | 标签数量上限，0 不限制                                                                                                  | `number`                                                    | `0`                          |
| `tag-nowrap`                                  | 标签单行显示；长文字省略、删除图标保留，标签行可横向滚动；悬停、聚焦或点按省略正文查看全文                              | `boolean`                                                   | `false`                      |
| `popup-container`                             | 选择器、元素、返回元素的函数或 false（原地渲染）                                                                        | `PopupContainer`                                            | `—`                          |
| `trigger-props`                               | 可选的下拉浮层 Trigger 配置；placement 默认 bottom-start，空间不足时自动调整；字段拥有展开状态，不提供顶层 placement    | `TriggerProps`                                              | `—`                          |
| `virtual-list-props`                          | Menu / List 的虚拟列表参数                                                                                              | `VirtualListProps`                                          | `—`                          |
| `search-delay`                                | search 事件防抖时长（毫秒）                                                                                             | `number`                                                    | `500`                        |
| `format-label`                                | 格式化已选标签；VNode 使用 label 插槽                                                                                   | `function`                                                  | `—`                          |
| `clearable`                                   | 允许清除，保留禁用的已选项                                                                                              | `boolean`                                                   | `true`                       |
| `empty-value`                                 | 清空输出覆盖；多选返回数组，保留不可清除项                                                                              | `SelectEmptyValue`                                          | `undefined`                  |
| `options`                                     | 原始值、对象、分组均支持；三种展示使用同一数据源                                                                        | `SelectOption[]` / `(query, { signal }) => Array / Promise` | `undefined`                  |
| `field-names`                                 | value、label、disabled、tagProps、render 字段映射；对象值须有唯一标识字段                                               | `SelectFieldNames`                                          | `—`                          |
| `filterable`                                  | 开启搜索，可设置 retainInputValue                                                                                       | `boolean 或 { retainInputValue?: boolean }`                 | `单选 false / 多选 true`     |
| case-sensitive                                | 内置本地过滤是否区分大小写，自定义过滤函数优先                                                                          | boolean                                                     | false                        |
| `filter-option`                               | false 关闭本地过滤；函数接收搜索词和原始选项                                                                            | `boolean 或 (input, option) => boolean`                     | 自动：数组开启，加载函数关闭 |
| `creatable`                                   | 允许创建不存在的选项                                                                                                    | `boolean`                                                   | `false`                      |
| `fallback-option`                             | 异步选项未到达时反显值，或返回完整回退选项                                                                              | `boolean 或 (value) => SelectOptionData`                    | `true`                       |
| `show-extra-options`                          | 菜单中展示回退/创建选项                                                                                                 | `boolean`                                                   | `true`                       |
| `limit`                                       | 多选数量上限，0 不限制                                                                                                  | `number`                                                    | `0`                          |
| `auto-fit-popup-width`                        | Menu 与字段等宽                                                                                                         | `boolean`                                                   | `true`                       |
| `default-active-first-option`                 | 打开选项列表时，无有效选中项则默认激活首个可用候选；仅高亮，不更新 modelValue 或触发 change。已有有效选中项优先激活该项 | `boolean`                                                   | `true`                       |
| `unmount-on-close`                            | 关闭 Menu 后销毁内容                                                                                                    | `boolean`                                                   | `false`                      |
| `scrollbar`                                   | Menu / List 滚动条配置                                                                                                  | `boolean 或 ScrollbarProps`                                 | `true`                       |
| `show-header-on-empty / show-footer-on-empty` | 空状态仍展示 header / footer                                                                                            | `boolean`                                                   | `false`                      |
| `edit-mode`                                   | 字段展示；未指定时继承 FormItem/Form                                                                                    | `direct / click / dblclick`                                 | `direct`                     |
| `before-commit`                               | 确认校验后可等待的保存拦截钩子                                                                                          | `(value, context) => void / false / Promise`                | —                            |

### 事件与方法

- `update:modelValue`、`change(value)`：提交时触发，编辑草稿不触发。
- `update:open`、`open-change(open)`：请求改变展开状态。
- `update:inputValue`、`input-value-change(text)`、`search(text)`：搜索状态。
- `focus(event)`、`blur(event)`、`clear(event)`：原生字段事件；只有字段所有者通知 Form。
- 方法：`focus()`、`blur()`。

Select 还提供 `remove(value)`、`exceed-limit(value, event)`、`dropdown-scroll(event)`、`dropdown-reach-bottom(event)`。

### 插槽与选项数据

使用 `label({ data })` 自定义已选标签，`selected` 替换整个已选区域。还支持 `prefix`、`suffix`、`clear-icon({ clear })`、`arrow-icon`、`loading-icon`、`search-icon`、`empty`、`option({ data })`。

选项 `label` 是用于搜索的纯文本；自定义选项内容使用 `render` 或 `option` 插槽，自定义反显使用 `format-label` 或 `label` 插槽。以 value 而非 label 识别选项。选项的 `disabled` 禁止选择和删除，`tagProps` 可定制已选标签。

Select 还支持 `header`、`footer`、`trigger` 和默认插槽中的 `Option / Optgroup`。Option 属性为 `value`、`label`、`disabled`、`tagProps`、`index`；默认插槽提供 `selected`。分组数据为 `{ isGroup: true, label, options }`。所有编辑展示共用相同选项模型；read 插槽可自定义阅读内容。

单选和多选选项统一使用 popup-option-padding-horizontal。组件没有隐式搜索高亮 DOM；自定义选项插槽负责其高亮片段样式。已删除无效的 multi-popup-option-padding-horizontal 与 popup-option-highlight-* 变量。

`read-pretty` 为独立布尔属性，与 `readonly`、`disabled` 同级；字段 > FormItem > Form 继承，显式 `false` 覆盖父级。默认 `false`。纯阅读不显示编辑器。

### Option Props

| 属性      | 说明                                  | 类型                                                   | 默认值    |
| --------- | ------------------------------------- | ------------------------------------------------------ | --------- |
| value     | 选项值，未传时取 label 或默认插槽文本 | string \| number \| boolean \| Record<string, unknown> | undefined |
| label     | 搜索与已选标签使用的文本              | string                                                 | undefined |
| disabled  | 禁止选择与移除                        | boolean                                                | false     |
| tag-props | 已选标签属性                          | TagProps                                               | undefined |
| index     | 手动指定选项顺序                      | number                                                 | undefined |

### Option Slots

| 插槽    | 说明           | 参数                  |
| ------- | -------------- | --------------------- |
| default | 自定义选项内容 | { selected: boolean } |
| icon    | 选项图标       | -                     |
| suffix  | 选项后缀       | -                     |

### Optgroup Props

| 属性  | 说明     | 类型   | 默认值    |
| ----- | -------- | ------ | --------- |
| label | 分组标题 | string | undefined |

### Optgroup Slots

| 插槽    | 说明                   | 参数 |
| ------- | ---------------------- | ---- |
| label   | 自定义分组标题         | -    |
| default | 分组下的 Option 子组件 | -    |

### Select Slots

| 插槽         | 说明                     | 参数            |
| ------------ | ------------------------ | --------------- |
| default      | Option / Optgroup 子组件 | -               |
| option       | 自定义选项内容           | { data }        |
| label        | 自定义已选标签           | { data }        |
| selected     | 替换整个已选区域         | -               |
| header       | 菜单页头                 | -               |
| footer       | 菜单页脚                 | -               |
| trigger      | 自定义选择器触发器       | -               |
| prefix       | 字段前缀                 | -               |
| suffix       | 字段后缀                 | -               |
| clear-icon   | 自定义清空操作           | { clear }       |
| arrow-icon   | 下拉箭头                 | -               |
| search-icon  | 搜索图标                 | -               |
| loading-icon | 加载图标                 | -               |
| empty        | 无选项内容               | -               |
| read         | 阅读展示                 | { value, text } |

### Select Events

| 事件                  | 说明         | 参数         |
| --------------------- | ------------ | ------------ |
| update:model-value    | 更新绑定值   | value        |
| change                | 提交选择     | value        |
| update:open           | 请求展开状态 | open         |
| open-change           | 展开状态改变 | open         |
| update:input-value    | 更新搜索文本 | text         |
| input-value-change    | 搜索文本改变 | text         |
| search                | 搜索通知     | text         |
| focus                 | 字段获得焦点 | event        |
| blur                  | 字段失去焦点 | event        |
| clear                 | 清空选择     | event        |
| remove                | 移除已选项   | value        |
| exceed-limit          | 超过多选上限 | value, event |
| dropdown-scroll       | 菜单滚动     | event        |
| dropdown-reach-bottom | 菜单滚到底部 | event        |

### Select Methods

| 方法  | 说明             | 参数 |
| ----- | ---------------- | ---- |
| focus | 聚焦实际字段     | -    |
| blur  | 移出实际字段焦点 | -    |

### 选中对勾样式变量

| 变量                                  | 默认值                              |
| ------------------------------------- | ----------------------------------- |
| `--c-select-popup-option-check-color` | `var(--c-sys-color-action-primary)` |
| `--c-select-popup-option-check-size`  | `var(--c-sys-font-size-md)`         |
| `--c-select-popup-option-check-gap`   | `var(--c-sys-space-4)`              |

### 公开类型入口

根入口和组件入口均导出 `SelectEmits`、`SelectSlots`、`SelectExpose`，与 Props、Instance 配套。Emits 为从运行时事件声明推导的参数元组映射；Expose 包含 focus/blur。

### 内置搜索字段配置

`searchFields` / `search-fields` 是只读 `('label' | 'value')[]`，默认 `['label']`；多字段为 OR 匹配，大小写默认不敏感。配置 `['value', 'label']` 可同时搜索编码和名称，fieldNames 将语义字段映射到业务字段；空数组对非空查询不匹配任何项。value 采用字符串比较，不做对象深层搜索，对象值或拼音等复杂规则仍用自定义回调。自定义回调优先并自行决定大小写；远程结果使用原有关闭本地过滤协议。Cascader 保留路径语义，会检查路径各节点的配置字段。

## 函数属性加载候选

直接传 options(query, { signal })，无需调用 useAsyncData。options 继续接收数组，显式数组（包括 []）优先。组件内部管理 loading、旧结果隔离与请求取消；load-error 通知失败，实例 refresh() 重试。业务函数可只接收 query，忽略第二参数。

filterable 表示允许输入搜索词。filterOption 只控制本地候选匹配，从不发请求。使用 options 加载函数时默认不再二次过滤远程结果；仅传数组时默认启用本地匹配。业务通常无需设置 filter-option。

```vue
<c-select v-model="value" :options="loadOptions" filterable />
```

`empty-value` 可显式设为 `null`（或 `() => null`），清空时原样提交 null；省略时保留组件原默认值。界面把 null 显示为空，不会把普通输入的空字符串自动转成 null。支持弹出编辑的字段中，清空先修改草稿，确认后提交，取消则保留原值。

守卫统一使用 `(payload, done, context)`：关闭 payload 为 `{ action }`，切换和提交为 `{ value, previousValue }`，Popup 为 `{ reason }`。context 提供 `signal` 和可选原始 `event`。返回 boolean/Promise，或调用 done()/done(false)；同步 void 等待 done，Promise&lt;void&gt; 放行。首次完成生效。等待期间自动管理 loading/disabled，取消后旧结果失效，不暴露内部按钮 refs。

---

Document: llms/zh-CN/components/skeleton.md

<!-- Source: src/skeleton/README.md; locale: zh-CN; page: /components/skeleton/ -->

# Skeleton

将加载中的数据用灰色占位。

## 基础示例

### 基础用法

Example source: src/skeleton/__demos__/basic.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
const loading = ref(true);
</script>

<template>
  <c-switch v-model="loading" />
  <c-skeleton :loading="loading">加载的数据</c-skeleton>
</template>
```

## 内容与展示

### 骨架内容形态对比

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `title` | 是否显示标题占位 | 骨架内容形态对比、动画 |
| `loading` | 是否展示骨架屏（加载中状态） | 骨架内容形态对比、全屏模式 |
| `avatar` | 是否显示头像占位 | 骨架内容形态对比、动画 |
| `rows` | 段落行数 | 骨架内容形态对比 |
| `rows-width` | 每行宽度 | 骨架内容形态对比 |
| `card` | 是否显示卡片占位 | 骨架内容形态对比 |
<!-- demo-config-notes:end -->

比较标题/文本行与头像/卡片形态，按最终内容轮廓选择占位布局；动画和全屏加载另行展示。

Example source: src/skeleton/__demos__/content-comparison.vue

```vue
<script setup lang="ts">
import { ref } from "vue"
import { proxyRefs as demoProxyRefs } from 'vue'

const scene1 = demoProxyRefs((() => {

const loading = ref(true);
return { loading }
})())
</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="title-and-rows">
    <h4><span lang="zh-CN">标题与段落</span><span lang="en-US">title and rows</span></h4>
    <c-skeleton
        title
        :rows="3"
        :loading="scene1.loading"
        :rows-width="['200px', '100px', '50px']"
      >
        加载的数据
      </c-skeleton>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="avatar-and-card">
    <h4><span lang="zh-CN">头像与卡片</span><span lang="en-US">avatar and card</span></h4>
    <c-skeleton title avatar card :rows="3">加载的数据</c-skeleton>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

### 动画

Example source: src/skeleton/__demos__/animation.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
const animation = ref(true);
</script>

<template>
  <c-switch v-model="animation" />
  <c-skeleton title avatar :animation="animation">加载的数据</c-skeleton>
</template>
```

### 全屏模式

点击后展示两秒再恢复，这是示例中的定时逻辑；组件本身不请求数据，也不会自动结束加载。实际业务应由请求结果控制 `loading`。

Example source: src/skeleton/__demos__/fullscreen.vue

```vue
<script setup lang="ts">
import { onUnmounted, ref } from "vue";
const loading = ref(false);
let timer: ReturnType<typeof setTimeout> | undefined;

function show() {
  loading.value = true;
  clearTimeout(timer);
  timer = setTimeout(() => {
    loading.value = false;
  }, 2000);
}
onUnmounted(() => clearTimeout(timer));
</script>

<template>
  <c-button status="danger" @click="show">切换全屏模式</c-button>
  <c-skeleton fullscreen :loading="loading" />
</template>
```

## 自定义与插槽

### 自定义模板

通过 `template` 插槽组合 `SkeletonLine` 和 `SkeletonShape`。

Example source: src/skeleton/__demos__/custom-template.vue

```vue
<template>
  <c-skeleton>
    <template #template>
      <c-space block direction="column" size="lg">
        <c-skeleton-line :rows="3" :widths="['100%', '100%', '60%']" />
        <c-skeleton-shape shape="circle" />
      </c-space>
    </template>
    加载的数据
  </c-skeleton>
</template>
```

## API

### `<skeleton>` Props

| 参数名             | 描述                         | 类型                      | 默认值  |
| ------------------ | ---------------------------- | ------------------------- | :-----: |
| loading            | 是否展示骨架屏（加载中状态） | `boolean`                 | `true`  |
| animation          | 是否开启骨架屏动画           | `boolean`                 | `true`  |
| title              | 是否显示标题占位             | `boolean`                 | `false` |
| avatar             | 是否显示头像占位             | `boolean`                 | `false` |
| card               | 是否显示卡片占位             | `boolean`                 | `false` |
| rows               | 段落行数                     | `number \| string`        |   `3`   |
| rows-width         | 每行宽度                     | `Array<number \| string>` |  `[]`   |
| title-width        | `50%` | `number \| string`        |   `-`   |
| avatar-size        | `34px` | `number \| string`        |   `-`   |
| card-height        | `160px` | `number \| string`        |   `-`   |
| fullscreen         | 是否使用全屏占位             | `boolean`                 | `false` |
| fullscreen-z-index | 全屏占位层级                 | `number \| string`        |  `100`  |

### `<skeleton>` Slots

| 插槽名   | 描述                 |
| -------- | -------------------- |
| default  | 加载完成后的真实内容 |
| template | 自定义加载占位模板   |

### `<skeleton-line>` Props

| 参数名       | 描述             | 类型                      | 默认值 |
| ------------ | ---------------- | ------------------------- | :----: |
| rows         | 展示的行数       | `number`                  |  `1`   |
| widths       | 线型骨架的宽度   | `Array<number \| string>` |  `[]`  |
| line-height  | 线型骨架的行高   | `number`                  |  `20`  |
| line-spacing | 线型骨架的行间距 | `number`                  |  `15`  |

### `<skeleton-shape>` Props

| 参数名 | 描述           | 类型                   |   默认值   |
| ------ | -------------- | ---------------------- | :--------: |
| shape  | 图形骨架的形状 | `'square' \| 'circle'` | `'square'` |
| size   | 图形骨架的大小 | `'sm' \| 'md' \| 'lg'` |   `'md'`   |

### 类型定义

组件导出以下类型定义

```ts
import type {
  SkeletonInstance,
  SkeletonLineProps,
  SkeletonShapeProps,
} from "@cedar-design/ui";
```

## 同源实现与平台边界

两端各自保存完整源码，不引用公共核心，不共享组件实例或响应式状态；修改时同步维护两份实现。主体、Props、关键样式及配对测试纳入只读源码一致性检查，主题 token 和安装入口各自维护。

Skeleton、SkeletonLine、SkeletonShape 均采用独立复制的源码；各库骨架主题和尺寸 token 独立维护。

### 受管默认值

| Token | Default |
| --- | --- |
| `--c-skeleton-content-padding` | `var(--c-sys-space-6)` |
| `--c-skeleton-card-border-radius` | `var(--c-sys-radius-md)` |
| `--c-skeleton-card-margin-bottom` | `var(--c-sys-space-6)` |
| `--c-skeleton-card-background-color` | `var(--c-sys-color-state-hover)` |
| `--c-skeleton-animation-background` | `linear-gradient(90deg, transparent, var(--c-sys-color-surface-default), transparent)` |
| `--c-skeleton-avatar-border-radius` | `50%` |
| `--c-skeleton-avatar-margin-right` | `var(--c-sys-space-6)` |
| `--c-skeleton-avatar-background-color` | `var(--c-sys-color-state-hover)` |
| `--c-skeleton-title-border-radius` | `10px` |
| `--c-skeleton-title-background-color` | `var(--c-sys-color-state-hover)` |
| `--c-skeleton-row-height` | `12px` |
| `--c-skeleton-row-border-radius` | `10px` |
| `--c-skeleton-row-margin-top` | `10px` |
| `--c-skeleton-shape-size-sm` | `36px` |
| `--c-skeleton-shape-size-md` | `48px` |
| `--c-skeleton-shape-size-lg` | `60px` |
| `--c-skeleton-shape-border-radius` | `var(--c-sys-radius-md)` |

### 动效变量

| Token | Default |
| --- | --- |
| `--c-skeleton-animation-duration` | `1s` |
| `--c-skeleton-transition-duration` | `var(--c-sys-motion-duration-slow)` |

内置动效遵循 prefers-reduced-motion: reduce：保留内容与状态反馈，关闭装饰性旋转、扫光和波纹。Icon 名称切换跳过等待，并取消尚未结束的切换。Ripple 时长变量只控制 CSS，250ms 生命周期计时未改变，每段视觉时长应不超过 250ms；自定义动画类由调用方负责适配。

---

Document: llms/zh-CN/components/slider.md

<!-- Source: src/slider/README.md; locale: zh-CN; page: /components/slider/ -->

# Slider 滑块

在有限数值范围内选择单值或区间。

## 基础示例

### 基础用法

Example source: src/slider/__demos__/basic.vue

```vue
<template>
  <c-slider></c-slider>
</template>
<script lang="ts" setup>
</script>
```

## 布局与排列

### 垂直方向

<!-- demo-config-notes:start -->

#### 本组配置对照

| 配置           | 作用                                                      | 相关示例 |
| -------------- | --------------------------------------------------------- | -------- |
| `orientation`  | 滑块轨道与操作的横纵轴向，默认 horizontal；不表示增减方向 | 垂直方向 |
| `aria-label`   | 可访问名称；范围可分别传入两个名称                        | 垂直方向 |
| `range`        | 两个固定低/高端，不可交叉；初始倒序自动排序               | 垂直方向 |
| `show-tooltip` | true悬浮/聚焦/拖动显示；false隐藏；always常驻             | 垂直方向 |

<!-- demo-config-notes:end -->

父容器提供 300px 高度，单值与范围分别回写。上移增大、下移减小；范围两端仍不能交叉。没有独立 reverse 属性。

Example source: src/slider/__demos__/vertical.vue

```vue
<script setup>
import { ref } from 'vue'

const value = ref(50)
const pair = ref([7, 64])
</script>

<template>
  <section class="slider-vertical-demo">
    <c-space justify="space-around">
      <div class="slider-vertical-demo__track">
        <c-slider v-model="value" orientation="vertical" aria-label="Vertical value" />
      </div>
      <div class="slider-vertical-demo__track">
        <c-slider
          v-model="pair"
          range
          show-tooltip="always"
          orientation="vertical"
          :aria-label="['Vertical minimum', 'Vertical maximum']"
        />
      </div>
    </c-space>
    <output aria-label="Vertical values">{{ value }} / {{ pair[0] }}–{{ pair[1] }}</output>
  </section>
</template>

<style scoped>
.slider-vertical-demo {
  display: flex;
  flex-direction: column;
  gap: 16px;
}
.slider-vertical-demo__track {
  height: 300px;
}
</style>
```

## 内容与展示

### 触控提示与定制

<!-- demo-config-notes:start -->

#### 本组配置对照

| 配置           | 作用                                          | 相关示例       |
| -------------- | --------------------------------------------- | -------------- |
| `show-tooltip` | true悬浮/聚焦/拖动显示；false隐藏；always常驻 | 触控提示与定制 |
| `aria-label`   | 可访问名称；范围可分别传入两个名称            | 触控提示与定制 |

<!-- demo-config-notes:end -->

Example source: src/slider/__demos__/touch-and-labels.vue

```vue
<script setup>
import { ref } from "vue";

const value = ref(45);
</script>
<template>
  <c-space direction="column" size="36px" style="padding: 32px 12px">
    <c-slider
      v-model="value"
      show-tooltip="always"
      aria-label="Always visible"
    />
    <c-slider
      v-model="value"
      :show-tooltip="false"
      active-color="#722ed1"
      thumb-color="#f4edff"
      :track-height="8"
      :thumb-size="24"
      aria-label="Custom size"
    />
    <c-slider v-model="value" aria-label="Custom handle"
      ><template #button="{ currentValue }"
        ><span class="slider-custom-handle">{{ currentValue }}</span></template
      ></c-slider
    >
  </c-space>
</template>
<style scoped>
.slider-custom-handle {
  display: flex;
  align-items: center;
  justify-content: center;
  width: 28px;
  height: 28px;
  border: 1px solid currentColor;
  border-radius: 50%;
  background: white;
  transform: translate(-6px, -6px);
}
</style>
```

## 交互与控制

### 交互状态切换

<!-- demo-config-notes:start -->

#### 本组配置对照

| 配置         | 作用                                                 | 相关示例                               |
| ------------ | ---------------------------------------------------- | -------------------------------------- |
| `aria-label` | 可访问名称；范围可分别传入两个名称                   | 刻度、标记和数字输入、受控与非交叉范围 |
| `range`      | 两个固定低/高端，不可交叉；初始倒序自动排序          | 刻度、标记和数字输入、受控与非交叉范围 |
| `step`       | 正有限步长，非法值回退1，按min对齐；max端点可达      | 刻度、标记和数字输入                   |
| `marks`      | 有限范围内位置到文本的映射                           | 刻度、标记和数字输入                   |
| `show-ticks` | 按step显示刻度，过密时省略，最多1000个               | 刻度、标记和数字输入                   |
| `show-input` | 显示InputNumber；Enter或失焦提交，使用同一归一化规则 | 刻度、标记和数字输入                   |

<!-- demo-config-notes:end -->

适用于连续区间内的数值调整。调整禁用、只读、错误反馈，用相同数据观察变化。控制区始终可用，可以随时恢复编辑；错误外观本身不会触发表单校验。

Example source: src/slider/__demos__/state-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref(30);
const __demoState = __demoReactive({
  disabled: false,
  readonly: false,
  error: false,
});
</script>
<template>
  <c-space direction="column" :size="16">
    <c-space wrap>
      <c-checkbox v-model="__demoState['disabled']">disabled</c-checkbox>
      <c-checkbox v-model="__demoState['readonly']">readonly</c-checkbox>
      <c-checkbox v-model="__demoState['error']">error</c-checkbox>
    </c-space>
    <c-slider v-model="value" v-bind="__demoState"></c-slider>
  </c-space>
</template>
```

### 刻度、标记和数字输入

Example source: src/slider/__demos__/keyboard-input.vue

```vue
<script setup>
import { ref } from "vue";

const value = ref(30);
const pair = ref([20, 80]);
const marks = { 0: "0", 25: "25", 50: "50", 75: "75", 100: "100" };
</script>
<template>
  <c-space direction="column" size="32px" style="padding: 24px 12px">
    <c-slider
      v-model="value"
      :step="5"
      :marks="marks"
      show-ticks
      show-input
      aria-label="Volume"
    />
    <c-slider
      v-model="pair"
      range
      show-input
      :aria-label="['Minimum', 'Maximum']"
      :format-tooltip="(value) => value + '%'"
    />
  </c-space>
</template>
```

### 受控与非交叉范围

Example source: src/slider/__demos__/controlled-range.vue

```vue
<script setup>
import { ref } from "vue";

const accepted = ref([30, 70]);
const proposed = ref(50);
</script>
<template>
  <c-space direction="column" size="28px" style="padding: 24px 12px">
    <c-slider
      v-model="accepted"
      range
      show-tooltip="always"
      :aria-label="['Minimum', 'Maximum']"
    />
    <c-slider
      :model-value="50"
      aria-label="Controlled rejection"
      @update:model-value="proposed = $event"
    />
    <output>{{ proposed }}</output>
    <c-slider :default-value="40" readonly aria-label="Read only" />
    <c-slider :default-value="40" disabled aria-label="Disabled" />
  </c-space>
</template>
```

## API

### 空值识别与阅读空文案

`empty-values` 用于空值识别，`empty-value` 保留原清空输出；`empty-text` 仅在 `read-pretty` 空内容下展示，默认 `'-'`，字段 > FormItem > Form，自定义 read 插槽优先。显式配置 empty-values 后，内置 required 接入该策略，自定义校验仍收到原值。详见[统一说明](llms/zh-CN/guide/empty-values.md)。

| 参数         | 类型               | 缺省与范围                                            |
| ------------ | ------------------ | ----------------------------------------------------- |
| empty-values | readonly unknown[] | 字段 > FormItem > Form > 组件族默认；完整覆盖，不合并 |
| empty-text   | string             | 字段 > FormItem > Form > '-'；显式 '' 有效            |

以上是字段展示层 API；纯面板不因此新增阅读模式。Form 与 FormItem 提供继承配置。empty-value 的现有类型与默认输出仍按该组件原 API 执行。

### Props

| 属性                                     | 说明                                                          | 类型                             | 默认值       |
| ---------------------------------------- | ------------------------------------------------------------- | -------------------------------- | ------------ |
| model-value                              | 受控值；range 使用二元组                                      | `SliderValue`                    | —            |
| default-value                            | 非受控初始值                                                  | `SliderValue`                    | `0`          |
| min / max                                | 有限边界，数字字符串可用；非法值回退 0/100；max<=min 不可交互 | `number \| string`               | `0 / 100`    |
| step                                     | 正有限步长，非法值回退1，按min对齐；max端点可达               | `number \| string`               | `1`          |
| range                                    | 两个固定低/高端，不可交叉；初始倒序自动排序                   | `boolean`                        | `false`      |
| orientation                              | 滑块轨道与操作的横纵轴向，默认 horizontal；不表示增减方向     | `horizontal \| vertical`         | `horizontal` |
| disabled / readonly / error              | 未传时继承FormItem/Form适用状态；只读可聚焦但不可改值         | `boolean`                        | 继承         |
| show-ticks                               | 按step显示刻度，过密时省略，最多1000个                        | `boolean`                        | `false`      |
| marks                                    | 有限范围内位置到文本的映射                                    | `Record<number,string>`          | —            |
| show-input                               | 显示InputNumber；Enter或失焦提交，使用同一归一化规则          | `boolean`                        | `false`      |
| show-tooltip                             | true悬浮/聚焦/拖动显示；false隐藏；always常驻                 | `boolean \| 'always'`            | `true`       |
| format-tooltip                           | 提示与aria-valuetext格式化                                    | `(value:number)=>string\|number` | 原值         |
| aria-label                               | 可访问名称；范围可分别传入两个名称                            | `string \| [string,string]`      | —            |
| active-color / track-color / thumb-color | 轨道激活色/背景色/拇指底色                                    | `string`                         | CSS变量      |
| label-color / label-text-color           | 提示背景/文字色                                               | `string`                         | CSS变量      |
| track-height / thumb-size                | 轨道厚度/拇指直径，数字px或CSS长度；非法值保留主题默认        | `number \| string`               | CSS变量      |

### 行为与键盘

方向键按step增加/减少，PageUp/PageDown为10步，Home/End到可用端点。范围的ARIA min/max随另一个拇指变化；重合时向左/下点击可分开低端，向右/上可分开高端。拇指内业务交互元素的键盘事件不被接管。只读保留焦点与提示，禁用不进入Tab顺序。

Pointer Events统一鼠标、触控、笔；pointerup提交最后坐标，pointercancel/丢失capture结束最近提议。禁用、卸载、KeepAlive失活会清理监听与capture且不继续发值事件。横向允许页面纵向滚动，纵向允许横向滚动。

受控模式只有父级回写才能改变显示；模型归一化不自动emit。change/update:model-value只报告不同提议，end携带最终提议，不保证父级接受。键盘及数字输入每次操作各有start/end；拖动是一组start/end。InputNumber内部不重复触发Form验证。已移除旧label-visible，直接使用show-tooltip，无兼容别名。

### Events

| 事件               | 参数          | 含义                         |
| ------------------ | ------------- | ---------------------------- |
| update:model-value | `SliderValue` | 请求更新                     |
| change             | `SliderValue` | 不同数值提议，与模型事件配对 |
| start              | —             | 交互开始                     |
| end                | `SliderValue` | 交互结束的最终提议           |

### Slots / Methods

button插槽收到`{ currentValue:number,index:number }`；自定义内容不移除键盘、ARIA与提示。focus(index=0)按显示顺序聚焦拇指，blur()移出焦点。

导出SliderProps、SliderValue、SliderOrientation、SliderTooltipFormatter、SliderTooltipVisibility、SliderEmits、SliderSlots、SliderExpose、SliderInstance和运行时sliderProps。两端主体/样式独立复制；仅安装和Form接线使用各库独立实现。

### 样式变量

| 变量                             | 默认值                                 |
| -------------------------------- | -------------------------------------- |
| `--c-slider-active-color`        | `var(--c-sys-color-content-brand)`     |
| `--c-slider-track-color`         | `var(--c-sys-color-state-hover)`       |
| `--c-slider-thumb-color`         | `var(--c-sys-color-surface-default)`   |
| `--c-slider-thumb-border-color`  | `var(--c-sys-color-content-brand)`     |
| `--c-slider-text-color`          | `var(--c-sys-color-content-secondary)` |
| `--c-slider-tooltip-background`  | `var(--c-sys-color-surface-tooltip)`   |
| `--c-slider-tooltip-color`       | `var(--c-sys-color-content-on-dark)`   |
| `--c-slider-error-color`         | `var(--c-sys-color-content-danger)`    |
| `--c-slider-disabled-color`      | `var(--c-sys-color-content-disabled)`  |
| `--c-slider-track-height`        | `4px`                                  |
| `--c-slider-thumb-size`          | `16px`                                 |
| `--c-slider-control-height`      | `var(--c-sys-control-height-md)`       |
| `--c-slider-font-size`           | `var(--c-sys-font-size-sm)`            |
| `--c-slider-gap`                 | `var(--c-sys-space-4)`                 |
| `--c-slider-radius`              | `var(--c-sys-radius-md)`               |
| `--c-slider-transition-duration` | `var(--c-sys-motion-duration-fast)`    |
| `--c-slider-input-width`         | `80px`                                 |

### Form 字段展示与确认

本组件支持 `edit-mode`，字段 > FormItem > Form 逐层继承；未指定时为 `direct`，保留原有交互。支持值：`direct / click / dblclick`。非 direct 编辑模式通过字段值入口打开编辑面板，并维护单份草稿；确认后才更新 v-model，取消、重置或启用 readPretty 时丢弃草稿。

Cedar 使用 edit-mode="click" / "dblclick" 在字段附近打开编辑浮层，Enter/F2 也可进入；取消/Escape 丢弃草稿，确认后提交。readPretty 为独立阅读属性，与 readonly、disabled 分开。

`before-commit(value, { previousValue, signal })` 可拦截弹层保存；FormItem 先校验候选值，失败保持编辑。`open / default-open / update:open` 控制编辑层。`#read="{ value, text }"` 可自定义阅读内容。集中示例见 Form 的“各类字段统一展示”。

`read-pretty` 为独立布尔属性，与 `readonly`、`disabled` 同级；字段 > FormItem > Form 继承，显式 `false` 覆盖父级。默认 `false`。纯阅读不显示编辑器。

`empty-value` 可显式设为 `null`（或 `() => null`），清空时原样提交 null；省略时保留组件原默认值。界面把 null 显示为空，不会把普通输入的空字符串自动转成 null。支持弹出编辑的字段中，清空先修改草稿，确认后提交，取消则保留原值。

---

Document: llms/zh-CN/components/space.md

<!-- Source: src/space/README.md; locale: zh-CN; page: /components/space/ -->

# Space

通过 flex gap 设置子元素间距，每个有效子节点外包裹一个 item 容器，支持 Fragment 展开与分隔符。

## 基础示例

### 基础用法

Example source: src/space/__demos__/basic.vue

```vue
<template>
  <c-space>
    <div>Space:</div>
    <c-tag v-if="false">Tag</c-tag>
    <c-button status="primary">Item1</c-button>
    <c-button status="primary">Item2</c-button>
  </c-space>
</template>
```

## 外观与状态

### 尺寸

内置 xs / sm / md / lg / xl 五档，默认 md；支持数字、CSS 长度和 [行间距, 列间距]，具体值见下方同源约定。

Example source: src/space/__demos__/size.vue

```vue
<template>
  <div>
    <div style="margin-bottom: 20px">
      <c-radio-group v-model="size" type="button">
        <c-radio value="xs">xs</c-radio>
        <c-radio value="sm">sm</c-radio>
        <c-radio value="md">md</c-radio>
        <c-radio value="lg">lg</c-radio>
        <c-radio value="xl">xl</c-radio>
      </c-radio-group>
    </div>
    <c-space :size="size">
      <c-button status="primary">Item1</c-button>
      <c-button status="primary">Item2</c-button>
      <c-button status="primary">Item3</c-button>
    </c-space>
  </div>
</template>
<script lang="ts">
import { defineComponent, ref } from 'vue'
export default defineComponent({
  setup() {
    const size = ref('md')

    return {
      size,
    }
  },
})
</script>
```

## 布局与排列

### 垂直间距

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `direction` | 子元素的行列排列顺序，默认 row；column 表示按列排列，不使用 horizontal/vertical | 垂直间距、对齐、布局与对齐 |
| `align` | 交叉轴排列方式 可选值为 `flex-start` `flex-end` `center` `stretch` `baseline`，未传时根据 `direction` 推断（`row` → `center`，`column` → `stretch`） | 对齐、布局与对齐 |
| `wrap` | 是否超出换行 | 环绕、分隔符 |
| `size` | 间距，可选值为 `xs` `sm` `md` `lg` `xl` 或 `[rowGap, columnGap]` (支持长度单位和简写方式) | 分隔符、布局与对齐 |
| `justify` | 主轴排列方式 可选值为 `flex-start` `flex-end` `center` `space-around` `space-between` `space-evenly` | 布局与对齐 |
<!-- demo-config-notes:end -->

可以设置垂直方向排列的间距。

Example source: src/space/__demos__/vertical.vue

```vue
<template>
  <c-space direction="column">
    <c-button status="primary" long>Item1</c-button>
    <c-button status="primary" long>Item2</c-button>
    <c-button status="primary" long>Item3</c-button>
  </c-space>
</template>
<script lang="ts">
import { defineComponent } from 'vue'
export default defineComponent({
  })
</script>
```

### 对齐

内置多种对齐方式，分别为 `flex-start` `center` `flex-end` `stretch` `baseline`。未传入时：`row` 默认为 `center`，`column` 默认为 `stretch`。

Example source: src/space/__demos__/align.vue

```vue
<template>
  <c-space direction="column" align="stretch">
    <c-space direction="column">
      <c-radio-group v-model="direction">
        <c-radio value="row">row</c-radio>
        <c-radio value="column">column</c-radio>
      </c-radio-group>
      <c-radio-group v-model="align">
        <c-radio value="flex-start">flex-start</c-radio>
        <c-radio value="flex-end">flex-end</c-radio>
        <c-radio value="center">center</c-radio>
        <c-radio value="stretch">stretch</c-radio>
        <c-radio value="baseline">baseline</c-radio>
      </c-radio-group>
    </c-space>
    <c-space :align="align" :direction="direction" style="padding: 10px; background-color: var(--color-fill-2)">
      <div>Space:</div>
      <c-button status="primary">Item2</c-button>
      <c-card title="Card"> Card content </c-card>
    </c-space>
  </c-space>
</template>
<script lang="ts" setup>
import { ref } from 'vue'
const direction = ref('row')
const align = ref('center')
</script>
```

### 环绕

默认不换行；显式设置 wrap 后允许超出换行。gap 只作用于子项之间，不增加容器外围间距。

Example source: src/space/__demos__/wrap.vue

```vue
<template>
  <c-space wrap>
    <c-button status="primary">Item1</c-button>
    <c-button status="primary">Item2</c-button>
    <c-button status="primary">Item3</c-button>
    <c-button status="primary">Item4</c-button>
    <c-button status="primary">Item5</c-button>
    <c-button status="primary">Item6</c-button>
    <c-button status="primary">Item7</c-button>
    <c-button status="primary">Item8</c-button>
    <c-button status="primary">Item9</c-button>
    <c-button status="primary">Item10</c-button>
    <c-button status="primary">Item11</c-button>
    <c-button status="primary">Item12</c-button>
    <c-button status="primary">Item13</c-button>
    <c-button status="primary">Item14</c-button>
    <c-button status="primary">Item15</c-button>
    <c-button status="primary">Item16</c-button>
    <c-button status="primary">Item17</c-button>
    <c-button status="primary">Item18</c-button>
    <c-button status="primary">Item19</c-button>
    <c-button status="primary">Item20</c-button>
  </c-space>
</template>
<script lang="ts">
import { defineComponent } from 'vue'
export default defineComponent({})
</script>
```

### 分隔符

为相邻子元素设置分隔符。

Example source: src/space/__demos__/split.vue

```vue
<template>
  <c-radio-group v-model="size">
    <c-radio value="xs">xs</c-radio>
    <c-radio value="sm">sm</c-radio>
    <c-radio value="md">md</c-radio>
    <c-radio value="lg">lg</c-radio>
    <c-radio value="xl">xl</c-radio>
  </c-radio-group>
  <br />
  <br />
  通过 divider 组件实现分割，并且通过 inset 和 spacing 调整分割线尺寸。
  <br />
  <br />
  <c-space :size="size" wrap>
    <template #split>
      <c-divider orientation="vertical" inset="md" spacing="0" />
    </template>
    <c-button status="primary">Item1</c-button>
    <c-button status="primary">Item2</c-button>
    <c-button status="primary">Item3</c-button>
    <c-button status="primary">Item4</c-button>
    <c-button status="primary">Item5</c-button>
    <c-button status="primary">Item6</c-button>
    <c-button status="primary">Item7</c-button>
    <c-button status="primary">Item8</c-button>
    <c-button status="primary">Item9</c-button>
    <c-button status="primary">Item10</c-button>
  </c-space>
  <br />
  通过自定义分割内容实现分割。
  <br />
  <br />
  <c-space :size="size" wrap>
    <template #split> <div>/</div> </template>
    <c-button status="primary">Item1</c-button>
    <c-button status="primary">Item2</c-button>
    <c-button status="primary">Item3</c-button>
    <c-button status="primary">Item4</c-button>
    <c-button status="primary">Item5</c-button>
    <c-button status="primary">Item6</c-button>
    <c-button status="primary">Item7</c-button>
    <c-button status="primary">Item8</c-button>
    <c-button status="primary">Item9</c-button>
    <c-button status="primary">Item10</c-button>
  </c-space>
</template>
<script lang="ts" setup>
import { ref } from 'vue'
const size = ref('md')
</script>
```

### 布局与对齐

适用于space。调整排列方向、交叉轴对齐、主轴分配，用相同数据观察变化。内容保持一致，便于比较不同设置的实际效果。

Example source: src/space/__demos__/layout-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";

const __demoLayout = __demoReactive({
  direction: "row",
  align: "flex-start",
  justify: "flex-start",
});
</script>
<template>
  <c-space direction="column" :size="16">
    <c-form layout="vertical">
      <c-form-item layout="vertical" size="sm" label="direction">
        <c-radio-group
          v-model="__demoLayout['direction']"
          aria-label="direction"
          :options="[
            { label: 'row', value: 'row' },
            { label: 'column', value: 'column' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
      <c-form-item layout="vertical" size="sm" label="align">
        <c-radio-group
          v-model="__demoLayout['align']"
          aria-label="align"
          :options="[
            { label: 'flex-start', value: 'flex-start' },
            { label: 'flex-end', value: 'flex-end' },
            { label: 'center', value: 'center' },
            { label: 'baseline', value: 'baseline' },
            { label: 'stretch', value: 'stretch' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
      <c-form-item layout="vertical" size="sm" label="justify">
        <c-select
          v-model="__demoLayout['justify']"
          :clearable="false"
          :options="[
            { label: 'flex-start', value: 'flex-start' },
            { label: 'flex-end', value: 'flex-end' },
            { label: 'center', value: 'center' },
            { label: 'space-around', value: 'space-around' },
            { label: 'space-between', value: 'space-between' },
            { label: 'space-evenly', value: 'space-evenly' },
          ]"
          aria-label="justify"
        />
      </c-form-item>
    </c-form>
    <c-space v-bind="__demoLayout">
      <div>Space:</div>
      <c-tag v-if="false">Tag</c-tag>
      <c-button status="primary">Item1</c-button>
      <c-button status="primary">Item2</c-button>
    </c-space>
  </c-space>
</template>
```

### 分隔换行与内容状态

输入草稿后切换换行、方向或顺序。分隔符跟随前一项，可出现在行尾，不会独占一行。

Example source: src/space/__demos__/split-wrapping.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'

const wrap = ref(true)
const direction = ref<'row' | 'column'>('row')
const items = ref(['A', 'B', 'C'])
</script>
<template>
  <c-space wrap :size="8">
    <c-button data-space-toggle-wrap @click="wrap = !wrap">换行 / Wrap</c-button>
    <c-button data-space-toggle-direction @click="direction = direction === 'row' ? 'column' : 'row'">方向 / Direction</c-button>
    <c-button data-space-reorder @click="items = [...items].reverse()">重排 / Reorder</c-button>
  </c-space>
  <p>输入草稿后切换布局或重排，文字仍跟随对应项。Drafts stay with their items.</p>
  <div style="max-width: 100%; overflow: auto">
    <c-space data-space-split-demo :size="12" :wrap="wrap" :direction="direction" style="width: 260px; max-width: 100%">
      <template v-for="item in items" :key="item">
        <label class="space-split-field">
          <span>Item {{ item }}</span>
          <input :aria-label="'Draft ' + item" placeholder="草稿 / Draft" />
        </label>
      </template>
      <template #split><span aria-hidden="true">/</span></template>
    </c-space>
  </div>
  <p>分隔符跟随前项，允许位于行尾。Separators stay with the preceding item.</p>
</template>
<style scoped>
.space-split-field {
  display: inline-flex;
  flex-direction: column;
  gap: 4px;
  width: 110px;
}
.space-split-field input {
  min-width: 0;
  width: 100%;
  box-sizing: border-box;
}
</style>
```

## 交互与控制

### 动态布局

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `wrap` | 是否超出换行 | 动态布局 |
| `size` | 间距，可选值为 `xs` `sm` `md` `lg` `xl` 或 `[rowGap, columnGap]` (支持长度单位和简写方式) | 动态布局 |
| `direction` | 子元素的行列排列顺序，默认 row；column 表示按列排列，不使用 horizontal/vertical | 动态布局 |
<!-- demo-config-notes:end -->

切换方向、列间距和换行，添加/删除子项；行间距固定8px，列间距在8px/24px间切换。方向不会交换两个gap的几何轴含义。窄容器内未换行时可横向滚动。

Example source: src/space/__demos__/interactive-layout.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'

const direction = ref<'row' | 'column'>('row')
const gap = ref(8)
const wrap = ref(false)
const count = ref(3)
</script>

<template>
  <div>
    <c-space wrap :size="8">
      <c-button @click="direction = direction === 'row' ? 'column' : 'row'">Toggle direction</c-button>
      <c-button @click="gap = gap === 8 ? 24 : 8">Toggle gap</c-button>
      <c-button @click="wrap = !wrap">Toggle wrap</c-button>
      <c-button :disabled="count >= 6" @click="count++">Add item</c-button>
      <c-button :disabled="count <= 1" @click="count--">Remove item</c-button>
    </c-space>
    <p aria-live="polite">{{ direction }} / gap {{ gap }} / wrap {{ wrap }} / items {{ count }}</p>
    <div style="max-width: 100%; overflow: auto">
      <c-space data-demo-layout :direction="direction" :size="[8, gap]" :wrap="wrap" style="width: 260px; max-width: 100%">
        <div v-for="item in count" :key="item" style="width: 72px; padding: 8px; box-sizing: border-box; border: 1px solid currentColor">Item {{ item }}</div>
      </c-space>
    </div>
  </div>
</template>
```

## 阅读方向

继承最近的 `dir="ltr|rtl"`。`direction="row"` 沿阅读顺序排列，`column` 保持从上到下；justify/align 的 flex-start、flex-end 跟随对应 flex 轴。`size=[rowGap,columnGap]` 始终分别表示行间距、列间距，不因 RTL 交换。换行与 split 插槽沿内容顺序排列，方向切换不反转数据或重建有稳定 key 的子节点。

## API

### 子节点与尺寸边界

带 key 的 Fragment 分组重排时保留局部子项身份。纯空白、空文本、注释和空 Fragment 不生成间距项；有意义的文字、数字 0 和空元素保留。空的 split 内容也不生成分隔项。

wrap 与 split 组合时，分隔符跟随前一项，可以出现在行尾；不承诺隐藏每行边缘的分隔符。单项宽度超出可用行宽时仍可能溢出。未开启 wrap 时，保持原有 Flex gap 与 justify 分配规则。切换布局不会重建内容节点。

block 将容器切换为 flex / inline-flex；align=stretch 拉伸内部 item 包装层，不保证其中的控件填满。需要撑满时使用子控件的 block 或 width:100%。

非法 size 结构、负数/非有限数字、非二元组数组会回退 md，并在开发环境提示。数组项为长度，不接受预设名。仍支持 CSS var/calc 表达式，具体 CSS 语法与解析值由浏览器处理。


### Space Props

### 属性

| 参数      | 说明                                                                                                 | 类型                                                       | 默认值                 |
| --------- | ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | ---------------------- |
| direction | 子元素的行列排列顺序，默认 row；column 表示按列排列，不使用 horizontal/vertical | _string_                                                   | `row`                  |
| justify   | 主轴排列方式 可选值为 `flex-start` `flex-end` `center` `space-around` `space-between` `space-evenly` | _string_                                                   | `flex-start`           |
| align     | 交叉轴排列方式 可选值为 `flex-start` `flex-end` `center` `stretch` `baseline`，未传时根据 `direction` 推断（`row` → `center`，`column` → `stretch`） | _string_                                                   | `-`                    |
| size      | 间距，可选值为 `xs` `sm` `md` `lg` `xl` 或 `[rowGap, columnGap]` (支持长度单位和简写方式)            | _string \| number \| [string \| number, string \| number]_ | `md`                   |
| wrap      | 是否超出换行                                                                                         | _boolean_                                                  | `false`                |
| block     | 容器使用 flex（false 使用 inline-flex）                                                                                       | _boolean_                                                  | `true`                 |

### 插槽

| 插槽名    | 说明       | 参数 |
| --------- | ---------- | ---- |
| `default` | Space 内容 | `-`  |
| `split`   | 分隔符     | `-`  |

### 类型定义

```ts
import type { SpaceProps, SpaceSize, SpaceDirection, SpaceAlign, SpaceJustify, SpaceInternalSize, SpaceInstance } from '@cedar-design/ui'
```

### 样式变量

| 变量名 | 默认值 |
| --- | --- |
| `--c-space-size-xs-row-gap` | `var(--c-sys-space-2)` |
| `--c-space-size-xs-column-gap` | `var(--c-sys-space-2)` |
| `--c-space-size-sm-row-gap` | `var(--c-sys-space-4)` |
| `--c-space-size-sm-column-gap` | `var(--c-sys-space-3)` |
| `--c-space-size-md-row-gap` | `var(--c-sys-space-5)` |
| `--c-space-size-md-column-gap` | `var(--c-sys-space-4)` |
| `--c-space-size-lg-row-gap` | `var(--c-sys-space-6)` |
| `--c-space-size-lg-column-gap` | `var(--c-sys-space-5)` |
| `--c-space-size-xl-row-gap` | `var(--c-sys-space-8)` |
| `--c-space-size-xl-column-gap` | `var(--c-sys-space-6)` |

## 同源实现与平台边界

两端各自保存完整源码，不引用公共核心，不共享组件实例或响应式状态；修改时同步维护两份实现。主体、Props、子节点展开、主样式、尺寸 token 和配对测试纳入只读一致性检查。仅安装入口与命名空间各自适配。

两端默认均为 `size="md"`、`wrap=false`、`block=true`、`direction="row"`。未传 align 时，row 为 center、column 为 stretch。Maple 原来依赖默认换行的用法请显式添加 `wrap`。

`size` 支持全部五档预设、number（px）、数字字符串（px）、CSS 长度或表达式（例如 1rem、var(--gap)）以及二元组 `[rowGap, columnGap]`。数组始终先行后列，direction 切换不会交换它们；数组项为长度，不支持预设名。预设 [行, 列]：xs=[4,4]、sm=[8,6]、md=[12,8]、lg=[16,12]、xl=[24,16] px，两端一致，仍可通过 CSS 变量覆盖。

---

Document: llms/zh-CN/components/split-button.md

<!-- Source: src/split-button/README.md; locale: zh-CN; page: /components/split-button/ -->

禁用的分段复用 Button 禁用配色并关闭交互反馈；整体禁用同时移除组阴影，仅禁用菜单按钮会阻止菜单打开并关闭非受控的已打开菜单。

# SplitButton 分裂按钮

将一个主操作与一组相关菜单操作组合在同一个按钮组中。

示例统一使用两端都支持的 `Message.info(...)`。默认选择菜单项后关闭；仅“浮层与连续选择”设置 `hide-on-select=false`，保留菜单并显示选择反馈。箭头通过 icon 插槽显示，两段默认继承相同的 variant、status 和自定义颜色，图标布局不改变配色。

两端示例场景及交互逻辑保持一致，分别维护代码副本；仅组件前缀、包名和文档语言接入不同。

## 基础示例

### 基础用法

主按钮执行发布，右侧按钮展开菜单；菜单项提供稳定的 value，并展示无权限的禁用项。

Example source: src/split-button/__demos__/basic.vue

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

const publish = () => {
  Message.info("发布成功");
};
const handleSelect = (_value: unknown, option: { label?: unknown }) => {
  Message.info(String(option.label));
};
</script>

<template>
  <c-split-button
    placement="bottom-end"
    @click="publish"
    @select="handleSelect"
  >
    发布

    <template #content>
      <c-menu-option label="保存草稿" value="draft" />
      <c-menu-option label="保存并发布" value="publish" />
      <c-menu-option label="暂无权限" value="restricted" disabled />
    </template>
  </c-split-button>
</template>
```

## 外观与状态

### 视觉变体

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `variant` | 按钮组变体 | 视觉变体 |
| `disabled` | 是否禁用整个分裂按钮 | 禁用状态 |
| `button-props` | 主按钮属性 | 禁用状态 |
| `trigger-button-props` | 菜单触发按钮属性 | 禁用状态 |
| `placement` | 浮层相对触发元素的首选方位，默认 bottom；启用默认的 auto-fit-position 时，空间不足会自动翻转并约束到可视区域，不保证最终停在该侧 | 外观配置对比 |
<!-- demo-config-notes:end -->

统一展示 default、outline、tonal、text 四种变体。

Example source: src/split-button/__demos__/variants.vue

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

const publish = () => {
  Message.info("发布成功");
};
const handleSelect = (_value: unknown, option: { label?: unknown }) => {
  Message.info(String(option.label));
};
const variants = ["default", "outline", "tonal", "text"] as const;
</script>

<template>
  <c-space wrap>
    <c-split-button
      v-for="variant in variants"
      :key="variant"
      :variant="variant"
      @click="publish"
      @select="handleSelect"
    >
      {{ variant }}

      <template #content>
        <c-menu-option label="保存草稿" value="draft" />
        <c-menu-option label="保存并发布" value="publish" />
        <c-menu-option label="暂无权限" value="restricted" disabled />
      </template>
    </c-split-button>
  </c-space>
</template>
```

### 禁用状态

对比整体禁用、仅主按钮禁用、仅菜单按钮禁用。整体 disabled 优先，子按钮的 disabled: false 不能解除整体禁用。

Example source: src/split-button/__demos__/disabled.vue

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

const publish = () => {
  Message.info("发布成功");
};
const handleSelect = (_value: unknown, option: { label?: unknown }) => {
  Message.info(String(option.label));
};
</script>

<template>
  <c-space wrap>
    <c-split-button
      disabled
      :button-props="{ disabled: false }"
      :trigger-button-props="{ disabled: false }"
      @click="publish"
      @select="handleSelect"
    >
      整体禁用

      <template #content>
        <c-menu-option label="保存草稿" value="draft" />
        <c-menu-option label="保存并发布" value="publish" />
        <c-menu-option label="暂无权限" value="restricted" disabled />
      </template>
    </c-split-button>
    <c-split-button
      :button-props="{ disabled: true }"
      @click="publish"
      @select="handleSelect"
    >
      仅禁用主按钮

      <template #content>
        <c-menu-option label="保存草稿" value="draft" />
        <c-menu-option label="保存并发布" value="publish" />
        <c-menu-option label="暂无权限" value="restricted" disabled />
      </template>
    </c-split-button>
    <c-split-button
      :trigger-button-props="{ disabled: true }"
      @click="publish"
      @select="handleSelect"
    >
      仅禁用菜单按钮

      <template #content>
        <c-menu-option label="保存草稿" value="draft" />
        <c-menu-option label="保存并发布" value="publish" />
        <c-menu-option label="暂无权限" value="restricted" disabled />
      </template>
    </c-split-button>
  </c-space>
</template>
```

### 外观配置对比

选择一个对比维度后，同屏展示它的全部可选值；其余配置和内容保持一致。可切换其他配置检查组合效果；输入类预览共享一个值。

<details>
<summary>配置说明与使用限制</summary>

#### 五档尺寸

支持 xs、sm、md、lg、xl 五档尺寸，默认 md；窄屏自动换行。

#### 外观组合

适用于主操作和附加菜单。调整状态、尺寸，用相同数据观察变化。内容保持一致，便于比较不同设置的实际效果。

</details>

Example source: src/split-button/__demos__/appearance-lab.vue

```vue
<script setup lang="ts">
import { reactive } from "vue";
import type { ComponentSize, SemanticStatus } from "../../_utils/constant";
import { Message } from "@cedar-design/ui";
const publish = () => {
  Message.info("发布成功");
};
const handleSelect = (_value: unknown, option: { label?: unknown }) => {
  Message.info(String(option.label));
};
const __demoAppearance = reactive<{ status: SemanticStatus; size: ComponentSize }>({
  status: "default",
  size: "md",
});

import { computed as demoComputed, ref as demoRef } from 'vue'

const demoCompareFields = [{"name":"status","values":["default","primary","secondary","tertiary","info","success","warning","danger"]},{"name":"size","values":["xs","sm","md","lg","xl"]}]
const demoCompareAxis = demoRef("status")
const demoComparedOptions = demoComputed(() => demoCompareFields.find(field => field.name === demoCompareAxis.value)?.values ?? [])
</script>
<template>
  <c-space direction="column" align="flex-start" :size="16">
    <c-form layout="vertical">
      <c-form-item layout="vertical" size="sm" label="status">
        <c-select
          v-model="__demoAppearance['status']"
          :clearable="false"
          :options="[
            { label: 'default', value: 'default' },
            { label: 'primary', value: 'primary' },
            { label: 'secondary', value: 'secondary' },
            { label: 'tertiary', value: 'tertiary' },
            { label: 'info', value: 'info' },
            { label: 'success', value: 'success' },
            { label: 'warning', value: 'warning' },
            { label: 'danger', value: 'danger' },
          ]"
          aria-label="status"
        />
      </c-form-item>
      <c-form-item layout="vertical" size="sm" label="size">
        <c-radio-group
          v-model="__demoAppearance['size']"
          aria-label="size"
          :options="[
            { label: 'xs', value: 'xs' },
            { label: 'sm', value: 'sm' },
            { label: 'md', value: 'md' },
            { label: 'lg', value: 'lg' },
            { label: 'xl', value: 'xl' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
    </c-form>
    <p class="demo-config-comparison-hint"><span lang="zh-CN">选择一个对比维度；其他配置和内容保持一致。输入类示例共享同一个值，便于比较外观。</span><span lang="en-US">Compare one dimension while keeping the other settings and content identical. Input specimens share the same value.</span></p>
<c-radio-group v-model="demoCompareAxis" aria-label="Compare configuration" :options="demoCompareFields.map(field => ({ label: field.name, value: field.name }))" />
<div class="demo-config-comparison">
<section v-for="sample in demoComparedOptions" :key="String(sample)">
<p><code>{{ demoCompareAxis }}={{ sample }}</code></p>
<c-split-button
      placement="bottom-end"
      @click="publish"
      @select="handleSelect"
      v-bind="{ ...__demoAppearance, [demoCompareAxis]: sample }"
    >
      发布

      <template #content>
        <c-menu-option label="保存草稿" value="draft" />
        <c-menu-option label="保存并发布" value="publish" />
        <c-menu-option label="暂无权限" value="restricted" disabled />
      </template>
    </c-split-button>
</section>
</div>
  </c-space>
</template>

<style scoped>
.demo-config-comparison { display: grid; grid-template-columns: repeat(auto-fit, minmax(min(100%, 220px), 1fr)); gap: 20px; min-width: 0; max-width: 100%; }
.demo-config-comparison > section { min-width: 0; }
.demo-config-comparison p { margin: 0 0 8px; }
html:not([lang='en-US']) .demo-config-comparison-hint > [lang='en-US'],
html[lang='en-US'] .demo-config-comparison-hint > [lang='zh-CN'] { display: none; }
</style>
```

## 内容与展示

### 浮层与连续选择

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `placement` | 浮层相对触发元素的首选方位，默认 bottom；启用默认的 auto-fit-position 时，空间不足会自动翻转并约束到可视区域，不保证最终停在该侧 | 浮层与连续选择 |
| `offset-y` | 屏幕垂直偏移，数字为 px，字符串按长度转换 | 浮层与连续选择 |
| `popup-max-height` | 菜单最大高度 | 浮层与连续选择 |
| `hide-on-select` | 选择菜单项后是否关闭菜单 | 浮层与连续选择 |
<!-- demo-config-notes:end -->

演示 bottom-start、8px 纵向偏移和 160px 最大高度。hide-on-select=false 支持连续选择，页面显示最近选中的 value。

Example source: src/split-button/__demos__/popup.vue

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

const lastAction = ref("");
const handleSelect = (value: unknown, option: { label?: unknown }) => {
  lastAction.value = String(value);
  Message.info(String(option.label));
};
</script>

<template>
  <c-space direction="column" align="flex-start">
    <c-split-button
      placement="bottom-start"
      :offset-y="8"
      :popup-max-height="160"
      :hide-on-select="false"
      @click="lastAction = 'publish'"
      @select="handleSelect"
    >
      选择操作
      <template #content>
        <c-menu-option label="保存草稿" value="draft" />
        <c-menu-option label="保存并发布" value="publish" />
        <c-menu-option label="暂无权限" value="restricted" disabled />
      </template>
    </c-split-button>
    <span aria-live="polite">最近操作: {{ lastAction || "暂无操作" }}</span>
    <span>选择后菜单保持展开，可连续选择；点击外部关闭。</span>
  </c-space>
</template>
```

## 自定义与插槽

### 自定义图标

使用 icon 插槽中的 open 状态旋转箭头，两端使用相同图标。

Example source: src/split-button/__demos__/custom-icon.vue

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

const publish = () => {
  Message.info("发布成功");
};
const handleSelect = (_value: unknown, option: { label?: unknown }) => {
  Message.info(String(option.label));
};
</script>

<template>
  <c-split-button @click="publish" @select="handleSelect">
    发布
    <template #icon="{ open }">
      <c-icon-menu-down
        :style="{
          transform: open ? 'rotate(180deg)' : undefined,
          transition: 'transform 0.2s',
        }"
      />
    </template>
    <template #content>
      <c-menu-option label="保存草稿" value="draft" />
      <c-menu-option label="保存并发布" value="publish" />
      <c-menu-option label="暂无权限" value="restricted" disabled />
    </template>
  </c-split-button>
</template>
```

## 交互与控制

### 受控展开

外部控制按钮使用 `@click.stop`，避免同一次点击冒泡到 document 后被判定为菜单外部点击。菜单触发器及正常的点击外部关闭逻辑不受影响。

使用 v-model:open 双向控制菜单；外部按钮、菜单触发器和选中关闭会同步更新状态。

Example source: src/split-button/__demos__/controlled.vue

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

const publish = () => {
  Message.info("发布成功");
};
const handleSelect = (_value: unknown, option: { label?: unknown }) => {
  Message.info(String(option.label));
};
const open = ref(false);
</script>

<template>
  <c-space direction="column" align="flex-start">
    <c-space wrap>
      <c-button @click.stop="open = true">展开菜单</c-button>
      <c-button @click.stop="open = false">关闭菜单</c-button>
    </c-space>
    <c-split-button v-model:open="open" @click="publish" @select="handleSelect">
      发布

      <template #content>
        <c-menu-option label="保存草稿" value="draft" />
        <c-menu-option label="保存并发布" value="publish" />
        <c-menu-option label="暂无权限" value="restricted" disabled />
      </template>
    </c-split-button>
    <span aria-live="polite">{{ open ? "已展开" : "已关闭" }}</span>
  </c-space>
</template>
```

## 异步与动态数据

### 异步操作

click 是普通事件通知，支持 async 回调；loading 由业务状态控制，建议在 finally 中恢复。事件监听器的 Promise 不会自动驱动加载。禁用／加载链接移除有效 href。

Example source: src/split-button/__demos__/async-action.vue

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

const completed = ref(0);
const publishing = ref(false)
const publish = async () => {
  if (publishing.value) return
  publishing.value = true
  try {
    await new Promise<void>((resolve) => setTimeout(resolve, 800))
    completed.value += 1
    Message.info('发布成功 / Published')
  } finally { publishing.value = false }
}
const handleSelect = (_value: unknown, option: { label?: unknown }) => {
  Message.info(String(option.label));
};
</script>

<template>
  <c-space direction="column" align="flex-start">
    <c-split-button :button-props="{ loading: publishing }" @click="publish" @select="handleSelect">
      发布

      <template #content>
        <c-menu-option label="保存草稿" value="draft" />
        <c-menu-option label="保存并发布" value="publish" />
        <c-menu-option label="暂无权限" value="restricted" disabled />
      </template>
    </c-split-button>
    <span aria-live="polite">完成次数: {{ completed }}</span>
  </c-space>
</template>
```

## 阅读方向

主按钮位于阅读起点，菜单按钮位于阅读终点；LTR/RTL 切换不交换业务动作或额外触发选择。Enter/Space 保留原生按钮行为，菜单按钮支持上下键打开菜单并跳过禁用项，Home/End 定位首尾，Enter 选择，Escape 关闭并归还焦点。弹层继承触发按钮来源方向，start/end 对齐随方向变化，显式 left/right 保持物理侧。自定义向下图形不额外镜像。

## API

### `<split-button>` Props

| 参数名               | 描述                                      | 类型                                             |  默认值   |
| -------------------- | ----------------------------------------- | ------------------------------------------------ | :-------: |
| open **(v-model)**   | 菜单是否打开                              | `boolean`                                        |    `-`    |
| default-open         | 菜单默认是否打开（非受控模式）            | `boolean`                                        |  `false`  |
| disabled             | 是否禁用整个分裂按钮                      | `boolean`                                        |  `false`  |
| status               | 按钮组主题色                              | `SemanticStatus`                                 | `default` |
| variant              | 按钮组变体                                | `ButtonVariant`                                  | `default` |
| size                 | 按钮组尺寸                                | `ComponentSize`                                  |   `md`    |
| color                | 自定义背景色                              | `string`                                         |   `''`    |
| text-color           | 自定义文字色                              | `string`                                         |   `''`    |
| elevation            | 按钮组海拔阴影                            | `boolean \| number`                              |  `true`   |
| button-props         | 主按钮属性                                | `Partial<ButtonProps>`                           |    `-`    |
| trigger-button-props | 菜单触发按钮属性                          | `Partial<ButtonProps>`                           |    `-`    |
| trigger              | 菜单触发方式                              | `'hover' \| 'click' \| 'focus' \| 'contextMenu'` |  `click`  |
| placement            | 浮层相对触发元素的首选方位，默认 bottom；启用默认的 auto-fit-position 时，空间不足会自动翻转并约束到可视区域，不保证最终停在该侧 | `MenuPlacement`（标准十二方位）           | `bottom`  |
| popup-container      | 菜单挂载容器                              | `PopupContainer`                                 |    `-`    |
| popup-max-height     | 菜单最大高度                              | `boolean \| number`                              |  `true`   |
| popup-class          | 菜单浮层类名                              | `string \| array \| object`                      |    `-`    |
| offset-x             | 屏幕水平偏移，数字为 px，字符串按长度转换 | `string \| number`                               |    `0`    |
| offset-y             | 屏幕垂直偏移，数字为 px，字符串按长度转换 | `string \| number`                               |    `0`    |
| hide-on-select       | 选择菜单项后是否关闭菜单                  | `boolean`                                        |  `true`   |

### `<split-button>` Events

| 事件名      | 描述                       | 参数                 |
| ----------- | -------------------------- | -------------------- |
| update:open | 菜单打开状态请求更新时触发 | open: `boolean`      |
| open-change | 菜单打开状态变化时触发     | open: `boolean`      |
| click       | 点击主按钮时触发           | event: `MouseEvent`  |
| select      | 选择菜单项时触发           | value, option, event |

### `<split-button>` Slots

| 插槽名  | 描述             | 参数            |
| ------- | ---------------- | --------------- |
| default | 主按钮内容       | -               |
| icon    | 菜单触发按钮图标 | open: `boolean` |
| content | 菜单内容         | -               |

### 实例方法

| 方法     | 说明                       |
| -------- | -------------------------- |
| open()   | 请求展开菜单；禁用时不展开 |
| close()  | 请求关闭菜单               |
| resize() | 重新计算菜单位置           |

受控 `open` 只发出更新请求，需由调用方更新。主按钮点击正常冒泡，不打开菜单。

`click` 与 Button 一样是普通事件通知；不会等待监听器的返回值。异步操作由业务通过 `button-props.loading` 控制主按钮加载。

两端主体、Props、样式依赖入口及契约测试独立同源复制；Cedar 菜单定位由 Menu 适配，不共享实例或运行时。

## 类型定义

```ts
import type { SplitButtonInstance, SplitButtonProps } from '@cedar-design/ui'
```


### 方位语义与配置入口

菜单方位通过内部 Menu 的 placement 传递给 Trigger，使用 MenuPlacement 类型，不新增第二个定位入口。

---

Document: llms/zh-CN/components/split.md

<!-- Source: src/split/README.md; locale: zh-CN; page: /components/split/ -->

# Split

将面板分割成两部分。

## 基础示例

### 基础用法

将一个面板分割成两个可以调整宽度或高度的两部分。用`orientation`控制分割方向。

Example source: src/split/__demos__/basic.vue

```vue
<template>
  <div>
    <c-split
      :style="{
        height: '200px',
        width: '100%',
        minWidth: '500px',
        border: '1px solid var(--c-color-border-2)',
      }"
      v-model:size="size"
      min="80px"
    >
      <template #first>
        <c-typography-paragraph>Left</c-typography-paragraph>
      </template>
      <template #second>
        <c-typography-paragraph>Right</c-typography-paragraph>
      </template>
    </c-split>
  </div>
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const size = ref(0.5)
</script>
```

## 布局与排列

### 面板分割嵌套

面板分割可以嵌套使用。

Example source: src/split/__demos__/nested.vue

```vue
<template>
  <div>
    <c-split
      :style="{
        height: '200px',
        width: '100%',
        minWidth: '500px',
        border: '1px solid var(--color-border)',
      }"
    >
      <template #first>
        <c-typography-paragraph>Left</c-typography-paragraph>
      </template>
      <template #second>
        <div>
          <c-split orientation="vertical" :style="{ height: '200px' }">
            <template #first>
              <c-typography-paragraph>Top</c-typography-paragraph>
            </template>
            <template #second>
              <c-typography-paragraph>Bottom</c-typography-paragraph>
            </template>
          </c-split>
        </div>
      </template>
    </c-split>
  </div>
</template>

<script lang="ts" setup>
</script>
```

## API

### `<split>` Props

| 参数名             | 描述                                                              | 类型                         |     默认值     |
| ------------------ | ----------------------------------------------------------------- | ---------------------------- | :------------: |
| component          | 分割框的 html 标签                                                | `string`                     |    `'div'`     |
| orientation          | 两个面板的排列轴向，默认 horizontal 表示左右面板；此时分割手柄自身为竖直 | `'horizontal' \| 'vertical'` | `'horizontal'` |
| size **(v-model)** | 分割的大小，可以是 0~1 代表百分比，或具体数值的像素，如 300px     | `number\|string`             |      `-`       |
| default-size       | 默认分割的大小，可以是 0~1 代表百分比，或具体数值的像素，如 300px | `number\|string`             |     `0.5`      |
| min                | 最小阈值，可以是 0~1 代表百分比，或具体数值的像素，如 300px       | `number\|string`             |      `-`       |
| max                | 最大阈值，可以是 0~1 代表百分比，或具体数值的像素，如 300px       | `number\|string`             |      `-`       |
| disabled           | 是否禁用                                                          | `boolean`                    |    `false`     |

### `<split>` Events

| 事件名     | 描述             | 参数 |
| ---------- | ---------------- | ---- |
| move-start | 开始拖拽之前触发 | -    |
| moving     | 拖拽时触发       | -    |
| move-end   | 拖拽结束之后触发 | -    |

### `<split>` Slots

| 插槽名              |       描述       | 参数 |
| ------------------- | :--------------: | ---- |
| first               | 第一个面板的内容 | -    |
| resize-trigger      |   伸缩杆的内容   | -    |
| resize-trigger-icon |   伸缩杆的图标   | -    |
| second              | 第二个面板的内容 | -    |

### 类型定义

组件导出以下类型定义

```ts
import type { SplitInstance } from '@cedar-design/ui'
```

`--c-split-trigger-size-icon-wrapper`（默认6px）控制分隔手柄粗细：竖直手柄为宽度，水平手柄为高度；不改变沿面板方向的100%长度。


## 阅读方向与交互

Split 继承最近的原生 `dir`，横向第一个面板位于阅读起点。`size/defaultSize/min/max` 始终描述第一个面板，RTL 不会将尺寸变成 `1-size`，数字比例与 px 字符串保持原有单位。

横向 RTL 拖动时向左增大第一个面板；纵向仍向下增大。分隔条可聚焦，左右键按屏幕方向移动，纵向使用上下键，步长 10px，Shift 为 50px；Home/End 到达最小/最大边界。鼠标、触摸指针共用同一尺寸计算。切换方向、朝向、禁用或卸载会取消进行中的拖动并恢复原来的光标。方向切换本身不触发尺寸更新。

---

Document: llms/zh-CN/components/statistic.md

<!-- Source: src/statistic/README.md; locale: zh-CN; page: /components/statistic/ -->

# Statistic 统计数值

突出展示某个或某组数字、带描述的统计类数据。

## 基础示例

### 基础用法

通过 `title` 展示描述，通过 `value` 展示数值。`value` 支持数字或字符串。

Example source: src/statistic/__demos__/basic.vue

```vue
<template>
  <c-space size="xl" wrap>
    <c-statistic title="Downloads" :value="125670" show-group-separator />
    <c-statistic title="Comments" extra="Compared to yesterday" :value="40509" :precision="2" />
    <c-statistic title="Active Users" value="1.28k" />
  </c-space>
</template>
```

## 内容与展示

### 等宽数字

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `title` | 数值展示的标题 | 等宽数字、额外信息、数值动画 |
| `value` | 数值展示的值 | 等宽数字、额外信息、数值动画 |
| `suffix` | 数值后缀 | 等宽数字 |
| `value-style` | 自定义显示值的样式 | 等宽数字 |
| `tabular-nums` | 是否使用等宽数字，避免数值变化时宽度跳动 | 等宽数字 |
| `prefix` | 数值前缀 | 额外信息 |
<!-- demo-config-notes:end -->

开启 `tabular-nums` 后，每个数字字符占用相同宽度，适合数值频繁变化或纵向对齐的场景。下面的数值始终保持四位，请观察右侧竖线：比例数字切换时竖线会左右跳动，等宽数字的竖线则保持稳定。

Example source: src/statistic/__demos__/tabular-nums.vue

```vue
<template>
  <c-space size="xl" wrap>
    <c-statistic
      title="比例数字（右侧标记会跳动）"
      :value="count"
      suffix="|"
      :value-style="{ fontVariantNumeric: 'proportional-nums' }"
    />
    <c-statistic title="等宽数字（右侧标记保持稳定）" :value="count" suffix="|" tabular-nums />
  </c-space>
</template>

<script lang="ts" setup>
import { onBeforeUnmount, onMounted, ref } from 'vue'

const values = [1111, 8888, 1010, 9090]
const index = ref(0)
const count = ref(values[0])
let timer = 0

onMounted(() => {
  timer = window.setInterval(() => {
    index.value = (index.value + 1) % values.length
    count.value = values[index.value]
  }, 800)
})

onBeforeUnmount(() => {
  window.clearInterval(timer)
})
</script>
```

### 额外信息

通过 `extra` 或 `extra` 插槽在数值下方展示补充说明。

Example source: src/statistic/__demos__/extra.vue

```vue
<template>
  <c-space size="xl" wrap>
    <c-statistic title="Revenue" :value="9280" prefix="$" show-group-separator extra="Compared to yesterday +12.8%" />
    <c-statistic title="New Users" :value="1280" show-group-separator>
      <template #extra>
        <span style="color: var(--c-color-success)">较上周 +8.4%</span>
      </template>
    </c-statistic>
  </c-space>
</template>
```

### 数值动画

通过 `animation` 开启数值滚动动画，可用 `start` 控制播放时机。

本例 Start 将父级 `start` 从 `false` 改为 `true`，从 `value-from` 播放到目标值；重复点击不会重播。`start=false` 暂停，随后切回 `true` 会从 `value-from` 重新播放，不是从暂停位置继续。需要可重播按钮时，由父级先设为 `false`，等待一次 Vue 更新后再设为 `true`。

Example source: src/statistic/__demos__/animation.vue

```vue
<template>
  <c-space size="xl" align="flex-end" wrap>
    <c-statistic
      title="Growth Rate"
      :value="50.52"
      :precision="2"
      :value-from="0"
      :start="started"
      animation
    >
      <template #prefix>
        <IconArrowRise />
      </template>
      <template #suffix>%</template>
    </c-statistic>
    <c-button status="primary" @click="started = true">Start</c-button>
  </c-space>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import { IconArrowRise } from '@cedar-design/icons-vue'

const started = ref(false)
</script>
```

### 倒计时

`Countdown` 是独立组件，模板中使用 `<c-countdown>`。完整用法见 [Countdown 倒计时](llms/zh-CN/components/countdown.md)。

Example source: src/countdown/__demos__/statistic.vue

```vue
<template>
  <c-space size="xl" wrap>
    <c-statistic title="Countdown">
      <c-countdown :time="2 * 60 * 60 * 1000" />
    </c-statistic>
    <c-statistic title="Campaign">
      <c-countdown :time="4 * 24 * 60 * 60 * 1000" format="DD 天 HH 时 mm 分 ss 秒" />
    </c-statistic>
  </c-space>
</template>
```

## 自定义与插槽

### 前缀 / 后缀

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `title` | 数值展示的标题 | 前缀 / 后缀、自定义数值 |
| `suffix` | 数值后缀 | 前缀 / 后缀、自定义数值 |
| `value` | 数值展示的值 | 前缀 / 后缀 |
| `prefix` | 数值前缀 | 前缀 / 后缀 |
| `show-group-separator` | 是否展示进位分隔符（数字模式使用） | 前缀 / 后缀 |
| `precision` | 小数保留位数（数字模式使用） | 前缀 / 后缀 |
<!-- demo-config-notes:end -->

通过 `prefix` / `suffix` 或同名插槽为数值添加单位、货币符号或趋势图标。

Example source: src/statistic/__demos__/prefix-suffix.vue

```vue
<template>
  <c-space size="xl" wrap>
    <c-statistic title="Account Balance" :value="125670" prefix="$" show-group-separator />
    <c-statistic title="Growth Rate" :value="12.8" :precision="1" suffix="%" :value-style="{ color: 'var(--c-color-success)' }">
      <template #prefix>
        <IconArrowRise />
      </template>
    </c-statistic>
    <c-statistic title="Bounce Rate" :value="3.2" :precision="1" suffix="%" :value-style="{ color: 'var(--c-color-danger)' }">
      <template #prefix>
        <IconArrowFall />
      </template>
    </c-statistic>
  </c-space>
</template>

<script lang="ts" setup>
import { IconArrowFall, IconArrowRise } from '@cedar-design/icons-vue'
</script>
```

### 自定义数值

未传入 `value` 时，可用默认插槽自定义数值内容。例如嵌入 `CountTo` 实现滚动数字。

Example source: src/statistic/__demos__/count-to.vue

```vue
<template>
  <c-space size="xl" wrap>
    <c-statistic title="Active Users">
      <c-count-to :from="0" :to="125670" :duration="2000" />
    </c-statistic>
    <c-statistic title="Conversion Rate" suffix="%">
      <c-count-to :from="0" :to="36.8" :duration="2000" :precision="1" />
    </c-statistic>
  </c-space>
</template>
```

## API

### `<Statistic>` Props

| 属性                   | 说明                                                           | 类型                      | 默认值       |
| ---------------------- | -------------------------------------------------------------- | ------------------------- | ------------ |
| `title`                | 数值展示的标题                                                 | `string`                  | -            |
| `value`                | 数值展示的值                                                   | `number \| string \| Date` | -            |
| `prefix`               | 数值前缀                                                       | `string`                  | -            |
| `suffix`               | 数值后缀                                                       | `string`                  | -            |
| `format`               | 数值展示的格式（日期模式使用）                                 | `string`                  | `'HH:mm:ss'` |
| `extra`                | 额外的显示内容                                                 | `string`                  | -            |
| `start`                | 是否开始动画                                                   | `boolean`                 | `true`       |
| `precision`            | 小数保留位数（数字模式使用）                                   | `number`                  | `0`          |
| `separator`            | 进位分隔符（数字模式使用）                                     | `string`                  | -            |
| `show-group-separator` | 是否展示进位分隔符（数字模式使用）                             | `boolean`                 | `false`      |
| `tabular-nums`         | 是否使用等宽数字，避免数值变化时宽度跳动                       | `boolean`                 | `false`      |
| `animation`            | 是否开启动画                                                   | `boolean`                 | `false`      |
| `animation-duration`   | 动画的过渡时间                                                 | `number`                  | `2000`       |
| `value-from`           | 动画的起始值                                                   | `number`                  | -            |
| `placeholder`          | 提示文字（当 `value` 为 `undefined` 且未使用默认插槽时显示）   | `string`                  | -            |
| `value-style`          | 自定义显示值的样式                                             | `CSSProperties`           | -            |

### `<Statistic>` Slots

| 插槽名    | 说明                                     | 参数 |
| --------- | ---------------------------------------- | ---- |
| `default` | 自定义数值内容，未传入 `value` 时生效    | `-`  |
| `title`   | 标题                                     | `-`  |
| `prefix`  | 前缀                                     | `-`  |
| `suffix`  | 后缀                                     | `-`  |
| `extra`   | 额外内容                                 | `-`  |

### 类型定义

组件导出以下类型定义

```ts
import type { StatisticProps } from '@cedar-design/ui'
```

### 样式变量

| 变量名 | 默认值 |
| --- | --- |
| `--c-statistic-title-color` | `var(--c-sys-color-content-secondary)` |
| `--c-statistic-title-font-size` | `var(--c-font-size-body-3)` |
| `--c-statistic-title-margin-bottom` | `var(--c-spacing-4)` |
| `--c-statistic-value-color` | `var(--c-sys-color-content-primary)` |
| `--c-statistic-value-font-size` | `26px` |
| `--c-statistic-value-font-weight` | `var(--c-font-weight-500)` |
| `--c-statistic-decimal-font-size` | `inherit` |
| `--c-statistic-prefix-color` | `var(--c-sys-color-content-secondary)` |
| `--c-statistic-prefix-font-size` | `14px` |
| `--c-statistic-prefix-spacing` | `var(--c-spacing-1)` |
| `--c-statistic-suffix-color` | `var(--c-sys-color-content-secondary)` |
| `--c-statistic-suffix-font-size` | `14px` |
| `--c-statistic-suffix-spacing` | `var(--c-spacing-1)` |
| `--c-statistic-extra-color` | `var(--c-sys-color-content-secondary)` |
| `--c-statistic-extra-font-size` | `var(--c-font-size-body-3)` |
| `--c-statistic-extra-margin-top` | `var(--c-spacing-4)` |

## 同源实现与平台边界

两端各自保存完整源码，不引用公共核心，不共享组件实例或响应式状态；修改时同步维护两份实现。主体、Props、关键样式及配对测试纳入只读源码一致性检查，主题 token 和安装入口各自维护。

默认插槽动态出现/消失时同步切换占位文字；动画在卸载及 KeepAlive 停用时暂停。

---

Document: llms/zh-CN/components/steps.md

<!-- Source: src/steps/README.md; locale: zh-CN; page: /components/steps/ -->

# Steps

明示任务流程和当前完成程度，引导用户按照步骤完成任务。

## 基础示例

### 基础用法

基础用法。

Example source: src/steps/__demos__/basic.vue

```vue
<template>
  <c-radio-group v-model="currentStatus" variant="button" style="margin-bottom: 16px">
    <c-radio v-for="status in statuses" :key="status" :value="status">{{ status }}</c-radio>
  </c-radio-group>
  <c-steps :status="currentStatus">
    <c-step description="This is a description">Succeeded</c-step>
    <c-step description="This is a description">Processing</c-step>
    <c-step description="This is a description">Pending</c-step>
  </c-steps>
</template>
<script setup lang="ts">
import { ref } from 'vue'

const statuses = ['wait', 'process', 'finish', 'error'] as const
const currentStatus = ref<(typeof statuses)[number]>('process')
</script>
```

## 外观与状态

### 外观组合

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `type` | 步骤条的类型 | 类型与状态对比 |
| `status` | 当前步骤状态 | 类型与状态对比 |
| `changeable` | 是否可以点击切换步骤 | 类型与状态对比 |
<!-- demo-config-notes:end -->

适用于多步骤流程的当前状态。调整状态、尺寸，用相同数据观察变化。内容保持一致，便于比较不同设置的实际效果。

Example source: src/steps/__demos__/appearance-lab.vue

```vue
<script setup lang="ts">
import { reactive as __demoReactive } from "vue";
const __demoAppearance = __demoReactive({ status: "wait", size: "md" });

import { computed as demoComputed, ref as demoRef } from 'vue'
const demoCompareFields = [{"name":"status","values":["wait","process","finish","error"]},{"name":"size","values":["sm","md"]}]
const demoCompareAxis = demoRef("status")
const demoComparedOptions = demoComputed(() => demoCompareFields.find(field => field.name === demoCompareAxis.value)?.values ?? [])
</script>
<template>
  <c-space direction="column" :size="16">
    <c-form layout="vertical">
      <c-form-item layout="vertical" size="sm" label="status">
        <c-radio-group
          v-model="__demoAppearance['status']"
          aria-label="status"
          :options="[
            { label: 'wait', value: 'wait' },
            { label: 'process', value: 'process' },
            { label: 'finish', value: 'finish' },
            { label: 'error', value: 'error' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
      <c-form-item layout="vertical" size="sm" label="size">
        <c-radio-group
          v-model="__demoAppearance['size']"
          aria-label="size"
          :options="[
            { label: 'sm', value: 'sm' },
            { label: 'md', value: 'md' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
    </c-form>
    <p class="demo-config-comparison-hint"><span lang="zh-CN">选择一个对比维度；其他配置和内容保持一致。输入类示例共享同一个值，便于比较外观。</span><span lang="en-US">Compare one dimension while keeping the other settings and content identical. Input specimens share the same value.</span></p>
<c-radio-group v-model="demoCompareAxis" aria-label="Compare configuration" :options="demoCompareFields.map(field => ({ label: field.name, value: field.name }))" />
<div class="demo-config-comparison">
<section v-for="sample in demoComparedOptions" :key="String(sample)">
<p><code>{{ demoCompareAxis }}={{ sample }}</code></p>
<c-steps :model-value="2" v-bind="{ ...__demoAppearance, [demoCompareAxis]: sample }">
      <c-step>Succeeded</c-step>
      <c-step>Processing</c-step>
      <c-step>Pending</c-step>
    </c-steps>
</section>
</div>
  </c-space>
</template>

<style scoped>
.demo-config-comparison { display: grid; grid-template-columns: repeat(auto-fit, minmax(min(100%, 220px), 1fr)); gap: 20px; min-width: 0; max-width: 100%; }
.demo-config-comparison > section { min-width: 0; }
.demo-config-comparison p { margin: 0 0 8px; }
html:not([lang='en-US']) .demo-config-comparison-hint > [lang='en-US'],
html[lang='en-US'] .demo-config-comparison-hint > [lang='zh-CN'] { display: none; }
</style>
```

### 类型与状态对比

四种类型共享当前步骤和状态。先点击步骤或选择 1–3，再切换 wait、process、finish、error，观察 default、arrow、dot、navigation 同步更新；status 改变当前节点的语义状态，不改变步骤序号。标题与描述按页面语言显示，方便在手机宽度内对比。

<details>
<summary>配置说明与使用限制</summary>

#### 四种外观类型

`type` 当前有 `default`（编号）、`arrow`（箭头）、`dot`（圆点）、`navigation`（导航）四种外观；`status` 独立表示流程状态。箭头和导航类型仅支持水平方向。切换当前步骤或点击步骤，对比相同进度下的外观。现有 `type` 保持兼容。

#### 步骤错误

通过设置`status="error"`来展示错误状态。

#### 箭头步骤条

通过设置`type="arrow"`，可以使用箭头类型的步骤条，**注意**，仅支持水平步骤条。

#### 点状步骤条

通过设置`type="dot"`，可以使用点状类型的步骤条。此模式没有small尺寸

#### 导航步骤条

通过设置`type="navigation"`，可以使用导航类型的步骤条。

</details>

Example source: src/steps/__demos__/types.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import type { StepsType } from "@cedar-design/ui";

const current = ref(2)
const statuses = ['wait', 'process', 'finish', 'error'] as const
const status = ref<(typeof statuses)[number]>('process')
const types: StepsType[] = ["default", "arrow", "dot", "navigation"];
</script>

<template>
  <section class="step-type-comparison">
    <c-form-item layout="vertical" size="sm" label="Current step">
      <c-radio-group
        v-model="current"
        aria-label="Current step"
        :options="[
          { label: '1', value: 1 },
          { label: '2', value: 2 },
          { label: '3', value: 3 },
        ]"
        variant="button"
        size="sm"
      />
    </c-form-item>
    <c-form-item layout="vertical" size="sm" label="Status"><c-radio-group v-model="status" aria-label="Step status" :options="statuses.map(value => ({ label: value, value }))" /></c-form-item>
    <p>
      点击步骤或选择序号，对比同一进度的四种外观。Click a step to compare the
      same progress.
    </p>
    <section v-for="type in types" :key="type" :data-step-type="type">
      <p>
        <code>{{ type }}</code>
      </p>
      <c-steps v-model="current" :type="type" :status="status" changeable>
        <c-step><span lang="zh-CN">提交</span><span lang="en-US">Submit</span><template #description><span lang="zh-CN">提交信息</span><span lang="en-US">Details</span></template></c-step>
        <c-step><span lang="zh-CN">审核</span><span lang="en-US">Review</span><template #description><span lang="zh-CN">审核信息</span><span lang="en-US">Review</span></template></c-step>
        <c-step><span lang="zh-CN">完成</span><span lang="en-US">Done</span><template #description><span lang="zh-CN">完成信息</span><span lang="en-US">Complete</span></template></c-step>
      </c-steps>
    </section>
  </section>
</template>

<style scoped>
html:not([lang='en-US']) .step-type-comparison [lang='en-US'],
html[lang='en-US'] .step-type-comparison [lang='zh-CN'] { display: none; }
</style>
```

## 布局与排列

### 内容放置位置

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `status` | 当前步骤状态 | 内容放置位置、竖直步骤条 |
| `content-placement` | 正文相对步骤节点的方位，可选 right 或 bottom，默认 right；dot 类型按横纵轴推导，navigation 固定 right | 内容放置位置 |
| `orientation` | 步骤流程的横纵轴向，默认 horizontal；arrow 和 navigation 类型固定横向 | 竖直步骤条 |
<!-- demo-config-notes:end -->

通过设置 `content-placement` 可以改变内容相对节点的位置，可选 `right`（默认）和 `bottom`。

Example source: src/steps/__demos__/content-placement.vue

```vue
<template>
  <c-radio-group v-model="currentStatus" variant="button" style="margin-bottom: 16px">
    <c-radio v-for="status in statuses" :key="status" :value="status">{{ status }}</c-radio>
  </c-radio-group>
  <c-steps content-placement="bottom" :status="currentStatus">
    <c-step description="This is a description">Succeeded</c-step>
    <c-step description="This is a description">Processing</c-step>
    <c-step description="This is a description">Pending</c-step>
  </c-steps>
</template>
<script setup lang="ts">
import { ref } from 'vue'

const statuses = ['wait', 'process', 'finish', 'error'] as const
const currentStatus = ref<(typeof statuses)[number]>('process')
</script>
```

### 竖直步骤条

竖直方向的步骤条。

Example source: src/steps/__demos__/vertical.vue

```vue
<template>
  <div class="frame-bg">
    <c-radio-group v-model="currentStatus" variant="button" style="margin-bottom: 16px">
      <c-radio v-for="status in statuses" :key="status" :value="status">{{ status }}</c-radio>
    </c-radio-group>
    <div class="frame-body">
      <div class="frame-aside">
        <c-steps :model-value="current" :status="currentStatus" orientation="vertical">
          <c-step>Succeeded</c-step>
          <c-step>Processing</c-step>
          <c-step>Pending</c-step>
        </c-steps>
      </div>
      <div class="frame-main">
        <div class="main-content">The content of this step.</div>
        <div class="main-bottom">
          <c-button :disabled="current === 1" @click="onPrev">
            <c-icon-left />
            Back
          </c-button>
          <c-button :disabled="current === 3" @click="onNext">
            Next
            <c-icon-right />
          </c-button>
        </div>
      </div>
    </div>
  </div>
</template>
<script lang="ts">
import { ref } from 'vue'

export default {
  setup() {
    const current = ref(1)
    const statuses = ['wait', 'process', 'finish', 'error'] as const
    const currentStatus = ref<(typeof statuses)[number]>('process')

    const onPrev = () => {
      current.value = Math.max(1, current.value - 1)
    }

    const onNext = () => {
      current.value = Math.min(3, current.value + 1)
    }

    return {
      current,
      statuses,
      currentStatus,
      onPrev,
      onNext,
    }
  },
}
</script>
```

## 内容与展示

### 描述信息

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `status` | 当前步骤状态 | 描述信息、隐藏连接线 |
| `show-line` | 是否显示连接线 | 隐藏连接线 |
<!-- demo-config-notes:end -->

通过设置 `description` 属性，可以在每个步骤下方添加描述信息。

Example source: src/steps/__demos__/description.vue

```vue
<template>
  <c-radio-group
    v-model="currentStatus"
    variant="button"
    style="margin-bottom: 16px"
  >
    <c-radio v-for="status in statuses" :key="status" :value="status">{{
      status
    }}</c-radio>
  </c-radio-group>
  <c-steps :model-value="2" :status="currentStatus">
    <c-step>Succeeded</c-step>
    <c-step>Processing</c-step>
    <c-step>Pending</c-step>
  </c-steps>
  <c-divider />
  <div style="line-height: 140px; color: #c9cdd4; text-align: center">
    Step 2 Content
  </div>
</template>
<script setup lang="ts">
import { ref } from "vue";

const statuses = ["wait", "process", "finish", "error"] as const;
const currentStatus = ref<(typeof statuses)[number]>("process");
</script>
```

### 隐藏连接线

通过设置`show-line="false"`可以使用无连接线模式。

Example source: src/steps/__demos__/line-less.vue

```vue
<template>
  <c-radio-group v-model="currentStatus" variant="button" style="margin-bottom: 16px">
    <c-radio v-for="status in statuses" :key="status" :value="status">{{ status }}</c-radio>
  </c-radio-group>
  <c-steps :model-value="2" :status="currentStatus" :show-line="false">
    <c-step description="This is a description">Succeeded</c-step>
    <c-step description="This is a description">Processing</c-step>
    <c-step description="This is a description">Pending</c-step>
  </c-steps>
</template>
<script setup lang="ts">
import { ref } from 'vue'

const statuses = ['wait', 'process', 'finish', 'error'] as const
const currentStatus = ref<(typeof statuses)[number]>('process')
</script>
```

## 自定义与插槽

### 自定义图标

通过`#icon`插槽可以自定义节点图标

Example source: src/steps/__demos__/custom-icon.vue

```vue
<template>
  <c-radio-group v-model="currentStatus" variant="button" style="margin-bottom: 16px">
    <c-radio v-for="status in statuses" :key="status" :value="status">{{ status }}</c-radio>
  </c-radio-group>
  <c-steps :status="currentStatus">
    <c-step description="This is a description">
      Succeeded
      <template #icon>
        <c-icon-home />
      </template>
    </c-step>
    <c-step description="This is a description">
      Processing
      <template #icon>
        <c-icon-loading />
      </template>
    </c-step>
    <c-step description="This is a description">
      Pending
      <template #icon>
        <c-icon-thumb-up />
      </template>
    </c-step>
  </c-steps>
</template>
<script setup lang="ts">
import { ref } from 'vue'

const statuses = ['wait', 'process', 'finish', 'error'] as const
const currentStatus = ref<(typeof statuses)[number]>('process')
</script>
```

## 交互与控制

### 可切换步骤条

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `changeable` | 是否可以点击切换步骤 | 可切换步骤条 |
| `status` | 当前步骤状态 | 可切换步骤条 |
<!-- demo-config-notes:end -->

设置`changeable`开启点击切换步骤。

Example source: src/steps/__demos__/changeable.vue

```vue
<template>
  <div>
    <c-radio-group v-model="currentStatus" variant="button" style="margin-bottom: 16px">
      <c-radio v-for="status in statuses" :key="status" :value="status">{{ status }}</c-radio>
    </c-radio-group>
    <c-steps changeable :model-value="current" :status="currentStatus" @change="setCurrent">
      <c-step description="This is a description">Succeeded</c-step>
      <c-step description="This is a description">Processing</c-step>
      <c-step description="This is a description">Pending</c-step>
    </c-steps>
    <div
      :style="{
        width: '100%',
        height: '200px',
        textAlign: 'center',
        background: 'var(--color-bg-2)',
        color: '#C2C7CC',
      }"
    >
      <div style="line-height: 160px">Step{{ current }} Content</div>
      <c-space size="lg">
        <c-button status="secondary" :disabled="current <= 1" @click="onPrev">
          <c-icon-left />
          Back
        </c-button>
        <c-button status="primary" :disabled="current >= 3" @click="onNext">
          Next
          <c-icon-right />
        </c-button>
      </c-space>
    </div>
  </div>
</template>
<script lang="ts">
import { ref } from 'vue'

export default {
  setup() {
    const current = ref(1)
    const statuses = ['wait', 'process', 'finish', 'error'] as const
    const currentStatus = ref<(typeof statuses)[number]>('process')
    const onPrev = () => {
      current.value = Math.max(1, current.value - 1)
    }
    const onNext = () => {
      current.value = Math.min(3, current.value + 1)
    }

    const setCurrent = (step: number) => {
      current.value = step
    }

    return {
      current,
      statuses,
      currentStatus,
      onPrev,
      onNext,
      setCurrent,
    }
  },
}
</script>
```

## API

主值使用普通 `v-model`：`modelValue` 表示当前步骤序号，从 1 开始。`defaultValue` 仅在创建时初始化非受控状态，之后修改不会重置当前值；初始化不触发 `update:modelValue`。提供 `modelValue` 时由父级控制，以受控值为准。

### Steps Props

| 属性                 | 说明                     | 类型                                                  | 默认值         |
| -------------------- | ------------------------ | ----------------------------------------------------- | -------------- |
| type                 | 步骤条的类型             | `'default'` \| `'arrow'` \| `'dot'` \| `'navigation'` | `'default'`    |
| orientation            | 步骤流程的横纵轴向，默认 horizontal；arrow 和 navigation 类型固定横向 | `'horizontal'` \| `'vertical'`                        | `'horizontal'` |
| content-placement    | 正文相对步骤节点的方位，可选 right 或 bottom，默认 right；dot 类型按横纵轴推导，navigation 固定 right | `'right'` \| `'bottom'`                               | `'right'`      |
| model-value(**v-model**) | 当前步骤数               | `number`                                              | `-`            |
| default-value      | 默认的步骤数(非受控状态) | `number`                                              | `1`            |
| status               | 当前步骤状态             | `'wait'` \| `'process'` \| `'finish'` \| `'error'`    | `'process'`    |
| show-line            | 是否显示连接线           | `boolean`                                             | `true`         |
| size                 | 步骤条尺寸               | `'sm'` \| `'md'`                                     | `'md'`         |
| changeable           | 是否可以点击切换步骤     | `boolean`                                             | `false`        |

### Steps Events

| 事件名              | 说明                           | 参数                         |
| ------------------- | ------------------------------ | ---------------------------- |
| change              | 步骤数发生改变时触发（需开启 `changeable`） | current:`number`<br/>previous:`number`<br/>ev:`Event` |
| update:modelValue      | `v-model` 同步         | step:`number`                |

### Steps Slots

| 插槽名      | 说明         |
| ----------- | ------------ |
| default     | 步骤内容     |
| finish-icon | 完成状态图标 |
| error-icon  | 错误状态图标 |

### Step Props

| 属性        | 说明         | 类型                                               | 默认值  |
| ----------- | ------------ | -------------------------------------------------- | ------- |
| title       | 步骤的标题   | `string`                                           | `-`     |
| description | 步骤的描述   | `string`                                           | `-`     |
| status      | 步骤的状态   | `'wait'` \| `'process'` \| `'finish'` \| `'error'` | `-`     |
| disabled    | 是否禁用步骤 | `boolean`                                          | `false` |

### Step Slots

| 插槽名      | 说明 | 参数                              |
| ----------- | ---- | --------------------------------- |
| default     | 标题 | `index`、`status`、`active`、`disabled` |
| title       | 标题 | `index`、`status`、`active`、`disabled` |
| node        | 节点 | `index`、`status`、`active`、`disabled` |
| icon        | 图标 | `index`、`status`、`active`、`disabled` |
| description | 描述 | `index`、`status`、`active`、`disabled` |

## 类型定义

组件导出以下类型定义

```ts
import type {
  StepsProps,
  StepProps,
  StepsType,
  StepStatus,
  StepsSize,
  StepsContentPlacement,
  StepsInstance,
  StepsStepInstance,
} from '@cedar-design/ui'
```

## 同源实现与平台边界

两端各自保存完整源码，不引用公共核心，不共享组件实例或响应式状态；修改时同步维护两份实现。主体、Props、关键样式及配对测试纳入只读源码一致性检查，主题 token 和安装入口各自维护。

Steps 和 Step 的主体、Props、上下文协议与样式同源复制；注入 Symbol 分别定义在各库，不跨库共享。保留四种 type 和原有状态/事件契约。

`active` 只表示当前步骤序号（从 1 开始）是否对应 modelValue；与 status（wait/process/finish/error）分开。当前步骤即使为 error，active 仍为 true；焦点、悬停不会改变 active。


### 方位语义与配置入口

content-placement 统一的是方位词汇和拼写，不要求所有组件开放相同集合。Steps 仅实现 right/bottom；dot 和 navigation 类型有各自推导规则，不为统一添加尚未实现的方位。


## 阅读方向与键盘交互

Steps 继承最近的 `dir="ltr"` 或 `dir="rtl"`，支持运行时切换。横向步骤、连接线和方向箭头随阅读方向排列，纵向步骤仍从上到下；序号、进度值和自定义图标内容保持原意。

`changeable` 开启时，左右键按当前阅读方向移动焦点，纵向使用上下键；Home/End 聚焦首尾可用步骤，禁用项会被跳过。Enter/Space 确认步骤；移动焦点和切换方向不会触发进度更新。

---

Document: llms/zh-CN/components/style-provider.md

<!-- Source: src/style-provider/README.md; locale: zh-CN; page: /components/style-provider/ -->

# StyleProvider 样式定制

两端独立同源，API、安装、默认值设置和运行逻辑一致；仅平台标识与本地导入不同。

## 基础示例

### 基础用法

Example source: src/style-provider/__demos__/basic.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'

const active = ref(true)
</script>

<template>
  <div>
    <c-button variant="outline" @click="active = !active">切换局部变量 / Toggle local variables</c-button>
    <c-style-provider tag="section" :style-vars="active ? { '--c-demo-color': 'teal' } : null">
      <p style="color: var(--c-demo-color, currentColor)">局部颜色 / Local color</p>
      <c-style-provider :style-vars="{ '--c-demo-color': 'coral' }">
        <p style="color: var(--c-demo-color)">嵌套覆盖 / Nested override</p>
      </c-style-provider>
    </c-style-provider>
    <p>外部不受影响 / Outside remains unchanged</p>
  </div>
</template>
```

按钮只切换本例外层 `section` 的局部变量：关闭时文字继承父级颜色，内层 coral 覆盖和外部文字不变；再次切换恢复 teal。该 Demo 不调用全局 `setStyleVars`，不能用它验证全局主题注入、替换或清理。

局部变量按 DOM 继承，嵌套 Provider 可覆盖父级变量；传入 `null` 清除本层覆盖（仍会继承父级）。通过 `popupContainer` 移到 Provider 外的节点不继承局部变量。组件式调用不修改全局主题属性。

局部组件定制优先设置实际 component 变量；只改 palette/system 变量，不会自动重算从根节点继承的组件别名。需要局部联动时在本层显式重声明相关映射；这不是自动完整主题重建。弹层变量放在真实挂载宿主。详见[Design Token 与 CSS 变量分层](llms/zh-CN/guide/design-tokens.md)。

## 全局调用

```ts
import { StyleProvider, Themes } from '@cedar-design/ui'

StyleProvider.setStyleVars(Themes.default.dark)
StyleProvider.setStyleVars(Themes.maple.light)
StyleProvider.setStyleVars(null)
```

每次调用替换上次注入，不累计合并。与当前基础样式一致的变量不重复写入。
`dark` 设置 `html[cedar-theme="dark"]`；`light` 移除该属性。未提供 color-scheme 时保留现有主题属性；`null` 移除本库注入和主题属性，不影响另一库。SSR 中函数调用无副作用。

变量支持完整 CSS 名称，也支持驼峰（如 `cColorScheme`）；不会自动补充库前缀。推荐完整 `--c-*` 名称。

## 安装与默认值

```ts
import { StyleProvider } from '@cedar-design/ui'

app.use(StyleProvider)

StyleProvider.setPropsDefaults({
  tag: 'section',
  styleVars: () => ({ '--c-demo-color': 'teal' }),
})
```

在应用初始化、挂载组件之前设置默认值，不追溯更新已挂载实例；显式 Props 优先。对象形式会为每个实例复制变量对象，也支持工厂和 `null`。默认配置仅属于本库，不跨库共享。
安装固定注册 `CStyleProvider`，不修改应用全局配置；自定义别名使用 `app.component('MyStyleProvider', StyleProvider)`。

## API

| 属性 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| `style-vars` | 局部变量，null 清空本层覆盖 | `Record<string, string> \| null` | `{}` |
| `tag` | 包裹标签 | `string` | `div` |

默认插槽为组件内容，无事件。

## 类型定义

导出 `StyleVars`、`StyleProviderProps`、`StyleProviderDefaults`、`StyleProviderInstance`；运行时只以 `StyleProvider` 作为公开组件入口，另导出 `styleProviderProps` 和供 resolver 使用的 `_StyleProviderComponent`。

本组件不声明专属主题 token；变量值为字符串，数字尺寸请写成带单位的字符串。

---

Document: llms/zh-CN/components/style/atomic-css.md

<!-- Source: src/style/atomic-css/README.md; locale: zh-CN; page: /components/style/atomic-css/ -->

# 原子化 CSS

Cedar 提供两套能力：

| 能力             | 包 / 入口                                                | 何时用                           |
| ---------------- | -------------------------------------------------------- | -------------------------------- |
| 固定工具类 `c-*` | `@cedar-design/ui` 的 `style/utilities/index.less`            | 不接 Uno/TW 时使用               |
| Uno / TW preset  | `@cedar-design/preset-unocss` / `@cedar-design/preset-tailwindcss` | 使用带 `c-` 前缀的完整原子化体系 |

Preset **不是组件**，是构建期配置：装好后即可写 `c-flex`、`c-p-16`、`c-bg-primary`、`c-text-md` 等。主题切换（暗色 / StyleProvider）只改 CSS 变量，类名不变。日常分类速查见 [常用写法](llms/zh-CN/components/style/atomic-usage.md)。

Maple 也提供 UnoCSS / Tailwind CSS preset。`mp-` 是否生效取决于生成器配置，详见下方“Maple 对应配置”。

> 下方 Demo 用与 Preset 等价的 CSS（`var(--c-*)`）做视觉预览；真实项目中这些类由 Uno / Tailwind 生成。

## 基础示例

### 新手示例

UnoCSS 和 Tailwind **二选一配置**，但组件里的类名完全相同。可以先复制下面这张卡片，再逐个调整类名观察效果：

```vue
<template>
  <div
    class="c-flex c-max-w-md c-flex-col c-gap-12 c-rounded-lg c-border c-border-solid c-border-gray-200 c-bg-body c-p-16"
  >
    <h3 class="c-m-0 c-text-lg c-text-primary">第一张原子化卡片</h3>
    <p class="c-m-0 c-text-sm">组合小类完成布局，不需要另外写组件样式。</p>

    <div
      class="c-flex c-items-center c-justify-between c-gap-8 c-rounded-md c-bg-gray-100 c-p-12"
    >
      <code>c-flex c-items-center c-gap-8</code>
      <span class="c-text-success">Success</span>
    </div>

    <c-button
      class="c-rounded-md c-border-0 c-bg-primary c-px-16 c-py-8 c-text-white hover:c-opacity-80"
    >
      保存
    </c-button>
  </div>
</template>
```

读法很简单：`c-` 是 Cedar 前缀；`flex` 是布局；`p/px/py/gap` 是间距；`bg/text/border` 是颜色；`rounded` 是圆角；`hover:` 是交互状态。

Example source: src/style/atomic-css/__demos__/starter.vue

```vue
<template>
  <div class="starter-card">
    <div class="starter-title">第一张原子化卡片</div>
    <div class="starter-description">
      组合小类完成布局，不需要另外写组件样式。
    </div>

    <div class="starter-row">
      <span class="starter-tag">c-flex c-items-center c-gap-8</span>
      <span class="starter-status">Success</span>
    </div>

    <c-button class="starter-button"
      >c-bg-primary · hover:c-opacity-80</c-button
    >
  </div>
</template>

<style scoped>
/* 文档站的等价视觉预览；业务项目中的样式由 UnoCSS 或 Tailwind 生成。 */
.starter-card {
  display: flex;
  flex-direction: column;
  gap: 12px;
  max-width: 420px;
  padding: 16px;
  border: 1px solid var(--c-color-border-2);
  border-radius: 8px;
  background: var(--c-color-body);
}

.starter-title {
  color: var(--c-color-primary);
  font-size: var(--c-font-size-lg);
  font-weight: 600;
}

.starter-description {
  color: var(--c-color-text-3);
}

.starter-row {
  display: flex;
  align-items: center;
  justify-content: space-between;
  gap: 8px;
  padding: 12px;
  border-radius: 6px;
  background: var(--c-color-fill-2);
}

.starter-tag {
  color: var(--c-color-text-2);
  font-family: monospace;
  font-size: 12px;
}

.starter-status {
  color: var(--c-color-success);
}

.starter-button {
  padding: 8px 16px;
  border: 0;
  border-radius: 6px;
  color: #fff;
  background: var(--c-color-primary);
  cursor: pointer;
  transition: opacity 0.2s;
}

.starter-button:hover {
  opacity: 0.8;
}
</style>
```

### 与固定工具类的分工

Example source: src/style/atomic-css/__demos__/overview.vue

```vue
<template>
  <c-space direction="column" block size="md">
    <c-alert status="info">
      Preset 在构建期注入主题；固定工具类是现成 CSS。二者可同时使用。
    </c-alert>
    <c-table :columns="columns" :data="data" :pagination="false" />
  </c-space>
</template>

<script lang="ts" setup>
const columns = [
  { title: "能力", dataIndex: "kind" },
  { title: "例子", dataIndex: "example" },
  { title: "说明", dataIndex: "note" },
];

const data = [
  {
    kind: "Preset 颜色",
    example: "c-bg-primary / c-text-success",
    note: "需配置 @cedar-design/preset-*",
  },
  {
    kind: "Preset 字号",
    example: "c-text-xs / c-text-lg",
    note: "挂 --c-font-size-*",
  },
  {
    kind: "Preset 断点",
    example: "sm: / md: / lg: / xl:",
    note: "数值与设计对齐",
  },
  {
    kind: "固定 Utilities",
    example: "c-text-1 / c-fill-1",
    note: "utilities 语义色，不经 Uno/TW",
  },
];
</script>
```

---

## 颜色、文字与间距

### 颜色 Color

主题色 key 使用无前缀语义名，最终生成的 utility 统一带 `c-` 前缀。

| Theme key  | CSS 变量             | 背景            | 文字              | 边框颜色           |
| ---------- | -------------------- | --------------- | ----------------- | ------------------ |
| `body`     | `--c-color-body`     | `c-bg-body`     | —                 | —                  |
| `primary`  | `--c-color-primary`  | `c-bg-primary`  | `c-text-primary`  | `c-border-primary` |
| `info`     | `--c-color-info`     | `c-bg-info`     | `c-text-info`     | `c-border-info`    |
| `success`  | `--c-color-success`  | `c-bg-success`  | `c-text-success`  | `c-border-success` |
| `warning`  | `--c-color-warning`  | `c-bg-warning`  | `c-text-warning`  | `c-border-warning` |
| `danger`   | `--c-color-danger`   | `c-bg-danger`   | `c-text-danger`   | `c-border-danger`  |
| `disabled` | `--c-color-disabled` | `c-bg-disabled` | `c-text-disabled` | —                  |

颜色类只设置对应的颜色属性。比如 `c-border-primary` 只设置 `border-color`，需要和边框宽度类一起使用：

```html
<div class="c-border c-border-primary">primary border</div>
<div class="c-border-2 c-border-danger">danger border</div>
```

常见组合方式：

```html
<!-- 静态颜色 -->
<div class="c-bg-body c-text-primary">primary</div>

<!-- 状态变体 -->
<c-button class="c-border c-border-primary hover:c-bg-primary">hover</c-button>

<!-- 响应式变体；断点本身不加 c- 前缀 -->
<div class="c-bg-primary sm:c-bg-info md:c-bg-warning">responsive</div>
```

UnoCSS / Tailwind 只扫描源码中完整出现的类名。不要用 `c-bg-${status}` 动态拼接；必须动态选择时，使用完整类名映射或生成器的 safelist。

Example source: src/style/atomic-css/__demos__/colors.vue

```vue
<template>
  <c-space direction="column" fill size="lg">
    <div>
      <div class="label">背景 c-bg-*</div>
      <div class="row">
        <div
          v-for="item in bgItems"
          :key="item.cls"
          class="swatch"
          :style="item.style"
        >
          <code>{{ item.cls }}</code>
        </div>
      </div>
    </div>
    <div>
      <div class="label">文字 c-text-*</div>
      <div class="row text-row">
        <span
          v-for="item in textItems"
          :key="item.cls"
          class="text-chip"
          :style="item.style"
        >
          {{ item.cls }}
        </span>
      </div>
    </div>
    <div>
      <div class="label">边框 c-border-*</div>
      <div class="row">
        <div
          v-for="item in borderItems"
          :key="item.cls"
          class="border-chip"
          :style="item.style"
        >
          <code>{{ item.cls }}</code>
        </div>
      </div>
    </div>
  </c-space>
</template>

<script lang="ts" setup>
const bgItems = [
  {
    cls: "c-bg-body",
    style: {
      background: "var(--c-color-body)",
      color: "var(--c-color-text-1)",
    },
  },
  {
    cls: "c-bg-primary",
    style: { background: "var(--c-color-primary)", color: "#fff" },
  },
  {
    cls: "c-bg-info",
    style: { background: "var(--c-color-info)", color: "#fff" },
  },
  {
    cls: "c-bg-success",
    style: { background: "var(--c-color-success)", color: "#fff" },
  },
  {
    cls: "c-bg-warning",
    style: { background: "var(--c-color-warning)", color: "#fff" },
  },
  {
    cls: "c-bg-danger",
    style: { background: "var(--c-color-danger)", color: "#fff" },
  },
  {
    cls: "c-bg-disabled",
    style: {
      background: "var(--c-color-disabled)",
      color: "var(--c-color-text-1)",
    },
  },
];

const textItems = [
  { cls: "c-text-primary", style: { color: "var(--c-color-primary)" } },
  { cls: "c-text-info", style: { color: "var(--c-color-info)" } },
  { cls: "c-text-success", style: { color: "var(--c-color-success)" } },
  { cls: "c-text-warning", style: { color: "var(--c-color-warning)" } },
  { cls: "c-text-danger", style: { color: "var(--c-color-danger)" } },
  { cls: "c-text-disabled", style: { color: "var(--c-color-disabled)" } },
];

const borderItems = [
  { cls: "c-border-primary", style: { borderColor: "var(--c-color-primary)" } },
  { cls: "c-border-info", style: { borderColor: "var(--c-color-info)" } },
  { cls: "c-border-success", style: { borderColor: "var(--c-color-success)" } },
  { cls: "c-border-warning", style: { borderColor: "var(--c-color-warning)" } },
  { cls: "c-border-danger", style: { borderColor: "var(--c-color-danger)" } },
];
</script>

<style scoped lang="scss">
.label {
  margin-bottom: 8px;
  color: var(--c-color-text-3);
}

.row {
  display: flex;
  flex-wrap: wrap;
  gap: 8px;
}

.swatch {
  min-width: 110px;
  padding: 10px 12px;
  border-radius: 4px;
  border: 1px solid var(--c-color-border-2);
  font-size: 12px;
  text-align: center;
}

.text-row {
  gap: 16px;
  align-items: center;
}

.text-chip {
  font-size: 14px;
  font-weight: 500;
}

.border-chip {
  min-width: 110px;
  padding: 10px 12px;
  border-width: 2px;
  border-style: solid;
  border-radius: 4px;
  text-align: center;
}
</style>
```

### 字号 Font size

| 档位 | CSS 变量           | Uno / Tailwind 类名 |
| ---- | ------------------ | ------------------- |
| xs   | `--c-font-size-xs` | `c-text-xs`         |
| sm   | `--c-font-size-sm` | `c-text-sm`         |
| md   | `--c-font-size-md` | `c-text-md`         |
| lg   | `--c-font-size-lg` | `c-text-lg`         |

> 两套引擎使用同一套类名。不要与固定工具类语义色 `c-text-1…4` 混淆。

Example source: src/style/atomic-css/__demos__/font-size.vue

```vue
<template>
  <c-space direction="column" fill size="md">
    <div
      v-for="item in items"
      :key="item.className"
      class="line"
      :style="{ fontSize: item.size }"
    >
      <code class="tag">{{ item.className }}</code>
      <span>Cedar Design — {{ item.label }}</span>
    </div>
  </c-space>
</template>

<script lang="ts" setup>
const items = [
  { label: "xs / 10px", className: "c-text-xs", size: "var(--c-font-size-xs)" },
  { label: "sm / 12px", className: "c-text-sm", size: "var(--c-font-size-sm)" },
  { label: "md / 14px", className: "c-text-md", size: "var(--c-font-size-md)" },
  { label: "lg / 16px", className: "c-text-lg", size: "var(--c-font-size-lg)" },
];
</script>

<style scoped lang="scss">
.line {
  display: flex;
  flex-wrap: wrap;
  align-items: baseline;
  gap: 8px;
  color: var(--c-color-text-1);
}

.tag {
  font-size: 12px;
  padding: 2px 6px;
  border-radius: 4px;
  background: var(--c-color-fill-2);
  color: var(--c-color-text-2);
}
</style>
```

### 间距 Spacing

间距与宽高数值直接对应像素：`1 = 1px`。例如 `c-p-8` 为 8px、`c-mt-16` 为 16px、`c-h-10` 为 10px；
百分比用 `c-w-full` / `c-h-full` 或 `c-w-1/2`。方向写法与 Uno / Tailwind 一致。

| 类型           | 示例                                              |
| -------------- | ------------------------------------------------- |
| margin         | `c-m-16` `c-mt-16` `c-mx-8` `c-my-24`             |
| padding        | `c-p-16` `c-pt-16` `c-px-8` `c-py-24`             |
| gap            | `c-gap-8` `c-gap-x-16` `c-gap-y-24`               |
| auto           | `c-m-auto` `c-ml-auto`                            |
| width / height | `c-w-10` `c-h-10` `c-w-full` `c-h-auto` `c-w-1/2` |

Example source: src/style/atomic-css/__demos__/spacing.vue

```vue
<template>
  <div class="spacing-demo">
    <div class="spacing-row">
      <code>c-p-4 · 4px</code>
      <div class="spacing-stage"><div class="spacing-box c-p-4">内容</div></div>
    </div>
    <div class="spacing-row">
      <code>c-p-8 · 8px</code>
      <div class="spacing-stage"><div class="spacing-box c-p-8">内容</div></div>
    </div>
    <div class="spacing-row">
      <code>c-p-16 · 16px</code>
      <div class="spacing-stage">
        <div class="spacing-box c-p-16">内容</div>
      </div>
    </div>
    <div class="spacing-row">
      <code>c-px-24 c-py-8 · 24px / 8px</code>
      <div class="spacing-stage">
        <div class="spacing-box c-px-24 c-py-8">内容</div>
      </div>
    </div>
  </div>
</template>

<style scoped>
.spacing-demo {
  display: grid;
  gap: 16px;
}

.spacing-row {
  display: grid;
  grid-template-columns: minmax(210px, 1fr) 2fr;
  align-items: center;
  gap: 16px;
}

.spacing-stage {
  background: var(--c-color-fill-2);
  border-radius: 4px;
}

.spacing-box {
  width: fit-content;
  color: #fff;
  background: var(--c-color-primary);
}

/* 文档站未接入 preset 时的等价预览，业务项目由 Uno / Tailwind 生成。 */
.c-p-4 {
  padding: 4px;
}
.c-p-8 {
  padding: 8px;
}
.c-p-16 {
  padding: 16px;
}
.c-px-24 {
  padding-right: 24px;
  padding-left: 24px;
}
.c-py-8 {
  padding-top: 8px;
  padding-bottom: 8px;
}

@media (max-width: 600px) {
  .spacing-row {
    grid-template-columns: 1fr;
    gap: 8px;
  }
}
</style>
```

## 响应式与组合

### 断点 Breakpoints / Screens

两边数值一致（框架惯例，**不加** `c-` 前缀）：

| 断点 | 宽度   |
| ---- | ------ |
| `sm` | 768px  |
| `md` | 992px  |
| `lg` | 1200px |
| `xl` | 1920px |

写法示例：`sm:c-bg-info` `md:c-bg-warning` `lg:c-bg-danger` `xl:c-bg-success`

Example source: src/style/atomic-css/__demos__/breakpoints.vue

```vue
<template>
  <c-space direction="column" fill size="md">
    <div class="hint">
      缩小浏览器窗口可观察当前命中的断点；类名形如
      <code>sm:c-bg-info</code>。
    </div>
    <div class="box">
      <div class="label">当前 ≥</div>
      <strong class="value">{{ active }}</strong>
    </div>
    <c-table :columns="columns" :data="rows" :pagination="false" />
  </c-space>
</template>

<script lang="ts" setup>
import { computed, onMounted, onUnmounted, ref } from "vue";

const width = ref(typeof window !== "undefined" ? window.innerWidth : 0);

const onResize = () => {
  width.value = window.innerWidth;
};

onMounted(() => {
  width.value = window.innerWidth;
  window.addEventListener("resize", onResize);
});

onUnmounted(() => {
  window.removeEventListener("resize", onResize);
});

const active = computed(() => {
  const w = width.value;
  if (w >= 1920) return "xl (1920px)";
  if (w >= 1200) return "lg (1200px)";
  if (w >= 992) return "md (992px)";
  if (w >= 768) return "sm (768px)";
  return "base (< sm)";
});

const columns = [
  { title: "前缀", dataIndex: "prefix" },
  { title: "最小宽度", dataIndex: "min" },
  { title: "示例类", dataIndex: "cls" },
];

const rows = [
  { prefix: "sm:", min: "768px", cls: "sm:c-bg-info" },
  { prefix: "md:", min: "992px", cls: "md:c-bg-warning" },
  { prefix: "lg:", min: "1200px", cls: "lg:c-bg-danger" },
  { prefix: "xl:", min: "1920px", cls: "xl:c-bg-success" },
];
</script>

<style scoped lang="scss">
.hint {
  font-size: 13px;
  color: var(--c-color-text-3);
}

.box {
  display: flex;
  align-items: baseline;
  gap: 8px;
  padding: 12px 16px;
  border-radius: 4px;
  background: var(--c-color-primary);
  color: #fff;
}

.label {
  opacity: 0.85;
  font-size: 13px;
}

.value {
  font-size: 18px;
}
</style>
```

### 组合示例

```html
<template>
  <div class="c-bg-body c-text-md">
    <span class="c-text-primary">primary</span>
    <div class="c-bg-primary c-text-lg sm:c-bg-info md:c-bg-warning">
      responsive
    </div>
  </div>
</template>
```

Example source: src/style/atomic-css/__demos__/combined.vue

```vue
<template>
  <div class="demo">
    <div class="card body">
      <div class="title">c-bg-body + c-text-md</div>
      <div class="row">
        <span class="primary">c-text-primary</span>
        <span class="success">c-text-success</span>
        <span class="danger">c-text-danger</span>
      </div>
      <div class="banner">
        <div class="banner-inner">
          c-bg-primary · Uno / TW <code>c-text-lg</code>
          <div class="sub">
            叠加：sm:c-bg-info → md:c-bg-warning → lg:c-bg-danger →
            xl:c-bg-success
          </div>
        </div>
      </div>
    </div>
  </div>
</template>

<style scoped lang="scss">
.demo {
  font-size: var(--c-font-size-md);
}

.card {
  padding: 16px;
  border-radius: 8px;
  border: 1px solid var(--c-color-border-2);
}

.body {
  background: var(--c-color-body);
  color: var(--c-color-text-1);
}

.title {
  margin-bottom: 12px;
  font-weight: 600;
}

.row {
  display: flex;
  flex-wrap: wrap;
  gap: 12px;
  margin-bottom: 16px;
}

.primary {
  color: var(--c-color-primary);
}

.success {
  color: var(--c-color-success);
}

.danger {
  color: var(--c-color-danger);
}

.banner {
  padding: 16px;
  border-radius: 4px;
  background: var(--c-color-primary);
  color: #fff;
  font-size: var(--c-font-size-lg);

  @media (min-width: 768px) {
    background: var(--c-color-info);
  }

  @media (min-width: 992px) {
    background: var(--c-color-warning);
  }

  @media (min-width: 1200px) {
    background: var(--c-color-danger);
  }

  @media (min-width: 1920px) {
    background: var(--c-color-success);
  }
}

.sub {
  margin-top: 6px;
  font-size: var(--c-font-size-sm);
  opacity: 0.9;
}

code {
  font-size: 12px;
  opacity: 0.95;
}
</style>
```

---

## UnoCSS

### 安装

```shell
pnpm add -D @cedar-design/preset-unocss unocss
```

### 配置

```js
// uno.config.ts
import { defineConfig } from "unocss";
import { presetCedar } from "@cedar-design/preset-unocss";

export default defineConfig({
  presets: [presetCedar()],
});
```

可选参数：`presetCedar({ colors, fontSize, breakpoints })`，设为 `false` 可关闭某一块。

### 需已加载主题变量

```js
import "@cedar-design/ui/dist/index.css";
// 或自行引入含 --c-* 的主题样式
```

---

## Tailwind CSS

### 安装

```shell
pnpm add -D @cedar-design/preset-tailwindcss tailwindcss
```

### Tailwind v3

```js
// tailwind.config.js
import { presetCedar } from "@cedar-design/preset-tailwindcss";

export default {
  content: ["./index.html", "./src/**/*.{vue,js,ts,jsx,tsx}"],
  presets: [presetCedar()],
};
```

### Tailwind v4

```js
// tailwind.config.js
import { presetCedar } from "@cedar-design/preset-tailwindcss";

export default {
  presets: [presetCedar()],
};
```

```css
/* src/style.css */
@import "tailwindcss";
@config '../tailwind.config.js';
```

---

完整分类（Flex / 间距 / 尺寸 / 溢出 / 圆角等）见 [常用写法](llms/zh-CN/components/style/atomic-usage.md)。下面只列 preset 挂到 Cedar token 上的那几项。

## 可选配置

```js
presetCedar({
  colors: true, // 或 false / 覆盖部分 key
  fontSize: true, // 设为 false 可关闭，也可传自定义 fontSize map
  // Uno:
  breakpoints: true,
  // TW:
  // screens: true,
});
```

### 自定义主题映射

`colors` 和 `fontSize` 可覆盖部分默认值，未传入的 key 保持默认映射：

```js
presetCedar({
  colors: {
    primary: "var(--app-color-brand)",
    danger: "var(--app-color-error)",
  },
  fontSize: {
    md: "15px",
  },
});
```

设为 `false` 会关闭 Cedar 对应的主题映射。生成器自身的默认 utility 仍可能存在，但不再绑定 Cedar CSS 变量。

---

## Maple 对应配置

Maple 的 UnoCSS preset 已内置带 `mp-` 前缀的 `presetUno`：

```js
import { defineConfig } from "unocss";
import { presetMaple } from "@nio-pow/maple-preset-unocss";

export default defineConfig({
  presets: [presetMaple()],
});
```

UnoCSS 和 Tailwind CSS 两套 Maple preset 均生成 `mp-bg-primary`、`mp-text-primary`、`mp-border mp-border-primary` 等类，不提供无前缀别名。

Tailwind 的 `prefix` 是全局配置，同一个 Tailwind 实例不适合同时加载使用不同前缀的 Cedar 与 Maple preset。

---

## 注意

- Preset 包含框架提供的完整原子类，全部使用 `c-` 前缀，如 `c-flex`、`c-p-16`。
- 类名必须以 `c-` 开头（如 `c-bg-primary`），不提供无前缀别名。
- UnoCSS 与 Tailwind CSS 二选一，不要在同一应用中同时启用两套生成器。
- Cedar 与 Maple 使用了同名 theme key。即使 UnoCSS 可配置不同 utility 前缀，也应避免在同一个配置中直接合并两套 theme；否则同名颜色可能按 preset 顺序相互覆盖。

---

Document: llms/zh-CN/components/style/atomic-usage.md

<!-- Source: src/style/atomic-usage/README.md; locale: zh-CN; page: /components/style/atomic-usage/ -->

# 常用写法

这一页按场景整理带 `c-` 前缀的原子类。布局、间距、尺寸等类由 UnoCSS 或 Tailwind preset 在构建期生成，**不是 UI 包默认附带的全部工具类**；安装配置见 [原子化 CSS](llms/zh-CN/components/style/atomic-css.md)。

下方 Demo 使用局部等价 CSS 展示效果，不要求文档读者先安装生成器。源码里的演示类只用于展示；业务中使用表格列出的 preset 类。

## 基础示例

### 布局与组合

| 场景 | 类名示例 |
| --- | --- |
| 横向排列 | `c-flex c-items-center c-justify-between` |
| 纵向排列 | `c-flex c-flex-col` |
| 换行 | `c-flex c-flex-wrap` |
| 间隔 | `c-gap-12` |

Example source: src/style/atomic-css/__demos__/combined.vue

```vue
<template>
  <div class="demo">
    <div class="card body">
      <div class="title">c-bg-body + c-text-md</div>
      <div class="row">
        <span class="primary">c-text-primary</span>
        <span class="success">c-text-success</span>
        <span class="danger">c-text-danger</span>
      </div>
      <div class="banner">
        <div class="banner-inner">
          c-bg-primary · Uno / TW <code>c-text-lg</code>
          <div class="sub">
            叠加：sm:c-bg-info → md:c-bg-warning → lg:c-bg-danger →
            xl:c-bg-success
          </div>
        </div>
      </div>
    </div>
  </div>
</template>

<style scoped lang="scss">
.demo {
  font-size: var(--c-font-size-md);
}

.card {
  padding: 16px;
  border-radius: 8px;
  border: 1px solid var(--c-color-border-2);
}

.body {
  background: var(--c-color-body);
  color: var(--c-color-text-1);
}

.title {
  margin-bottom: 12px;
  font-weight: 600;
}

.row {
  display: flex;
  flex-wrap: wrap;
  gap: 12px;
  margin-bottom: 16px;
}

.primary {
  color: var(--c-color-primary);
}

.success {
  color: var(--c-color-success);
}

.danger {
  color: var(--c-color-danger);
}

.banner {
  padding: 16px;
  border-radius: 4px;
  background: var(--c-color-primary);
  color: #fff;
  font-size: var(--c-font-size-lg);

  @media (min-width: 768px) {
    background: var(--c-color-info);
  }

  @media (min-width: 992px) {
    background: var(--c-color-warning);
  }

  @media (min-width: 1200px) {
    background: var(--c-color-danger);
  }

  @media (min-width: 1920px) {
    background: var(--c-color-success);
  }
}

.sub {
  margin-top: 6px;
  font-size: var(--c-font-size-sm);
  opacity: 0.9;
}

code {
  font-size: 12px;
  opacity: 0.95;
}
</style>
```

## 间距与响应式

### 内外间距

`p` / `m` 表示内 / 外间距，`x` / `y` 表示水平 / 垂直双轴，`t/r/b/l` 表示单侧。例如 `c-p-16`、`c-px-8`、`c-mt-16`。

Example source: src/style/atomic-css/__demos__/spacing.vue

```vue
<template>
  <div class="spacing-demo">
    <div class="spacing-row">
      <code>c-p-4 · 4px</code>
      <div class="spacing-stage"><div class="spacing-box c-p-4">内容</div></div>
    </div>
    <div class="spacing-row">
      <code>c-p-8 · 8px</code>
      <div class="spacing-stage"><div class="spacing-box c-p-8">内容</div></div>
    </div>
    <div class="spacing-row">
      <code>c-p-16 · 16px</code>
      <div class="spacing-stage">
        <div class="spacing-box c-p-16">内容</div>
      </div>
    </div>
    <div class="spacing-row">
      <code>c-px-24 c-py-8 · 24px / 8px</code>
      <div class="spacing-stage">
        <div class="spacing-box c-px-24 c-py-8">内容</div>
      </div>
    </div>
  </div>
</template>

<style scoped>
.spacing-demo {
  display: grid;
  gap: 16px;
}

.spacing-row {
  display: grid;
  grid-template-columns: minmax(210px, 1fr) 2fr;
  align-items: center;
  gap: 16px;
}

.spacing-stage {
  background: var(--c-color-fill-2);
  border-radius: 4px;
}

.spacing-box {
  width: fit-content;
  color: #fff;
  background: var(--c-color-primary);
}

/* 文档站未接入 preset 时的等价预览，业务项目由 Uno / Tailwind 生成。 */
.c-p-4 {
  padding: 4px;
}
.c-p-8 {
  padding: 8px;
}
.c-p-16 {
  padding: 16px;
}
.c-px-24 {
  padding-right: 24px;
  padding-left: 24px;
}
.c-py-8 {
  padding-top: 8px;
  padding-bottom: 8px;
}

@media (max-width: 600px) {
  .spacing-row {
    grid-template-columns: 1fr;
    gap: 8px;
  }
}
</style>
```

### 响应式布局

`sm:`、`md:`、`lg:`、`xl:` 在对应视口断点应用类；容器宽度与 viewport 不是同一概念。

Example source: src/style/atomic-css/__demos__/breakpoints.vue

```vue
<template>
  <c-space direction="column" fill size="md">
    <div class="hint">
      缩小浏览器窗口可观察当前命中的断点；类名形如
      <code>sm:c-bg-info</code>。
    </div>
    <div class="box">
      <div class="label">当前 ≥</div>
      <strong class="value">{{ active }}</strong>
    </div>
    <c-table :columns="columns" :data="rows" :pagination="false" />
  </c-space>
</template>

<script lang="ts" setup>
import { computed, onMounted, onUnmounted, ref } from "vue";

const width = ref(typeof window !== "undefined" ? window.innerWidth : 0);

const onResize = () => {
  width.value = window.innerWidth;
};

onMounted(() => {
  width.value = window.innerWidth;
  window.addEventListener("resize", onResize);
});

onUnmounted(() => {
  window.removeEventListener("resize", onResize);
});

const active = computed(() => {
  const w = width.value;
  if (w >= 1920) return "xl (1920px)";
  if (w >= 1200) return "lg (1200px)";
  if (w >= 992) return "md (992px)";
  if (w >= 768) return "sm (768px)";
  return "base (< sm)";
});

const columns = [
  { title: "前缀", dataIndex: "prefix" },
  { title: "最小宽度", dataIndex: "min" },
  { title: "示例类", dataIndex: "cls" },
];

const rows = [
  { prefix: "sm:", min: "768px", cls: "sm:c-bg-info" },
  { prefix: "md:", min: "992px", cls: "md:c-bg-warning" },
  { prefix: "lg:", min: "1200px", cls: "lg:c-bg-danger" },
  { prefix: "xl:", min: "1920px", cls: "xl:c-bg-success" },
];
</script>

<style scoped lang="scss">
.hint {
  font-size: 13px;
  color: var(--c-color-text-3);
}

.box {
  display: flex;
  align-items: baseline;
  gap: 8px;
  padding: 12px 16px;
  border-radius: 4px;
  background: var(--c-color-primary);
  color: #fff;
}

.label {
  opacity: 0.85;
  font-size: 13px;
}

.value {
  font-size: 18px;
}
</style>
```

## 颜色与文字

### 语义颜色与字号

业务优先使用语义颜色，不在组件中硬编码品牌色。固定颜色工具类与 preset 类的能力范围不同，见 [颜色 Color](llms/zh-CN/components/style/color.md) 与 [Utilities 总览](llms/zh-CN/components/style/utilities.md)。

Example source: src/style/atomic-css/__demos__/colors.vue

```vue
<template>
  <c-space direction="column" fill size="lg">
    <div>
      <div class="label">背景 c-bg-*</div>
      <div class="row">
        <div
          v-for="item in bgItems"
          :key="item.cls"
          class="swatch"
          :style="item.style"
        >
          <code>{{ item.cls }}</code>
        </div>
      </div>
    </div>
    <div>
      <div class="label">文字 c-text-*</div>
      <div class="row text-row">
        <span
          v-for="item in textItems"
          :key="item.cls"
          class="text-chip"
          :style="item.style"
        >
          {{ item.cls }}
        </span>
      </div>
    </div>
    <div>
      <div class="label">边框 c-border-*</div>
      <div class="row">
        <div
          v-for="item in borderItems"
          :key="item.cls"
          class="border-chip"
          :style="item.style"
        >
          <code>{{ item.cls }}</code>
        </div>
      </div>
    </div>
  </c-space>
</template>

<script lang="ts" setup>
const bgItems = [
  {
    cls: "c-bg-body",
    style: {
      background: "var(--c-color-body)",
      color: "var(--c-color-text-1)",
    },
  },
  {
    cls: "c-bg-primary",
    style: { background: "var(--c-color-primary)", color: "#fff" },
  },
  {
    cls: "c-bg-info",
    style: { background: "var(--c-color-info)", color: "#fff" },
  },
  {
    cls: "c-bg-success",
    style: { background: "var(--c-color-success)", color: "#fff" },
  },
  {
    cls: "c-bg-warning",
    style: { background: "var(--c-color-warning)", color: "#fff" },
  },
  {
    cls: "c-bg-danger",
    style: { background: "var(--c-color-danger)", color: "#fff" },
  },
  {
    cls: "c-bg-disabled",
    style: {
      background: "var(--c-color-disabled)",
      color: "var(--c-color-text-1)",
    },
  },
];

const textItems = [
  { cls: "c-text-primary", style: { color: "var(--c-color-primary)" } },
  { cls: "c-text-info", style: { color: "var(--c-color-info)" } },
  { cls: "c-text-success", style: { color: "var(--c-color-success)" } },
  { cls: "c-text-warning", style: { color: "var(--c-color-warning)" } },
  { cls: "c-text-danger", style: { color: "var(--c-color-danger)" } },
  { cls: "c-text-disabled", style: { color: "var(--c-color-disabled)" } },
];

const borderItems = [
  { cls: "c-border-primary", style: { borderColor: "var(--c-color-primary)" } },
  { cls: "c-border-info", style: { borderColor: "var(--c-color-info)" } },
  { cls: "c-border-success", style: { borderColor: "var(--c-color-success)" } },
  { cls: "c-border-warning", style: { borderColor: "var(--c-color-warning)" } },
  { cls: "c-border-danger", style: { borderColor: "var(--c-color-danger)" } },
];
</script>

<style scoped lang="scss">
.label {
  margin-bottom: 8px;
  color: var(--c-color-text-3);
}

.row {
  display: flex;
  flex-wrap: wrap;
  gap: 8px;
}

.swatch {
  min-width: 110px;
  padding: 10px 12px;
  border-radius: 4px;
  border: 1px solid var(--c-color-border-2);
  font-size: 12px;
  text-align: center;
}

.text-row {
  gap: 16px;
  align-items: center;
}

.text-chip {
  font-size: 14px;
  font-weight: 500;
}

.border-chip {
  min-width: 110px;
  padding: 10px 12px;
  border-width: 2px;
  border-style: solid;
  border-radius: 4px;
  text-align: center;
}
</style>
```
Example source: src/style/atomic-css/__demos__/font-size.vue

```vue
<template>
  <c-space direction="column" fill size="md">
    <div
      v-for="item in items"
      :key="item.className"
      class="line"
      :style="{ fontSize: item.size }"
    >
      <code class="tag">{{ item.className }}</code>
      <span>Cedar Design — {{ item.label }}</span>
    </div>
  </c-space>
</template>

<script lang="ts" setup>
const items = [
  { label: "xs / 10px", className: "c-text-xs", size: "var(--c-font-size-xs)" },
  { label: "sm / 12px", className: "c-text-sm", size: "var(--c-font-size-sm)" },
  { label: "md / 14px", className: "c-text-md", size: "var(--c-font-size-md)" },
  { label: "lg / 16px", className: "c-text-lg", size: "var(--c-font-size-lg)" },
];
</script>

<style scoped lang="scss">
.line {
  display: flex;
  flex-wrap: wrap;
  align-items: baseline;
  gap: 8px;
  color: var(--c-color-text-1);
}

.tag {
  font-size: 12px;
  padding: 2px 6px;
  border-radius: 4px;
  background: var(--c-color-fill-2);
  color: var(--c-color-text-2);
}
</style>
```

---

Document: llms/zh-CN/components/style/color.md

<!-- Source: src/style/color/README.md; locale: zh-CN; page: /components/style/color/ -->

# 颜色 Color

语义色工具类带库前缀：Cedar `c-*`，Maple `mp-*`（变量 `--c-*` / `--mp-*`）。
完整色阶与语义变量见 [色板 Palette](llms/zh-CN/components/palette.md)。

- 业务页用类名（`c-text-1`）；主题覆盖 / 组件 token 用变量（`--c-color-text-1`）
- 点击 Class 可快捷复制
- 不做无前缀别名、不做向后兼容

### 类名规则

| 类名                                    | 变量                                                                      |
| --------------------------------------- | ------------------------------------------------------------------------- |
| `c-text-1` … `c-text-4`                 | `var(--c-color-text-1)` … `var(--c-color-text-4)`                         |
| `c-fill-1` … `c-fill-4`                 | `var(--c-color-fill-1)` … `var(--c-color-fill-4)`                         |
| `c-color-border-1` … `c-color-border-4` | `var(--c-color-border-1)` … `var(--c-color-border-4)`                     |
| `c-bg-0` / `c-bg-1` / `c-bg-2`          | `var(--c-color-bg-white)` / `var(--c-color-bg-1)` / `var(--c-color-bg-2)` |

## 基础示例

### 填充颜色 Fill

Example source: src/style/color/__demos__/fill.vue

```vue
<template>
  <c-table :columns="columns" :data="data" :pagination="false" />
</template>

<script lang="ts" setup>
import { reactive } from "vue";
import { columns } from "./columns";

const data = reactive([
  {
    properties: "var(--c-color-fill-1)",
    description: "浅/禁用",
    class: "c-fill-1",
  },
  {
    properties: "var(--c-color-fill-2)",
    description: "常规/白底悬浮",
    class: "c-fill-2",
  },
  {
    properties: "var(--c-color-fill-3)",
    description: "深/灰底悬浮",
    class: "c-fill-3",
  },
  {
    properties: "var(--c-color-fill-4)",
    description: "重/特殊场景",
    class: "c-fill-4",
  },
]);
</script>
<style lang="scss" scoped></style>
```

## 颜色应用

### 边框颜色 Border

Example source: src/style/color/__demos__/border.vue

```vue
<template>
  <c-table :columns="columns" :data="data" :pagination="false" />
</template>

<script lang="ts" setup>
import { reactive } from "vue";
import { columns } from "./columns";

const data = reactive([
  {
    properties: "var(--c-color-border-1)",
    description: "浅色",
    class: "c-color-border-1",
  },
  {
    properties: "var(--c-color-border-2)",
    description: "一般",
    class: "c-color-border-2",
  },
  {
    properties: "var(--c-color-border-3)",
    description: "深/悬浮",
    class: "c-color-border-3",
  },
  {
    properties: "var(--c-color-border-4)",
    description: "重/按钮描边",
    class: "c-color-border-4",
  },
]);
</script>
<style lang="scss" scoped></style>
```

### 文字颜色 Text

Example source: src/style/color/__demos__/text.vue

```vue
<template>
  <c-table :columns="columns" :data="data" :pagination="false" />
</template>

<script lang="ts" setup>
import { reactive } from "vue";
import { columns } from "./columns";

const data = reactive([
  {
    properties: "var(--c-color-text-1)",
    description: "强调/正文标题、一级文字",
    class: "c-text-1",
  },
  {
    properties: "var(--c-color-text-2)",
    description: "次强调/正文标题、二级文字 图标",
    class: "c-text-2",
  },
  {
    properties: "var(--c-color-text-3)",
    description: "次要信息、三级文字",
    class: "c-text-3",
  },
  {
    properties: "var(--c-color-text-4)",
    description: "置灰禁用 / 占位",
    class: "c-text-4",
  },
]);
</script>
<style lang="scss" scoped></style>
```

### 背景颜色 Background

Example source: src/style/color/__demos__/background.vue

```vue
<template>
  <c-table :columns="columns" :data="data" :pagination="false" />
</template>

<script lang="ts" setup>
import { reactive } from "vue";
import { columns } from "./columns";

const data = reactive([
  {
    properties: "var(--c-color-bg-white)",
    description: "顶层的白色背景",
    class: "c-bg-0",
  },
  {
    properties: "var(--c-color-bg-1)",
    description: "一般/常规",
    class: "c-bg-1",
  },
  {
    properties: "var(--c-color-bg-2)",
    description: "重/特殊场景",
    class: "c-bg-2",
  },
]);
</script>
<style lang="scss" scoped></style>
```

---

Document: llms/zh-CN/components/style/elevation.md

<!-- Source: src/style/elevation/README.md; locale: zh-CN; page: /components/style/elevation/ -->

# 海拔 Elevation

Material 式海拔阴影 `c-elevation--0` … `c-elevation--24`，表现元素立体层次。

Maple 对应：`mp-elevation--0` … `mp-elevation--24`（独立引入 `elevation.css`）。

## 基础示例

### 类名

Example source: src/style/elevation/__demos__/class.vue

```vue
<template>
  <c-space direction="column" fill size="lg">
    <c-table :columns="columns" :data="data" :pagination="false" />
  </c-space>
</template>
<script lang="ts" setup>
import { h } from "vue";
import { Message } from "@cedar-design/ui";

const columns = [
  {
    title: "Class",
    dataIndex: "class",
    render: (data) => {
      return h(
        "div",
        {
          style: {
            cursor: "pointer",
          },
          onClick: () => {
            navigator.clipboard
              .writeText(data.record.class)
              .then(() => {
                Message.success("copy success");
              })
              .catch(() => {
                Message.fail("copy fail");
              });
          },
        },
        data.record.class,
      );
    },
  },
  {
    title: "Properties",
    dataIndex: "properties",
  },
];

const data = Array.from({ length: 25 }, (_, i) => ({
  class: `c-elevation--${i}`,
  properties: `Material elevation level ${i}`,
}));
</script>
```

## 阴影组合

### 示例 Demo

Example source: src/style/elevation/__demos__/demo.vue

```vue
<template>
  <c-space class="elevation-demo" :size="[24, 24]" wrap>
    <div
      v-for="level in 25"
      :key="level"
      class="elevation-item"
      :class="`c-elevation--${level - 1}`"
    >
      {{ level - 1 }}
    </div>
  </c-space>
</template>

<style lang="scss">
.elevation-demo {
  margin-top: 8px;
}

.elevation-item {
  display: flex;
  justify-content: center;
  align-items: center;
  width: 72px;
  height: 72px;
  border-radius: 4px;
  background: var(--c-color-bg-1);
}
</style>
```

---

Document: llms/zh-CN/components/style/typography.md

<!-- Source: src/style/typography/README.md; locale: zh-CN; page: /components/style/typography/ -->

# 字体排版 Typography

样式工具类，用来设置文本与排版相关属性（Cedar PC 扩展；Maple 侧栏保留同名入口，能力见 Maple Typography 说明页）。

- 点击 Class 可快捷复制
- Properties 表示该 Class 设置的属性值
- Effective CSS 表示该 Class 最终生效的 CSS 属性

## 基础示例

### 字阶

Example source: src/style/typography/__demos__/font.vue

```vue
<template>
  <c-table :columns="columns2" :data="dataFont" :pagination="false" />
</template>
<script lang="ts" setup>
import { h } from "vue";
import { Message } from "@cedar-design/ui";

const columns2 = [
  {
    title: "Class",
    dataIndex: "class",
    render: (data) => {
      return h(
        "div",
        {
          style: {
            cursor: "pointer",
          },
          onClick: () => {
            navigator.clipboard
              .writeText(data.record.class)
              .then(() => {
                Message.success("copy success");
              })
              .catch((err) => {
                Message.fail("copy fail");
              });
          },
        },
        data.record.class,
      );
    },
  },
  {
    title: "Properties/Effective CSS",
    dataIndex: "properties",
    render: (data) => {
      return [
        h("div", {
          innerHTML: `<div>${data.record.properties.replaceAll("\n", "<br/>")}</div>`, // 等效于 v-html
        }),
        h("div", {
          class: data.record.class,
          style: "margin-top: 10px;",
          innerHTML: `<div>${data.record.effective?.replaceAll("\n", "<br/>")}</div>`, // 等效于 v-html
        }),
      ];
    },
  },
];
const dataFont = [
  {
    class: "c-text-body-2-regular",
    properties:
      "font-family: var(--c-font-regular);\nfont-size: var(--c-font-size-body-1);\nfont-weight: var(--c-font-weight-regular);\nline-height: var(--c-line-height-default);",
    effective:
      "font-family:Auto;\nfont-size: 12px;\nfont-weight: 400;\nline-height: 1.5;",
  },
  {
    class: "c-text-body-2-semibold",
    properties:
      "font-family: var(--c-font-regular);\nfont-size: var(--c-font-size-body-1);\nfont-weight: var(--c-font-weight-semibold);\nline-height: var(--c-line-height-default);",
    effective:
      "font-family:Auto;\nfont-size: 12px;\nfont-weight: 600;\nline-height: 1.5;",
  },
  {
    class: "c-text-body-1-regular",
    properties:
      "font-family: var(--c-font-regular);\nfont-size: var(--c-font-size-body-2);\nfont-weight: var(--c-font-weight-regular);\nline-height: var(--c-line-height-default);",
    effective:
      "font-family:Auto;\nfont-size: 14px;\nfont-weight: 400;\nline-height: 1.5;",
  },
  {
    class: "c-text-body-1-semibold",
    properties:
      "font-family: var(--c-font-regular);\nfont-size: var(--c-font-size-body-2);\nfont-weight: var(--c-font-weight-semibold);\nline-height: var(--c-line-height-default);",
    effective:
      "font-family:Auto;\nfont-size: 14px;\nfont-weight: 600;\nline-height: 1.5;",
  },
  {
    class: "c-text-subtitle-2-regular",
    properties:
      "font-family: var(--c-font-regular);\nfont-size: var(--c-font-size-subtitle-1);\nfont-weight: var(--c-font-weight-regular);\nline-height: var(--c-line-height-default);",
    effective:
      "font-family:Auto;\nfont-size: 16px;\nfont-weight: 400;\nline-height: 1.5;",
  },
  {
    class: "c-text-subtitle-2-semibold",
    properties:
      "font-family: var(--c-font-regular);\nfont-size: var(--c-font-size-subtitle-1);\nfont-weight: var(--c-font-weight-semibold);\nline-height: var(--c-line-height-default);",
    effective:
      "font-family:Auto;\nfont-size: 16px;\nfont-weight: 600;\nline-height: 1.5;",
  },
  {
    class: "c-text-subtitle-1-regular",
    properties:
      "font-family: var(--c-font-regular);\nfont-size: var(--c-font-size-subtitle-2);\nfont-weight: var(--c-font-weight-regular);\nline-height: var(--c-line-height-default);",
    effective:
      "font-family:Auto;\nfont-size: 18px;\nfont-weight: 400;\nline-height: 1.5;",
  },
  {
    class: "c-text-subtitle-1-semibold",
    properties:
      "font-family: var(--c-font-regular);\nfont-size: var(--c-font-size-subtitle-2);\nfont-weight: var(--c-font-weight-semibold);\nline-height: var(--c-line-height-default);",
    effective:
      "font-family:Auto;\nfont-size: 18px;\nfont-weight: 600;\nline-height: 1.5;",
  },
  {
    class: "c-text-heading-4-semibold",
    properties:
      "font-family: var(--c-font-regular);\nfont-size: var(--c-font-size-heading-1);\nfont-weight: var(--c-font-weight-semibold);\nline-height: var(--c-line-height-default);",
    effective:
      "font-family:Auto;\nfont-size: 20px;\nfont-weight: 600;\nline-height: 1.5;",
  },
  {
    class: "c-text-heading-3-semibold",
    properties:
      "font-family: var(--c-font-regular);\nfont-size: var(--c-font-size-heading-2);\nfont-weight: var(--c-font-weight-semibold);\nline-height: var(--c-line-height-default);",
    effective:
      "font-family:Auto;\nfont-size: 24px;\nfont-weight: 600;\nline-height: 1.5;",
  },
  {
    class: "c-text-heading-2-semibold",
    properties:
      "font-family: var(--c-font-regular);\nfont-size: var(--c-font-size-heading-3);\nfont-weight: var(--c-font-weight-semibold);\nline-height: var(--c-line-height-default);",
    effective:
      "font-family:Auto;\nfont-size: 32px;\nfont-weight: 600;\nline-height: 1.5;",
  },
  {
    class: "c-text-heading-1-semibold",
    properties:
      "font-family: var(--c-font-regular);\nfont-size: var(--c-font-size-heading-4);\nfont-weight: var(--c-font-weight-semibold);\nline-height: var(--c-line-height-default);",
    effective:
      "font-family:Auto;\nfont-size: 40px;\nfont-weight: 600;\nline-height: 1.5;",
  },
  {
    class: "text-number-7-regular",
    properties:
      "font-family: var(--c-font-number-regular);\nfont-size: var(--c-font-size-body-2);\nfont-weight: var(--c-font-weight-regular);\nline-height: var(--c-line-height-default);",
    effective:
      "font-family: Barlow;\nfont-size: 14px;\nfont-weight: 400;\nline-height: 1.5;",
  },
  {
    class: "text-number-7-bold",
    properties:
      "font-family: var(--c-font-number-bold);\nfont-size: var(--c-font-size-body-2);\nfont-weight: var(--c-font-weight-blod);\nline-height: var(--c-line-height-default);",
    effective:
      "font-family: Barlow;\nfont-size: 14px;\nfont-weight: 700;\nline-height: 1.5;",
  },
  {
    class: "text-number-6-regular",
    properties:
      "font-family: var(--c-font-number-regular);\nfont-size: var(--c-font-size-subtitle-1);\nfont-weight: var(--c-font-weight-regular);\nline-height: var(--c-line-height-default);",
    effective:
      "font-family: Barlow;\nfont-size: 16px;\nfont-weight: 400;\nline-height: 1.5;",
  },
  {
    class: "text-number-6-bold",
    properties:
      "font-family: var(--c-font-number-bold);\nfont-size: var(--c-font-size-subtitle-1);\nfont-weight: var(--c-font-weight-bold);\nline-height: var(--c-line-height-default);",
    effective:
      "font-family: Barlow;\nfont-size: 16px;\nfont-weight: 700;\nline-height: 1.5;",
  },
  {
    class: "text-number-5-bold",
    properties:
      "font-family: var(--c-font-number-bold);\nfont-size: var(--c-font-size-subtitle-2);\nfont-weight: var(--c-font-weight-bold);\nline-height: var(--c-line-height-default);",
    effective:
      "font-family: Barlow;\nfont-size: 18px;\nfont-weight: 700;\nline-height: 1.5;",
  },
  {
    class: "text-number-4-bold",
    properties:
      "font-family: var(--c-font-number-bold);\nfont-size: var(--c-font-size-heading-1);\nfont-weight: var(--c-font-weight-bold);\nline-height: 24px;",
    effective:
      "font-family: Barlow;\nfont-size: 20px;\nfont-weight: 700;\nline-height: 1;",
  },
  {
    class: "text-number-3-bold",
    properties:
      "font-family: var(--c-font-number-bold);\nfont-size: var(--c-font-size-heading-2);\nfont-weight: var(--c-font-weight-bold);\nline-height: 29px;",
    effective:
      "font-family: Barlow;\nfont-size: 24px;\nfont-weight: 700;\nline-height: 1;",
  },
  {
    class: "text-number-2-bold",
    properties:
      "font-family: var(--c-font-number-bold);\nfont-size: var(--c-font-size-heading-3);\nfont-weight: var(--c-font-weight-bold);\nline-height: 38px;",
    effective:
      "font-family: Barlow;\nfont-size: 32px;\nfont-weight: 700;\nline-height: 1;",
  },
  {
    class: "text-number-1-bold",
    properties:
      "font-family: var(--c-font-number-bold);\nfont-size: var(--c-font-size-heading-4);\nfont-weight: var(--c-font-weight-bold);\nline-height: 48px;",
    effective:
      "font-family: Barlow;\nfont-size: 40px;\nfont-weight: 700;\nline-height: 1;",
  },
];
</script>

<style lang="scss">
.table-line-height-unset .c-table-td {
  line-height: unset;
}
</style>
```

## 字号与字形

### 字号

Example source: src/style/typography/__demos__/font-size.vue

```vue
<template>
  <c-table
    :columns="columns"
    :data="dataSize"
    :pagination="false"
    class="table-line-height-unset"
  />
</template>
<script lang="ts" setup>
import { columns } from "./columns";

const dataSize = [
  {
    class: "font-size-body-1",
    properties: "font-size: var(--c-font-size-body-1);",
    effective: "font-size: 12px;",
  },
  {
    class: "font-size-body-2",
    properties: "font-size: var(--c-font-size-body-2);",
    effective: "font-size: 14px;",
  },
  {
    class: "font-size-subtitle-1",
    properties: "font-size: var(--c-font-size-subtitle-1);",
    effective: "font-size: 16px;",
  },
  {
    class: "font-size-subtitle-2",
    properties: "font-size: var(--c-font-size-subtitle-2);",
    effective: "font-size: 18px;",
  },
  {
    class: "font-size-heading-1",
    properties: "font-size: var(--c-font-size-heading-1);",
    effective: "font-size: 20px;",
  },
  {
    class: "font-size-heading-2",
    properties: "font-size: var(--c-font-size-heading-2);",
    effective: "font-size: 24px;",
  },
  {
    class: "font-size-heading-3",
    properties: "font-size: var(--c-font-size-heading-3);",
    effective: "font-size: 32px;",
  },
  {
    class: "font-size-heading-4",
    properties: "font-size: var(--c-font-size-heading-4);",
    effective: "font-size: 40px;",
  },
  {
    class: "font-size-display-1",
    properties: "font-size: var(--c-font-size-display-1);",
    effective: "font-size: 48px;",
  },
  {
    class: "font-size-display-2",
    properties: "font-size: var(--c-font-size-display-2);",
    effective: "font-size: 56px;",
  },
];
</script>

<style lang="scss">
.table-line-height-unset .c-table-td {
  line-height: unset;
}
</style>
```

### 字族

Example source: src/style/typography/__demos__/font-family.vue

```vue
<template>
  <c-table :columns="columns" :data="dataFamily" :pagination="false" />
</template>
<script lang="ts" setup>
import { columns } from "./columns";

const dataFamily = [
  {
    class: "font-regular",
    properties: "font-family: var(--c-font-regular);",
    effective: "font-family: Auto;",
  },
  {
    class: "font-number",
    properties: "font-family: var(--c-font-number-bold);",
    effective: "font-family: Barlow-Bold;",
  },
  {
    class: "font-number-regular",
    properties: "font-family: var(--c-font-number-regular);",
    effective: "font-family: Barlow-Regular;",
  },
  {
    class: "font-number-bold",
    properties: "font-family: var(--c-font-number-bold);",
    effective: "font-family: Barlow-Bold;",
  },
];
</script>

<style lang="scss">
.table-line-height-unset .c-table-td {
  line-height: unset;
}
</style>
```

### 字重

Example source: src/style/typography/__demos__/font-weight.vue

```vue
<template>
  <c-table :columns="columns" :data="dataWeight" :pagination="false" />
</template>
<script lang="ts" setup>
import { columns } from "./columns";

const dataWeight = [
  {
    class: "font-weight-thin",
    properties: "font-weight: var(--c-font-weight-thin);",
    effective: "font-weight: 100;",
  },
  {
    class: "font-weight-x-light",
    properties: "font-weight: var(--c-font-weight-x-light);",
    effective: "font-weight: 200;",
  },
  {
    class: "font-weight-light",
    properties: "font-weight: var(--c-font-weight-light);",
    effective: "font-weight: 300;",
  },
  {
    class: "font-weight-regular",
    properties: "font-weight: var(--c-font-weight-regular);",
    effective: "font-weight: 400;",
  },
  {
    class: "font-weight-medium",
    properties: "font-weight: var(--c-font-weight-medium);",
    effective: "font-weight: 500;",
  },
  {
    class: "font-weight-semibold",
    properties: "font-weight: var(--c-font-weight-semibold);",
    effective: "font-weight: 600;",
  },
  {
    class: "font-weight-bold",
    properties: "font-weight: var(--c-font-weight-bold);",
    effective: "font-weight: 700;",
  },
  {
    class: "font-weight-x-bold",
    properties: "font-weight: var(--c-font-weight-x-bold);",
    effective: "font-weight: 800;",
  },
  {
    class: "font-weight-xx-bold",
    properties: "font-weight: var(--c-font-weight-xx-bold);",
    effective: "font-weight: 900;",
  },
];
</script>

<style lang="scss"></style>
```

## 对齐与行高

### 文本对齐

Example source: src/style/typography/__demos__/text-align.vue

```vue
<template>
  <c-table :columns="columns" :data="data" :pagination="false" />
</template>
<script lang="ts" setup>
import { h } from "vue";
import { Message } from "@cedar-design/ui";

const columns = [
  {
    title: "Class",
    dataIndex: "class",
    render: (data) => {
      return h(
        "div",
        {
          style: {
            cursor: "pointer",
          },
          onClick: () => {
            navigator.clipboard
              .writeText(data.record.class)
              .then(() => {
                Message.success("copy success");
              })
              .catch((err) => {
                Message.fail("copy fail");
              });
          },
        },
        data.record.class,
      );
    },
  },
  {
    title: "Effective CSS",
    dataIndex: "effective",
    render: (data) => {
      return h("div", {
        innerHTML: `<div>${data.record.effective?.replaceAll("\n", "<br/>")}</div>`, // 等效于 v-html
      });
    },
  },
];
const data = [
  {
    class: "c-text-left",
    properties: "text-align: left !important;",
    effective: "text-align: left !important;",
  },
  {
    class: "c-text-center",
    properties: "text-align: center !important;",
    effective: "text-align: center !important;",
  },
  {
    class: "c-text-right",
    properties: "text-align: right !important;",
    effective: "text-align: right !important;",
  },
  {
    class: "c-text-justify",
    properties: "text-align: justify !important;",
    effective: "text-align: justify !important;",
  },
];
</script>

<style lang="scss"></style>
```

### 行高

Example source: src/style/typography/__demos__/line-height.vue

```vue
<template>
  <c-table :columns="columns" :data="dataLineHeight" :pagination="false" />
</template>
<script lang="ts" setup>
import { columns } from "./columns";

const dataLineHeight = [
  {
    class: "line-height-1",
    properties: "line-height: var(--c-line-height-default);",
    effective: "line-height: 1.5;",
  },
];
</script>

<style lang="scss"></style>
```

---

Document: llms/zh-CN/components/style/utilities.md

<!-- Source: src/style/utilities/README.md; locale: zh-CN; page: /components/style/utilities/ -->

# Utilities 工具类总览

Cedar / Maple 语义与结构一致，**类名必须带库前缀**（`c-` / `mp-`），变量分别为 `--c-*` / `--mp-*`，避免两端混用撞名。  
不做无前缀别名，不做向后兼容。

|               | Cedar                                                    | Maple                                                                |
| ------------- | -------------------------------------------------------- | -------------------------------------------------------------------- |
| 类名          | `c-text-1`、`c-mt-16`                                    | `mp-text-1`、`mp-mt-16`                                              |
| 形态          | 固定 Utilities + Uno/TW preset                           | 独立 Utilities + Uno/TW preset                                       |
| Token         | `--c-*`                                                  | `--mp-*`                                                             |
| 暗色          | 只改 token，类名不变                                     | 同左                                                                 |
| 原子化 preset | `@cedar-design/preset-unocss` / `@cedar-design/preset-tailwindcss` | `@maple-design/preset-unocss` / `@maple-design/preset-tailwindcss` |

完整规范见 [Utility 工具类规范](llms/zh-CN/practices/utility-spec.md)。色阶变量（`--c-red-1…10` 等）见 [Palette](llms/zh-CN/components/palette.md)，不进默认工具包。

## 基础示例

### 快速预览

Example source: src/style/utilities/__demos__/overview.vue

```vue
<template>
  <div class="overview">
    <section class="block">
      <div class="label c-text-3">Color text</div>
      <div class="row c-flex c-items-center">
        <span class="c-text-1 c-mr-16">c-text-1</span>
        <span class="c-text-2 c-mr-16">c-text-2</span>
        <span class="c-text-3 c-mr-16">c-text-3</span>
        <span class="c-text-4">c-text-4</span>
      </div>
    </section>

    <section class="block c-mt-24">
      <div class="label c-text-3">Background</div>
      <div class="row c-flex c-items-center">
        <div class="swatch c-bg-0 border-box c-p-8 c-mr-8">c-bg-0</div>
        <div class="swatch c-bg-1 c-p-8 c-mr-8">c-bg-1</div>
        <div class="swatch c-bg-2 c-p-8">c-bg-2</div>
      </div>
    </section>

    <section class="block c-mt-24">
      <div class="label c-text-3">Spacing</div>
      <div class="spacing-stage c-fill-2 c-p-16">
        <div class="box c-fill-2 c-mt-16 c-px-8">
          <div class="inner c-bg-0">c-mt-16 c-px-8</div>
        </div>
        <div class="box c-fill-3 c-mx-16 c-py-8">
          <div class="inner c-bg-0">c-mx-16 c-py-8</div>
        </div>
        <div class="box c-fill-4 c-p-24">
          <div class="inner c-bg-0">c-p-24</div>
        </div>
      </div>
    </section>

    <section class="block c-mt-24">
      <div class="label c-text-3">Flex</div>
      <div class="c-flex c-justify-between c-items-center c-fill-2 c-p-16">
        <div class="chip c-fill-1 c-p-8">start</div>
        <div class="chip c-fill-2 c-p-8">between</div>
        <div class="chip c-fill-3 c-p-8">end</div>
      </div>
    </section>
  </div>
</template>

<script lang="ts" setup></script>

<style lang="scss" scoped>
.overview {
  font-size: 13px;
}

.label {
  margin-bottom: 8px;
}

.swatch {
  min-width: 72px;
  text-align: center;
  border: 1px solid var(--c-color-border-2);
}

.border-box {
  border: 1px solid var(--c-color-border-2);
}

.spacing-stage {
  display: flex;
  flex-wrap: wrap;
  gap: 8px;
}

.box {
  display: inline-block;
}

.inner {
  min-width: 88px;
  text-align: center;
  line-height: 32px;
}

.chip {
  min-width: 64px;
  text-align: center;
}
</style>
```

### 分册

| 页面                                                 | 内容                                         |
| ---------------------------------------------------- | -------------------------------------------- |
| [颜色 Color](llms/zh-CN/components/style/color.md)                     | 文字 / 填充 / 边框 / 背景层级                |
| [常用写法](llms/zh-CN/components/style/atomic-usage.md)          | Flex / 间距 / 尺寸 / 溢出 / 圆角等日常原子类 |
| [海拔 Elevation](llms/zh-CN/components/style/elevation.md)       | `c-elevation--0` … `--24`                    |
| [字体排版 Typography](llms/zh-CN/components/style/typography.md) | PC 排版工具包                                |
| [原子化 CSS](llms/zh-CN/components/style/atomic-css.md)          | Uno / TW 安装与配置                          |

---

Document: llms/zh-CN/components/switch.md

<!-- Source: src/switch/README.md; locale: zh-CN; page: /components/switch/ -->

# Switch

与 Maple 使用相同场景、参数和交互顺序；示例源码仅替换组件前缀，主题与站点外壳各自保留。

## 阅读方向

开关继承来源 dir：未选中手柄位于阅读起点，选中后向阅读终点移动。Space/Enter 仍表示切换；方向变化本身不改变业务值，禁用、只读和 loading 时不提交切换。

## 基础示例

### 双向绑定与默认值

Example source: src/switch/__demos__/basic.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const enabled = ref(false)
</script>

<template>
  <c-space wrap
    ><c-switch v-model="enabled" aria-label="Enable notifications" /><output>{{ enabled }}</output
    ><c-switch :default-value="true" aria-label="Initially enabled"
  /></c-space>
</template>
```

## 外观与状态

### 外观配置对比

选择一个对比维度后，同屏展示它的全部可选值；其余配置和内容保持一致。可切换其他配置检查组合效果；输入类预览共享一个值。

<details>
<summary>配置说明与使用限制</summary>

#### 外观组合

适用于即时生效的开关设置。调整变体、尺寸，用相同数据观察变化。内容保持一致，便于比较不同设置的实际效果。

</details>

Example source: src/switch/__demos__/appearance-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref(false);
const __demoAppearance = __demoReactive({ variant: "circle", size: "md" });

import { computed as demoComputed, ref as demoRef } from 'vue'
const demoCompareFields = [{"name":"variant","values":["circle","round","line","tonal"]},{"name":"size","values":["sm","md","lg"]}]
const demoCompareAxis = demoRef("variant")
const demoComparedOptions = demoComputed(() => demoCompareFields.find(field => field.name === demoCompareAxis.value)?.values ?? [])
</script>
<template>
  <c-space direction="column" :size="16">
    <c-form layout="vertical">
      <c-form-item layout="vertical" size="sm" label="variant">
        <c-radio-group
          v-model="__demoAppearance['variant']"
          aria-label="variant"
          :options="[
            { label: 'circle', value: 'circle' },
            { label: 'round', value: 'round' },
            { label: 'line', value: 'line' },
            { label: 'tonal', value: 'tonal' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
      <c-form-item layout="vertical" size="sm" label="size">
        <c-radio-group
          v-model="__demoAppearance['size']"
          aria-label="size"
          :options="[
            { label: 'sm', value: 'sm' },
            { label: 'md', value: 'md' },
            { label: 'lg', value: 'lg' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
    </c-form>
    <p class="demo-config-comparison-hint"><span lang="zh-CN">选择一个对比维度；其他配置和内容保持一致。输入类示例共享同一个值，便于比较外观。</span><span lang="en-US">Compare one dimension while keeping the other settings and content identical. Input specimens share the same value.</span></p>
<c-radio-group v-model="demoCompareAxis" aria-label="Compare configuration" :options="demoCompareFields.map(field => ({ label: field.name, value: field.name }))" />
<div class="demo-config-comparison">
<section v-for="sample in demoComparedOptions" :key="String(sample)">
<p><code>{{ demoCompareAxis }}={{ sample }}</code></p>
<c-switch v-model="value" v-bind="{ ...__demoAppearance, [demoCompareAxis]: sample }"></c-switch>
</section>
</div>
  </c-space>
</template>

<style scoped>
.demo-config-comparison { display: grid; grid-template-columns: repeat(auto-fit, minmax(min(100%, 220px), 1fr)); gap: 20px; min-width: 0; max-width: 100%; }
.demo-config-comparison > section { min-width: 0; }
.demo-config-comparison p { margin: 0 0 8px; }
html:not([lang='en-US']) .demo-config-comparison-hint > [lang='en-US'],
html[lang='en-US'] .demo-config-comparison-hint > [lang='zh-CN'] { display: none; }
</style>
```

## 自定义与插槽

### 自定义颜色

<!-- demo-config-notes:start -->

#### 本组配置对照

| 配置              | 作用           | 相关示例               |
| ----------------- | -------------- | ---------------------- |
| `variant`         | 造型           | 自定义文字、自定义图标 |
| `checked-color`   | 选中轨道颜色   | 自定义颜色             |
| `unchecked-color` | 未选中轨道颜色 | 自定义颜色             |
| `checked-text`    | 选中文案       | 自定义文字             |
| `unchecked-text`  | 未选中文案     | 自定义文字             |
| `ripple`          | 点击波纹       | 水波与滑块阴影         |

<!-- demo-config-notes:end -->

Example source: src/switch/__demos__/custom-color.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const enabled = ref(false)
</script>

<template>
  <c-switch
    v-model="enabled"
    checked-color="#005f73"
    unchecked-color="#9b2226"
    aria-label="Custom color switch"
  />
</template>
```

### 自定义文字

Example source: src/switch/__demos__/custom-text.vue

```vue
<template>
  <c-space wrap
    ><c-switch checked-text="ON" unchecked-text="OFF" aria-label="Text props" /><c-switch
      variant="round"
      aria-label="Text slots"
      ><template #checked>ON</template><template #unchecked>OFF</template></c-switch
    ></c-space
  >
</template>
```

### 自定义图标

Example source: src/switch/__demos__/custom-icon.vue

```vue
<script setup lang="ts">
const variants = ['circle', 'round', 'line', 'tonal'] as const
</script>

<template>
  <c-space wrap
    ><c-switch v-for="variant in variants" :key="variant" :variant="variant" :aria-label="variant"
      ><template #checked-icon>✓</template><template #unchecked-icon>×</template></c-switch
    ></c-space
  >
</template>
```

### 水波与滑块阴影

Example source: src/switch/__demos__/custom.vue

```vue
<template>
  <c-space wrap
    ><c-switch :ripple="false" :handle-elevation="false" aria-label="No ripple or shadow" /><c-switch
      :handle-elevation="4"
      aria-label="Elevated handle"
  /></c-space>
</template>
```

## 交互与控制

### 交互状态对比

<!-- demo-config-notes:start -->

#### 本组配置对照

| 配置            | 作用                                                      | 相关示例       |
| --------------- | --------------------------------------------------------- | -------------- |
| `disabled`      | 禁用；表单禁用也阻止交互                                  | 交互状态对比   |
| `readonly`      | 只读；仍可聚焦与通知 click，不切换                        | 交互状态对比   |
| `variant`       | 造型                                                      | 加载中         |
| `loading`       | 加载中；禁止 click 和切换                                 | 加载中         |
| `default-value` | 非受控初始实际值，仅创建时读取；省略时使用 uncheckedValue | 加载中         |
| `size`          | 尺寸档位；省略时见跨端说明                                | 焦点与事件顺序 |

<!-- demo-config-notes:end -->

在同一实例上切换禁用、只读和错误状态后再操作控件，比较可编辑性和交互反馈。恢复开关位于目标控件外；错误外观本身不会执行校验。

<details>
<summary>配置说明与使用限制</summary>

#### 交互状态切换

适用于即时生效的开关设置。调整禁用、只读，用相同数据观察变化。控制区始终可用，可以随时恢复编辑；错误外观本身不会触发表单校验。

</details>

Example source: src/switch/__demos__/state-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref(false);
const __demoState = __demoReactive({ disabled: false, readonly: false });
</script>
<template>
  <c-space direction="column" :size="16">
    <c-space wrap>
      <c-checkbox v-model="__demoState['disabled']">disabled</c-checkbox>
      <c-checkbox v-model="__demoState['readonly']">readonly</c-checkbox>
    </c-space>
    <c-switch v-model="value" v-bind="__demoState"></c-switch>
  </c-space>
</template>
```

### 加载中

Example source: src/switch/__demos__/loading.vue

```vue
<script setup lang="ts">
const variants = ['circle', 'round', 'line', 'tonal'] as const
</script>

<template>
  <c-space wrap
    ><template v-for="variant in variants" :key="variant"
      ><c-switch :variant="variant" loading :aria-label="variant + ' off'" /><c-switch
        :variant="variant"
        :default-value="true"
        loading
        :aria-label="variant + ' on'" /></template
  ></c-space>
</template>
```

### 焦点与事件顺序

Example source: src/switch/__demos__/events.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const value = ref(false)
const events = ref<string[]>([])
function record(name: string) {
  events.value = [...events.value.slice(-7), name]
}
</script>

<template>
  <p>Use Tab to focus, then Space or Enter to toggle.</p>
  <c-switch
    v-model="value"
    size="md"
    aria-label="Event sequence"
    @focus="record('focus')"
    @blur="record('blur')"
    @click="record('click')"
    @update:model-value="record(`update: ${$event}`)"
    @change="record(`change: ${$event}`)"
  />
  <p aria-live="polite">{{ events.join(' → ') || 'No events yet' }}</p>
  <c-button @click="events = []">Clear events</c-button>
</template>
```

### 自定义值与事件

Example source: src/switch/__demos__/custom-value.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const value = ref('disabled')
const lastChange = ref('—')
</script>

<template>
  <c-space direction="column"
    ><c-switch
      v-model="value"
      checked-value="enabled"
      unchecked-value="disabled"
      aria-label="String value"
      @change="lastChange = String($event)"
    /><output aria-live="polite">Value: {{ value }}; change: {{ lastChange }}</output></c-space
  >
</template>
```

## 异步与动态数据

### 异步允许、阻止与异常

Example source: src/switch/__demos__/switch-interception.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const result = ref('Ready')
const wait = () => new Promise<void>((resolve) => setTimeout(resolve, 500))
async function allow() {
  await wait()
  result.value = 'Allowed'
  return true
}
async function deny() {
  await wait()
  result.value = 'Blocked'
  return false
}
async function reject() {
  await wait()
  result.value = 'Rejected'
  throw new Error('Demo rejection')
}
</script>

<template>
  <c-space direction="column">
    <label>Allow after 500ms <c-switch :before-change="allow" aria-label="Async allow" /></label>
    <label>Return false <c-switch :before-change="deny" aria-label="Async deny" /></label>
    <label>Reject Promise <c-switch :before-change="reject" aria-label="Async rejection" /></label>
    <output aria-live="polite">{{ result }}</output>
  </c-space>
</template>
```

## API

### 空值识别与阅读空文案

`empty-values` 用于空值识别，`empty-value` 保留原清空输出；`empty-text` 仅在 `read-pretty` 空内容下展示，默认 `'-'`，字段 > FormItem > Form，自定义 read 插槽优先。显式配置 empty-values 后，内置 required 接入该策略，自定义校验仍收到原值。详见[统一说明](llms/zh-CN/guide/empty-values.md)。

| 参数         | 类型               | 缺省与范围                                            |
| ------------ | ------------------ | ----------------------------------------------------- |
| empty-values | readonly unknown[] | 字段 > FormItem > Form > 组件族默认；完整覆盖，不合并 |
| empty-text   | string             | 字段 > FormItem > Form > '-'；显式 '' 有效            |

以上是字段展示层 API；纯面板不因此新增阅读模式。Form 与 FormItem 提供继承配置。empty-value 的现有类型与默认输出仍按该组件原 API 执行。

### 主值与默认值

使用普通 `v-model`。`modelValue` 表示开关的实际值，类型与 checkedValue/uncheckedValue 一致；`defaultValue` 仅在创建时初始化非受控值，后续修改不会重置当前状态。显式绑定值优先，初始化不发出 `update:modelValue`。

<!-- same-source-api:start -->

### Props

| Prop             | 含义                                                         | 类型                                                                 | 默认值    |
| ---------------- | ------------------------------------------------------------ | -------------------------------------------------------------------- | --------- |
| model-value      | 受控值；省略时内部管理                                       | string / number / boolean                                            | undefined |
| default-value    | 非受控初始实际值，仅创建时读取；省略时使用 uncheckedValue    | string / number / boolean                                            | undefined |
| clearable        | 弹出编辑时显示清空操作                                       | boolean                                                              | false     |
| empty-value      | 清空后提交的值，可传值或工厂函数                             | SwitchValue \| null \| (() => SwitchValue \| null)                   | undefined |
| edit-mode        | 编辑模式；未设置时继承 FormItem/Form，平台值域见编辑模式说明 | FieldEditMode                                                        | undefined |
| read-pretty      | 纯阅读展示，独立于 readonly                                  | boolean                                                              | undefined |
| before-commit    | 编辑层保存前的可取消拦截器                                   | BeforeFieldCommit                                                    | undefined |
| open             | 编辑层受控打开状态                                           | boolean                                                              | undefined |
| default-open     | 编辑层非受控初始状态                                         | boolean                                                              | false     |
| popup-container  | 编辑层挂载容器                                               | PopupContainer                                                       | undefined |
| checked-value    | 选中值                                                       | string / number / boolean                                            | true      |
| unchecked-value  | 未选中值                                                     | string / number / boolean                                            | false     |
| variant          | 造型                                                         | circle / round / line / tonal                                        | circle    |
| size             | 尺寸档位；省略时见跨端说明                                   | sm / md / lg                                                         | undefined |
| disabled         | 禁用；表单禁用也阻止交互                                     | boolean                                                              | undefined |
| readonly         | 只读；仍可聚焦与通知 click，不切换                           | boolean                                                              | undefined |
| loading          | 加载中；禁止 click 和切换                                    | boolean                                                              | false     |
| before-change    | 切换拦截器，不是事件                                         | (payload, done, context) => boolean / void / Promise<boolean / void> | —         |
| checked-text     | 选中文案                                                     | string                                                               | —         |
| unchecked-text   | 未选中文案                                                   | string                                                               | —         |
| checked-color    | 选中轨道颜色                                                 | string                                                               | —         |
| unchecked-color  | 未选中轨道颜色                                               | string                                                               | —         |
| loading-color    | 加载图标颜色                                                 | string                                                               | —         |
| ripple           | 点击波纹                                                     | boolean                                                              | true      |
| handle-elevation | 滑块阴影，true 等级 2，数字取整数并限制 0～24                | boolean / number                                                     | true      |

before-change 返回 false、抛错或拒绝 Promise 均取消切换；其他正常完成允许切换。等待 Promise 或 done 期间自动 loading，重复输入被阻止。
等待期间卸载、KeepAlive 停用、值被外部更新、禁用/只读/loading 状态改变时，旧结果失效。
受控模式仅发送更新请求；父级更新 model-value 后才改变选中状态。省略 model-value 时使用内部状态。

### Events

| 事件               | 参数与时机                                           |
| ------------------ | ---------------------------------------------------- |
| click              | (event: Event)，允许点击时，拦截前                   |
| update:model-value | (nextValue: SwitchValue)，允许切换后，先于 change    |
| change             | (nextValue: SwitchValue, event: Event)，每次提交一次 |
| focus              | (event: FocusEvent)，获得焦点                        |
| blur               | (event: FocusEvent)，失去焦点                        |

支持 Enter、Space；按键长按重复不重复切换。disabled/loading 不触发 click 或值变化；readonly 可通知 click，但不执行拦截器。
外部 model-value 更新不会额外触发 change。

### Slots

| 插槽           | 说明                                                 | 参数 |
| -------------- | ---------------------------------------------------- | ---- |
| checked        | 选中文案，优先于 checked-text；line 与 sm 不展示     | —    |
| unchecked      | 未选中文案，优先于 unchecked-text；line 与 sm 不展示 | —    |
| checked-icon   | 选中滑块图标，loading 时被加载图标替代               | —    |
| unchecked-icon | 未选中滑块图标，loading 时被加载图标替代             | —    |

### Methods

无公开方法。

### 跨端说明

组件属性、事件参数和插槽一致。Cedar 省略 size 时继承表单／全局尺寸（xs/sm 映射 sm，lg/xl 映射 lg）；Maple 回退 md。两端的 disabled / readonly 均按字段 > FormItem > Form 继承，显式 false 覆盖父级；表单集成由各端适配。
<!-- same-source-api:end -->

### 类型

SwitchProps、SwitchVariant、SwitchSize、SwitchValue、SwitchBeforeChange、SwitchInstance 均由根入口及组件入口导出。

### 样式变量

| Token（Cedar 使用 --c-，Maple 使用 --mp-）                | 默认值                              |
| --------------------------------------------------------- | ----------------------------------- |
| --c-switch-width / height / handle-size                   | 40px / 24px / 16px                  |
| --c-switch-size-sm-scale / size-lg-scale                  | .8 / 1.2                            |
| --c-switch-tonal-width / tonal-height / tonal-handle-size | 52px / 32px / 24px                  |
| --c-switch-line-height / line-handle-size                 | 12px / 20px                         |
| --c-switch-hit-area                                       | 0px，点击区域向外扩展量，不改变布局 |
| --c-switch-track-background / track-active-background     | 中性色 / 主题色                     |
| --c-switch-handle-background / handle-color               | 白色 / 主题色                       |
| --c-switch-disabled-opacity                               | .5                                  |
| --c-switch-round-radius / gap                             | 4px / 4px                           |

完整可调变量见 style/token.less；旧版各端 Switch 几何 token 不保证保留。

## 迁移

Maple standard → line；不传 variant 现在使用 circle。两端统一四变体，不将 standard 保留为别名。
移除 lazy-change；before-change 从 (value, change) 回调改为返回值/Promise，应用不再手动调用 change。
Maple change 补齐第二个原始事件参数；checked-color/unchecked-color 统一控制轨道，滑块颜色通过 token 定制。

### 颜色变量与 tonal 前景迁移

| 变量后缀（--c-switch-） | system 默认角色   | 职责                                     |
| ----------------------- | ----------------- | ---------------------------------------- |
| track-background        | content-secondary | 普通未选中实心轨道                       |
| track-active-background | content-brand     | 选中轨道及键盘焦点环                     |
| track-error-background  | content-danger    | 可交互错误轨道及 tonal 错误边框          |
| handle-background       | surface-default   | 普通／选中／错误滑块底色                 |
| handle-color            | content-brand     | 普通／选中／错误滑块图标色               |
| text-color              | surface-default   | 实心轨道上的文字色                       |
| checked-text-color      | switch-text-color | 选中轨道文字；错误态仍遵循原有前景优先级 |
| tonal-track-background  | surface-muted     | tonal 未选中轨道底色                     |
| tonal-border-color      | content-secondary | tonal 未选中边框及滑块底色               |
| tonal-text-color        | content-secondary | 新增：tonal 未选中轨道文字               |
| tonal-handle-color      | surface-default   | 新增：tonal 未选中滑块图标               |

默认值引用对应 system 角色，例如 var(--c-sys-color-content-secondary)。tonal 未选中时使用 tonal-text-color / tonal-handle-color；需要全变体定制时请同时覆盖普通和 tonal 前景。可交互错误态使用普通文字／滑块配对，disabled / loading 抑制错误色。自定义轨道颜色需自行验证前景对比。阴影、尺寸及动效不在本批颜色契约中。

### 主题名与造型名

当前主题入口为 Themes.default.light / dark 与 Themes.maple.light / dark。Switch 的 tonal 是造型，不是主题；公开变体与八项专用变量统一使用 tonal 命名，不保留旧名称别名。

### 动效变量

内置动效遵循 `prefers-reduced-motion: reduce`；减少动效不会阻止加载状态或关闭事件更新。

| Token                         | Default |
| ----------------------------- | ------- |
| `--c-switch-loading-duration` | `1s`    |

### Form 字段展示与确认

本组件支持 `edit-mode`，字段 > FormItem > Form 逐层继承；未指定时为 `direct`，保留原有交互。支持值：`direct / click / dblclick`。非 direct 编辑模式通过字段值入口打开编辑面板，并维护单份草稿；确认后才更新 v-model，取消、重置或启用 readPretty 时丢弃草稿。

Cedar 使用 edit-mode="click" / "dblclick" 在字段附近打开编辑浮层，Enter/F2 也可进入；取消/Escape 丢弃草稿，确认后提交。readPretty 为独立阅读属性，与 readonly、disabled 分开。

`before-commit(value, { previousValue, signal })` 可拦截弹层保存；FormItem 先校验候选值，失败保持编辑。`open / default-open / update:open` 控制编辑层。`#read="{ value, text }"` 可自定义阅读内容。集中示例见 Form 的“各类字段统一展示”。

`read-pretty` 为独立布尔属性，与 `readonly`、`disabled` 同级；字段 > FormItem > Form 继承，显式 `false` 覆盖父级。默认 `false`。纯阅读不显示编辑器。

### 表单状态继承

省略 `disabled` / `readonly` 时依次继承 FormItem、Form；显式 `false` 覆盖父级。等待 `beforeChange` 时，父级变为禁用或只读会使此次切换失效，迟到结果不再改值。表单外省略时仍表现为 false。

## 表单 disabled 的继承

disabled 默认 undefined 表示继承，有效状态按 local ?? FormItem ?? Form ?? false 解析。显式 false 不会被吞掉，可以让一个字段保持可用，其他未指定字段仍跟随 Form。Form disabled 仍是整张表单的默认策略，不是禁止所有子项覆盖的强制锁。

`empty-value` 可显式设为 `null`（或 `() => null`），清空时原样提交 null；省略时保留组件原默认值。界面把 null 显示为空，不会把普通输入的空字符串自动转成 null。支持弹出编辑的字段中，清空先修改草稿，确认后提交，取消则保留原值。

```vue
<c-switch v-model="flag" :before-change="beforeChange" />
```

```ts
const beforeChange = (next, done) => {
  canChange(next).then((allowed) => done(allowed));
};
```

守卫统一使用 `(payload, done, context)`：关闭 payload 为 `{ action }`，切换和提交为 `{ value, previousValue }`，Popup 为 `{ reason }`。context 提供 `signal` 和可选原始 `event`。返回 boolean/Promise，或调用 done()/done(false)；同步 void 等待 done，Promise&lt;void&gt; 放行。首次完成生效。等待期间自动管理 loading/disabled，取消后旧结果失效，不暴露内部按钮 refs。

### 守卫等待反馈

before-* 等待期间显示加载反馈并标记 aria-busy；拒绝或失败后恢复，重复提交不再启动同一操作。普通事件返回的 Promise 不参与加载。

---

Document: llms/zh-CN/components/table-column-manager.md

<!-- Source: src/table-column-manager/README.md; locale: zh-CN; page: /components/table-column-manager/ -->

# TableColumnManager 表格列管理

双栏列管理内容组件：左侧搜索勾选，右侧拖拽排序 / 冻结 / 删除。

- 默认自带抽屉容器（`v-model:open`），确认后通过 `confirm` 事件回写 `columns`。
- 传入 `inline` 可只渲染内联面板，用于放入自定义弹窗 / 容器。
- 与 Table **解耦**：Table 只提供 `v-model:columns`、`extra-column`、`#header-cell-actions` 等扩展点；列管理 UI / 算法由外部组合。

## 基础示例

### 基础用法

组件自身渲染抽屉；弹窗场景使用 `inline` 内联面板放入 `c-dialog`。

Example source: src/table-column-manager/__demos__/basic.vue

```vue
<template>
  <c-space>
    <c-button @click="openDrawer = true">抽屉中管理列</c-button>
    <c-button @click="openDialog = true">弹窗中管理列</c-button>
  </c-space>

  <c-table-column-manager
    v-model:open="openDrawer"
    v-model="items"
    :columns="columns"
    :options="columnDefinitions"
    :fallback-item="fallbackItem"
    @confirm="applyResult"
  />

  <c-dialog v-model:open="openDialog" title="列管理" :width="720" :body-padding="false" unmount-on-close>
    <div style="height: 480px">
      <c-table-column-manager
        inline
        v-model="items"
        :columns="columns"
        :options="columnDefinitions"
      />
    </div>
  </c-dialog>

  <pre style="margin-top: 16px; font-size: 12px">
items: {{ items }}
columns: {{ columns.map((c) => c.dataIndex).join(', ') }}</pre
  >
</template>

<script setup lang="ts">
import { ref } from 'vue'
import type {
  ColumnDefinition,
  ColumnDefinitions,
  ColumnManagerItem,
  ColumnManagerResult,
  TableColumnData,
} from '@cedar-design/ui'

const openDrawer = ref(false)
const openDialog = ref(false)

const items = ref<ColumnManagerItem[]>([
  { dataIndex: 'connectorId', fixed: 'left' },
  { dataIndex: 'connectorName' },
  { dataIndex: 'deviceName' },
])

const columns = ref<TableColumnData[]>([
  { dataIndex: 'connectorId', title: '枪ID', width: 100, fixed: 'left' },
  { dataIndex: 'connectorName', title: '枪名称', width: 120 },
  { dataIndex: 'deviceName', title: '设备名称', width: 120 },
])

const columnDefinitions = ref<ColumnDefinitions>([
  {
    title: '基本信息',
    key: 'basic',
    children: [
      {
        dataIndex: 'connectorId',
        title: '枪ID',
        required: true,
        tip: '必选列',
      },
      {
        dataIndex: 'connectorName',
        title: '枪名称',
      },
      {
        dataIndex: 'areaCompany',
        title: '区域公司区域公司区域公司区域公司区域公司区域公司',
        tip: '区域公司说明',
      },
    ],
  },
  {
    title: '设备信息',
    key: 'device',
    children: [
      { dataIndex: 'deviceId', title: '设备ID' },
      { dataIndex: 'deviceName', title: '设备名称' },
      { dataIndex: 'lockStatus', title: '地锁' },
    ],
  },
  { dataIndex: 'workingStatus', title: '工作状态' },
  { dataIndex: 'connectStatus', title: '连接状态' },
])

const fallbackItem = (dataIndex: string): ColumnDefinition => {
  return { dataIndex, title: dataIndex }
}

const applyResult = (result: ColumnManagerResult) => {
  columns.value = result.columns
  items.value = result.items
}
</script>
```

## Table 组合与持久化

### 与 Table 组合：不分组

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `open` | 抽屉是否可见（`v-model:open`） | 按钮切换抽屉 / 弹窗 |
| `columns` | 当前表格列，确认时拼回完整列定义 | 按钮切换抽屉 / 弹窗 |
| `options` | 左侧列定义 | 按钮切换抽屉 / 弹窗 |
| `drawer-title` | 抽屉标题 | 按钮切换抽屉 / 弹窗 |
| `inline` | 是否只渲染内联面板（不渲染抽屉） | 按钮切换抽屉 / 弹窗 |
<!-- demo-config-notes:end -->

普通数组形式的 `columnDefinitions`，覆盖必选列、左右冻结、列宽调整、插槽、重命名和表头快捷操作。

Example source: src/table-column-manager/__demos__/with-table-ungrouped.vue

```vue
<template>
  <c-space direction="column" size="md">
    <c-alert type="info" :show-icon="false">
      不分组列示例：目录就是普通数组。工号为必选左冻结列，备注和入职日期默认隐藏；支持搜索、显隐、拖拽排序、冻结、删除、重命名和列宽记忆。
    </c-alert>

    <div class="demo-toolbar">
      <c-button status="secondary" size="sm" @click="open">管理列</c-button>
      <c-link @click="resetToDefault">恢复默认</c-link>
      <span class="demo-summary"
        >已展示 {{ leafColumns.length }} /
        {{ columnDefinitions.length }} 列</span
      >
    </div>

    <c-table
      v-model:columns="columns"
      extra-column
      column-resizable
      :data="data"
      :pagination="false"
      :bordered="{ cell: true, headerCell: true }"
      size="xs"
      @column-resize="handleColumnResize"
    >
      <template #extra-column-header>
        <c-button variant="text" size="xs" aria-label="管理列" @click="open"
          ><c-icon-settings
        /></c-button>
      </template>
      <template #extra-column-cell />

      <template #header-cell-actions="{ column, dataIndex }">
        <HeaderAction :data-index="dataIndex" :column="column" />
      </template>

      <template #status="{ record }">
        <c-tag :color="record.status === '在职' ? 'green' : 'gray'" size="sm">{{
          record.status
        }}</c-tag>
      </template>
    </c-table>

    <c-table-column-manager v-bind="managerProps" />
  </c-space>
</template>

<script setup lang="ts">
import { ref } from "vue";
import { useTableColumnManager } from "@cedar-design/ui";
import type { ColumnDefinitions, ManagedTableColumn } from "@cedar-design/ui";

const defaultColumns: ManagedTableColumn[] = [
  {
    dataIndex: "employeeId",
    title: "工号",
    manager: { required: true },
    fixed: "left",
    width: 110,
  },
  { dataIndex: "name", title: "姓名", minWidth: 140 },
  { dataIndex: "department", title: "部门", width: 140 },
  { dataIndex: "position", title: "职位", minWidth: 160 },
  { dataIndex: "phone", title: "手机号", width: 150 },
  { dataIndex: "status", title: "状态", width: 100, slotName: "status" },
];

const columnDefinitions: ColumnDefinitions = [
  {
    dataIndex: "employeeId",
    title: "工号",
    tip: "必选规则来自 defaultColumns",
  },
  { dataIndex: "name", title: "姓名" },
  { dataIndex: "department", title: "部门" },
  { dataIndex: "position", title: "职位" },
  { dataIndex: "phone", title: "手机号" },
  { dataIndex: "status", title: "状态" },
  { dataIndex: "joinedAt", title: "入职日期" },
  { dataIndex: "remark", title: "备注", tip: "不在默认列中，可从弹窗添加" },
];

const {
  columns,
  managerProps,
  leafColumns,
  open,
  handleColumnResize,
  HeaderAction,
  resetToDefault,
} = useTableColumnManager({
  defaultColumns,
  columnDefinitions,
  columnDefaults: { width: 130, ellipsis: true },
  createColumn: (definition) =>
    definition.dataIndex === "remark"
      ? {
          dataIndex: definition.dataIndex,
          title: definition.title,
          minWidth: 220,
          width: undefined,
        }
      : { dataIndex: definition.dataIndex, title: definition.title },
});

const data = ref([
  {
    employeeId: "E-1001",
    name: "张三",
    department: "产品研发部",
    position: "前端工程师",
    phone: "138****1024",
    status: "在职",
    joinedAt: "2023-04-18",
    remark: "负责组件库和中后台基础设施",
  },
  {
    employeeId: "E-1002",
    name: "李四",
    department: "质量保障部",
    position: "测试工程师",
    phone: "139****3072",
    status: "在职",
    joinedAt: "2022-11-07",
    remark: "负责自动化测试平台",
  },
  {
    employeeId: "E-1003",
    name: "王五",
    department: "数据平台部",
    position: "数据分析师",
    phone: "136****8841",
    status: "离职",
    joinedAt: "2021-08-23",
    remark: "历史项目成员",
  },
]);
</script>

<style scoped>
.demo-toolbar {
  display: flex;
  align-items: center;
  gap: 12px;
}

.demo-summary {
  margin-left: auto;
  color: var(--c-color-text-3);
}
</style>
```

### 与 Table 组合：分组与持久化

配合 `useTableColumnManager` 组合式函数，一行接入：

- `extra-column` + `#extra-column-header`：末列冻结设置按钮
- `#header-cell-actions`：表头右侧操作，使用 `HeaderAction` 组件
- `v-model:columns` / `@column-resize`：改列并重渲染

表头操作项通过 `headerActions` 配置 key，事件绑定在组件内部完成；插入/编辑弹窗由 `c-table-column-manager` 内部渲染。

Example source: src/table-column-manager/__demos__/with-table-header-menu.vue

```vue
<template>
  <c-space direction="column" size="md">
    <c-alert type="info" :show-icon="false">
      分组列示例：左侧 <code>优先级</code> 冻结，右侧 <code>状态</code> 冻结；
      <code>名称</code>、<code>更新时间</code> 只设
      <code>min-width</code> 作为弹性列。表格始终铺满父容器：<code>fit</code>
      开启时剩余空间按 min-width
      比例分给弹性列，关闭时按各列宽度比例放大；extra-column 固定 28px
      不参与分配。<code>table-layout="auto"</code> 时 colgroup 不渲染
      <code>col</code>，列宽交给浏览器按内容分配，且不显示拖拽把手（拖拽仅
      <code>fixed</code> 布局可用）。
    </c-alert>

    <c-space wrap size="16px" align="center">
      <c-button status="secondary" size="sm" @click="open">列管理</c-button>
      <c-link @click="resetToDefault">重置</c-link>
      <c-switch
        v-model="fit"
        checked-text="fit"
        unchecked-text="fit"
        size="sm"
      />
      <c-switch
        v-model="isFixedLayout"
        checked-text="fixed"
        unchecked-text="auto"
        size="sm"
      />
      <span style="color: var(--c-color-text-3); margin-left: 8px">
        当前 {{ leafColumns.length }} 列
      </span>
    </c-space>

    <c-space wrap size="8px" align="center">
      <c-tag
        v-for="col in leafColumns"
        :key="col.dataIndex"
        size="sm"
        color="gray"
      >
        {{ col.title }}
        <template v-if="col.width"> · {{ col.width }}px</template>
        <template v-if="col.fixed"
          >（{{ col.fixed === "left" ? "左冻" : "右冻" }}）</template
        >
      </c-tag>
    </c-space>

    <c-table
      v-model:columns="columns"
      extra-column
      column-resizable
      :data="data"
      :pagination="false"
      :bordered="{ cell: true, headerCell: true }"
      :fit="fit"
      :table-layout="tableLayout"
      size="xs"
      @column-resize="handleColumnResize"
    >
      <template #extra-column-header>
        <c-button variant="text" size="xs" aria-label="管理列" @click="open">
          <c-icon-settings />
        </c-button>
      </template>
      <template #extra-column-cell />

      <template #header-cell-actions="{ column, dataIndex }">
        <HeaderAction :data-index="dataIndex" :column="column" />
      </template>

      <template #priority="{ record }">
        <c-tag :color="priorityColor(record.priority)" size="sm">{{
          record.priority
        }}</c-tag>
      </template>
      <template #status="{ record }">
        <c-tag :color="statusColor(record.status)" size="sm">{{
          record.status
        }}</c-tag>
      </template>
    </c-table>

    <!-- 列管理抽屉 + 插入/编辑弹窗 -->
    <c-table-column-manager v-bind="managerProps" />
  </c-space>
</template>

<script lang="ts" setup>
import { computed, onMounted, ref, watch } from "vue";
import { useTableColumnManager } from "@cedar-design/ui";
import type { ColumnDefinitions, ManagedTableColumn } from "@cedar-design/ui";

const STORAGE_KEY = "cedar-demo:table-column-manager:with-table-header-menu";
let storage: Storage | undefined;
const storageReady = ref(false);

const fit = ref(true);
// fixed：列宽由布局引擎计算写入 col，不被内容撑开；auto：不渲染 col，交给浏览器按内容分配
const tableLayout = ref<"fixed" | "auto">("fixed");
const isFixedLayout = computed({
  get: () => tableLayout.value === "fixed",
  set: (val: boolean) => {
    tableLayout.value = val ? "fixed" : "auto";
  },
});

const defaultColumns: ManagedTableColumn[] = [
  {
    title: "基本信息",
    children: [
      {
        dataIndex: "priority",
        title: "优先级",
        manager: { required: true },
        fixed: "left",
        width: 120,
        slotName: "priority",
      },
      {
        dataIndex: "name",
        title: "名称",
        minWidth: 200,
      },
      {
        dataIndex: "bizLine",
        title: "业务线",
        width: 120,
      },
    ],
  },
  {
    title: "人员与状态",
    children: [
      {
        dataIndex: "owner",
        title: "负责人",
        width: 100,
      },
      {
        dataIndex: "updatedAt",
        title: "更新时间",
        minWidth: 140,
      },
      {
        dataIndex: "status",
        title: "状态",
        fixed: "right",
        width: 120,
        slotName: "status",
      },
    ],
  },
];

// 候选定义只服务于弹窗展示和搜索，不重复配置 Table 宽度、插槽或必选规则。
const columnDefinitions: ColumnDefinitions = [
  {
    key: "base",
    title: "基本信息",
    children: [
      {
        dataIndex: "priority",
        title: "优先级",
        tip: "必选规则来自 defaultColumns",
      },
      { dataIndex: "name", title: "名称" },
      { dataIndex: "bizLine", title: "业务线" },
      {
        dataIndex: "description",
        title: "任务描述",
        tip: "候选的新列，通过 createColumn 设置特殊宽度",
      },
    ],
  },
  {
    key: "people",
    title: "人员与状态",
    children: [
      { dataIndex: "owner", title: "负责人" },
      { dataIndex: "updatedAt", title: "更新时间" },
      { dataIndex: "status", title: "状态" },
      { dataIndex: "deadline", title: "截止时间" },
    ],
  },
];

// ---------- 核心：一行接入列管理 ----------

const manager = useTableColumnManager({
  defaultColumns,
  columnDefinitions,
  // 普通新增列统一使用该默认 Table 配置。
  columnDefaults: { width: 140, ellipsis: true },
  // 少量特殊候选列在这里补充本地渲染配置。
  createColumn: (definition) =>
    definition.dataIndex === "description"
      ? {
          dataIndex: definition.dataIndex,
          title: definition.title,
          minWidth: 240,
          width: undefined,
        }
      : { dataIndex: definition.dataIndex, title: definition.title },
});
const {
  columns,
  state,
  restore,
  managerProps,
  leafColumns,
  open,
  handleColumnResize,
  HeaderAction,
  resetToDefault: resetManagerToDefault,
} = manager;

// 持久化属于业务层：组件和 useTableColumnManager 不读写 localStorage。
onMounted(async () => {
  storage = window.localStorage;
  try {
    const raw = storage.getItem(STORAGE_KEY);
    if (raw) await restore(JSON.parse(raw));
  } catch {
    storage.removeItem(STORAGE_KEY);
  } finally {
    storageReady.value = true;
  }
});

watch(
  state,
  (value) => {
    if (!storageReady.value) return;
    storage?.setItem(STORAGE_KEY, JSON.stringify(value));
  },
  { deep: true },
);

const resetToDefault = () => {
  storage?.removeItem(STORAGE_KEY);
  resetManagerToDefault();
};

// ---------- 渲染辅助 ----------

const priorityColor = (value: string) => {
  if (value === "P0") return "red";
  if (value === "P1") return "orange";
  return "gray";
};

const statusColor = (value: string) => {
  if (value === "进行中") return "blue";
  if (value === "已完成") return "green";
  if (value === "已阻塞") return "red";
  return "gray";
};

const data = ref([
  {
    priority: "P0",
    name: "任务 A",
    bizLine: "交易",
    description: "修复支付链路并补充异常监控",
    owner: "张三",
    updatedAt: "2026-07-21 10:30",
    status: "进行中",
    deadline: "2026-08-10",
  },
  {
    priority: "P1",
    name: "任务 B",
    bizLine: "物流",
    description: "优化仓配系统的库存同步效率",
    owner: "李四",
    updatedAt: "2026-07-22 14:00",
    status: "已完成",
    deadline: "2026-08-05",
  },
  {
    priority: "P0",
    name: "任务 C",
    bizLine: "交易",
    description: "排查高峰期订单重复提交问题",
    owner: "王五",
    updatedAt: "2026-07-25 09:15",
    status: "已阻塞",
    deadline: "2026-08-12",
  },
]);
</script>
```

### 按钮切换抽屉 / 弹窗

外部选择容器类型：抽屉模式直接用组件，弹窗模式传入 `inline`。

Example source: src/table-column-manager/__demos__/with-table.vue

```vue
<template>
  <c-space direction="column" size="md">
    <c-alert type="info" :show-icon="false">
      <code>c-table-column-manager</code> 自身包含抽屉；弹窗场景传入
      <code>inline</code> 后以内联面板形式放入自定义容器。
    </c-alert>

    <c-space wrap size="8px" justify="flex-end">
      <c-button variant="outline" @click="openAs('drawer')"
        >抽屉管理列</c-button
      >
      <c-button variant="outline" @click="openAs('dialog')"
        >弹窗管理列</c-button
      >
    </c-space>

    <c-table
      v-model:columns="columns"
      :data="data"
      :pagination="false"
      size="xs"
    />

    <!-- 抽屉模式：组件自带抽屉 -->
    <c-table-column-manager
      v-if="container === 'drawer'"
      v-model:open="visible"
      v-model="items"
      :columns="columns"
      :options="columnDefinitions"
      drawer-title="列管理"
      @confirm="handleConfirm"
    />

    <!-- 弹窗模式：inline 内联面板放入 c-dialog -->
    <c-dialog
      v-else
      v-model:open="visible"
      title="列管理"
      :width="720"
      :body-padding="false"
      unmount-on-close
    >
      <div style="height: 480px">
        <c-table-column-manager
          inline
          v-model:open="visible"
          v-model="items"
          :columns="columns"
          :options="columnDefinitions"
          @confirm="handleConfirm"
        />
      </div>
    </c-dialog>
  </c-space>
</template>

<script setup lang="ts">
import { ref, watch } from "vue";
import { stateFromColumns } from "@cedar-design/ui";
import type {
  ColumnDefinitions,
  ColumnManagerResult,
  TableColumnData,
} from "@cedar-design/ui";

const visible = ref(false);
const container = ref<"drawer" | "dialog">("drawer");
const items = ref([]);

const columns = ref<TableColumnData[]>([
  { dataIndex: "name", title: "姓名", width: 120, fixed: "left" },
  { dataIndex: "salary", title: "薪资", width: 100 },
  { dataIndex: "address", title: "地址" },
]);

const columnDefinitions: ColumnDefinitions = [
  {
    title: "基础信息",
    key: "basic",
    children: [
      { dataIndex: "name", title: "姓名", required: true, tip: "必选列" },
      { dataIndex: "salary", title: "薪资" },
      { dataIndex: "email", title: "邮箱" },
    ],
  },
  {
    title: "扩展信息",
    key: "extra",
    children: [
      { dataIndex: "address", title: "地址" },
      { dataIndex: "department", title: "部门" },
      {
        dataIndex: "action",
        title: "操作",
      },
    ],
  },
];

const syncManagerState = () => {
  const state = stateFromColumns(columns.value, columnDefinitions);
  items.value = state.items;
};

watch(visible, (val) => {
  if (val) syncManagerState();
});

const openAs = (type: "drawer" | "dialog") => {
  container.value = type;
  visible.value = true;
};

const handleConfirm = (result: ColumnManagerResult) => {
  columns.value = result.columns;
};
</script>
```

## 异步目录与搜索

### 异步目录与远程搜索

`loadOptions` 加载全量目录，`remoteSearch` 驱动搜索。

Example source: src/table-column-manager/__demos__/remote.vue

```vue
<template>
  <c-space direction="column" size="md">
    <c-alert type="info" :show-icon="false">
      弹窗候选列由 <code>columnSource.search</code> 远程搜索；恢复缓存遇到本地未知列时，通过
      <code>columnSource.resolve</code> 批量反显。远程接口只返回 dataIndex、title 和分组信息。
    </c-alert>

    <div class="demo-toolbar">
      <c-button status="secondary" size="sm" @click="open">远程管理列</c-button>
      <c-link @click="resetToDefault">恢复本地默认列</c-link>
    </div>

    <c-table v-model:columns="columns" :data="data" :pagination="false" size="xs" />
    <c-table-column-manager v-bind="managerProps" />
  </c-space>
</template>

<script setup lang="ts">
import { onMounted, ref } from 'vue'
import { useTableColumnManager } from '@cedar-design/ui'
import type { ColumnDefinition, ColumnDefinitionSource, ManagedTableColumn } from '@cedar-design/ui'

const defaultColumns: ManagedTableColumn[] = [
  { dataIndex: 'id', title: '编号', width: 100, fixed: 'left', manager: { required: true } },
  { dataIndex: 'name', title: '名称', minWidth: 180 },
]

// 模拟服务端保存的轻量字段目录。
const remoteFields: Array<ColumnDefinition & { group?: string }> = [
  { dataIndex: 'id', title: '编号', group: '基础信息' },
  { dataIndex: 'name', title: '名称', group: '基础信息' },
  { dataIndex: 'owner', title: '负责人', group: '基础信息' },
  { dataIndex: 'remoteConfig1', title: '远程配置 1', group: '远程配置' },
  { dataIndex: 'remoteConfig2', title: '远程配置 2', group: '远程配置' },
  { dataIndex: 'remoteStatus', title: '远程状态', group: '远程配置' },
]

const wait = (duration: number) => new Promise((resolve) => setTimeout(resolve, duration))
const groupDefinitions = (items: typeof remoteFields) =>
  [...new Set(items.map((item) => item.group ?? '其他'))].map((group) => ({
    key: group,
    title: group,
    children: items
      .filter((item) => (item.group ?? '其他') === group)
      .map(({ group: _group, ...definition }) => definition),
  }))

const columnSource: ColumnDefinitionSource = {
  async search({ keyword }) {
    await wait(300)
    const normalized = keyword.trim().toLowerCase()
    const matched = normalized
      ? remoteFields.filter(
          (item) => item.title.toLowerCase().includes(normalized) || item.dataIndex.toLowerCase().includes(normalized)
        )
      : remoteFields
    return { items: groupDefinitions(matched), total: matched.length }
  },
  async resolve(dataIndexes) {
    await wait(200)
    const keys = new Set(dataIndexes)
    return remoteFields.filter((item) => keys.has(item.dataIndex)).map(({ group: _group, ...item }) => item)
  },
}

const { columns, managerProps, open, restore, resetToDefault } = useTableColumnManager({
  defaultColumns,
  columnSource,
  columnDefaults: { width: 140, ellipsis: true },
  createColumn: (definition) =>
    definition.dataIndex === 'remoteStatus'
      ? { dataIndex: definition.dataIndex, title: definition.title, width: 110 }
      : { dataIndex: definition.dataIndex, title: definition.title },
})

onMounted(async () => {
  // 模拟缓存中包含一个不在本地 defaultColumns 里的远程列。
  await restore({
    version: 2,
    items: [{ dataIndex: 'id', fixed: 'left' }, { dataIndex: 'name' }, { dataIndex: 'remoteConfig2' }],
  })
})

const data = ref([
  {
    id: 'T-001',
    name: '远程字段示例',
    owner: '张三',
    remoteConfig1: '配置 A',
    remoteConfig2: '配置 B',
    remoteStatus: '已同步',
  },
])
</script>

<style scoped>
.demo-toolbar {
  display: flex;
  align-items: center;
  gap: 12px;
}
</style>
```

## API

### 状态与持久化结构

列的顺序、标题和冻结状态统一存放在 `items` 中。组件和 `useTableColumnManager` 不维护缓存，业务层可按需将
以下状态存入 localStorage、Pinia 或服务端：

```ts
const state: ColumnManagerState = {
  version: 2,
  items: [
    { dataIndex: 'id', fixed: 'left', width: 120 },
    { dataIndex: 'name', title: '用户名称' },
  ],
  layout: [],
}
```

这是大版本破坏性调整，不再读取旧的 `keys`、`fixedMap`、`titleMap` 结构。

```ts
const { state, restore } = useTableColumnManager({ defaultColumns, columnDefinitions })
const storageReady = ref(false)

onMounted(async () => {
  const raw = window.localStorage.getItem(STORAGE_KEY)
  if (raw) await restore(JSON.parse(raw))
  storageReady.value = true
})

watch(
  state,
  (value) => {
    if (!storageReady.value) return
    window.localStorage.setItem(STORAGE_KEY, JSON.stringify(value))
  },
  { deep: true }
)
```

`restore()` 会校验版本、移除失效或重复列、清洗非法宽度和布局、补齐 `required` 列，并修复冻结区顺序。
`state` 只记录用户重命名的标题和通过 `handleColumnResize` 调整过的宽度。保存到服务端时建议在业务层增加防抖。

### 默认列与候选定义

`defaultColumns` 是完整的 Table 初始列和重置基准；`columnDefinitions` 只负责弹窗候选项，可以只有
`dataIndex`、`title`、分组和提示：

```ts
const defaultColumns: ManagedTableColumn[] = [
  {
    title: '基本信息',
    children: [
      {
        dataIndex: 'id',
        title: '编号',
        fixed: 'left',
        width: 120,
        manager: { required: true },
      },
      { dataIndex: 'name', title: '名称', minWidth: 180 },
    ],
  },
]

const columnDefinitions: ColumnDefinitions = [
  {
    key: 'base',
    title: '基本信息',
    children: [
      { dataIndex: 'id', title: '编号' },
      { dataIndex: 'name', title: '名称' },
      { dataIndex: 'remark', title: '备注', tip: '可选列' },
    ],
  },
]

const manager = useTableColumnManager({
  defaultColumns,
  columnDefinitions,
  columnDefaults: { width: 140, ellipsis: true },
  createColumn: (definition) => ({ dataIndex: definition.dataIndex, title: definition.title }),
})
```

- `defaultColumns` 决定初始展示、重置、默认宽度、冻结、插槽、渲染和 `manager.required`。
- `columnDefinitions` 决定弹窗候选范围，不承担 Table 渲染配置。
- `columnDefaults` 是新增普通列的统一 Table 默认值。
- `createColumn` 用于少数需要特殊宽度、插槽或渲染的候选列。
- 远程场景使用 `columnSource.search` 搜索、`columnSource.resolve` 恢复未知的已选列；此时 `restore()` 返回 Promise。

### `<TableColumnManager>` Props

| 参数名        | 描述                               | 类型                                                    | 默认值     |
| ------------- | ---------------------------------- | ------------------------------------------------------- | ---------- |
| model-value   | 已选列完整状态（顺序、标题、冻结） | `ColumnManagerItem[]`                                   | `-`        |
| default-value | 非受控初始已选状态                 | `ColumnManagerItem[]`                                   | `-`        |
| columns       | 当前表格列，确认时拼回完整列定义   | `TableColumnData[]`                                     | `[]`       |
| options       | 左侧列定义                         | `ColumnDefinitions`                                     | `[]`       |
| load-options  | 异步加载列定义                     | `() => Promise<ColumnDefinitions>`                      | `-`        |
| remote-search | 远程搜索（有值时隐藏顶栏全选）     | `(keyword: string) => Promise<void>`                    | `-`        |
| fallback-item | 值不在定义中时反显                 | `(dataIndex: string) => ColumnDefinition \| undefined` | `-`        |
| insert-at     | 插入上下文，影响新增列落点         | `{ dataIndex: string; side: 'left' \| 'right' }`        | `-`        |
| open          | 抽屉是否可见（`v-model:open`）     | `boolean`                                               | `-`        |
| drawer-title  | 抽屉标题                           | `string`                                                | `自定义列` |
| drawer-width  | 抽屉宽度                           | `number \| string`                                      | `720`      |
| inline        | 是否只渲染内联面板（不渲染抽屉）   | `boolean`                                               | `false`    |
| placeholder   | 搜索框占位                         | `string`                                                | `-`        |

### Events

| 事件名            | 描述                            | 参数                  |
| ----------------- | ------------------------------- | --------------------- |
| update:model-value | 已选完整状态变更                | `ColumnManagerItem[]` |
| update:open       | 抽屉可见性变更                  | `boolean`             |
| confirm           | 点击抽屉/弹窗确认后返回组装结果 | `ColumnManagerResult` |
| change            | 选择、排序、冻结或标题变化      | `ColumnManagerItem[]` |

### Methods

| 方法名      | 描述                     | 返回值                |
| ----------- | ------------------------ | --------------------- |
| getResult   | 按当前选择组装表格列结果 | `ColumnManagerResult` |
| loadCatalog | 手动触发 `loadOptions`   | `Promise<void>`       |

### `useTableColumnManager`

推荐与 `c-table` 组合使用。返回 `columns`、`state`、`restore`、`managerProps`、`HeaderAction` 等，其中
`HeaderAction` 直接通过 `inject` 获取上下文，模板中只需：

```vue
<template #header-cell-actions="{ column, dataIndex }">
  <HeaderAction :data-index="dataIndex" :column="column" />
</template>
```

可通过 `headerActions` 配置要展示的表头操作 key，默认全部展示。

表头操作行为：

- **向左 / 向右插入**：新列会写入锚点所在一级分组，保证分组标题与 `colspan` 正确；若锚点列已冻结，新列会继承相同的冻结位置。
- **冻结 / 取消冻结**：按规则重排叶子列顺序，冻结列集中靠左或靠右。
- **编辑列**：可修改一级分组标题与列名称，相邻同名分组会自动合并。

必选规则只需要在 `defaultColumns` 中声明，Transfer、清空操作和表头删除都会遵循同一规则：

```ts
{
  dataIndex: 'priority',
  title: '优先级',
  manager: { required: true },
  fixed: 'left',
  width: 120,
  slotName: 'priority',
}
```

`columnDefinitions` 中无需重复宽度、冻结和必选规则。用户拖拽后的宽度保存在对应的 `items[].width`。

### 扩展列宽度

`c-table` 的 `extra-column` 扩展列（如设置按钮）默认宽度为 **28px**，可通过 `extraColumn: { width: number }` 覆盖。

### 工具函数（列管理包内）

`buildColumnsResult` / `stateFromColumns` / `applyColumnEdit` / `applyColumnFixed` / `applyInsertToLayout` / `mapLeafColumns` 等用于外部组合时拼装、编辑分组、冻结重排。扁平叶子列表请在业务侧从 `columns` 自行遍历，不必依赖 Table 导出。

目录加载、远程搜索分别持有等待状态，旧任务不能解除新任务的等待。loadOptions 在创建时、函数更换时以及显式 loadCatalog 调用时读取，不由普通通知事件返回的 Promise 驱动；手动调用拒绝仍向调用方传递，自动读取异常进入 Vue 错误通道。hook 目录读取/远程搜索使用最新目录代次，restore 有独立代次，更新的列编辑或卸载令旧恢复结果失效。

---

Document: llms/zh-CN/components/table.md

<!-- Source: src/table/README.md; locale: zh-CN; page: /components/table/ -->

# Table

跨端边界：本组件与 Maple Table 独立维护，菜单保留“独立”。Maple 的轻量插槽表格/本地分页示例不提供本组件的排序、行选择或远程数据 API；两端有交互记录不等于 API 同源或全部配置已验收。

用于数据收集展示、分析整理、操作处理。

## 基础示例

### 基础用法

传入 `columns` 和 `data` 即可展示表格；默认铺满容器，列宽超出时自动横向滚动。

Example source: src/table/__demos__/basic.vue

```vue
<script setup lang="ts">
const columns = [
  { title: 'Name', dataIndex: 'name' },
  { title: 'Salary', dataIndex: 'salary' },
  { title: 'Address', dataIndex: 'address' },
]
const data = [
  { key: '1', name: 'Jane Doe', salary: 23000, address: '32 Park Road, London' },
  { key: '2', name: 'Alisa Ross', salary: 25000, address: '35 Park Road, London' },
  { key: '3', name: 'Kevin Sandra', salary: 22000, address: '31 Park Road, London' },
]
</script>
<template>
  <c-table :columns="columns" :data="data" :pagination="false" />
</template>
```

### 手动加载与原生插槽

布尔值或对象 loading 同时适用于数据模式与原生插槽模式；对象需要显式 loading: true。切换加载时保留行、草稿与焦点，通知事件不负责自动执行加载任务。

Example source: src/table/__demos__/loading.vue

```vue
<template>
  <c-space direction="column" style="width: 100%">
    <c-space
      ><c-switch v-model="loading" edit-mode="direct" /><span
        >手动控制两种表格的加载状态</span
      ></c-space
    >
    <c-table
      :columns="columns"
      :data="data"
      :loading="loading"
      :pagination="false"
    />
    <c-table :loading="loading" :pagination="false">
      <thead>
        <tr>
          <th>原生插槽</th>
          <th>保留编辑内容</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <td>切换加载不会重建行</td>
          <td><input v-model="draft" aria-label="表格草稿" /></td>
        </tr>
      </tbody>
    </c-table>
    <small>loading 仅由业务状态控制。输入草稿后切换加载，内容继续保留。</small>
  </c-space>
</template>
<script setup lang="ts">
import { ref } from "vue";
const loading = ref(false);
const draft = ref("可编辑草稿");
const columns = [{ title: "数据模式", dataIndex: "name" }];
const data = [{ key: "row", name: "与原生插槽使用相同的 loading 合同" }];
</script>
```

### 空数据

数据为空时显示缺省提示；通过 `empty` 插槽提供业务引导，不把空状态和尺寸控制混在基础案例中。

Example source: src/table/__demos__/empty-state.vue

```vue
<script setup lang="ts">
const columns = [{ title: 'Name', dataIndex: 'name' }, { title: 'Address', dataIndex: 'address' }]
</script>
<template>
  <c-table :columns="columns" :data="[]" :pagination="false">
    <template #empty>暂无记录，请调整筛选条件后重试。</template>
  </c-table>
</template>
```

## 列宽、布局与固定列

### 列宽配置场景

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `columns` | 表格的列描述信息 | 列宽配置场景、固定列、分组表头与固定列 |
| `data` | 表格的数据 | 列宽配置场景、固定列、分组表头与固定列 |
| `pagination` | 分页的属性配置 | 列宽配置场景、布局、自适应与拖拽调宽 |
| `bordered` | 是否显示边框 | 分组表头与固定列、布局、自适应与拖拽调宽 |
| `sticky-pagination` | 分页相对页面/外层滚动容器吸底；数字为距底部偏移（px） | 列宽配置场景 |
| `row-selection` | 表格的行选择器配置 | 列宽配置场景 |
<!-- demo-config-notes:end -->

表格宽度和列宽是两层配置：`style="width: 100%"` 或 `style="width: 480px"` 控制外层容器，`columns` 中的 `width` / `minWidth` 控制各列。无需设置 `scroll.x` 或 `scroll.y`。

先用下面七种组合比较不指定列宽、全部最小宽、定宽与弹性混合、全部定宽、横向溢出、左右固定列，以及选择列/扩展列。切换 100%、480px、360px 可以直接观察重算和横向滚动。

| 配置 | 分配规则（默认 `table-layout="fixed"`、`fit=true`） |
| --- | --- |
| 不设置列宽 | 以每列 80px 为基础，按比例分配剩余空间 |
| `minWidth` | 指定弹性列的基础宽度；空间不足时保留基础宽度并横向滚动 |
| `width` + 弹性列 | 显式 `width` 保持不变，剩余空间给弹性列，按各自 `minWidth` 比例分配 |
| 全部指定 `width` | 超出容器时保留列宽；不足容器时按比例放大普通数据列以铺满 |
| `fit=false` | 仍至少铺满容器；剩余空间由所有普通数据列按基础宽度比例分摊 |
| 选择列 / 扩展列 | 选择列按自己的操作列宽度保留；扩展列不参与普通数据列的比例放大 |

这里的“弹性”指剩余宽度分配，不是浏览器的 `table-layout: auto`。未设置 `width` 的列才是弹性列；`minWidth` 不会让显式 `width` 的列变成弹性列。以上分配规则针对默认的 `fixed` 布局。

Example source: src/table/__demos__/column-width-scenarios.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
import type { TableColumnData } from '@cedar-design/ui'

const tableWidth = ref('100%')
const data = [{ key: '1', name: '设备巡检', owner: '张三', status: '进行中' }]
const base: TableColumnData[] = [
  { title: '任务', dataIndex: 'name' },
  { title: '负责人', dataIndex: 'owner' },
  { title: '状态', dataIndex: 'status' },
]
const scenarios = [
  { title: '不指定列宽', description: '每列以 80px 为基础，均分剩余空间。', columns: base },
  { title: '全部使用 minWidth', description: '按 160 : 80 : 80 的基础宽度比例分配剩余空间。', columns: base.map((column, index) => ({ ...column, minWidth: index === 0 ? 160 : 80 })) },
  { title: '定宽列与弹性列混合', description: '负责人、状态各保持 120px，任务列吸收剩余空间。', columns: base.map((column, index) => ({ ...column, ...(index === 0 ? { minWidth: 160 } : { width: 120 }) })) },
  { title: '全部指定 width', description: '列宽之和不足容器时，Cedar 按比例放大普通数据列以铺满容器。', columns: base.map((column, index) => ({ ...column, width: index === 0 ? 160 : 80 })) },
  { title: '列宽之和超出容器', description: '三列各 280px，保留列宽并自动出现横向滚动条，无需 scroll.x。', columns: base.map(column => ({ ...column, width: 280 })) },
  { title: '左右固定列与混合列宽', description: '左右各固定 140px、120px，中间列 minWidth 为 440px；无需 scroll.x，底部粘性滚动条随表格悬浮显示。', columns: [{ ...base[0], width: 140, fixed: 'left' as const }, { ...base[1], minWidth: 440 }, { ...base[2], width: 120, fixed: 'right' as const }], sticky: true },
  { title: '选择列、弹性列与扩展列', description: '选择列保持 40px，扩展列保持 28px，任务列分配剩余空间。', columns: base.map((column, index) => ({ ...column, ...(index === 0 ? { minWidth: 160 } : { width: 120 }) })), operations: true },
]
</script>

<template>
  <div class="column-width-scenarios">
    <c-radio-group v-model="tableWidth" type="button" aria-label="表格宽度">
      <c-radio value="480px">定宽 480px</c-radio>
      <c-radio value="100%">100% 宽度</c-radio>
      <c-radio value="360px">窄屏 360px</c-radio>
    </c-radio-group>
    <section v-for="scenario in scenarios" :key="scenario.title">
      <h4>{{ scenario.title }}</h4>
      <p>{{ scenario.description }}</p>
      <c-table
        :columns="scenario.columns"
        :data="data"
        :style="{ width: tableWidth }"
        :pagination="scenario.sticky ? { pageSize: 5 } : false"
        :sticky-pagination="scenario.sticky ? 0 : false"
        :row-selection="scenario.operations ? { width: 40 } : undefined"
        :extra-column="scenario.operations"
      />
    </section>
  </div>
</template>

<style scoped>
.column-width-scenarios { width: 640px; max-width: 100%; }
.column-width-scenarios > section { margin-top: 24px; }
h4 { margin: 0 0 8px; }
p { margin: 0 0 12px; }
</style>
```

### 固定列

在 `columns` 中指定 `fixed: 'left'` 或 `fixed: 'right'`，可将列固定到左侧或右侧。固定列建议设置 `width`。当列最小宽之和超过容器时会自动出现横向滚动。

Example source: src/table/__demos__/fixed.vue

```vue
<template>
  <c-table :columns="columns" :data="data" :height="200" :expandable="expandable" />
</template>

<script lang="ts" setup>
import { reactive } from 'vue'
const columns = [
  {
    title: 'Name',
    dataIndex: 'name',
    fixed: 'left',
    width: 140,
  },
  {
    title: 'Salary',
    dataIndex: 'salary',
    minWidth: 200,
  },
  {
    title: 'Address',
    dataIndex: 'address',
    minWidth: 400,
  },
  {
    title: 'Email',
    dataIndex: 'email',
    fixed: 'right',
    width: 200,
  },
]

const expandable = {
  title: 'Expand',
  width: 80,
}

const data = reactive([
  {
    key: '1',
    name: 'Jane Doe',
    salary: 23000,
    address: '32 Park Road, London',
    email: 'jane.doe@example.com',
    expand: 'Expand Content',
  },
  {
    key: '2',
    name: 'Alisa Ross',
    salary: 25000,
    address: '35 Park Road, London',
    email: 'alisa.ross@example.com',
  },
  {
    key: '3',
    name: 'Kevin Sandra',
    salary: 22000,
    address: '31 Park Road, London',
    email: 'kevin.sandra@example.com',
  },
  {
    key: '4',
    name: 'Ed Hellen',
    salary: 17000,
    address: '42 Park Road, London',
    email: 'ed.hellen@example.com',
  },
  {
    key: '5',
    name: 'William Smith',
    salary: 27000,
    address: '62 Park Road, London',
    email: 'william.smith@example.com',
  },
])
</script>
```

### 分组表头与固定列

分组表头使用固定列时，需要优先指定数据列为固定列。
如果一个分组下的所有数据列都是固定列，此时可以设置分组列为固定列，宽度为子列宽度之和。

Example source: src/table/__demos__/columns-children-and-fixed.vue

```vue
<template>
  <c-table :columns="columns" :data="data" :bordered="{ cell: true }" />
</template>

<script lang="ts" setup>
import { reactive } from 'vue'
const columns = [
  {
    title: 'Name',
    dataIndex: 'name',
    fixed: 'left',
    width: 140,
  },
  {
    title: 'User Info',
    children: [
      {
        title: 'Birthday',
        dataIndex: 'birthday',
        fixed: 'left',
        width: 200,
      },
      {
        title: 'Address',
        children: [
          {
            title: 'City',
            dataIndex: 'city',
            fixed: 'left',
            width: 100,
          },
          {
            title: 'Road',
            dataIndex: 'road',
            minWidth: 200,
          },
          {
            title: 'No.',
            dataIndex: 'no',
            minWidth: 120,
          },
        ],
      },
    ],
  },
  {
    title: 'Information',
    children: [
      {
        title: 'Email',
        dataIndex: 'email',
        minWidth: 240,
      },
      {
        title: 'Phone',
        dataIndex: 'phone',
        minWidth: 160,
      },
    ],
  },
  {
    title: 'Salary',
    dataIndex: 'salary',
    fixed: 'right',
    width: 120,
  },
]
const data = reactive([
  {
    key: '1',
    name: 'Jane Doe',
    salary: 23000,
    birthday: '1994-04-21',
    city: 'London',
    road: 'Park',
    no: '34',
    phone: '12345678',
    email: 'jane.doe@example.com',
  },
  {
    key: '2',
    name: 'Alisa Ross',
    salary: 25000,
    birthday: '1994-05-21',
    city: 'London',
    road: 'Park',
    no: '37',
    phone: '12345678',
    email: 'alisa.ross@example.com',
  },
  {
    key: '3',
    name: 'Kevin Sandra',
    salary: 22000,
    birthday: '1992-02-11',
    city: 'Paris',
    road: 'Cedar',
    no: '67',
    phone: '12345678',
    email: 'kevin.sandra@example.com',
  },
  {
    key: '4',
    name: 'Ed Hellen',
    salary: 17000,
    birthday: '1991-06-21',
    city: 'London',
    road: 'Park',
    no: '317',
    phone: '12345678',
    email: 'ed.hellen@example.com',
  },
  {
    key: '5',
    name: 'William Smith',
    salary: 27000,
    birthday: '1996-08-21',
    city: 'Paris',
    road: 'Park',
    no: '114',
    phone: '12345678',
    email: 'william.smith@example.com',
  },
])
</script>
```

### 布局、自适应与拖拽调宽

在同一张表中依次切换布局、剩余空间分配、分组表头、拖拽调宽和窄容器，直接比较相同列配置的变化。

| 配置 | 作用与限制 |
| --- | --- |
| `table-layout="fixed"`（默认） | 组件计算列宽并写入 `<col>`，长文本不会任意撑开列 |
| `table-layout="auto"` | 浏览器按内容分配实际列宽，长文本可能撑开列；固定列偏移根据渲染后实测宽度修正 |
| `column-resizable` | 仅 `fixed` 布局渲染拖拽把手；拖拽后的宽度参与下一次宽度计算 |
| `max-height` 或任意列 `ellipsis` | 会强制使用 `fixed`，保证高度限制和省略行为可靠 |

`width` 不代表任何配置下都严格不变：存在弹性列且 `fit=true` 时定宽列保持原宽；全部指定宽度或 `fit=false` 时，Cedar 会按上面的规则铺满容器。

Example source: src/table/__demos__/column-sizing-playground.vue

```vue
<script setup lang="ts">
import { computed, ref } from 'vue'
import type { TableColumnData } from '@cedar-design/ui'

const props = defineProps<{ english?: boolean }>()
const layout = ref<'fixed' | 'auto'>('fixed')
const fit = ref(true)
const grouped = ref(false)
const resizable = ref(false)
const narrow = ref(false)
const labels = computed(() => props.english
  ? { fit: 'Distribute space to flexible columns', grouped: 'Grouped headers', resizable: 'Resize columns', narrow: 'Narrow container', priority: 'Priority', name: 'Task', owner: 'Owner', status: 'Status', task: 'Task information', people: 'People and status', hint: 'fixed uses computed column widths; auto lets cell content affect widths. Resizing is available only in fixed mode. Turning fit off still fills the container, but distributes space across all data columns.', drag: 'Drag a column boundary to resize it.', auto: 'auto mode hides resize handles.' }
  : { fit: '剩余空间优先给弹性列', grouped: '分组表头', resizable: '拖拽调宽', narrow: '窄容器', priority: '优先级', name: '任务', owner: '负责人', status: '状态', task: '任务信息', people: '人员与状态', hint: 'fixed 使用计算列宽；auto 允许内容影响列宽。拖拽调宽仅 fixed 可用。关闭 fit 后仍铺满容器，但剩余空间改为所有普通数据列按比例分摊。', drag: '拖动列边界可调整列宽。', auto: 'auto 模式下不显示拖拽把手。' })
const columns = computed<TableColumnData[]>(() => {
  const flat: TableColumnData[] = [
    { title: labels.value.priority, dataIndex: 'priority', width: 100, fixed: 'left' },
    { title: labels.value.name, dataIndex: 'name', minWidth: 200 },
    { title: labels.value.owner, dataIndex: 'owner', minWidth: 120 },
    { title: labels.value.status, dataIndex: 'status', width: 100, fixed: 'right' },
  ]
  return grouped.value
    ? [{ title: labels.value.task, children: flat.slice(0, 2) }, { title: labels.value.people, children: flat.slice(2) }]
    : flat
})
const data = computed(() => [
  { key: '1', priority: 'P0', name: props.english ? 'Inspect charging equipment' : '充电设备巡检', owner: 'Alex', status: props.english ? 'Active' : '进行中' },
  { key: '2', priority: 'P1', name: props.english ? 'Compare a longer task name and observe how auto layout changes column widths' : '较长的巡检任务名称，用于观察 auto 布局如何根据内容分配宽度', owner: 'Lee', status: props.english ? 'Done' : '已完成' },
])
</script>

<template>
  <div class="column-sizing-playground">
    <c-space wrap>
      <c-radio-group v-model="layout" type="button" aria-label="table-layout">
        <c-radio value="fixed">fixed</c-radio>
        <c-radio value="auto">auto</c-radio>
      </c-radio-group>
      <c-checkbox v-model="fit">fit：{{ labels.fit }}</c-checkbox>
      <c-checkbox v-model="grouped">{{ labels.grouped }}</c-checkbox>
      <c-checkbox v-model="resizable">{{ labels.resizable }}</c-checkbox>
      <c-checkbox v-model="narrow">{{ labels.narrow }}</c-checkbox>
    </c-space>
    <p>{{ labels.hint }}</p>
    <p v-if="resizable" role="status">{{ layout === 'fixed' ? labels.drag : labels.auto }}</p>
    <c-table
      :columns="columns" :data="data" :pagination="false"
      :style="{ width: narrow ? '420px' : '100%' }"
      :table-layout="layout" :fit="fit" :column-resizable="resizable"
      :bordered="{ cell: true }"
    />
  </div>
</template>

<style scoped>
.column-sizing-playground { width: 760px; max-width: 100%; }
p { margin: 12px 0; }
</style>
```

### 自动滚动与高度设置

- 横向：组件比较计算后的列宽总和与可用容器宽度，自动决定是否需要滚动；调整容器或列配置会重新计算。
- 纵向：设置 `height` 固定高度，或设置 `max-height` 让内容少时收缩、超出后滚动。不限制高度时，由页面/外层容器负责纵向滚动。
- 粘性：`sticky-header` / `sticky-pagination` 控制相对页面或外层滚动容器的定位。存在横向溢出且启用了粘性分页时，悬浮表格或焦点位于表格内即可显示底部同步滚动条。

下方“滚动与粘性定位”分组专门展示高度、表头和分页的组合。

## 表头与列结构

### 分组表头

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `columns` | 表格的列描述信息 | 分组表头、文本省略和提示、单元格合并 |
| `data` | 表格的数据 | 分组表头、文本省略和提示、单元格合并 |
| `bordered` | 是否显示边框 | 分组表头、单元格合并 |
| `span-method` | 单元格合并方法（索引从数据项开始计数） | 单元格合并 |
| `row-selection` | 表格的行选择器配置 | 单元格合并 |
| `span-all` | 是否让合并方法的索引包含所有 | 单元格合并 |
<!-- demo-config-notes:end -->

`columns` 内可以设置 `children`，用于表头分组。

Example source: src/table/__demos__/columns-children.vue

```vue
<template>
  <c-table :columns="columns" :data="data" :bordered="{ headerCell: true }" />
</template>

<script lang="ts" setup>
import { reactive } from 'vue'
const columns = [
  {
    title: 'Name',
    dataIndex: 'name',
    fixed: 'left',
    width: 140,
  },
  {
    title: 'User Info',
    children: [
      {
        title: 'Birthday',
        dataIndex: 'birthday',
      },
      {
        title: 'Address',
        children: [
          {
            title: 'City',
            dataIndex: 'city',
          },
          {
            title: 'Road',
            dataIndex: 'road',
          },
          {
            title: 'No.',
            dataIndex: 'no',
          },
        ],
      },
    ],
  },
  {
    title: 'Information',
    children: [
      {
        title: 'Email',
        dataIndex: 'email',
      },
      {
        title: 'Phone',
        dataIndex: 'phone',
      },
    ],
  },
  {
    title: 'Salary',
    dataIndex: 'salary',
    fixed: 'right',
    width: 120,
  },
]
const data = reactive([
  {
    key: '1',
    name: 'Jane Doe',
    salary: 23000,
    birthday: '1994-04-21',
    city: 'London',
    road: 'Park',
    no: '34',
    phone: '12345678',
    email: 'jane.doe@example.com',
  },
  {
    key: '2',
    name: 'Alisa Ross',
    salary: 25000,
    birthday: '1994-05-21',
    city: 'London',
    road: 'Park',
    no: '37',
    phone: '12345678',
    email: 'alisa.ross@example.com',
  },
  {
    key: '3',
    name: 'Kevin Sandra',
    salary: 22000,
    birthday: '1992-02-11',
    city: 'Paris',
    road: 'Cedar',
    no: '67',
    phone: '12345678',
    email: 'kevin.sandra@example.com',
  },
  {
    key: '4',
    name: 'Ed Hellen',
    salary: 17000,
    birthday: '1991-06-21',
    city: 'London',
    road: 'Park',
    no: '317',
    phone: '12345678',
    email: 'ed.hellen@example.com',
  },
  {
    key: '5',
    name: 'William Smith',
    salary: 27000,
    birthday: '1996-08-21',
    city: 'Paris',
    road: 'Park',
    no: '114',
    phone: '12345678',
    email: 'william.smith@example.com',
  },
])
</script>
```

### 文本省略和提示

开启 `ellipsis` 属性可以显示省略号，如果同时开启 `tooltip` 会在显示省略号时使用文本提示。注意：开启 `tooltip`
后会修改 `table-cell` 中的 DOM 结构。

Example source: src/table/__demos__/ellipsis-and-tooltip.vue

```vue
<template>
  <c-table :columns="columns" :data="data" />
</template>

<script lang="ts" setup>
import { reactive } from 'vue'
const columns = [
  {
    title: 'Name',
    dataIndex: 'name',
    ellipsis: true,
    tooltip: true,
    width: 100,
  },
  {
    title: 'Salary',
    dataIndex: 'salary',
  },
  {
    title: 'Address',
    dataIndex: 'address',
    ellipsis: true,
    width: 150,
  },
  {
    title: 'Email',
    dataIndex: 'email',
    ellipsis: true,
    tooltip: { placement: 'left' },
    width: 200,
  },
]
const data = reactive([
  {
    key: '1',
    name: 'Jane Doe',
    salary: 23000,
    address: '32 Park Road, London',
    email: 'jane.doe@example.com',
  },
  {
    key: '2',
    name: 'Alisa Ross',
    salary: 25000,
    address: '35 Park Road, London',
    email: 'alisa.ross@example.com',
  },
  {
    key: '3',
    name: 'Kevin Sandra',
    salary: 22000,
    address: '31 Park Road, London',
    email: 'kevin.sandra@example.com',
  },
  {
    key: '4',
    name: 'Ed Hellen',
    salary: 17000,
    address: '42 Park Road, London',
    email: 'ed.hellen@example.com',
  },
  {
    key: '5',
    name: 'William Smith',
    salary: 27000,
    address: '62 Park Road, London',
    email: 'william.smith@example.com',
  },
])
</script>
```

### 单元格合并

通过 `span-method` 属性进行单元格合并。可以设置 `span-all` 让列索引包含操作列，注意：目前如果合并多项选择器会导致全选状态判断错误。

Example source: src/table/__demos__/span-method.vue

```vue
<template>
  <c-space direction="column" size="lg" style="width: 100%">
    <c-table :columns="columns" :data="data" :span-method="spanMethod" />
    <c-table :columns="columns" :data="data" :span-method="dataSpanMethod" :bordered="{ wrapper: true, cell: true }" />
    <c-table
      :columns="columns"
      :data="data"
      :row-selection="{ type: 'checkbox' }"
      :span-method="spanMethodAll"
      span-all
      :bordered="{ wrapper: true, cell: true }" />
  </c-space>
</template>

<script lang="ts" setup>
const spanMethod = ({ rowIndex, columnIndex }) => {
  if (rowIndex === 1 && columnIndex === 1) {
    return {
      rowspan: 2,
      colspan: 3,
    }
  }
}
const dataSpanMethod = ({ record, column }) => {
  if (record.name === 'Alisa Ross' && column.dataIndex === 'salary') {
    return {
      rowspan: 2,
    }
  }
}
const spanMethodAll = ({ rowIndex, columnIndex }) => {
  if (rowIndex === 1 && columnIndex === 0) {
    return { rowspan: 2 }
  }

  if (rowIndex === 1 && columnIndex === 2) {
    return {
      rowspan: 2,
      colspan: 3,
    }
  }
}
const columns = [
  {
    title: 'Name',
    dataIndex: 'name',
  },
  {
    title: 'Salary',
    dataIndex: 'salary',
  },
  {
    title: 'Address',
    dataIndex: 'address',
  },
  {
    title: 'Email',
    dataIndex: 'email',
  },
]
const data = [
  {
    key: '1',
    name: 'Jane Doe',
    salary: 23000,
    address: '32 Park Road, London',
    email: 'jane.doe@example.com',
  },
  {
    key: '2',
    name: 'Alisa Ross',
    salary: 25000,
    address: '35 Park Road, London',
    email: 'alisa.ross@example.com',
  },
  {
    key: '3',
    name: 'Kevin Sandra',
    salary: 22000,
    address: '31 Park Road, London',
    email: 'kevin.sandra@example.com',
  },
  {
    key: '4',
    name: 'Ed Hellen',
    salary: 17000,
    address: '42 Park Road, London',
    email: 'ed.hellen@example.com',
  },
  {
    key: '5',
    name: 'William Smith',
    salary: 27000,
    address: '62 Park Road, London',
    email: 'william.smith@example.com',
  },
]
</script>
```

### 总结行

设置 `summary` 可以开启表尾总结行，并可以通过 `summary-text` 指定首列文字。
如果想要自定义总结行展示，可以传入函数。函数的返回值为需要展示的数据，结构同 `data` 一样即可，支持多行数据。
注意：控制列暂不可以自定义内容

Example source: src/table/__demos__/summary.vue

```vue
<template>
  <c-table :columns="columns" :data="data" :summary="true" :summary-span-method="spanMethod" />
  <c-table :columns="columns" :data="data" :height="200" :expandable="expandable" :summary="summary">
    <template #summary-cell="{ column, record, rowIndex }">
      <div :style="getColorStyle(column, record)">{{ record[column.dataIndex] }}</div>
    </template>
  </c-table>
</template>

<script lang="ts" setup>
import { reactive } from 'vue'
const expandable = {
  title: 'Expand',
  width: 80,
}
const columns = reactive([
  {
    title: 'Name',
    dataIndex: 'name',
    fixed: 'left',
    width: 140,
  },
  {
    title: 'Salary',
    dataIndex: 'salary',
    minWidth: 200,
    summaryCellStyle: (record) => {
      if (record.salary > 100000) {
        return {
          backgroundColor: 'rgb(var(--brand-6))',
          color: '#fff',
        }
      }
    },
  },
  {
    title: 'Data1',
    dataIndex: 'data1',
    minWidth: 300,
  },
  {
    title: 'Data2',
    dataIndex: 'data2',
    minWidth: 300,
  },
])
const data = reactive([
  {
    key: '1',
    name: 'Jane Doe',
    salary: 23000,
    data1: 10,
    data2: 8,
    expand: 'Expand Content',
  },
  {
    key: '2',
    name: 'Alisa Ross',
    salary: 25000,
    data1: 9,
    data2: -12,
  },
  {
    key: '3',
    name: 'Kevin Sandra',
    salary: 22000,
    data1: 15,
    data2: -2,
  },
  {
    key: '4',
    name: 'Ed Hellen',
    salary: 17000,
    data1: 2,
    data2: 3,
  },
  {
    key: '5',
    name: 'William Smith',
    salary: 27000,
    data1: 11,
    data2: 0,
  },
])

const summary = ({ columns, data }) => {
  let countData = {
    salary: 0,
    data1: 0,
    data2: 0,
  }
  data.forEach((record) => {
    countData.salary += record.salary
    countData.data1 += record.data1
    countData.data2 += record.data2
  })

  return [
    {
      name: 'Avg',
      salary: countData.salary / data.length,
      data1: countData.data1 / data.length,
      data2: countData.data2 / data.length,
    },
    {
      name: 'Sum',
      salary: countData.salary,
      data1: countData.data1,
      data2: countData.data2,
    },
  ]
}

const getColorStyle = (column, record) => {
  if (['data1', 'data2'].includes(column.dataIndex)) {
    return { color: record[column.dataIndex] > 0 ? 'red' : 'green' }
  }
  return undefined
}

const spanMethod = ({ rowIndex, columnIndex }) => {
  if (rowIndex === 0 && columnIndex === 1) {
    return {
      colspan: 2,
    }
  }
}
</script>
```

## 滚动与粘性定位

### 纵向滚动（height）

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `columns` | 表格的列描述信息 | 纵向滚动（height）、流体高度（max-height）、固定列 + 固定表头 |
| `data` | 表格的数据 | 纵向滚动（height）、流体高度（max-height）、固定列 + 固定表头 |
| `pagination` | 分页的属性配置 | 纵向滚动（height）、流体高度（max-height）、固定列 + 固定表头 |
| `height` | 表格高度。设置后表头固定，表体滚动。数字单位为 px | 纵向滚动（height）、固定列 + 固定表头 |
| `sticky-header` | 表头相对页面/外层滚动容器吸顶；数字为距顶部偏移（px） | 表头吸顶（页面滚动）、粘性表头、分页与横向滚动条 |
| `sticky-pagination` | 分页相对页面/外层滚动容器吸底；数字为距底部偏移（px） | 分页吸底（页面滚动）、粘性表头、分页与横向滚动条 |
<!-- demo-config-notes:end -->

通过 `height` 开启固定高度：表头固定，表体纵向滚动。

Example source: src/table/__demos__/scroll.vue

```vue
<template>
  <div style="margin-bottom: 16px">
    <c-switch v-model="scrollbar" />
    Virtual Scrollbar
  </div>
  <p style="margin-bottom: 8px">固定高度 <code>height</code>：表头固定，表体纵向滚动。</p>
  <c-table :columns="columns" :data="data" :height="200" :pagination="false" :scrollbar="scrollbar" />
  <br />
  <p style="margin-bottom: 8px">百分比高度：外层定高，表格 <code>height="100%"</code> 填满。</p>
  <div style="height: 220px">
    <c-table :columns="columns" :data="data" height="100%" :pagination="false" :scrollbar="scrollbar" />
  </div>
</template>

<script lang="ts" setup>
import { reactive, ref } from 'vue'

const scrollbar = ref(true)

const columns = [
  {
    title: 'Name',
    dataIndex: 'name',
    width: 140,
  },
  {
    title: 'Salary',
    dataIndex: 'salary',
    minWidth: 120,
  },
  {
    title: 'Address',
    dataIndex: 'address',
    minWidth: 200,
  },
  {
    title: 'Email',
    dataIndex: 'email',
    minWidth: 180,
  },
]

const data = reactive(
  Array.from({ length: 8 }, (_, index) => ({
    key: String(index + 1),
    name: `User ${index + 1}`,
    salary: 17000 + index * 1000,
    address: `${30 + index} Park Road, London`,
    email: `user.${index + 1}@example.com`,
  })),
)
</script>
```

### 流体高度（max-height）

`max-height`：内容少时收缩，超出后滚动；并强制 `table-layout: fixed`。可与固定列组合。

Example source: src/table/__demos__/fluid-height.vue

```vue
<template>
  <p style="margin-bottom: 8px">
    <code>max-height</code> 场景下会强制 <code>table-layout: fixed</code>（与 Element 一致）。内容少时表格收缩，超出后表体滚动；可点按钮增减行观察。
  </p>
  <c-table :columns="columns" :data="data" :max-height="250" :pagination="false" />
  <c-button style="margin-top: 12px; width: 100%" @click="onAddItem">Add Item</c-button>
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const columns = [
  {
    title: 'Date',
    dataIndex: 'date',
    fixed: 'left',
    width: 150,
  },
  {
    title: 'Name',
    dataIndex: 'name',
    width: 120,
  },
  {
    title: 'State',
    dataIndex: 'state',
    width: 120,
  },
  {
    title: 'City',
    dataIndex: 'city',
    width: 120,
  },
  {
    title: 'Address',
    dataIndex: 'address',
    width: 600,
  },
  {
    title: 'Zip',
    dataIndex: 'zip',
    width: 120,
  },
  {
    title: 'Operations',
    dataIndex: 'operations',
    fixed: 'right',
    minWidth: 120,
  },
]

let seed = 3
const data = ref([
  {
    key: '1',
    date: '2016-05-01',
    name: 'Tom',
    state: 'California',
    city: 'Los Angeles',
    address: 'No. 189, Grove St, Los Angeles',
    zip: 'CA 90036',
    operations: 'Remove',
  },
  {
    key: '2',
    date: '2016-05-02',
    name: 'Tom',
    state: 'California',
    city: 'Los Angeles',
    address: 'No. 189, Grove St, Los Angeles',
    zip: 'CA 90036',
    operations: 'Remove',
  },
  {
    key: '3',
    date: '2016-05-03',
    name: 'Tom',
    state: 'California',
    city: 'Los Angeles',
    address: 'No. 189, Grove St, Los Angeles',
    zip: 'CA 90036',
    operations: 'Remove',
  },
])

const onAddItem = () => {
  seed += 1
  data.value.push({
    key: String(seed),
    date: `2016-05-${String(seed).padStart(2, '0')}`,
    name: 'Tom',
    state: 'California',
    city: 'Los Angeles',
    address: 'No. 189, Grove St, Los Angeles',
    zip: 'CA 90036',
    operations: 'Remove',
  })
}
</script>
```

### 固定列 + 固定表头

同时设置 `height` 与左右固定列（对齐 Element 的 fixed column and header 场景）。

Example source: src/table/__demos__/fixed-column-and-header.vue

```vue
<template>
  <p style="margin-bottom: 8px">
    同时设置 <code>height</code> 与左右 <code>fixed</code> 列：表头固定 + 横向滚动时固定列保持可见。
  </p>
  <c-table :columns="columns" :data="data" :height="250" :pagination="false" />
</template>

<script lang="ts" setup>
import { reactive } from 'vue'

const columns = [
  {
    title: 'Date',
    dataIndex: 'date',
    fixed: 'left',
    width: 150,
  },
  {
    title: 'Name',
    dataIndex: 'name',
    width: 120,
  },
  {
    title: 'State',
    dataIndex: 'state',
    width: 120,
  },
  {
    title: 'City',
    dataIndex: 'city',
    width: 120,
  },
  {
    title: 'Address',
    dataIndex: 'address',
    minWidth: 600,
  },
  {
    title: 'Zip',
    dataIndex: 'zip',
    width: 120,
  },
  {
    title: 'Operations',
    dataIndex: 'operations',
    fixed: 'right',
    width: 120,
  },
]

const data = reactive(
  Array.from({ length: 10 }, (_, index) => ({
    key: String(index + 1),
    date: `2016-05-${String(index + 1).padStart(2, '0')}`,
    name: 'Tom',
    state: 'California',
    city: 'Los Angeles',
    address: 'No. 189, Grove St, Los Angeles',
    zip: 'CA 90036',
    operations: 'Detail',
  })),
)
</script>
```

### 表头吸顶（页面滚动）

`sticky-header` 是相对**页面/外层滚动容器**的 CSS sticky，和 `height` 造成的「表体内滚动 + 表头固定」不是一回事。

- 适用：表格很高、页面整体滚动时希望表头贴在视口顶部
- 不适用：只想在表格内部滚动看数据 → 用 `height` / `max-height`
- 传数字可指定距顶部偏移（例如避开全局导航）

Example source: src/table/__demos__/sticky-header.vue

```vue
<template>
  <p style="margin-bottom: 8px; color: var(--color-text-3); font-size: 13px">
    <code>sticky-header</code> 相对页面/外层滚动容器吸顶。传数字可指定距顶部偏移，例如导航高度
    <code>60</code> → <code>top: 60px</code>。请滚动文档页查看效果。
  </p>
  <c-table :columns="columns" :data="data" :sticky-header="60" :pagination="false" />
</template>

<script lang="ts" setup>
import { reactive } from 'vue'

const columns = [
  {
    title: 'Name',
    dataIndex: 'name',
    width: 140,
  },
  {
    title: 'Salary',
    dataIndex: 'salary',
    minWidth: 120,
  },
  {
    title: 'Address',
    dataIndex: 'address',
    minWidth: 200,
  },
  {
    title: 'Email',
    dataIndex: 'email',
    minWidth: 180,
  },
]

const data = reactive(
  Array.from({ length: 40 }, (_, index) => ({
    key: String(index + 1),
    name: `User ${index + 1}`,
    salary: 17000 + index * 500,
    address: `${30 + (index % 20)} Park Road, London`,
    email: `user.${index + 1}@example.com`,
  })),
)
</script>
```

### 分页吸底（页面滚动）

`sticky-pagination` 相对**页面/外层滚动容器**吸底，翻长列表时分页条留在视口底部。传数字可指定距底部偏移。

Example source: src/table/__demos__/sticky-panation.vue

```vue
<template>
  <p style="margin-bottom: 8px; color: var(--color-text-3); font-size: 13px">
    <code>sticky-pagination</code> 相对<strong>页面/外层滚动容器</strong>吸底。适合长列表翻页时分页条常驻视口底部；数字为距底部偏移（px）。
  </p>
  <c-table
    :columns="columns"
    :data="data"
    sticky-pagination
    :pagination="{ pageSize: 20 }"
  />
</template>

<script lang="ts" setup>
import { reactive } from 'vue'

const columns = [
  {
    title: 'Name',
    dataIndex: 'name',
    width: 140,
  },
  {
    title: 'Salary',
    dataIndex: 'salary',
    minWidth: 120,
  },
  {
    title: 'Address',
    dataIndex: 'address',
    minWidth: 200,
  },
  {
    title: 'Email',
    dataIndex: 'email',
    minWidth: 180,
  },
]

const data = reactive(
  Array.from({ length: 80 }, (_, index) => ({
    key: String(index + 1),
    name: `User ${index + 1}`,
    salary: 17000 + index * 500,
    address: `${30 + (index % 20)} Park Road, London`,
    email: `user.${index + 1}@example.com`,
  })),
)
</script>
```

### 粘性表头、分页与横向滚动条

Example source: src/table/__demos__/sticky-layout.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const pageScroll = ref(false)
const custom = ref(false)
const external = ref(false)
const pagerHost = ref<HTMLElement>()
const page = ref(1)
const rows = Array.from({ length: 160 }, (_, index) => ({ key: index + 1, name: `User ${index + 1}`, city: 'Shanghai', email: `user${index + 1}@example.com`, description: `Rightmost field ${index + 1}` }))
const columns = [{ title: 'Name', dataIndex: 'name', width: 200 }, { title: 'City', dataIndex: 'city', width: 200 }, { title: 'Email', dataIndex: 'email', width: 360 }, { title: 'Description', dataIndex: 'description', width: 480 }]
</script>
<template>
 <c-space direction="column">
  <c-space>
   <c-checkbox v-model="pageScroll">整页滚动</c-checkbox>
   <c-checkbox v-model="custom">自定义分页</c-checkbox>
   <c-checkbox v-model="external">将底部区域移到 Table 外部</c-checkbox>
  </c-space>
  <p>滚动发生在外层容器；Table 不设置 height 或 max-height。切换整页滚动，验证相同的表头和底部区域。</p>
  <p role="status">当前页: {{ page }}</p>
  <div :class="['sticky-table-demo', { 'sticky-table-demo--page': pageScroll }]">
   <c-table
    :columns="columns" :data="rows"
    :sticky-header="0" :sticky-pagination="0"
    :pagination="{ modelValue: page, pageSize: 40, container: external ? pagerHost : undefined }"
    @page-change="page = $event"
   >
    <template v-if="custom" #pagination="{ page: current, pageSize, total, onChange }">
     <c-space>
      <c-button :disabled="current <= 1" @click="onChange(current - 1)">上一页</c-button>
      <span>{{ current }} / {{ Math.max(1, Math.ceil(total / pageSize)) }}</span>
      <c-button :disabled="current * pageSize >= total" @click="onChange(current + 1)">下一页</c-button>
     </c-space>
    </template>
   </c-table>
   <div ref="pagerHost" class="sticky-table-pagination-host" />
  </div>
 </c-space>
</template>
<style scoped>
.sticky-table-demo { max-height: 420px; overflow: auto; isolation: isolate; }
.sticky-table-demo--page { max-height: none; overflow: visible; }
.sticky-table-pagination-host { display: contents; }
</style>
```

sticky-header 与 sticky-pagination 相对页面或外层滚动容器定位。数值 0 表示启用且偏移为 0。与 height/max-height 限制表格内部滚动是两种不同场景。祖先应保留实际滚动布局，不要额外套 overflow:hidden 阻断粘性定位。

内置分页吸底时，将同步横向滚动条放在分页上方并一起吸底。表体与该滚动条双向同步，分页不再盖住唯一可用的横向滚动入口；没有横向溢出时不显示这条滚动条。

需要完全自定义布局时传 pagination=false，分页和当前页数据由业务控制。示例可以切换这种模式。此时 Table 不进行内置分页切片；后端分页传当前页，前端分页由业务先 slice。pagination 对象里的 total 仅控制分页总数，不会自动发请求。

### 只替换分页内容，保留 Table 的吸底布局

完整 pagination 插槽接收 { page, pageSize, total, onChange, onPageSizeChange }。放入业务分页组件即可替换内置 Pagination；Table 继续负责数据分页与滚动条/分页的上下布局。业务分页不要自行 position:fixed，否则会离开该布局。pagination=false 则完全退出这套分页协议，适合业务自己管理当前页数据和整个布局。

```vue
<c-table :data="rows" :columns="columns" sticky-header sticky-pagination :pagination="{ pageSize: 20 }">
  <template #pagination="pager">
    <business-pagination :page="pager.page" :page-size="pager.pageSize" :total="pager.total" @change="pager.onChange" />
  </template>
</c-table>
```

横向操作条的最小高度由 `--c-table-sticky-scrollbar-height` 控制，默认 16px；实际高度同时保留浏览器原生滚动条所需空间。

### 分页挂载到外部容器

`pagination.container` 接收 CSS 选择器或 HTMLElement，省略时分页仍在表格内部。只是改变挂载位置，页码、数据切片、事件和粘性底部仍由同一个 Table 管理，无需插槽或另一套分页状态。使用同一个滚动容器时，外部宿主可设为 display: contents，让粘性分页与横向滚动条共享滚动上下文。指定目标必须实际存在；Vue 3.5 defer 支持同一渲染批次内创建的目标。SSR 由宿主框架处理 Teleport 输出。`pagination=false` 仍表示完全关闭 Table 分页及数据切片。

```vue
<c-table
  :data="rows" :columns="columns"
  :sticky-header="0" :sticky-pagination="0"
  :pagination="{ pageSize: 10, total: 500, container: '#table-pagination' }"
/>
<div id="table-pagination" style="display: contents" />
```

粘性定位示例提供外层滚动容器，Table 本身不设置 height/max-height 或纵向滚动限制。可切换整页滚动、自定义分页和外置底部挂载点。Table 统一管理同步横向滚动条与 pagination 插槽组成的吸附区域，pagination.container 移动整个区域。外置目标必须处于预期的滚动与布局边界内，任意 DOM 位置不保证相同的 sticky 效果。

开启粘性分页时隐藏内部横向滑块及原生横向滚动条，底部复用 Scrollbar 的 embed 模式，在鼠标悬浮整个 Table 或键盘焦点进入 Table 时显示；分页挂载到外部容器时同样生效。拖动、轨道点击和触控板保持同步。示例的纵向滚动由外层容器负责，Table 未设置 height/max-height。

## 选择与数据交互

### 行选择器

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `columns` | 表格的列描述信息 | 行选择器、行选择器(单选框)、展开行 |
| `data` | 表格的数据 | 行选择器、行选择器(单选框)、展开行 |
| `row-selection` | 表格的行选择器配置 | 行选择器、行选择器(单选框)、树形数据展示 |
| `draggable` | 表格拖拽排序的配置 | 可拖拽表格、拖拽锚点 |
| `selected-keys` | 已选择的行（受控模式）优先于 `rowSelection` | 行选择器 |
| `pagination` | 分页的属性配置 | 行选择器 |
<!-- demo-config-notes:end -->

通过设置 `row-selection` 开启行选择器。

Example source: src/table/__demos__/row-selection.vue

```vue
<template>
  <c-space direction="column" fill size="lg">
    <div>
      <span>OnlyCurrent:</span>
      <c-switch v-model="rowSelection.onlyCurrent" />
    </div>
    <c-table
      v-model:selectedKeys="selectedKeys"
      :columns="columns"
      :data="data"
      :pagination="pagination"
      :row-selection="rowSelection"
      row-key="name" />
  </c-space>
</template>

<script lang="ts" setup>
import { reactive, ref } from 'vue'
const selectedKeys = ref(['Jane Doe', 'Alisa Ross'])

const rowSelection = reactive({
  type: 'checkbox',
  showCheckedAll: true,
  onlyCurrent: false,
})
const pagination = { pageSize: 5 }

const columns = [
  {
    title: 'Name',
    dataIndex: 'name',
  },
  {
    title: 'Salary',
    dataIndex: 'salary',
  },
  {
    title: 'Address',
    dataIndex: 'address',
  },
  {
    title: 'Email',
    dataIndex: 'email',
  },
]
const data = reactive([
  {
    key: '1',
    name: 'Jane Doe',
    salary: 23000,
    address: '32 Park Road, London',
    email: 'jane.doe@example.com',
  },
  {
    key: '2',
    name: 'Alisa Ross',
    salary: 25000,
    address: '35 Park Road, London',
    email: 'alisa.ross@example.com',
  },
  {
    key: '3',
    name: 'Kevin Sandra',
    salary: 22000,
    address: '31 Park Road, London',
    email: 'kevin.sandra@example.com',
    disabled: true,
  },
  {
    key: '4',
    name: 'Ed Hellen',
    salary: 17000,
    address: '42 Park Road, London',
    email: 'ed.hellen@example.com',
  },
  {
    key: '5',
    name: 'William Smith',
    salary: 27000,
    address: '62 Park Road, London',
    email: 'william.smith@example.com',
  },
  {
    key: '6',
    name: 'Jane Doe 2',
    salary: 15000,
    address: '32 Park Road, London',
    email: 'jane.doe@example.com',
  },
  {
    key: '7',
    name: 'Alisa Ross 2',
    salary: 28000,
    address: '35 Park Road, London',
    email: 'alisa.ross@example.com',
  },
  {
    key: '8',
    name: 'Kevin Sandra 2',
    salary: 26000,
    address: '31 Park Road, London',
    email: 'kevin.sandra@example.com',
  },
  {
    key: '9',
    name: 'Ed Hellen 2',
    salary: 18000,
    address: '42 Park Road, London',
    email: 'ed.hellen@example.com',
  },
  {
    key: '10',
    name: 'William Smith 2',
    salary: 12000,
    address: '62 Park Road, London',
    email: 'william.smith@example.com',
  },
])
</script>
```

### 行选择器(单选框)

通过设置 `rowSelection.type='radio'` 开启单选模式。

Example source: src/table/__demos__/row-selection-single.vue

```vue
<template>
  <c-table :columns="columns" :data="data" :row-selection="rowSelection" />
</template>

<script lang="ts" setup>
import { reactive } from 'vue'
const rowSelection = {
  type: 'radio',
}
const columns = [
  {
    title: 'Name',
    dataIndex: 'name',
  },
  {
    title: 'Salary',
    dataIndex: 'salary',
  },
  {
    title: 'Address',
    dataIndex: 'address',
  },
  {
    title: 'Email',
    dataIndex: 'email',
  },
]
const data = reactive([
  {
    key: '1',
    name: 'Jane Doe',
    salary: 23000,
    address: '32 Park Road, London',
    email: 'jane.doe@example.com',
  },
  {
    key: '2',
    name: 'Alisa Ross',
    salary: 25000,
    address: '35 Park Road, London',
    email: 'alisa.ross@example.com',
  },
  {
    key: '3',
    name: 'Kevin Sandra',
    salary: 22000,
    address: '31 Park Road, London',
    email: 'kevin.sandra@example.com',
  },
  {
    key: '4',
    name: 'Ed Hellen',
    salary: 17000,
    address: '42 Park Road, London',
    email: 'ed.hellen@example.com',
  },
  {
    key: '5',
    name: 'William Smith',
    salary: 27000,
    address: '62 Park Road, London',
    email: 'william.smith@example.com',
  },
])
</script>
```

### 展开行

通过设置 `expandable` 开启展开行功能。可以在 `data` 中添加 `expand` 属性，设置展开行显示内容。

Example source: src/table/__demos__/expandable.vue

```vue
<template>
  <c-table :columns="columns" :data="data" :expandable="expandable" />
</template>

<script lang="ts" setup>
import { reactive } from 'vue'
const expandable = reactive({
  title: 'Expand',
  width: 80,
  expandedRowRender: (record) => {
    if (record.key === '3') {
      return `My Name is ${record.name}`
    }
  },
})

const columns = [
  {
    title: 'Name',
    dataIndex: 'name',
  },
  {
    title: 'Salary',
    dataIndex: 'salary',
  },
  {
    title: 'Address',
    dataIndex: 'address',
  },
  {
    title: 'Email',
    dataIndex: 'email',
  },
]

const data = reactive([
  {
    key: '1',
    name: 'Jane Doe',
    salary: 23000,
    address: '32 Park Road, London',
    email: 'jane.doe@example.com',
    expand: 'Expand Data',
  },
  {
    key: '2',
    name: 'Alisa Ross',
    salary: 25000,
    address: '35 Park Road, London',
    email: 'alisa.ross@example.com',
  },
  {
    key: '3',
    name: 'Kevin Sandra',
    salary: 22000,
    address: '31 Park Road, London',
    email: 'kevin.sandra@example.com',
  },
  {
    key: '4',
    name: 'Ed Hellen',
    salary: 17000,
    address: '42 Park Road, London',
    email: 'ed.hellen@example.com',
  },
  {
    key: '5',
    name: 'William Smith',
    salary: 27000,
    address: '62 Park Road, London',
    email: 'william.smith@example.com',
  },
])
</script>
```

### 树形数据展示

树形数据展示的例子，`data` 里有 `children` 字段时会展示为树形表格。

Example source: src/table/__demos__/tree-children.vue

```vue
<template>
  <c-space>
    <span>checkStrictly:</span>
    <c-switch v-model="rowSelection.checkStrictly" />
  </c-space>
  <c-table
    :columns="columns"
    :data="data"
    v-model:expandedKeys="expandedKeys"
    :row-selection="rowSelection"
    show-empty-tree
    style="margin-top: 20px" />
</template>

<script lang="ts" setup>
import { ref, reactive } from 'vue'
const expandedKeys = ref([])

const rowSelection = reactive({
  type: 'checkbox',
  showCheckedAll: true,
  checkStrictly: true,
})

const columns = [
  {
    title: 'Name',
    dataIndex: 'name',
  },
  {
    title: 'Salary',
    dataIndex: 'salary',
  },
  {
    title: 'Address',
    dataIndex: 'address',
  },
  {
    title: 'Email',
    dataIndex: 'email',
  },
]
const data = [
  {
    key: '1',
    name: 'Jane Doe',
    salary: 23000,
    address: '32 Park Road, London',
    email: 'jane.doe@example.com',
    children: [
      {
        key: '2',
        name: 'Alisa Ross',
        salary: 25000,
        address: '35 Park Road, London',
        email: 'alisa.ross@example.com',
        children: [
          {
            key: '3',
            name: 'Ed Hellen',
            salary: 17000,
            address: '42 Park Road, London',
            email: 'ed.hellen@example.com',
          },
          {
            key: '4',
            name: 'William Smith',
            salary: 27000,
            address: '62 Park Road, London',
            email: 'william.smith@example.com',
          },
        ],
      },
      {
        key: '5',
        name: 'Alisa Ross',
        salary: 25000,
        address: '35 Park Road, London',
        email: 'alisa.ross@example.com',
      },
    ],
  },
  {
    key: '6',
    name: 'Alisa Ross',
    salary: 25000,
    address: '35 Park Road, London',
    email: 'alisa.ross@example.com',
  },
  {
    key: '7',
    name: 'Kevin Sandra',
    salary: 22000,
    address: '31 Park Road, London',
    email: 'kevin.sandra@example.com',
  },
  {
    key: '8',
    name: 'Ed Hellen',
    salary: 17000,
    address: '42 Park Road, London',
    email: 'ed.hellen@example.com',
  },
  {
    key: '9',
    name: 'William Smith',
    salary: 27000,
    address: '62 Park Road, London',
    email: 'william.smith@example.com',
    children: [],
  },
]
</script>
```

### 排序和筛选

通过设置 `columns` 中的 `sortable` 和 `filterable` 属性，可以配置排序和筛选功能。 通过 `filter-icon-align-left`
属性可以让筛选按钮左对齐。
<br/>
如果想实现远程排序，可以通过`sortable.sorter=true` 来关闭内部排序，并通过 `change` 或者 `sorterChange` 事件来实现服务器端排序。
<br/>
如果想实现远程筛选，则需要不传`filterable.filter`或者使`filterable.filter`返回`true`,来关闭内部筛选，并通过 `change`
或者`filterChange`事件来实现服务器端筛选。
Example source: src/table/__demos__/sort-and-filter.vue

```vue
<template>
  <c-space direction="column" size="lg" fill>
    <c-space>
      <c-switch v-model="alignLeft" />
      <span>Filter icon align left: {{ alignLeft }}</span>
    </c-space>
    <c-table :columns="columns" :data="data" :filter-icon-align-left="alignLeft" @change="handleChange" />
  </c-space>
</template>

<script lang="ts" setup>
import { reactive, ref } from 'vue'
const alignLeft = ref(false)

const columns = [
  {
    title: 'Name',
    dataIndex: 'name',
    sortable: {
      sortDirections: ['ascend', 'descend'],
    },
  },
  {
    title: 'Salary',
    dataIndex: 'salary',
    sortable: {
      sortDirections: ['ascend'],
    },
    filterable: {
      filters: [
        {
          text: '> 20000',
          value: '20000',
        },
        {
          text: '> 30000',
          value: '30000',
        },
      ],
      filter: (value, record) => record.salary > value,
      multiple: true,
    },
  },
  {
    title: 'Address',
    dataIndex: 'address',
    filterable: {
      filters: [
        {
          text: 'London',
          value: 'London',
        },
        {
          text: 'Paris',
          value: 'Paris',
        },
      ],
      filter: (value, row) => row.address.includes(value),
    },
  },
  {
    title: 'Email',
    dataIndex: 'email',
  },
]
const data = reactive([
  {
    key: '1',
    name: 'Jane Doe',
    salary: 23000,
    address: '32 Park Road, London',
    email: 'jane.doe@example.com',
  },
  {
    key: '2',
    name: 'Alisa Ross',
    salary: 25000,
    address: '35 Park Road, London',
    email: 'alisa.ross@example.com',
  },
  {
    key: '3',
    name: 'Kevin Sandra',
    salary: 22000,
    address: '31 Park Road, London',
    email: 'kevin.sandra@example.com',
  },
  {
    key: '4',
    name: 'Ed Hellen',
    salary: 17000,
    address: '42 Park Road, London',
    email: 'ed.hellen@example.com',
  },
  {
    key: '5',
    name: 'William Smith',
    salary: 27000,
    address: '62 Park Road, London',
    email: 'william.smith@example.com',
  },
])

const handleChange = (data, extra, currentDataSource) => {
  console.log('change', data, extra, currentDataSource)
}
</script>
```

### 可拖拽表格

（实验性）
开启表格行可拖拽功能

Example source: src/table/__demos__/droppable-table.vue

```vue
<template>
  <c-table :columns="columns" :data="data" @change="handleChange" :draggable="{}"></c-table>
</template>

<script lang="ts" setup>
import { reactive, ref } from 'vue'
const columns = reactive([
  {
    title: 'Name',
    dataIndex: 'name',
  },
  {
    title: 'Salary',
    dataIndex: 'salary',
  },
  {
    title: 'Address',
    dataIndex: 'address',
  },
  {
    title: 'Email',
    dataIndex: 'email',
  },
])
const data = ref([
  {
    key: '1',
    name: 'Jane Doe',
    salary: 23000,
    address: '32 Park Road, London',
    email: 'jane.doe@example.com',
  },
  {
    key: '2',
    name: 'Alisa Ross',
    salary: 25000,
    address: '35 Park Road, London',
    email: 'alisa.ross@example.com',
  },
  {
    key: '3',
    name: 'Kevin Sandra',
    salary: 22000,
    address: '31 Park Road, London',
    email: 'kevin.sandra@example.com',
  },
  {
    key: '4',
    name: 'Ed Hellen',
    salary: 17000,
    address: '42 Park Road, London',
    email: 'ed.hellen@example.com',
  },
  {
    key: '5',
    name: 'William Smith',
    salary: 27000,
    address: '62 Park Road, London',
    email: 'william.smith@example.com',
  },
])
const handleChange = (_data) => {
  console.log(_data)
  data.value = _data
}
</script>
```

### 拖拽锚点

（实验性）
开启锚点拖拽功能

Example source: src/table/__demos__/droppable-anchor.vue

```vue
<template>
  <c-table :columns="columns" :data="data" @change="handleChange" :draggable="{ type: 'handle', width: 40 }" />
</template>

<script lang="ts" setup>
import { reactive, ref } from 'vue'
const columns = reactive([
  {
    title: 'Name',
    dataIndex: 'name',
  },
  {
    title: 'Salary',
    dataIndex: 'salary',
  },
  {
    title: 'Address',
    dataIndex: 'address',
  },
  {
    title: 'Email',
    dataIndex: 'email',
  },
])
const data = ref([
  {
    key: '1',
    name: 'Jane Doe',
    salary: 23000,
    address: '32 Park Road, London',
    email: 'jane.doe@example.com',
  },
  {
    key: '2',
    name: 'Alisa Ross',
    salary: 25000,
    address: '35 Park Road, London',
    email: 'alisa.ross@example.com',
  },
  {
    key: '3',
    name: 'Kevin Sandra',
    salary: 22000,
    address: '31 Park Road, London',
    email: 'kevin.sandra@example.com',
  },
  {
    key: '4',
    name: 'Ed Hellen',
    salary: 17000,
    address: '42 Park Road, London',
    email: 'ed.hellen@example.com',
  },
  {
    key: '5',
    name: 'William Smith',
    salary: 27000,
    address: '62 Park Road, London',
    email: 'william.smith@example.com',
  },
])
const handleChange = (_data) => {
  console.log(_data)
  data.value = _data
}
</script>
```

### 可编辑表格

可以在使用插槽获得的数据，修改 `data` 中的数据，达到可编辑表格的功能。
可以直接修改插槽传出的 `record` 变量。这个 `record` 变量是传入的 `data` 中对应数据的引用，请保证 `data` 为 Reactive 类型。

Example source: src/table/__demos__/editable-form.vue

```vue
<template>
  <c-table :columns="columns" :data="data">
    <template #name="{ rowIndex }">
      <c-input v-model="data[rowIndex].name" />
    </template>
    <template #province="{ rowIndex }">
      <c-form-item layout="vertical" hide-label>
        <c-select
          v-model="data[rowIndex].province"
          @change="() => handleChange(rowIndex)"
        >
          <c-option v-for="value of Object.keys(options)">{{ value }}</c-option>
        </c-select>
      </c-form-item>
    </template>
    <template #city="{ rowIndex }">
      <c-form-item layout="vertical" hide-label>
        <c-select
          :options="options[data[rowIndex].province] || []"
          v-model="data[rowIndex].city"
        />
      </c-form-item>
    </template>
  </c-table>
  <!-- support from v2.25.0  -->
  <c-table :columns="columns" :data="data" style="margin-top: 20px">
    <template #name="{ record, rowIndex }">
      <c-input v-model="record.name" />
    </template>
    <template #province="{ record, rowIndex }">
      <c-form-item layout="vertical" hide-label>
        <c-select
          v-model="record.province"
          @change="
            () => {
              record.city = '';
            }
          "
        >
          <c-option v-for="value of Object.keys(options)">{{ value }}</c-option>
        </c-select>
      </c-form-item>
    </template>
    <template #city="{ record, rowIndex }">
      <c-form-item layout="vertical" hide-label>
        <c-select
          :options="options[record.province] || []"
          v-model="record.city"
        />
      </c-form-item>
    </template>
  </c-table>
</template>

<script lang="ts" setup>
import { reactive } from "vue";
const options = {
  Beijing: ["Haidian", "Chaoyang", "Changping"],
  Sichuan: ["Chengdu", "Mianyang", "Aba"],
  Guangdong: ["Guangzhou", "Shenzhen", "Shantou"],
};
const columns = [
  {
    title: "Name",
    dataIndex: "name",
    slotName: "name",
  },
  {
    title: "Salary",
    dataIndex: "salary",
  },
  {
    title: "Address",
    dataIndex: "address",
  },
  {
    title: "Province",
    dataIndex: "province",
    slotName: "province",
  },
  {
    title: "City",
    dataIndex: "city",
    slotName: "city",
  },
  {
    title: "Email",
    dataIndex: "email",
  },
];

const data = reactive([
  {
    key: "1",
    name: "Jane Doe",
    salary: 23000,
    address: "32 Park Road, London",
    province: "Beijing",
    city: "Haidian",
    email: "jane.doe@example.com",
  },
  {
    key: "2",
    name: "Alisa Ross",
    salary: 25000,
    address: "35 Park Road, London",
    email: "alisa.ross@example.com",
  },
  {
    key: "3",
    name: "Kevin Sandra",
    salary: 22000,
    address: "31 Park Road, London",
    province: "Sichuan",
    city: "Mianyang",
    email: "kevin.sandra@example.com",
  },
  {
    key: "4",
    name: "Ed Hellen",
    salary: 17000,
    address: "42 Park Road, London",
    email: "ed.hellen@example.com",
  },
  {
    key: "5",
    name: "William Smith",
    salary: 27000,
    address: "62 Park Road, London",
    email: "william.smith@example.com",
  },
]);

const handleChange = (rowIndex) => {
  data[rowIndex].city = "";
};
</script>
```

## 列管理与渲染定制

### 自定义表头 / 列管理

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `columns` | 表格的列描述信息 | 自定义表头 / 列管理、自定义筛选菜单、自定义渲染 |
| `data` | 表格的数据 | 自定义表头 / 列管理、自定义筛选菜单、自定义渲染 |
| `pagination` | 分页的属性配置 | 自定义表头 / 列管理 |
| `size` | 表格的大小 | 自定义表头 / 列管理 |
| `row-class` | 表格行元素的类名。 | 自定义表格元素 |
<!-- demo-config-notes:end -->

Table **不内置**列管理。通过扩展点与外部 `TableColumnManager` 组合：

- `extra-column`：末尾扩展列（如设置图标），内容用 `#extra-column-header` / `#extra-column-cell`；默认宽度 **28px**，可通过 `extraColumn: { width: number }` 覆盖
- `#header-cell-actions`：表头右侧操作区，菜单内容由外部完全控制
- `v-model:columns` + `@column-resize`：外部改列并触发重渲染

基础组合：

Example source: src/table/__demos__/column-manager-basic.vue

```vue
<template>
  <c-space wrap justify="flex-end" style="margin-bottom: 8px">
    <c-link @click="visible = true">列管理</c-link>
  </c-space>

  <c-table
    v-model:columns="columns"
    :data="data"
    :pagination="false"
    size="xs"
  />

  <c-drawer
    v-model:open="visible"
    title="列管理"
    :width="720"
    unmount-on-close
    @confirm="handleConfirm"
  >
    <div style="height: calc(100vh - 120px)">
      <c-table-column-manager
        ref="mgrRef"
        v-model="items"
        :columns="columns"
        :options="columnDefinitions"
      />
    </div>
  </c-drawer>
</template>

<script setup lang="ts">
import { ref, watch } from "vue";
import { stateFromColumns } from "@cedar-design/ui";
import type {
  ColumnDefinitions,
  TableColumnData,
  TableColumnManagerInstance,
} from "@cedar-design/ui";

const visible = ref(false);
const mgrRef = ref<TableColumnManagerInstance>();
const items = ref([]);

const columns = ref<TableColumnData[]>([
  { dataIndex: "name", title: "姓名", width: 120 },
  { dataIndex: "salary", title: "薪资", width: 100 },
  { dataIndex: "address", title: "地址", width: 180 },
]);

const columnDefinitions: ColumnDefinitions = [
  {
    title: "基础",
    key: "basic",
    children: [
      { dataIndex: "name", title: "姓名", required: true },
      { dataIndex: "salary", title: "薪资" },
      { dataIndex: "email", title: "邮箱" },
      { dataIndex: "address", title: "地址" },
    ],
  },
];

watch(visible, (val) => {
  if (!val) return;
  const state = stateFromColumns(columns.value, columnDefinitions);
  items.value = state.items;
});

const handleConfirm = () => {
  const result = mgrRef.value?.getResult?.();
  if (result) columns.value = result.columns;
  visible.value = false;
};

const data = ref([
  { name: "Jane", salary: 23000, address: "London", email: "jane@example.com" },
  {
    name: "Alisa",
    salary: 25000,
    address: "Paris",
    email: "alisa@example.com",
  },
]);
</script>
```

自定义入口与本地记忆：

Example source: src/table/__demos__/custom-table-columns.vue

```vue
<template>
  <c-space wrap size="12px" justify="flex-end" style="margin-bottom: 8px">
    <c-link @click="open">列管理</c-link>
    <c-link @click="resetColumns">重置列</c-link>
  </c-space>

  <c-table
    v-model:columns="columns"
    :data="data"
    :pagination="false"
    size="xs"
  />

  <c-table-column-manager v-bind="managerProps" />
</template>

<script lang="ts" setup>
import { onMounted, ref, watch } from "vue";
import { useTableColumnManager } from "@cedar-design/ui";
import type { ColumnDefinitions, ManagedTableColumn } from "@cedar-design/ui";

const STORAGE_KEY = "cedar-demo-table-columns";
let storage: Storage | undefined;
const storageReady = ref(false);

const defaultColumns: ManagedTableColumn[] = [
  {
    dataIndex: "connectorId",
    title: "枪ID",
    width: 100,
    fixed: "left",
    manager: { required: true },
  },
  { dataIndex: "connectorName", title: "枪名称", width: 120 },
  {
    dataIndex: "deviceName",
    title: "设备名称",
    width: 140,
    manager: { required: true },
  },
];

const columnDefinitions: ColumnDefinitions = [
  {
    title: "枪基本信息",
    key: "connectorBasicInfo",
    children: [
      {
        dataIndex: "connectorId",
        title: "枪ID",
        tip: "必选列",
      },
      { dataIndex: "connectorName", title: "枪名称" },
      { dataIndex: "connectorNo", title: "枪序号" },
      { dataIndex: "workingStatus", title: "工作状态" },
      { dataIndex: "connectStatus", title: "连接状态" },
      { dataIndex: "parkNo", title: "停车位" },
    ],
  },
  {
    title: "桩基本信息",
    key: "chargerBasicInfo",
    children: [
      { dataIndex: "deviceId", title: "设备ID" },
      {
        dataIndex: "deviceName",
        title: "设备名称",
        tip: "必选规则来自 defaultColumns",
      },
      { dataIndex: "lockStatus", title: "地锁" },
      { dataIndex: "ratedVoltage", title: "额定电压" },
    ],
  },
  {
    title: "其他信息",
    key: "other",
    children: [
      { dataIndex: "batteryStatus", title: "电池状态" },
      { dataIndex: "temperature", title: "温度" },
      { dataIndex: "current", title: "电流" },
      { dataIndex: "power", title: "功率" },
      { dataIndex: "action", title: "操作" },
    ],
  },
];

const { columns, state, restore, managerProps, open, resetToDefault } =
  useTableColumnManager({
    defaultColumns,
    columnDefinitions,
    columnDefaults: { width: 110, ellipsis: true },
    createColumn: (definition) => ({
      dataIndex: definition.dataIndex,
      title: definition.title,
      ...(definition.dataIndex === "action"
        ? { width: 100, fixed: "right" }
        : {}),
    }),
  });

onMounted(async () => {
  storage = window.localStorage;
  try {
    const raw = storage.getItem(STORAGE_KEY);
    if (raw) await restore(JSON.parse(raw));
  } catch {
    storage.removeItem(STORAGE_KEY);
  } finally {
    storageReady.value = true;
  }
});

watch(
  state,
  (value) => {
    if (!storageReady.value) return;
    storage?.setItem(STORAGE_KEY, JSON.stringify(value));
  },
  { deep: true },
);

const resetColumns = () => {
  try {
    storage?.removeItem(STORAGE_KEY);
  } catch {
    // ignore
  }
  resetToDefault();
};

const data = ref([
  {
    connectorId: "1",
    connectorName: "Jane Doe",
    connectorNo: "001",
    workingStatus: "正常",
    connectStatus: "连接中",
    parkNo: "A1",
    deviceId: "D001",
    deviceName: "Device A",
    lockStatus: "解锁",
    ratedVoltage: "220V",
    batteryStatus: "良好",
    temperature: "36",
    current: "10A",
    power: "2kW",
    action: "详情",
  },
]);
</script>
```

### 自定义筛选菜单

通过插槽可以自定义筛选菜单内容。

Example source: src/table/__demos__/custom-filter.vue

```vue
<template>
  <c-table :columns="columns" :data="data" @change="handleChange">
    <template #name-filter="{ filterValue, setFilterValue, handleFilterConfirm, handleFilterReset }">
      <div class="custom-filter">
        <c-space direction="column">
          <c-input :model-value="filterValue[0]" @input="(value) => setFilterValue([value])" />
          <div class="custom-filter-footer">
            <c-button @click="handleFilterConfirm">Confirm</c-button>
            <c-button @click="handleFilterReset">Reset</c-button>
          </div>
        </c-space>
      </div>
    </template>
  </c-table>
</template>

<script lang="ts" setup>
import { reactive, h } from 'vue'
import { Search } from '@cedar-design/ui'
const columns = [
  {
    title: 'Name',
    dataIndex: 'name',
    filterable: {
      filter: (value, record) => record.name.includes(value),
      slotName: 'name-filter',
      icon: () => h(Search),
    },
  },
  {
    title: 'Salary',
    dataIndex: 'salary',
    sortable: {
      sortDirections: ['ascend'],
    },
  },
  {
    title: 'Address',
    dataIndex: 'address',
  },
  {
    title: 'Email',
    dataIndex: 'email',
  },
]
const data = reactive([
  {
    key: '1',
    name: 'Jane Doe',
    salary: 23000,
    address: '32 Park Road, London',
    email: 'jane.doe@example.com',
  },
  {
    key: '2',
    name: 'Alisa Ross',
    salary: 25000,
    address: '35 Park Road, London',
    email: 'alisa.ross@example.com',
  },
  {
    key: '3',
    name: 'Kevin Sandra',
    salary: 22000,
    address: '31 Park Road, London',
    email: 'kevin.sandra@example.com',
  },
  {
    key: '4',
    name: 'Ed Hellen',
    salary: 17000,
    address: '42 Park Road, London',
    email: 'ed.hellen@example.com',
  },
  {
    key: '5',
    name: 'William Smith',
    salary: 27000,
    address: '62 Park Road, London',
    email: 'william.smith@example.com',
  },
])

const handleChange = (data, extra, currentDataSource) => {
  console.log('change', data, extra, currentDataSource)
}
</script>

<style>
.custom-filter {
  padding: 20px;
  background: var(--color-bg-5);
  border: 1px solid var(--color-neutral-3);
  border-radius: var(--border-radius-medium);
  box-shadow: 0 2px 5px rgb(0 0 0 / 10%);
}

.custom-filter-footer {
  display: flex;
  justify-content: space-between;
}
</style>
```

### 自定义渲染

通过 `#columns` 插槽和 `<c-table-column>` 组件可以使用模板的方法自定义列渲染。
注意：在使用 `#columns` 插槽后，将会屏蔽 `columns` 属性

Example source: src/table/__demos__/custom-rendering.vue

```vue
<template>
  <c-table :columns="columns" :data="data">
    <template #optional="{ record }">
      <c-button @click="$dialog.info({ title: 'Name', content: record.name })">view</c-button>
    </template>
  </c-table>
  <c-table :data="data" style="margin-top: 30px">
    <template #columns>
      <c-table-column title="Name">
        <c-table-column data-index="first" title="First Name"></c-table-column>
        <c-table-column data-index="last" title="Last Name"></c-table-column>
      </c-table-column>
      <c-table-column data-index="salary" title="Salary"></c-table-column>
      <c-table-column data-index="address" title="Address"></c-table-column>
      <c-table-column data-index="email" title="Email"></c-table-column>
      <c-table-column title="Optional">
        <template #cell="{ record }">
          <c-button @click="$dialog.info({ title: 'Name', content: record.name })">view</c-button>
        </template>
      </c-table-column>
    </template>
  </c-table>
</template>

<script>
import { ref } from 'vue'
export default {
  setup() {
    const show = ref(true)

    const columns = [
      {
        title: 'Name',
        dataIndex: 'name',
      },
      {
        title: 'Salary',
        dataIndex: 'salary',
      },
      {
        title: 'Address',
        dataIndex: 'address',
      },
      {
        title: 'Email',
        dataIndex: 'email',
      },
      {
        title: 'Optional',
        slotName: 'optional',
      },
    ]
    const data = [
      {
        key: '1',
        name: 'Jane Doe',
        first: 'Jane',
        last: 'Doe',
        salary: 23000,
        address: '32 Park Road, London',
        email: 'jane.doe@example.com',
      },
      {
        key: '2',
        name: 'Alisa Ross',
        first: 'Alisa',
        last: 'Ross',
        salary: 25000,
        address: '35 Park Road, London',
        email: 'alisa.ross@example.com',
      },
      {
        key: '3',
        name: 'Kevin Sandra',
        first: 'Kevin',
        last: 'Sandra',
        salary: 22000,
        address: '31 Park Road, London',
        email: 'kevin.sandra@example.com',
      },
      {
        key: '4',
        name: 'Ed Hellen',
        first: 'Ed',
        last: 'Hellen',
        salary: 17000,
        address: '42 Park Road, London',
        email: 'ed.hellen@example.com',
      },
      {
        key: '5',
        name: 'William Smith',
        first: 'William',
        last: 'Smith',
        salary: 27000,
        address: '62 Park Road, London',
        email: 'william.smith@example.com',
      },
    ]

    return {
      columns,
      data,
      show,
    }
  },
}
</script>
```

### 自定义表格元素

可以通过特定插槽自定义表格元素的渲染。仅需要传入表格元素，内部属性会自动附加上去

Example source: src/table/__demos__/customize-table-elements.vue

```vue
<template>
  <c-table :columns="columns" :data="data" row-class="common-row">
    <template #tr>
      <tr class="my-tr" @contextmenu.prevent="onContextMenu" />
    </template>
    <template #td>
      <td class="my-td" />
    </template>
  </c-table>
  <c-tag>行右键回调：{{ contextMenus }}</c-tag>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
const contextMenus = ref(0)
const onContextMenu = () => {
  contextMenus.value++
}

const columns = [
  {
    title: 'Name',
    dataIndex: 'name',
  },
  {
    title: 'Salary',
    dataIndex: 'salary',
  },
  {
    title: 'Address',
    dataIndex: 'address',
  },
  {
    title: 'Email',
    dataIndex: 'email',
  },
]
const data = [
  {
    key: '1',
    name: 'Jane Doe',
    salary: 23000,
    address: '32 Park Road, London',
    email: 'jane.doe@example.com',
  },
  {
    key: '2',
    name: 'Alisa Ross',
    salary: 25000,
    address: '35 Park Road, London',
    email: 'alisa.ross@example.com',
  },
  {
    key: '3',
    name: 'Kevin Sandra',
    salary: 22000,
    address: '31 Park Road, London',
    email: 'kevin.sandra@example.com',
  },
  {
    key: '4',
    name: 'Ed Hellen',
    salary: 17000,
    address: '42 Park Road, London',
    email: 'ed.hellen@example.com',
  },
  {
    key: '5',
    name: 'William Smith',
    salary: 27000,
    address: '62 Park Road, London',
    email: 'william.smith@example.com',
  },
]
</script>
```

## 异步与大数据

### 子树懒加载

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `columns` | 表格的列描述信息 | 子树懒加载、异步目录、虚拟列表 |
| `data` | 表格的数据 | 子树懒加载、异步目录、虚拟列表 |
| `pagination` | 分页的属性配置 | 异步目录、虚拟列表 |
| `load-more` | 数据懒加载函数，传入时开启懒加载功能 | 子树懒加载 |
| `size` | 表格的大小 | 异步目录 |
| `row-selection` | 表格的行选择器配置 | 虚拟列表 |
<!-- demo-config-notes:end -->

通过 `load-more` 属性可以开启子树懒加载功能。
开启子树懒加载功能后，需要在无子树节点标注 `isLeaf: true`，没有标注且没有 `children` 属性的节点会认为需要子树懒加载处理。
`load-more` 属性有提供 `done` 函数进行回调，可以在回调中传入懒加载的子树。如果 `done` 函数没有传入数据会认为懒加载失败，此节点可以再次触发懒加载。

Example source: src/table/__demos__/load-more.vue

```vue
<template>
  <c-table :columns="columns" :data="data" :load-more="loadMore" />
</template>

<script lang="ts" setup>
import { reactive } from 'vue'
const columns = [
  {
    title: 'Name',
    dataIndex: 'name',
  },
  {
    title: 'Salary',
    dataIndex: 'salary',
  },
  {
    title: 'Address',
    dataIndex: 'address',
  },
  {
    title: 'Email',
    dataIndex: 'email',
  },
]
const data = reactive([
  {
    key: '1',
    name: 'Jane Doe',
    salary: 23000,
    address: '32 Park Road, London',
    email: 'jane.doe@example.com',
    children: [
      {
        key: '2',
        name: 'Alisa Ross',
        salary: 25000,
        address: '35 Park Road, London',
        email: 'alisa.ross@example.com',
      },
      {
        key: '5',
        name: 'Alisa Ross',
        salary: 25000,
        address: '35 Park Road, London',
        email: 'alisa.ross@example.com',
        isLeaf: true,
      },
    ],
  },
  {
    key: '6',
    name: 'Alisa Ross',
    salary: 25000,
    address: '35 Park Road, London',
    email: 'alisa.ross@example.com',
  },
  {
    key: '7',
    name: 'Kevin Sandra',
    salary: 22000,
    address: '31 Park Road, London',
    email: 'kevin.sandra@example.com',
    isLeaf: true,
  },
  {
    key: '8',
    name: 'Ed Hellen',
    salary: 17000,
    address: '42 Park Road, London',
    email: 'ed.hellen@example.com',
    isLeaf: true,
  },
  {
    key: '9',
    name: 'William Smith',
    salary: 27000,
    address: '62 Park Road, London',
    email: 'william.smith@example.com',
    isLeaf: true,
  },
])

const loadMore = (record, done) => {
  window.setTimeout(() => {
    done([
      {
        key: `${record.key}-1`,
        name: 'Ed Hellen',
        salary: 17000,
        address: '42 Park Road, London',
        email: 'ed.hellen@example.com',
        isLeaf: true,
      },
      {
        key: `${record.key}-2`,
        name: 'William Smith',
        salary: 27000,
        address: '62 Park Road, London',
        email: 'william.smith@example.com',
        isLeaf: true,
      },
    ])
  }, 2000)
}
</script>
```

### 异步目录

`TableColumnManager` 的 `loadOptions` / `remoteSearch` 在外部弹层中使用。

Example source: src/table/__demos__/column-manager-async.vue

```vue
<template>
  <c-space wrap justify="flex-end" style="margin-bottom: 8px">
    <c-link @click="visible = true">列管理</c-link>
  </c-space>

  <c-table
    v-model:columns="columns"
    :data="data"
    :pagination="false"
    size="xs"
  />

  <c-drawer
    v-model:open="visible"
    title="列管理"
    :width="720"
    unmount-on-close
    @confirm="handleConfirm"
  >
    <div style="height: calc(100vh - 120px)">
      <c-table-column-manager
        ref="mgrRef"
        v-model="items"
        :columns="columns"
        :load-options="loadOptions"
      />
    </div>
  </c-drawer>
</template>

<script setup lang="ts">
import { ref, watch } from "vue";
import { stateFromColumns } from "@cedar-design/ui";
import type {
  ColumnDefinitions,
  TableColumnData,
  TableColumnManagerInstance,
} from "@cedar-design/ui";

const visible = ref(false);
const mgrRef = ref<TableColumnManagerInstance>();
const items = ref([]);

const columns = ref<TableColumnData[]>([
  { dataIndex: "name", title: "姓名", width: 120 },
  { dataIndex: "salary", title: "薪资", width: 100 },
]);

const loadOptions = async (): Promise<ColumnDefinitions> => {
  await new Promise((r) => setTimeout(r, 400));
  return [
    {
      title: "基础",
      key: "basic",
      children: [
        { dataIndex: "name", title: "姓名", required: true },
        { dataIndex: "salary", title: "薪资" },
        { dataIndex: "email", title: "邮箱" },
        { dataIndex: "address", title: "地址" },
      ],
    },
  ];
};

watch(visible, async (val) => {
  if (!val) return;
  const columnDefinitions = await loadOptions();
  const state = stateFromColumns(columns.value, columnDefinitions);
  items.value = state.items;
});

const handleConfirm = () => {
  const result = mgrRef.value?.getResult?.();
  if (result) columns.value = result.columns;
  visible.value = false;
};

const data = ref([
  { name: "Jane", salary: 23000, address: "London", email: "jane@example.com" },
]);
</script>
```

详见 [`TableColumnManager`](llms/zh-CN/components/table-column-manager.md)。

### 虚拟列表

设置 `virtual-list-props` 开启虚拟列表功能。
目前虚拟滚动表格受限比较多，开启虚拟滚动后不能使用展开行、树形数据、固定列等功能

Example source: src/table/__demos__/virtual-list-props.vue

```vue
<template>
  <c-table
    :columns="columns"
    :data="data"
    :row-selection="rowSelection"
    :virtual-list-props="{ height: 400 }"
    :pagination="false" />
</template>

<script lang="ts" setup>
import { reactive } from 'vue'
const columns = [
  {
    title: 'Name',
    dataIndex: 'name',
    fixed: 'left',
    width: 140,
  },
  {
    title: 'Address',
    dataIndex: 'address',
    minWidth: 400,
  },
  {
    title: 'Email',
    dataIndex: 'email',
    minWidth: 300,
  },
]
const data = reactive(
  Array(1000)
    .fill(null)
    .map((_, index) => ({
      key: String(index),
      name: `User ${index + 1}`,
      address: '32 Park Road, London',
      email: `user.${index + 1}@example.com`,
    })),
)
const rowSelection = {
  type: 'checkbox',
  showCheckedAll: true,
}
</script>
```

## 业务组合

### 关联业务行与列类型

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `columns` | 表格的列描述信息 | 任务筛选与数据联动、表格属性 |
| `data` | 表格的数据 | 任务筛选与数据联动、表格属性 |
| `pagination` | 分页的属性配置 | 任务筛选与数据联动 |
| `bordered` | 是否显示边框 | 表格属性 |
| `hoverable` | 是否显示选中效果 | 表格属性 |
| `stripe` | 是否开启斑马纹效果 | 表格属性 |
<!-- demo-config-notes:end -->

使用 `defineTableConfig<User>` 将数据、列路径、渲染、排序和筛选回调关联到业务行。`rowKey` 显式指定业务身份；示例增加行时通过 computed 重新校验配置，数据更新照常传给原 Table。

Example source: src/table/__demos__/typed-config.vue

```vue
<script setup lang="ts">
import { computed, ref } from 'vue'
import { defineTableConfig } from '@cedar-design/ui'
interface User {
  id: string
  name: string
  age: number
  profile: { city: string }
}
const rows = ref<User[]>([
  { id: 'alice', name: 'Alice', age: 28, profile: { city: '杭州' } },
  { id: 'bob', name: 'Bob', age: 16, profile: { city: '宁波' } },
])
const config = computed(() => defineTableConfig<User>({
  rowKey: 'id',
  data: rows.value,
  pagination: false,
  columns: [
    { title: '姓名', dataIndex: 'name', render: ({ record }) => record.name.toUpperCase() },
    { title: '城市', dataIndex: 'profile.city' },
    { title: '年龄', dataIndex: 'age',
      sortable: { sortDirections: ['ascend', 'descend'], sorter: (a, b) => a.age - b.age },
      filterable: { filters: [{ text: '仅成年人', value: 'adult' }], filter: (values, record) => !values.length || !values.includes('adult') || record.age >= 18 },
    },
  ],
}))
function addRow() {
  if (rows.value.length < 3) rows.value = [...rows.value, { id: 'carol', name: 'Carol', age: 35, profile: { city: '上海' } }]
}
</script>
<template>
  <c-space direction="column" fill>
    <c-button :disabled="rows.length >= 3" @click="addRow">增加一行</c-button>
    <c-table v-bind="config" />
    <p role="status">业务数据：{{ rows.length }} 行；年龄列支持排序和筛选。</p>
  </c-space>
</template>
```

### 任务筛选与数据联动

查询任务或部门、按状态筛选、完成任务；统计和结果同步更新，支持空结果与恢复。

Example source: src/table/__demos__/task-workbench.vue

```vue
<script setup>
import { computed, ref } from "vue";
const original = () => [
  { key: "01", name: "展厅设备巡检", department: "运营部", status: "待处理" },
  { key: "02", name: "网站交互验收", department: "研发部", status: "进行中" },
  { key: "03", name: "品牌物料审核", department: "设计部", status: "待处理" },
  { key: "04", name: "移动端体验走查", department: "研发部", status: "已完成" },
  { key: "05", name: "会议室设备维护", department: "运营部", status: "进行中" },
];
const rows = ref(original());
const keyword = ref("");
const status = ref("全部");
const applied = ref({ keyword: "", status: "全部" });
const message = ref("显示全部任务。输入条件后点击查询。");
const options = ["全部", "待处理", "进行中", "已完成"].map((value) => ({
  value,
  label: value,
}));
const filtered = computed(() =>
  rows.value.filter(
    (row) =>
      (!applied.value.keyword ||
        `${row.name} ${row.department}`.includes(applied.value.keyword)) &&
      (applied.value.status === "全部" || row.status === applied.value.status),
  ),
);
const completed = computed(
  () => rows.value.filter((row) => row.status === "已完成").length,
);
const columns = [
  { title: "任务", dataIndex: "name" },
  { title: "部门", dataIndex: "department" },
  { title: "状态", dataIndex: "status" },
  { title: "操作", slotName: "action" },
];
function search() {
  applied.value = { keyword: keyword.value.trim(), status: status.value };
  message.value = `查询完成，找到 ${filtered.value.length} 条任务。`;
}
function clear() {
  keyword.value = "";
  status.value = "全部";
  applied.value = { keyword: "", status: "全部" };
  message.value = "已清空筛选条件。";
}
function finish(row) {
  row.status = "已完成";
  message.value = `已完成“${row.name}”，统计与列表已同步。`;
}
function reset() {
  rows.value = original();
  clear();
  message.value = "任务和筛选已恢复，可以重新演示。";
}
</script>
<template>
  <section class="task-workbench" aria-label="巡检任务数据联动">
    <div class="task-workbench__metrics">
      <span
        >全部 <strong>{{ rows.length }}</strong></span
      ><span
        >已完成 <strong>{{ completed }}</strong></span
      ><span
        >当前结果 <strong>{{ filtered.length }}</strong></span
      >
    </div>
    <c-form :model="applied" layout="vertical" @submit="search">
      <c-form-item label="搜索任务或部门"
        ><c-input
          v-model="keyword"
          edit-mode="direct"
          placeholder="搜索任务或部门"
          clearable
      /></c-form-item>
      <c-form-item label="任务状态"
        ><c-select v-model="status" :options="options" edit-mode="direct"
      /></c-form-item>
      <c-space wrap
        ><c-button html-type="submit" status="primary">查询任务</c-button
        ><c-button @click="clear">清空筛选</c-button
        ><c-button @click="reset">恢复全部任务</c-button></c-space
      >
    </c-form>
    <p role="status" aria-live="polite">{{ message }}</p>
    <c-table :columns="columns" :data="filtered" :pagination="false"
      ><template #action="{ record }"
        ><c-button
          :disabled="record.status === '已完成'"
          :aria-label="`完成${record.name}`"
          @click="finish(record)"
          >完成</c-button
        ></template
      ></c-table
    >
    <p v-if="!filtered.length">
      没有匹配任务。修改关键词或点击“清空筛选”恢复结果。
    </p>
    <small
      >先查询“运营部”，完成一条任务，再用状态过滤；统计与结果来自同一份本地任务数据。</small
    >
  </section>
</template>
<style scoped>
.task-workbench {
  min-width: 0;
  width: 100%;
}
.task-workbench__metrics {
  display: flex;
  flex-wrap: wrap;
  gap: 12px;
  margin-bottom: 16px;
}
.task-workbench__metrics > span {
  padding: 12px 16px;
  background: var(--c-color-fill-1);
  border-radius: 8px;
}
.task-workbench__metrics strong {
  margin-left: 8px;
  color: var(--c-color-primary);
}
.task-workbench small {
  display: block;
  margin-top: 8px;
  color: var(--c-color-text-2);
}
</style>
```

### 表格属性

这里罗列了一些表格的属性，你可以方便的打开或关闭一些属性，查看它的效果。

Example source: src/table/__demos__/form-attribute.vue

```vue
<template>
  <c-form layout="inline" :model="form">
    <c-form-item label="Border" field="border">
      <c-switch v-model="form.border" />
    </c-form-item>
    <c-form-item label="Hover" field="hover">
      <c-switch v-model="form.hover" />
    </c-form-item>
    <c-form-item label="stripe" field="stripe">
      <c-switch v-model="form.stripe" />
    </c-form-item>
    <c-form-item label="checkbox" field="checkbox">
      <c-switch v-model="form.checkbox" />
    </c-form-item>
    <c-form-item label="checkAll" field="checkAll">
      <c-switch v-model="rowSelection.showCheckedAll" />
    </c-form-item>
    <c-form-item label="loading" field="loading">
      <c-switch v-model="form.loading" />
    </c-form-item>
    <c-form-item label="tableHeader" field="tableHeader">
      <c-switch v-model="form.tableHeader" />
    </c-form-item>
    <c-form-item label="noData" field="noData">
      <c-switch v-model="form.noData" />
    </c-form-item>
  </c-form>
  <c-table
    :columns="columns"
    :data="form.noData ? [] : data"
    :bordered="form.border"
    :hoverable="form.hover"
    :stripe="form.stripe"
    :loading="form.loading"
    :show-header="form.tableHeader"
    :row-selection="form.checkbox ? rowSelection : undefined" />
</template>

<script lang="ts" setup>
import { reactive } from 'vue'
const form = reactive({
  border: true,
  borderCell: false,
  hover: true,
  stripe: false,
  checkbox: true,
  loading: false,
  tableHeader: true,
  noData: false,
})

const rowSelection = reactive({
  type: 'checkbox',
  showCheckedAll: true,
})

const columns = [
  {
    title: 'Name',
    dataIndex: 'name',
  },
  {
    title: 'Salary',
    dataIndex: 'salary',
  },
  {
    title: 'Address',
    dataIndex: 'address',
  },
  {
    title: 'Email',
    dataIndex: 'email',
  },
]

const data = [
  {
    key: '1',
    name: 'Jane Doe',
    salary: 23000,
    address: '32 Park Road, London',
    email: 'jane.doe@example.com',
  },
  {
    key: '2',
    name: 'Alisa Ross',
    salary: 25000,
    address: '35 Park Road, London',
    email: 'alisa.ross@example.com',
  },
  {
    key: '3',
    name: 'Kevin Sandra',
    salary: 22000,
    address: '31 Park Road, London',
    email: 'kevin.sandra@example.com',
  },
  {
    key: '4',
    name: 'Ed Hellen',
    salary: 17000,
    address: '42 Park Road, London',
    email: 'ed.hellen@example.com',
  },
  {
    key: '5',
    name: 'William Smith',
    salary: 27000,
    address: '62 Park Road, London',
    email: 'william.smith@example.com',
  },
]
</script>
```

## API

### `<Table>` Props

| 参数名                      | 描述                                                                                       | 类型                                                                                                                                                                          |   默认值    |
| --------------------------- | ------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------: |
| columns                     | 表格的列描述信息                                                                           | `TableColumnData[]`                                                                                                                                                           |    `[]`     |
| data                        | 表格的数据                                                                                 | `TableData[]`                                                                                                                                                                 |    `[]`     |
| bordered                    | 是否显示边框                                                                               | `boolean \| TableBorder`                                                                                                                                                      |   `true`    |
| hoverable                   | 是否显示选中效果                                                                           | `boolean`                                                                                                                                                                     |   `true`    |
| stripe                      | 是否开启斑马纹效果                                                                         | `boolean`                                                                                                                                                                     |   `false`   |
| size                        | 表格的大小                                                                                 | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'`                                                                                                                                        |   `'md'`    |
| table-layout                | 表格布局算法，同 CSS `table-layout`。默认 `fixed`，列宽由计算决定不被内容撑开           | `'fixed' \| 'auto'`                                                                                                                                                           |  `'fixed'`  |
| loading                     | 是否为加载中状态                                                                           | `boolean\|object`                                                                                                                                                             |   `false`   |
| row-selection               | 表格的行选择器配置                                                                         | `TableRowSelection`                                                                                                                                                           |     `-`     |
| expandable                  | 表格的展开行配置                                                                           | `TableExpandable`                                                                                                                                                             |     `-`     |
| height                      | 表格高度。设置后表头固定，表体滚动。数字单位为 px                                          | `number \| string`                                                                                                                                                            |     `-`     |
| max-height                  | 表格最大高度。内容不足时收缩，超出后表体滚动。数字单位为 px                                | `number \| string`                                                                                                                                                            |     `-`     |
| fit                         | 剩余空间的分配方式（表格始终至少铺满父容器）。`true`：全给未设 `width` 的弹性列；`false`：按各列基础宽度比例放大分摊 | `boolean`                                                                                                                                                                     |   `true`    |
| pagination                  | 分页的属性配置                                                                             | `boolean \| TablePaginationConfig`                                                                                                                                                  |   `true`    |
| page-position               | 分页器在表格容器内部的区域，当前使用 tl/top/tr/bl/bottom/br；不是条数选择器的弹层方位 | `'tl' \| 'top' \| tr' \| 'bl' \| 'bottom' \| 'br'`                                                                                                                            |   `'br'`    |
| indent-size                 | 树形表格的缩进距离                                                                         | `number`                                                                                                                                                                      |    `16`     |
| row-key                     | 表格行 `key` 的取值字段                                                                    | `string`                                                                                                                                                                      |   `'key'`   |
| show-header                 | 是否显示表头                                                                               | `boolean`                                                                                                                                                                     |   `true`    |
| virtual-list-props          | 传递虚拟列表属性，传入此参数以开启虚拟滚动 [VirtualListProps](#virtuallistprops)           | `VirtualListProps`                                                                                                                                                            |     `-`     |
| span-method                 | 单元格合并方法（索引从数据项开始计数）                                                     | `(data: {  record: TableData;  column: TableColumnData \| TableOperationColumn;  rowIndex: number;  columnIndex: number;}) => { rowspan?: number; colspan?: number } \| void` |     `-`     |
| span-all                    | 是否让合并方法的索引包含所有                                                               | `boolean`                                                                                                                                                                     |   `false`   |
| load-more                   | 数据懒加载函数，传入时开启懒加载功能                                                       | `(record: TableData, done: (children?: TableData[]) => void) => void`                                                                                                         |     `-`     |
| filter-icon-align-left      | 筛选图标是否左对齐                                                                         | `boolean`                                                                                                                                                                     |   `false`   |
| hide-expand-button-on-empty | 是否在子树为空时隐藏展开按钮                                                               | `boolean`                                                                                                                                                                     |   `false`   |
| row-class                   | 表格行元素的类名。                                                                         | `string\| any[]\| Record<string, any>\| ((record: TableData, rowIndex: number) => any)`                                                                                       |     `-`     |
| draggable                   | 表格拖拽排序的配置                                                                         | `TableDraggable`                                                                                                                                                              |     `-`     |
| column-resizable            | 是否允许调整列宽（仅 `table-layout: fixed` 下渲染拖拽把手）                                | `boolean`                                                                                                                                                                     |   `false`   |
| summary                     | 显示表尾总结行                                                                             | `boolean\| ((params: {    columns: TableColumnData[];    data: TableData[];  }) => TableData[])`                                                                              |     `-`     |
| summary-text                | 总结行的首列文字                                                                           | `string`                                                                                                                                                                      | `'Summary'` |
| summary-span-method         | 总结行的单元格合并方法                                                                     | `(data: {  record: TableData;  column: TableColumnData \| TableOperationColumn;  rowIndex: number;  columnIndex: number;}) => { rowspan?: number; colspan?: number } \| void` |     `-`     |
| selected-keys               | 已选择的行（受控模式）优先于 `rowSelection`                                                | `(string \| number)[]`                                                                                                                                                        |     `-`     |
| default-selected-keys       | 默认已选择的行（非受控模式）优先于 `rowSelection`                                          | `(string \| number)[]`                                                                                                                                                        |     `-`     |
| expanded-keys               | 显示的展开行、子树（受控模式）优先于 `expandable`                                          | `(string \| number)[]`                                                                                                                                                        |     `-`     |
| default-expanded-keys       | 默认显示的展开行、子树（非受控模式）优先于 `expandable`                                    | `(string \| number)[]`                                                                                                                                                        |     `-`     |
| default-expand-all-rows     | 是否默认展开所有的行                                                                       | `boolean`                                                                                                                                                                     |   `false`   |
| sticky-header               | 表头相对页面/外层滚动容器吸顶；数字为距顶部偏移（px）                                      | `boolean \| number`                                                                                                                                                           |   `false`   |
| sticky-pagination           | 分页相对页面/外层滚动容器吸底；数字为距底部偏移（px）                                      | `boolean \| number`                                                                                                                                                           |   `false`   |
| scrollbar                   | 是否开启虚拟滚动条                                                                         | `boolean \| ScrollbarProps`                                                                                                                                                   |   `true`    |
| show-empty-tree             | 是否展示空子树                                                                             | `boolean`                                                                                                                                                                     |   `false`   |
| extra-column                | 在表格末尾插入扩展列（如设置按钮）；内容由插槽提供                                         | `boolean \| TableExtraColumnConfig`                                                                                                                                           |   `false`   |
| empty-type                   | 空白状态类型                                                                               | <br/>`default`\|`network`\|`unknown`\|`success` <br/> <br/>                                                                                                                   |  `default`  |
| empty-text                   | 空白状态类型文案                                                                           | <br/>`string` <br/> <br/>                                                                                                                                                     |     `-`     |

### `<Table>` Events

| 事件名           | 描述                           | 参数                                                                               |
| ---------------- | ------------------------------ | ---------------------------------------------------------------------------------- |
| expand           | 点击展开行时触发               | rowKey: `string \| number`<br>record: `TableData`                                  |
| expanded-change  | 已展开的数据行发生改变时触发   | rowKeys: `(string \| number)[]`                                                    |
| select           | 点击行选择器时触发             | rowKeys: `string \| number[]`<br>rowKey: `string \| number`<br>record: `TableData` |
| select-all       | 点击全选选择器时触发           | checked: `boolean`                                                                 |
| selection-change | 已选择的数据行发生改变时触发   | rowKeys: `(string \| number)[]`                                                    |
| sorter-change    | 排序规则发生改变时触发         | dataIndex: `string`<br>direction: `string`                                         |
| filter-change    | 过滤选项发生改变时触发         | dataIndex: `string`<br>filteredValues: `string[]`                                  |
| page-change      | 表格分页发生改变时触发         | page: `number`                                                                     |
| page-size-change | 表格每页数据数量发生改变时触发 | pageSize: `number`                                                                 |
| change           | 表格数据发生变化时触发         | data: `TableData[]`<br>extra: `TableChangeExtra`<br>currentData: `TableData[]`     |
| update:columns   | 列配置变更时触发（配合 v-model:columns） | columns: `TableColumnData[]`                                                       |
| cell-mouse-enter | 单元格hover进入时触发          | record: `TableData`<br>column: `TableColumnData`<br>ev: `Event`                    |
| cell-mouse-leave | 单元格hover退出时触发          | record: `TableData`<br>column: `TableColumnData`<br>ev: `Event`                    |
| cell-click       | 点击单元格时触发               | record: `TableData`<br>column: `TableColumnData`<br>ev: `Event`                    |
| row-click        | 点击行数据时触发               | record: `TableData`<br>ev: `Event`                                                 |
| header-click     | 点击表头数据时触发             | column: `TableColumnData`<br>ev: `Event`                                           |
| column-resize    | 调整列宽时触发                 | dataIndex: `string`<br>width: `number`                                             |
| row-dblclick     | 双击行数据时触发               | record: `TableData`<br>ev: `Event`                                                 |
| cell-dblclick    | 双击单元格时触发               | record: `TableData`<br>column: `TableColumnData`<br>ev: `Event`                    |
| row-contextmenu  | 右击行数据时触发               | record: `TableData`<br>ev: `Event`                                                 |
| cell-contextmenu | 右击单元格时触发               | record: `TableData`column: `TableColumnData`<br>ev: `Event`                        |

### `<Table>` Methods

| 方法名       | 描述             | 参数                                                                     | 返回值 |
| ------------ | ---------------- | ------------------------------------------------------------------------ | ------ |
| selectAll    | 设置全选状态     | checked: `boolean`                                                       | -      |
| select       | 设置行选择器状态 | rowKey: `string \| number \| (string \| number)[]`<br>checked: `boolean` | -      |
| expandAll    | 设置全部展开状态 | checked: `boolean`                                                       | -      |
| expand       | 设置展开状态     | rowKey: `string \| number \| (string \| number)[]`<br>checked: `boolean` | -      |
| resetFilters | 重置列的筛选器   | dataIndex: `string \| string[]`                                          | -      |
| clearFilters | 清空列的筛选器   | dataIndex: `string \| string[]`                                          | -      |
| resetSorters | 重置列的排序     | -                                                                        | -      |
| clearSorters | 清空列的排序     | -                                                                        | -      |

### `<Table>` Slots

| 插槽名           |                 描述                  | 参数                                                                   |
| ---------------- | :-----------------------------------: | ---------------------------------------------------------------------- |
| th               |            自定义 th 元素             | column: `TableColumnData`                                              |
| thead            |           自定义 thead 元素           | -                                                                      |
| empty            |               空白展示                | -                                                                      |
| summary-cell     |                总结行                 | column: `TableColumnData`<br>record: `TableData`<br>rowIndex: `number` |
| pagination-right |            分页器右侧内容             | -                                                                      |
| pagination-left  |            分页器左侧内容             | -                                                                      |
| td               |            自定义 td 元素             | column: `TableColumnData`<br>record: `TableData`<br>rowIndex: `number` |
| tr               |            自定义 tr 元素             | record: `TableData`<br>rowIndex: `number`                              |
| tbody            |           自定义 tbody 元素           | -                                                                      |
| drag-handle-icon |             拖拽锚点图标              | -                                                                      |
| footer           |               表格底部                | -                                                                      |
| expand-row       |              展开行内容               | record: `TableData`                                                    |
| expand-icon      |              展开行图标               | expanded: `boolean`<br>record: `TableData`                             |
| columns          | 表格列定义。启用时会屏蔽 columns 属性 | -                                                                      |
| extra-column-header | 末列扩展列表头内容 | - |
| extra-column-cell | 末列扩展列单元格内容 | record / rowIndex 等 |
| header-cell-actions | 表头右侧操作区（叶子列）；内容由外部完全控制 | column / dataIndex |

### `<TableColumn>` Props

| 参数名             | 描述                                | 类型                                                      | 默认值  |
| ------------------ | ----------------------------------- | --------------------------------------------------------- | :-----: |
| data-index         | 列信息的标识，对应TableData中的数据 | `string`                                                  |   `-`   |
| title              | 列标题                              | `string`                                                  |   `-`   |
| width              | 列宽度                              | `number`                                                  |   `-`   |
| min-width          | 最小列宽                            | `number`                                                  |   `80`  |
| align              | 对齐方向                            | `TableColumnData['align']`                                |   `-`   |
| fixed              | 固定位置                            | `TableColumnData['fixed']`                                |   `-`   |
| ellipsis           | 是否显示为省略                      | `boolean`                                                 | `false` |
| sortable           | 排序相关选项                        | `TableSortable`                                           |   `-`   |
| filterable         | 过滤相关选项                        | `TableFilterable`                                         |   `-`   |
| cell-class         | 自定义单元格类名                    | `ClassName`                                               |   `-`   |
| header-cell-class  | 自定义表头单元格类名                | `ClassName`                                               |   `-`   |
| body-cell-class    | 自定义内容单元格类名                | `ClassName \| ((record: TableData) => ClassName)`         |   `-`   |
| summary-cell-class | 自定义总结栏单元格类名              | `ClassName \| ((record: TableData) => ClassName)`         |   `-`   |
| cell-style         | 自定义单元格样式                    | `CSSProperties`                                           |   `-`   |
| header-cell-style  | 自定义表头单元格样式                | `CSSProperties`                                           |   `-`   |
| body-cell-style    | 自定义内容单元格样式                | `CSSProperties \| ((record: TableData) => CSSProperties)` |   `-`   |
| summary-cell-style | 自定义总结栏单元格样式              | `CSSProperties \| ((record: TableData) => CSSProperties)` |   `-`   |
| index              | 用于手动指定选项的 index。          | `number`                                                  |   `-`   |
| tooltip            | 在省略时是否显示文字提示            | `boolean\|object`                                         | `false` |

### `<TableColumn>` Slots

| 插槽名         |         描述         | 参数                                                                                                                                                                         |
| -------------- | :------------------: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filter-icon    |     筛选按钮图标     | -                                                                                                                                                                            |
| filter-content | 自定义筛选弹出框内容 | filterValue: `string[]`<br>setFilterValue: `(filterValue: string[]) => void`<br>handleFilterConfirm: `(event: Event) => void`<br>handleFilterReset: `(event: Event) => void` |
| title          |         标题         | -                                                                                                                                                                            |
| cell           |        单元格        | record: `TableData`<br>column: `TableColumnData`<br>rowIndex: `number`                                                                                                       |

### TableData

| 参数名   | 描述             | 类型                       | 默认值  |
| -------- | ---------------- | -------------------------- | :-----: |
| key      | 数据行的key      | `string`                   |   `-`   |
| expand   | 扩展行内容       | `string \| RenderFunction` |   `-`   |
| children | 子数据           | `TableData[]`              |   `-`   |
| disabled | 是否禁用行选择器 | `boolean`                  | `false` |
| isLeaf   | 是否是叶子节点   | `boolean`                  | `false` |

### TableSortable

| 参数名           | 描述                                     | 类型                                                                                                                                                 | 默认值 |
| ---------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | :----: |
| sortDirections   | 支持的排序方向                           | `('ascend' \| 'descend')[]`                                                                                                                          |  `-`   |
| sorter           | 排序函数。设置为 `true` 可关闭内部排序。 | `((        a: TableData,        b: TableData,        extra: { dataIndex: string; direction: 'ascend' \| 'descend' }      ) => number)    \| boolean` |  `-`   |
| sortOrder        | 排序方向                                 | `'ascend' \| 'descend' \| ''`                                                                                                                        |  `-`   |
| defaultSortOrder | 默认排序方向（非受控模式）               | `'ascend' \| 'descend' \| ''`                                                                                                                        |  `-`   |

### TableFilterData

| 参数名 | 描述               | 类型                       | 默认值 |
| ------ | ------------------ | -------------------------- | :----: |
| text   | 筛选数据选项的内容 | `string \| RenderFunction` |  `-`   |
| value  | 筛选数据选项的值   | `string`                   |  `-`   |

### TableFilterable

| 参数名               | 描述                                      | 类型                                                                                                                                                                                                     | 默认值  |
| -------------------- | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-----: |
| filters              | 筛选数据                                  | `TableFilterData[]`                                                                                                                                                                                      |   `-`   |
| filter               | 筛选函数,用法类似于Array.prototype.filter | `(filteredValue: string[], <br/>record:TableData)=> boolean`                                                                                                                                             |   `-`   |
| multiple             | 是否支持多选                              | `boolean`                                                                                                                                                                                                | `false` |
| filteredValue        | 筛选项                                    | `string[]`                                                                                                                                                                                               |   `-`   |
| defaultFilteredValue | 默认筛选项                                | `string[]`                                                                                                                                                                                               |   `-`   |
| renderContent        | 筛选框的内容                              | `(data: {    filterValue: string[];    setFilterValue: (filterValue: string[]) => void;    handleFilterConfirm: (event: Event) => void;    handleFilterReset: (event: Event) => void;  }) => VNodeChild` |   `-`   |
| icon                 | 筛选按钮的图标                            | `RenderFunction`                                                                                                                                                                                         |   `-`   |
| triggerProps         | 筛选框的弹出框配置                        | `TriggerProps`                                                                                                                                                                                           |   `-`   |
| alignLeft            | 筛选图标是否左对齐                        | `boolean`                                                                                                                                                                                                | `false` |

### TableColumnData

| 参数名           | 描述                                                    | 类型                                                                                                | 默认值  |
| ---------------- | ------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | :-----: |
| dataIndex        | 列信息的标识，对应 `TableData` 中的数据                 | `string`                                                                                            |   `-`   |
| title            | 列标题                                                  | `string \| RenderFunction`                                                                          |   `-`   |
| width            | 列宽基准。有弹性列且 fit=true 时保持固定；全部定宽且不足容器时按比例放大            | `number`                                                                                            |   `-`   |
| minWidth         | 最小列宽。未设置 `width` 时按比例分配剩余空间；默认 80  | `number`                                                                                            |   `80`  |
| align            | 对齐方向                                                | `'left' \| 'center' \| 'right'`                                                                     |   `-`   |
| fixed            | 固定位置                                                | `'left' \| 'right'`                                                                                 |   `-`   |
| ellipsis         | 是否显示省略号                                          | `boolean`                                                                                           | `false` |
| tooltip          | 是否在显示省略号时显示文本提示。可填入 tooltip 组件属性 | `boolean \| Record<string, any>`                                                                    |   `-`   |
| sortable         | 排序相关选项                                            | `TableSortable`                                                                                     |   `-`   |
| filterable       | 过滤相关选项                                            | `TableFilterable`                                                                                   |   `-`   |
| children         | 表头子数据，用于表头分组                                | `TableColumnData[]`                                                                                 |   `-`   |
| cellClass        | 自定义单元格类名                                        | `ClassName`                                                                                         |   `-`   |
| headerCellClass  | 自定义表头单元格类名                                    | `ClassName`                                                                                         |   `-`   |
| bodyCellClass    | 自定义内容单元格类名                                    | `ClassName \| ((record: TableData) => ClassName)`                                                   |   `-`   |
| summaryCellClass | 自定义总结栏单元格类名                                  | `ClassName \| ((record: TableData) => ClassName)`                                                   |   `-`   |
| cellStyle        | 自定义单元格样式                                        | `CSSProperties`                                                                                     |   `-`   |
| headerCellStyle  | 自定义表头单元格样式                                    | `CSSProperties`                                                                                     |   `-`   |
| bodyCellStyle    | 自定义内容单元格样式                                    | `CSSProperties \| ((record: TableData) => CSSProperties)`                                           |   `-`   |
| summaryCellStyle | 自定义总结栏单元格样式                                  | `CSSProperties \| ((record: TableData) => CSSProperties)`                                           |   `-`   |
| render           | 自定义列单元格的渲染                                    | `(data: {    record: TableData;    column: TableColumnData;    rowIndex: number;  }) => VNodeChild` |   `-`   |
| slotName         | 设置当前列的渲染插槽的名字。插槽参数同 #cell            | `string`                                                                                            |   `-`   |
| titleSlotName    | 设置当前列的标题的渲染插槽的名字                        | `string`                                                                                            |   `-`   |

### TableBorder

| 参数名     | 描述                            | 类型      | 默认值  |
| ---------- | ------------------------------- | --------- | :-----: |
| wrapper    | 是否展示外边框                  | `boolean` | `false` |
| cell       | 是否展示单元格边框（表头+主体） | `boolean` | `false` |
| headerCell | 是否展示表头单元格边框          | `boolean` | `false` |
| bodyCell   | 是否展示主体单元格边框          | `boolean` | `false` |

### TableRowSelection

| 参数名                 | 描述                                           | 类型                    | 默认值  |
| ---------------------- | ---------------------------------------------- | ----------------------- | :-----: |
| type                   | 行选择器的类型                                 | `'checkbox' \| 'radio'` |   `-`   |
| selectedRowKeys        | 已选择的行（受控模式）                         | `BaseType[]`            |   `-`   |
| defaultSelectedRowKeys | 默认已选择的行（非受控模式）                   | `BaseType[]`            |   `-`   |
| showCheckedAll         | 是否显示全选选择器                             | `boolean`               | `false` |
| title                  | 列标题                                         | `string`                |   `-`   |
| width                  | 列宽度                                         | `number`                |   `-`   |
| fixed                  | 是否固定                                       | `boolean`               | `false` |
| checkStrictly          | 是否开启严格选择模式                           | `boolean`               | `true`  |
| onlyCurrent            | 是否仅展示当前页的 keys（切换分页时清空 keys） | `boolean`               | `false` |

### TableExpandable

| 参数名                 | 描述                           | 类型                                                   | 默认值  |
| ---------------------- | ------------------------------ | ------------------------------------------------------ | :-----: |
| expandedRowKeys        | 显示的展开行（受控模式）       | `BaseType[]`                                           |   `-`   |
| defaultExpandedRowKeys | 默认显示的展开行（非受控模式） | `BaseType[]`                                           |   `-`   |
| defaultExpandAllRows   | 是否默认展开所有的行           | `boolean`                                              | `false` |
| expandedRowRender      | 自定义展开行内容               | `(record: TableData) => VNodeChild`                    |   `-`   |
| icon                   | 展开图标                       | `(expanded: boolean, record: TableData) => VNodeChild` |   `-`   |
| title                  | 列标题                         | `string`                                               |   `-`   |
| width                  | 列宽度                         | `number`                                               |   `-`   |
| fixed                  | 是否固定                       | `boolean`                                              | `false` |

### TableDraggable

| 参数名 | 描述     | 类型                | 默认值  |
| ------ | -------- | ------------------- | :-----: |
| type   | 拖拽类型 | `'row' \| 'handle'` |   `-`   |
| title  | 列标题   | `string`            |   `-`   |
| width  | 列宽度   | `number`            |   `-`   |
| fixed  | 是否固定 | `boolean`           | `false` |

### TableChangeExtra

| 参数名     | 描述       | 类型                                             | 默认值 |
| ---------- | ---------- | ------------------------------------------------ | :----: |
| type       | 触发类型   | `'pagination' \| 'sorter' \| 'filter' \| 'drag'` |  `-`   |
| page       | 页码       | `number`                                         |  `-`   |
| pageSize   | 每页数据数 | `number`                                         |  `-`   |
| sorter     | 排序信息   | `Sorter`                                         |  `-`   |
| filters    | 筛选信息   | `Filters`                                        |  `-`   |
| dragTarget | 拖拽信息   | `TableData`                                      |  `-`   |

### VirtualListProps

| 参数名             | 描述                                                               | 类型               | 默认值  |
| :----------------- | ------------------------------------------------------------------ | ------------------ | :-----: |
| height             | 可视区域高度                                                       | `number \| string` |   `-`   |
| threshold          | 开启虚拟滚动的元素数量阈值，当数据数量小于阈值时不会开启虚拟滚动。 | `number`           |   `-`   |
| isStaticItemHeight | （已废除）元素高度是否是固定的，请使用 `fixedSize`                 | `boolean`          | `false` |
| fixedSize          | 元素高度是否是固定的。                                             | `boolean`          | `false` |
| estimatedSize      | 元素高度不固定时的预估高度。                                       | `number`           |   `-`   |
| buffer             | 视口边界外提前挂载的元素数量。                                     | `number`           |  `10`   |

### TableExtraColumnConfig

| 参数名 | 描述 | 类型 | 默认值 |
| :----- | ---- | ---- | :----: |
| width | 列宽；未传按表格 size | `number` | xs 28 / sm 32 / md·lg·xl 36 |
| fixed | 固定位置 | `'left' \| 'right'` | `'right'` |
| align | 对齐 | `'left' \| 'center' \| 'right'` | `'center'` |
| dataIndex | 列标识 | `string` | `__cedar_table_extra__` |

### 分页配置类型

`TablePaginationConfig = Omit<PaginationProps, 'total'> & { total?: number }`。表格省略 `pagination.total` 时由有效数据条数推导；远程分页可继续显式传入总数。原 `PaginationProps` 对象仍可直接传给表格，独立 `Pagination` 的 `total` 必填要求不变。根入口与 table 入口均导出 `TablePaginationConfig`。


### 透传配置的现有优先级（F07）

列 filterable.triggerProps 在内部 Trigger 配置之后展开，嵌套 open 等字段目前可以覆盖筛选浮层状态。F07 兼容阶段保留该顺序和类型，不自动禁止这些旧能力；如未来收紧，需单独评估筛选状态与浮层状态的迁移。


## 可选的业务行类型配置（F08-A）

```ts
import { defineTableConfig } from '@cedar-design/ui'
import type { TypedTableConfig, TypedTableColumn, TableDataPath } from '@cedar-design/ui/table'

interface User { id: string; name: string; age: number }
const users: User[] = [{ id: 'a', name: 'Alice', age: 20 }]
const config = defineTableConfig<User>({
  rowKey: 'id', data: users,
  columns: [{ dataIndex: 'age', render: ({ record }) => record.age.toFixed(0) }],
})
```

将 config 用于 `<c-table v-bind="config" />` 或 TSX `<Table {...config} />`。无需业务侧 as any；原 TableData、TableColumnData、TableProps 及组件 Props 保持。新入口检查发生在入参阶段，返回原 TableProps 供旧组件调用，运行时返回同一对象，不复制数据/列、不调整排序筛选、不包装组件。

| 关联范围 | 新类型的规则 |
| --- | --- |
| data / columns | 相同 Row，树形 children 递归使用同一业务结构 |
| dataIndex | 校验字段与嵌套路径，例如 profile.city、tags[0].label、tags.0.label；递归最多五层业务结构；动态字符串和更深路径继续使用旧入口 |
| render / sortable / filterable | record、比较器与筛选器参数为 Row，分组 children 列同样关联 |
| 行回调 | 单元格样式/类、rowClass、expandable、loadMore、spanMethod 与自定义合计关联 Row |
| rowKey | 必须显式传入 Row 中值为 string/number 的字段；这里是字段名，不是嵌套路径 |
| summary | 可省略、false，或返回完整 Row 的自定义函数；自动 summary=true 不保证是业务行，新入口不接受，原 Table 配置仍支持 |

业务接口通常不需要显式 extends TableData；其 any 索引会使 keyof 变宽，削弱字段拼写检查。使用普通业务 interface，通过泛型约束检查表格保留元数据的兼容性。后端数据内容仍需业务校验，类型不会检查 ID 是否唯一。

类型入口只覆盖这份配置内的关联；原组件的模板插槽、组件事件和自定义 components 扩展不会自动变成 Row 泛型。返回的 TableProps 仍为旧宽类型，不应期待后续任意修改返回对象也继续校验 Row。响应式来源会替换数组时，用 `computed(() => defineTableConfig<Row>(...))` 保持更新；不要把调用时的 rows.value 当成持续跟随 ref 的订阅。

自动合计行可能包含文本、总数和缺失字段，不能让 render(record: User) 假定其完整。需要自动合计或异构树行时继续使用原宽配置；采用自定义合计的新入口需提供完整业务行。两种入口的原 Table 行为都不改变。

跨端范围：Maple Table 是原生表格展示容器，没有 data/columns API，本次不增加关联配置入口；两端 Select/Cascader 类型关联留待分别确认。


## 阅读方向与滚动

Table 继承最近的原生 `dir`。普通列按阅读方向排列；显式 `fixed: left/right` 保持物理侧，内部按冻结区稳定分区，不修改传入的列、数据或业务索引。跨冻结区的多级分组表头会分段显示，保持每段与正文列对齐。省略 align 时按阅读起点对齐，显式 left/right 保持物理对齐。

表头、正文、汇总和吸底滚动条以非负的“距阅读起点距离”同步，适配原生 RTL 的负 scrollLeft。切换方向保留该距离并按新视口范围钳制；虚拟行的纵向定位不改变横向距离。Teleport 分页/吸底区域继承来源表格方向。

列宽手柄支持方向感知的鼠标/触摸拖动与左右键调整，键盘步长 10px、Shift 为 50px，Home 到达 40px 下限；保持原有 fixed 布局才可调宽的约束。吸底滚动条支持左右键、Home/End，测量按帧合并并在停用/卸载时清理。切换阅读方向不会更改选择、排序、筛选、分页状态或触发列宽事件。

懒加载子节点缓存归属于源节点对象及其行 key，不因复用同一 key 而继承旧节点缓存。替换节点、行 key 或加载函数会使旧任务/缓存失效；停用或卸载会使待完成的单元格回调失效。done() 表示未取得子节点，结束等待并允许重试；done([]) 接受空结果，同一次任务只接受首次完成。同步加载异常释放等待后仍进入 Vue 错误通道。保持 load-more 的 done 回调协议，不将通知事件返回的 Promise 当作任务入口。

回调式加载函数若返回 Promise，其拒绝会释放等待并进入 Vue 错误通道；完成值会被忽略，不能代替 done。这是显式加载属性的异常处理，不会收集 expand 等通知事件的 Promise。

---

Document: llms/zh-CN/components/tabs.md

<!-- Source: src/tabs/README.md; locale: zh-CN; page: /components/tabs/ -->

# Tabs 标签页

导航与内容使用同一套 API，PC 和移动端通过主题变量保留视觉密度差异。

## 基础示例

### 最简单用法

最简单的写法只需要在 `Tabs` 中声明带 `title` 的 `TabPane`，导航与内容会自动生成。

Example source: src/tabs/__demos__/basic.vue

```vue
<template>
  <c-tabs default-value="overview">
    <c-tab-pane name="overview" title="概览">概览内容</c-tab-pane>
    <c-tab-pane name="details" title="详情">详情内容</c-tab-pane>
    <c-tab-pane name="settings" title="设置">设置内容</c-tab-pane>
  </c-tabs>
</template>
```

## 外观与状态

### 外观组合

适用于同级内容之间的切换。调整变体、尺寸，用相同数据观察变化。内容保持一致，便于比较不同设置的实际效果。

Example source: src/tabs/__demos__/appearance-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";

const __demoAppearance = __demoReactive({ variant: "line", size: "md" });

import { computed as demoComputed, ref as demoRef } from 'vue'
const demoCompareFields = [{"name":"variant","values":["line","card","outline","plain","capsule","enclosed"]},{"name":"size","values":["xs","sm","md","lg","xl"]}]
const demoCompareAxis = demoRef("variant")
const demoComparedOptions = demoComputed(() => demoCompareFields.find(field => field.name === demoCompareAxis.value)?.values ?? [])
</script>
<template>
  <c-space direction="column" :size="16">
    <c-form layout="vertical">
      <c-form-item layout="vertical" size="sm" label="variant">
        <c-select
          v-model="__demoAppearance['variant']"
          :clearable="false"
          :options="[
            { label: 'line', value: 'line' },
            { label: 'card', value: 'card' },
            { label: 'outline', value: 'outline' },
            { label: 'plain', value: 'plain' },
            { label: 'capsule', value: 'capsule' },
            { label: 'enclosed', value: 'enclosed' },
          ]"
          aria-label="variant"
        />
      </c-form-item>
      <c-form-item layout="vertical" size="sm" label="size">
        <c-radio-group
          v-model="__demoAppearance['size']"
          aria-label="size"
          :options="[
            { label: 'xs', value: 'xs' },
            { label: 'sm', value: 'sm' },
            { label: 'md', value: 'md' },
            { label: 'lg', value: 'lg' },
            { label: 'xl', value: 'xl' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
    </c-form>
    <p class="demo-config-comparison-hint"><span lang="zh-CN">选择一个对比维度；其他配置和内容保持一致。输入类示例共享同一个值，便于比较外观。</span><span lang="en-US">Compare one dimension while keeping the other settings and content identical. Input specimens share the same value.</span></p>
<c-radio-group v-model="demoCompareAxis" aria-label="Compare configuration" :options="demoCompareFields.map(field => ({ label: field.name, value: field.name }))" />
<div class="demo-config-comparison">
<section v-for="sample in demoComparedOptions" :key="String(sample)">
<p><code>{{ demoCompareAxis }}={{ sample }}</code></p>
<c-tabs default-value="overview" v-bind="{ ...__demoAppearance, [demoCompareAxis]: sample }">
      <c-tab-pane name="overview" title="概览">概览内容</c-tab-pane>
      <c-tab-pane name="details" title="详情">详情内容</c-tab-pane>
      <c-tab-pane name="settings" title="设置">设置内容</c-tab-pane>
    </c-tabs>
</section>
</div>
  </c-space>
</template>

<style scoped>
.demo-config-comparison { display: grid; grid-template-columns: repeat(auto-fit, minmax(min(100%, 220px), 1fr)); gap: 20px; min-width: 0; max-width: 100%; }
.demo-config-comparison > section { min-width: 0; }
.demo-config-comparison p { margin: 0 0 8px; }
html:not([lang='en-US']) .demo-config-comparison-hint > [lang='en-US'],
html[lang='en-US'] .demo-config-comparison-hint > [lang='zh-CN'] { display: none; }
</style>
```

## 外观与方向

### 外观变体与尺寸

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `orientation` | 标签导航的横纵轴向，默认 horizontal；影响导航布局和方向键操作 | 外观变体与尺寸、方向与指示器位置 |
| `item-style` | `StyleValue` | 自定义内容间距、自定义内部样式 |
| `default-value` | `string / number` | 自定义内容间距、自定义内部样式 |
| `variant` | `line / card / outline / plain / capsule / enclosed` | 外观变体与尺寸 |
| `size` | `xs / sm / md / lg / xl` | 外观变体与尺寸 |
| `editable` | `boolean` | 外观变体与尺寸 |
<!-- demo-config-notes:end -->

通过 `variant`、`size` 和 `orientation` 切换标签页的外观、尺寸与排列方向。

Example source: src/tabs/__demos__/type.vue

```vue
<template>
  <c-space direction="column" size="lg">
    <c-radio-group v-model="isVertical" type="button">
      <c-radio value="horizontal">Horizontal</c-radio>
      <c-radio value="vertical">Vertical</c-radio>
    </c-radio-group>
    <c-radio-group v-model="variant" type="button">
      <c-radio value="line">Line</c-radio>
      <c-radio value="card">Card</c-radio>
      <c-radio value="outline">Outline</c-radio>
      <c-radio value="plain">Plain</c-radio>
      <c-radio value="capsule">Capsule</c-radio>
      <c-radio value="enclosed">Enclosed</c-radio>
    </c-radio-group>
    <c-radio-group v-model="size" type="button">
      <c-radio value="xs">Xs</c-radio>
      <c-radio value="sm">Sm</c-radio>
      <c-radio value="md">Md</c-radio>
      <c-radio value="lg">Lg</c-radio>
      <c-radio value="xl">Xl</c-radio>
    </c-radio-group>
  </c-space>
  <c-tabs
    :variant="variant"
    :size="size"
    :orientation="isVertical"
    :editable="true"
    @add="handleAdd"
    @delete="handleDelete"
    show-add-button
    auto-switch
    :style="isVertical !== 'vertical' ? { height: '240px' } : undefined"
  >
    <c-tabs-navs>
      <c-tab-nav v-for="(item, index) of data" :key="item.key" :name="item.key" :title="item.title" :closable="index !== 2" />
      <template #prefix><c-button size="xs">Action</c-button></template>
      <template #suffix>suffix</template>
    </c-tabs-navs>
    <c-tabs-items>
      <c-tab-item v-for="(item, index) of data" :key="item.key" :name="item.key">{{ item?.content }}</c-tab-item>
    </c-tabs-items>
  </c-tabs>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
const variant = ref('line')
const size = ref('md')
const isVertical = ref('horizontal')
const data = ref([
  {
    key: '1',
    title: 'Tab 1',
    content: 'Content of Tab Panel 1',
  },
  {
    key: '2',
    title: 'Tab 2',
    content: 'Content of Tab Panel 2',
  },
  {
    key: '3',
    title: 'Tab 3',
    content: 'Content of Tab Panel 3',
  },
  {
    key: '4',
    title: 'Tab 4',
    content: 'Content of Tab Panel 4',
  },
])
let count = 5
const handleAdd = () => {
  const number = count++
  data.value = data.value.concat({
    key: `${number}`,
    title: `New Tab ${number}`,
    content: `Content of New Tab Panel ${number}`,
  })
}
const handleDelete = (key) => {
  data.value = data.value.filter((item) => item.key !== key)
}
</script>
```

### 方向与指示器位置

通过 `orientation` 设置横向或纵向布局，使用 `indicator-position` 调整指示器所在方向；还可以交换
`TabsNavs` 与 `TabsItems` 的声明顺序，将导航放在内容的另一侧。

Example source: src/tabs/__demos__/position.vue

```vue
<template>
  <c-space direction="column" size="lg">
    <c-radio-group v-model="indicatorPosition" type="button">
      <c-radio value="normal">Normal (bottom/right)</c-radio>
      <c-radio value="reverse">Reverse (top/left)</c-radio>
    </c-radio-group>
    <c-radio-group v-model="vertical" type="button">
      <c-radio value="horizontal">Horizontal</c-radio>
      <c-radio value="vertical">Vertical</c-radio>
    </c-radio-group>
    <c-radio-group v-model="componentOrder" type="button">
      <c-radio value="nav-first">TabsNavs → TabsItems</c-radio>
      <c-radio value="items-first">TabsItems → TabsNavs</c-radio>
    </c-radio-group>
    <c-tabs :indicator-position="indicatorPosition" :orientation="vertical">
      <template v-if="componentOrder === 'items-first'">
        <c-tabs-items>
          <c-tab-item name="1">Content of Tab Panel 1</c-tab-item>
          <c-tab-item name="2">Content of Tab Panel 2</c-tab-item>
          <c-tab-item name="3">Content of Tab Panel 3</c-tab-item>
        </c-tabs-items>
        <c-tabs-navs>
          <c-tab-nav name="1" title="Tab 1" />
          <c-tab-nav name="2" title="Tab 2" />
          <c-tab-nav name="3" title="Tab 3" />
        </c-tabs-navs>
      </template>
      <template v-else>
        <c-tabs-navs>
          <c-tab-nav name="1" title="Tab 1" />
          <c-tab-nav name="2" title="Tab 2" />
          <c-tab-nav name="3" title="Tab 3" />
        </c-tabs-navs>
        <c-tabs-items>
          <c-tab-item name="1">Content of Tab Panel 1</c-tab-item>
          <c-tab-item name="2">Content of Tab Panel 2</c-tab-item>
          <c-tab-item name="3">Content of Tab Panel 3</c-tab-item>
        </c-tabs-items>
      </template>
    </c-tabs>
  </c-space>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
const indicatorPosition = ref('normal')
const vertical = ref('horizontal')
const componentOrder = ref('nav-first')
</script>
```

### 图标标签

通过 `icon` 插槽为标签添加图标，配合 `item-vertical` 可以让图标与文字纵向排列。

Example source: src/tabs/__demos__/icon-tabs.vue

```vue
<template>
  <c-space direction="column" size="lg">
    <c-tabs>
      <c-tabs-navs>
        <c-tab-nav name="1">
          <template #icon> <c-icon-calendar /> </template>
          <template #title>Tab 1</template>
        </c-tab-nav>
        <c-tab-nav name="2">
          <template #icon> <c-icon-clock-circle /> </template>
          <template #title>Tab 2</template>
        </c-tab-nav>
        <c-tab-nav name="3">
          <template #icon> <c-icon-user /> </template>
          <template #title>Tab 3</template>
        </c-tab-nav>
      </c-tabs-navs>
      <c-tabs-items>
        <c-tab-item name="1"> Content of Tab Panel 1</c-tab-item>
        <c-tab-item name="2"> Content of Tab Panel 2</c-tab-item>
        <c-tab-item name="3"> Content of Tab Panel 3</c-tab-item>
      </c-tabs-items>
    </c-tabs>

    <c-tabs>
      <c-tabs-navs>
        <c-tab-nav name="1" item-vertical>
          <template #icon> <c-icon-calendar /> </template>
          <template #title>日历</template>
        </c-tab-nav>
        <c-tab-nav name="2" item-vertical>
          <template #icon> <c-icon-clock-circle /> </template>
          <template #title>时钟</template>
        </c-tab-nav>
        <c-tab-nav name="3" item-vertical>
          <template #icon> <c-icon-user /> </template>
          <template #title>用户</template>
        </c-tab-nav>
      </c-tabs-navs>
      <c-tabs-items>
        <c-tab-item name="1"> Content of Tab Panel 1</c-tab-item>
        <c-tab-item name="2"> Content of Tab Panel 2</c-tab-item>
        <c-tab-item name="3"> Content of Tab Panel 3</c-tab-item>
      </c-tabs-items>
    </c-tabs>
  </c-space>
</template>

<script lang="ts" setup>
</script>
```

### 自定义内容间距

通过 `item-style` 调整面板内容间距，也可以直接为 `TabsNavs` 设置导航区域样式。

Example source: src/tabs/__demos__/no-padding.vue

```vue
<template>
  <c-tabs :item-style="{ padding: 0 }" default-value="2">
    <c-tabs-navs :style="{ paddingInline: 0 }">
      <c-tab-nav name="1" title="Tab 1" />
      <c-tab-nav name="2" title="Tab 2" />
      <c-tab-nav name="3">
        <template #title>Tab 3</template>
      </c-tab-nav>
    </c-tabs-navs>
    <c-tabs-items>
      <c-tab-item name="1">
        <div class="p-24">通过 item-style 设置内容间距，并通过 TabsNavs 的 style 去掉导航两端内边距</div>
      </c-tab-item>
      <c-tab-item name="2"> Content of Tab Panel 2</c-tab-item>
      <c-tab-item name="3">Content of Tab Panel 3</c-tab-item>
    </c-tabs-items>
  </c-tabs>
</template>

<script lang="ts" setup>
</script>
```

### 自定义内部样式

Example source: src/tabs/__demos__/custom-style.vue

```vue
<template>
  <c-tabs
    default-value="overview"
    item-class="custom-tab-content"
    :item-style="{ padding: '16px' }"
    item-wrapper-class="custom-tab-panel"
    :item-wrapper-style="{ border: '1px solid currentColor', borderRadius: '8px' }"
    tab-class="custom-tab-label"
    :tab-style="{ borderRadius: '8px' }"
  >
    <c-tabs-navs :style="{ paddingInline: 0 }">
      <c-tab-nav name="overview" title="概览" />
      <c-tab-nav name="details" title="详情" />
    </c-tabs-navs>
    <c-tabs-items>
      <c-tab-item name="overview">统一设置导航、内容和内容外层样式。</c-tab-item>
      <c-tab-item name="details">自定义类名保留内置选中状态，样式支持响应式更新。</c-tab-item>
    </c-tabs-items>
  </c-tabs>
</template>
```

六个样式属性统一配置在 Tabs 上，对所有对应项生效。自定义类名与内置类名合并；内联样式可覆盖默认间距。`item-wrapper-*` 对应 role="tabpanel" 外层，`item-*` 对应实际内容内层，`tab-*` 对应导航标签外层。

内容间距使用 `item-style`，导航整体间距可通过 TabsNavs 的 `style` 或 CSS token 调整。

## 导航与内容组合

### 仅导航

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `default-value` | `string / number` | 仅导航 |
| `swipeable` | `boolean` | 完整组合 |
| `lazy-load` | `boolean` | 完整组合 |
<!-- demo-config-notes:end -->

只需要标签导航时，无需编写内容组件；直接在 `TabsNavs` 中声明 `TabNav` 即可。

Example source: src/tabs/__demos__/nav-content.vue

```vue
<template>
  <c-tabs default-value="overview">
    <c-tabs-navs aria-label="内容分类">
      <c-tab-nav name="overview" title="概览" />
      <c-tab-nav name="details" title="详情" />
      <c-tab-nav name="settings" title="设置" />
    </c-tabs-navs>
  </c-tabs>
</template>
```

### 完整组合

需要分别控制导航和内容时，可以组合使用 `TabsNavs`、`TabNav`、`TabsItems` 和 `TabItem`。

Example source: src/tabs/__demos__/same-source.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const active = ref('overview')
const items = [{ key: 'overview', title: '概览' }, { key: 'details', title: '详情' }, { key: 'disabled', title: '不可用', disabled: true }]
</script>
<template>
  <c-tabs v-model="active" swipeable lazy-load>
    <c-tabs-navs aria-label="内容分类">
      <c-tab-nav v-for="item in items" :key="item.key" :name="item.key" :title="item.title" :disabled="item.disabled" />
    </c-tabs-navs>
    <c-tabs-items>
      <c-tab-item v-for="item in items" :key="item.key" :name="item.key">{{ item.title }}内容</c-tab-item>
    </c-tabs-items>
  </c-tabs>
</template>
```

### 导航附加内容

使用 `TabsNavs` 的 `prefix`、`suffix` 和 `add-icon` 插槽扩展导航区域。

Example source: src/tabs/__demos__/suffix.vue

```vue
<template>
  <c-tabs>
    <c-tabs-navs>
      <template #suffix>
        <c-button>Action</c-button>
      </template>
      <c-tab-nav name="1" title="Tab 1" />
      <c-tab-nav name="2" title="Tab 2" />
      <c-tab-nav name="3" title="Tab 3" />
    </c-tabs-navs>
    <c-tabs-items>
      <c-tab-item name="1"> Content of Tab Panel 1 </c-tab-item>
      <c-tab-item name="2"> Content of Tab Panel 2 </c-tab-item>
      <c-tab-item name="3"> Content of Tab Panel 3 </c-tab-item>
    </c-tabs-items>
  </c-tabs>
</template>

<script lang="ts" setup>
</script>
```

## 交互与动态标签

### 切换触发方式

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `default-value` | `string / number` | 切换触发方式、按需挂载内容 |
| `trigger` | `click / hover` | 切换触发方式 |
| `lazy-load` | `boolean` | 按需挂载内容 |
| `variant` | `line / card / outline / plain / capsule / enclosed` | 动态增删标签 |
| `editable` | `boolean` | 动态增删标签 |
| `show-add-button` | `boolean` | 动态增删标签 |
<!-- demo-config-notes:end -->

`trigger` 支持点击或悬浮切换；触摸设备始终使用点击操作。

Example source: src/tabs/__demos__/trigger.vue

```vue
<template>
  <c-radio-group v-model="trigger">
    <c-radio value="click">click</c-radio>
    <c-radio value="hover">hover</c-radio>
  </c-radio-group>
  <c-tabs default-value="1" :trigger="trigger">
    <c-tabs-navs>
      <c-tab-nav name="1" title="Tab 1" />
      <c-tab-nav name="2" title="Tab 2" />
      <c-tab-nav name="3">
        <template #title>Tab 3</template>
      </c-tab-nav>
    </c-tabs-navs>
    <c-tabs-items>
      <c-tab-item name="1">Content of Tab Panel 1</c-tab-item>
      <c-tab-item name="2">Content of Tab Panel 2</c-tab-item>
      <c-tab-item name="3">Content of Tab Panel 3</c-tab-item>
    </c-tabs-items>
  </c-tabs>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
const trigger = ref('click')
</script>
```

### 按需挂载内容

开启 `lazy-load` 后，面板会在第一次激活时挂载，适合初始化成本较高的内容。

Example source: src/tabs/__demos__/lazy-load.vue

```vue
<template>
  <c-tabs default-value="2" lazy-load>
    <c-tabs-navs>
      <c-tab-nav name="1" title="Tab 1" />
      <c-tab-nav name="2" title="Tab 2" />
      <c-tab-nav name="3" title="Tab 3" />
    </c-tabs-navs>
    <c-tabs-items>
      <c-tab-item name="1"> Content of Tab Panel 1 </c-tab-item>
      <c-tab-item name="2"> Content of Tab Panel 2 </c-tab-item>
      <c-tab-item name="3"> Content of Tab Panel 3 </c-tab-item>
    </c-tabs-items>
  </c-tabs>
</template>

<script lang="ts" setup>
</script>
```

### 动态增删标签

编辑模式支持增加和关闭标签，标签数据仍由使用者维护。

Example source: src/tabs/__demos__/editable.vue

```vue
<template>
  <c-tabs variant="card" :editable="true" @add="handleAdd" @delete="handleDelete" show-add-button auto-switch>
    <c-tabs-navs>
      <template #suffix>
        <c-button>Action</c-button>
      </template>
      <c-tab-nav v-for="(item, index) of data" :key="item.key" :name="item.key" :title="item.title" :closable="index !== 2" />
    </c-tabs-navs>
    <c-tabs-items>
      <c-tab-item v-for="(item, index) of data" :key="item.key" :name="item.key">{{ item?.content }}</c-tab-item>
    </c-tabs-items>
  </c-tabs>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
let count = 5

const data = ref([
  {
    key: '1',
    title: 'Tab 1',
    content: 'Content of Tab Panel 1',
  },
  {
    key: '2',
    title: 'Tab 2',
    content: 'Content of Tab Panel 2',
  },
  {
    key: '3',
    title: 'Tab 3',
    content: 'Content of Tab Panel 3',
  },
  {
    key: '4',
    title: 'Tab 4',
    content: 'Content of Tab Panel 4',
  },
])

const handleAdd = () => {
  const number = count++
  data.value = data.value.concat({
    key: `${number}`,
    title: `New Tab ${number}`,
    content: `Content of New Tab Panel ${number}`,
  })
}
const handleDelete = (key: string | number) => {
  data.value = data.value.filter((item) => item.key !== key)
}
</script>
```

## API

TabPane、TabNav、TabItem 都需要唯一的 `name`；选中值及导航与面板对应关系均使用 name。Vue 的 key 只负责节点复用，循环渲染时单独提供 `:key`。

主值使用普通 `v-model`：`modelValue` 表示选中标签的 name。`defaultValue` 仅在创建时初始化非受控状态，之后修改不会重置当前值；初始化不触发 `update:modelValue`。提供 `modelValue` 时由父级控制，以受控值为准。

### Tabs Props

| 属性 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| model-value | `string / number` | `undefined` | 当前选中 name；提供时受控 |
| default-value | `string / number` | `undefined` | 非受控初值，省略选首个可用项 |
| variant | `line / card / outline / plain / capsule / enclosed` | `line` | 视觉变体 |
| size | `xs / sm / md / lg / xl` | `全局值或 md` | 尺寸 |
| orientation | 标签导航的横纵轴向，默认 horizontal；影响导航布局和方向键操作 | `horizontal` | 导航方向 |
| indicator-position | 指示器位于导航靠内容的一侧 normal 或相反侧 reverse，默认 normal；不使用四边值 | `normal` | 指示器在内容侧或相反侧 |
| editable | `boolean` | `false` | 允许关闭标签 |
| show-add-button | `boolean` | `false` | 编辑模式显示新增按钮 |
| auto-switch | `boolean` | `false` | 新增后切换最后一个可用标签 |
| lazy-load | `boolean` | `false` | 首次激活挂载 |
| destroy-on-hide | `boolean` | `false` | 隐藏即卸载内容 |
| justify | `boolean` | `false` | 水平方向撑满容器高度 |
| animation | `boolean` | `false` | 内容淡入动画 |
| item-class | `string / object / array` | `undefined` | 每页内容内层类名，合并内置类名 |
| item-style | `StyleValue` | `undefined` | 每页内容内层样式，支持字符串、对象和数组 |
| item-wrapper-class | `string / object / array` | `undefined` | 每页内容外层容器类名，合并内置类名 |
| item-wrapper-style | `StyleValue` | `undefined` | 每页内容外层容器样式，支持字符串、对象和数组 |
| tab-class | `string / object / array` | `undefined` | 导航标签外层（含标题与关闭按钮）类名，合并内置类名 |
| tab-style | `StyleValue` | `undefined` | 导航标签外层（含标题与关闭按钮）样式，支持字符串、对象和数组 |
| hide-content | `boolean` | `false` | 隐藏内容区域 |
| trigger | `click / hover` | `click` | 鼠标触发方式，触摸始终点击 |
| scroll-position | 选中标签在导航滚动视口中的目标位置或数值偏移，默认 auto；不是弹层方位 | `auto` | 选中标签滚动位置，数字为起点偏移 |
| scroll-buttons | `boolean / auto` | `auto` | 溢出时显示箭头，auto 在触摸设备隐藏 |
| activation-mode | `automatic / manual` | `automatic` | 方向键是否立即选中 |
| swipeable | `boolean` | `false` | 内容横向触摸切换；不循环 |

### Tabs Events

| 事件 | 参数 | 说明 |
| --- | --- | --- |
| update:model-value | name: string / number | 请求更新选中值 |
| change | name: string / number | 选择不同可用项时通知；受控模式仍由父级更新 modelValue |
| tab-click | name, event: Event | 点击可用项，重复点击仍触发；hover/方向键/滑动不触发 |
| add | event: Event | 请求增加标签；由使用者修改数据 |
| delete | name, event: Event | 请求删除标签；由使用者修改数据 |

### TabPane Props

| 属性 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| name **(必填)** | string / number | — | 业务唯一标识，与 modelValue 对应 |
| title | string | undefined | 导航标题 |
| disabled | boolean | false | 禁止选择和关闭 |
| closable | boolean | true | editable 模式显示关闭按钮 |
| item-vertical | boolean | false | 图标文字垂直布局 |
| lazy-load | boolean | undefined | 继承 Tabs，显式 false 可覆盖 |
| destroy-on-hide | boolean | undefined | 继承 Tabs，显式 false 可覆盖 |

### TabNav Props

| 属性 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| name **(必填)** | string / number | — | 业务唯一标识，与 modelValue 对应 |
| title | string | undefined | 标题 |
| disabled | boolean | false | 禁止选择和关闭 |
| closable | boolean | true | editable 模式显示关闭按钮 |
| item-vertical | boolean | false | 图标文字垂直布局 |

TabNav 与 TabItem 使用相同的 `name` 建立对应关系；`name` 在同组内唯一，数字 `1` 与字符串 `'1'` 不同。Vue 的 `key` 只负责节点复用，循环渲染时仍应提供 `:key`，它不参与选中值计算。

### TabItem Props

| 属性 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| name **(必填)** | string / number | — | 业务唯一标识，与 modelValue 对应 |
| lazy-load | boolean | undefined | 继承 Tabs，显式 false 可覆盖 |
| destroy-on-hide | boolean | undefined | 继承 Tabs，显式 false 可覆盖 |

未激活的 panel 始终带 hidden，内部状态是否保留由上述属性决定。destroy-on-hide 优先于 lazy-load；active 内容始终挂载。TabsNavs 和 TabsItems 没有业务 Props。

### Slots

| 组件 | 插槽 | 说明 |
| --- | --- | --- |
| Tabs | default | TabPane 列表；或高级组合所需的 TabsNavs 与 TabsItems |
| TabPane | default / title | 面板内容 / 自定义导航标题 |
| TabsNavs | default | TabNav 列表 |
| TabsNavs | prefix / suffix / add-icon | 导航前后附加区、新增图标 |
| TabNav | title / default / icon | title 插槽或默认插槽为自定义标题；icon 为图标 |
| TabsItems | default | TabItem 列表 |
| TabItem | default | 面板内容 |

### Expose

`TabsNavs.resize(): void` 重新测量溢出并将选中标签滚入可见区域。尺寸变化有 ResizeObserver 自动监听。

### 键盘与方向

方向键跳过禁用项并循环；Home/End 到首尾；可编辑标签按 Delete 请求关闭。horizontal 使用左右键，vertical 使用上下键。manual 模式只移动焦点，Enter/Space 通过原生 button 激活。使用 `dir="rtl"` 支持从右向左布局。TabsNavs 可传 `aria-label` 为导航命名。

### 类型

导出 TabsName、TabsVariant、TabsTrigger、TabsIndicatorPosition、TabsScrollPosition、TabsActivationMode，以及六组件对应的 Props / Instance / 运行时 props / `_XxxComponent`。同一 props 定义用于两端。

## 样式变量

相同 token 后缀在两端意义一致，只有默认值不同。完整对比见 Cedar Tabs comparison.md。

| 变量 | 默认值 |
| --- | --- |
| `--c-tabs-background` | `var(--c-sys-color-surface-default)` |
| `--c-tabs-title-text-color` | `var(--c-sys-color-content-secondary)` |
| `--c-tabs-title-text-color-active` | `var(--c-sys-color-content-brand)` |
| `--c-tabs-title-text-color-disabled` | `var(--c-sys-color-content-disabled)` |
| `--c-tabs-muted-background` | `var(--c-sys-color-surface-muted)` |
| `--c-tabs-border-color` | `var(--c-sys-color-border-default)` |
| `--c-tabs-hover-background` | `var(--c-sys-color-state-hover)` |
| `--c-tabs-nav-gap` | `var(--c-sys-space-2)` |
| `--c-tabs-tab-gap` | `var(--c-sys-space-2)` |
| `--c-tabs-header-padding` | `var(--c-sys-space-5)` |
| `--c-tabs-control-height` | `var(--c-sys-control-height-xs)` |
| `--c-tabs-touch-target` | `var(--c-sys-control-touch-target)` |
| `--c-tabs-border-width` | `1px` |
| `--c-tabs-focus-width` | `2px` |
| `--c-tabs-focus-offset` | `-3px` |
| `--c-tabs-radius` | `var(--c-sys-radius-md)` |
| `--c-tabs-icon-gap` | `var(--c-sys-space-3)` |
| `--c-tabs-content-padding` | `var(--c-sys-space-6)` |
| `--c-tabs-indicator-size` | `2px` |
| `--c-tabs-indicator-radius` | `1px` |
| `--c-tabs-animation-duration` | `var(--c-sys-motion-duration-standard)` |
| `--c-tabs-active-font-weight` | `var(--c-sys-font-weight-semibold)` |
| `--c-tabs-group-padding` | `var(--c-sys-space-2)` |
| `--c-tabs-capsule-radius` | `var(--c-sys-radius-pill)` |
| `--c-tabs-active-shadow` | `0 1px 3px rgba(0, 0, 0, 0.12)` |
| `--c-tabs-size-xs-tab-height` | `var(--c-sys-control-height-xs)` |
| `--c-tabs-size-xs-tab-padding` | `var(--c-sys-space-2) var(--c-sys-space-4)` |
| `--c-tabs-size-xs-tab-font-size` | `var(--c-sys-font-size-xs)` |
| `--c-tabs-size-sm-tab-height` | `var(--c-sys-control-height-sm)` |
| `--c-tabs-size-sm-tab-padding` | `var(--c-sys-space-3) var(--c-sys-space-5)` |
| `--c-tabs-size-sm-tab-font-size` | `var(--c-sys-font-size-sm)` |
| `--c-tabs-size-md-tab-height` | `var(--c-sys-control-height-md)` |
| `--c-tabs-size-md-tab-padding` | `var(--c-sys-space-4) var(--c-sys-space-6)` |
| `--c-tabs-size-md-tab-font-size` | `var(--c-sys-font-size-md)` |
| `--c-tabs-size-lg-tab-height` | `var(--c-sys-control-height-lg)` |
| `--c-tabs-size-lg-tab-padding` | `10px var(--c-sys-space-7)` |
| `--c-tabs-size-lg-tab-font-size` | `var(--c-sys-font-size-lg)` |
| `--c-tabs-size-xl-tab-height` | `var(--c-sys-control-height-xl)` |
| `--c-tabs-size-xl-tab-padding` | `var(--c-sys-space-5) var(--c-sys-space-8)` |
| `--c-tabs-size-xl-tab-font-size` | `var(--c-sys-font-size-xl)` |

[全面对比与设计依据](./comparison.md)

## 独立同源与公开类型

两端独立维护 Tabs、TabPane、TabsNavs、TabNav、TabsItems、TabItem 六件套，不跨库引用运行时，也不使用通用平台配置。size 的 xs/sm/md/lg/xl 五档均已实现。Cedar 继承 ConfigProvider 的 size/rtl；Maple 默认 md，支持 setPropsDefaults、显式 size 与 DOM dir。面板通过原生 hidden 显隐，InfiniteScroll 直接观察可见性，不再依赖旧面板注册。

公开类型包括 TabsEmits、TabsSlots、TabPaneSlots、TabsNavsSlots、TabNavSlots、TabsItemsSlots、TabItemSlots、TabsNavsExpose。自有实例方法仅 TabsNavs.resize()；其余成员没有自有命令式方法或通知事件，选择及编辑事件归属 Tabs。

---

Document: llms/zh-CN/components/tag.md

<!-- Source: src/tag/README.md; locale: zh-CN; page: /components/tag/ -->

# Tag

用于信息的选择、筛选、分类。用户通过标签进行信息反馈和交互操作。

## 基础示例

### 基础用法

标签的基本用法、常用颜色。

Example source: src/tag/__demos__/basic.vue

```vue
<template>
  <c-space wrap fill>
    <c-tag>Default</c-tag>
    <c-tag>Tag 1</c-tag>
    <c-tag>Tag 2</c-tag>
    <c-tag>
      <template #icon>
        <c-icon-check-circle-fill />
      </template>
      Complete
    </c-tag>
  </c-space>
  <br />
  <c-space wrap fill>
    <c-tag>gray</c-tag>
    <c-tag color="brand">brand</c-tag>
    <c-tag color="green">green</c-tag>
    <c-tag color="orange">orange</c-tag>
    <c-tag color="red">red</c-tag>
    <c-tag color="blue">blue</c-tag>
  </c-space>
</template>

<script lang="ts" setup>
</script>
```

## 外观与状态

### 标签的颜色

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `color` | 自定义背景色（outline 时为边框色） | 标签的颜色 |
| `closable` | 标签是否可关闭 | 标签的颜色 |
<!-- demo-config-notes:end -->

我们提供多种预设色彩的标签样式，通过 `color` 设置不同颜色。如果预设值不能满足你的需求，`color` 字段也可以设置自定义色值。

Example source: src/tag/__demos__/color.vue

```vue
<template>
  <c-space wrap>
    <c-tag v-for="(color, index) of colors" :key="index" :color="color" closable>{{ color }}</c-tag>
  </c-space>
  <h3>Custom Color:</h3>
  <c-space wrap>
    <c-tag v-for="(color, index) of custom" :key="index" :color="color" closable>{{ color }}</c-tag>
  </c-space>
</template>

<script lang="ts" setup>
const colors = [
  'red',
  'orangered',
  'orange',
  'gold',
  'lime',
  'green',
  'cyan',
  'blue',
  'brand',
  'purple',
  'pinkpurple',
  'magenta',
  'gray',
]
const custom = [
  '#f53f3f',
  '#7816ff',
  '#00b42a',
  '#00BEBE',
  '#ff7d00',
  '#eb0aa4',
  '#7bc616',
  '#86909c',
  '#b71de8',
  '#0fc6c2',
  '#ffb400',
  '#168cff',
  '#ff5722',
]
</script>
```

### 外观配置对比

选择一个对比维度后，同屏展示它的全部可选值；其余配置和内容保持一致。可切换其他配置检查组合效果；输入类预览共享一个值。

<details>
<summary>配置说明与使用限制</summary>

#### 标签的尺寸

标签的大小分为：`sm`、`md`、`lg` 三种，可以在不同场景下选择合适按钮尺寸。推荐及默认尺寸为 `md`。

#### 状态与变体

通过 `status` 与 `variant` 切换不同语义颜色和呈现风格（与 Button 对齐）。`color` 与 `status` 同时设置时 `color` 优先。

#### 外观组合

适用于短标签与分类标记。调整变体、状态、尺寸，用相同数据观察变化。内容保持一致，便于比较不同设置的实际效果。

</details>

Example source: src/tag/__demos__/appearance-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";

const __demoAppearance = __demoReactive({
  variant: "default",
  status: "default",
  size: "md",
});

import { computed as demoComputed, ref as demoRef } from 'vue'
const demoCompareFields = [{"name":"variant","values":["default","outline"]},{"name":"status","values":["default","primary","secondary","tertiary","info","success","warning","danger"]},{"name":"size","values":["xs","sm","md","lg","xl"]}]
const demoCompareAxis = demoRef("variant")
const demoComparedOptions = demoComputed(() => demoCompareFields.find(field => field.name === demoCompareAxis.value)?.values ?? [])
</script>
<template>
  <c-space direction="column" :size="16">
    <c-form layout="vertical">
      <c-form-item layout="vertical" size="sm" label="variant">
        <c-radio-group
          v-model="__demoAppearance['variant']"
          aria-label="variant"
          :options="[
            { label: 'default', value: 'default' },
            { label: 'outline', value: 'outline' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
      <c-form-item layout="vertical" size="sm" label="status">
        <c-select
          v-model="__demoAppearance['status']"
          :clearable="false"
          :options="[
            { label: 'default', value: 'default' },
            { label: 'primary', value: 'primary' },
            { label: 'secondary', value: 'secondary' },
            { label: 'tertiary', value: 'tertiary' },
            { label: 'info', value: 'info' },
            { label: 'success', value: 'success' },
            { label: 'warning', value: 'warning' },
            { label: 'danger', value: 'danger' },
          ]"
          aria-label="status"
        />
      </c-form-item>
      <c-form-item layout="vertical" size="sm" label="size">
        <c-radio-group
          v-model="__demoAppearance['size']"
          aria-label="size"
          :options="[
            { label: 'xs', value: 'xs' },
            { label: 'sm', value: 'sm' },
            { label: 'md', value: 'md' },
            { label: 'lg', value: 'lg' },
            { label: 'xl', value: 'xl' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
    </c-form>
    <p class="demo-config-comparison-hint"><span lang="zh-CN">选择一个对比维度；其他配置和内容保持一致。输入类示例共享同一个值，便于比较外观。</span><span lang="en-US">Compare one dimension while keeping the other settings and content identical. Input specimens share the same value.</span></p>
<c-radio-group v-model="demoCompareAxis" aria-label="Compare configuration" :options="demoCompareFields.map(field => ({ label: field.name, value: field.name }))" />
<div class="demo-config-comparison">
<section v-for="sample in demoComparedOptions" :key="String(sample)">
<p><code>{{ demoCompareAxis }}={{ sample }}</code></p>
<c-tag v-bind="{ ...__demoAppearance, [demoCompareAxis]: sample }">gray</c-tag>
</section>
</div>
  </c-space>
</template>

<style scoped>
.demo-config-comparison { display: grid; grid-template-columns: repeat(auto-fit, minmax(min(100%, 220px), 1fr)); gap: 20px; min-width: 0; max-width: 100%; }
.demo-config-comparison > section { min-width: 0; }
.demo-config-comparison p { margin: 0 0 8px; }
html:not([lang='en-US']) .demo-config-comparison-hint > [lang='en-US'],
html[lang='en-US'] .demo-config-comparison-hint > [lang='zh-CN'] { display: none; }
</style>
```

## 内容与展示

### 可选中

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `color` | 自定义背景色（outline 时为边框色） | 可选中、带图标的标签 |
| `checkable` | 标签是否可选中 | 可选中 |
| `status` | 标签状态色（与 `color` 互斥，`color` 优先） | 可选中 |
| `default-value` | 标签默认选中状态（标签可选中时可用） | 可选中 |
| `variant` | 标签变体（与 Button 对齐） | 可选中 |
| `loading` | 标签是否为加载中状态 | 可选中 |
<!-- demo-config-notes:end -->

可选中标签可用 Space / Enter 切换，checked 受控时仍由父级决定是否接受；未传 checked 的此示例由组件自持状态。loading 阻止选中动作，但不是 disabled API。关闭按钮也支持 Space / Enter，关闭不应冒泡为选中。动态示例点击 Add Tag 后聚焦输入，Enter 新增一项；固定首项不提供关闭按钮。这里只说明已展示的操作，不代表长按/异步与触屏组合已全部验收。

通过设置 `checkable` ，可以实现点击选中的效果。

Example source: src/tag/__demos__/checkable.vue

```vue
<template>
  <c-space wrap>
    <c-tag checkable>Awesome</c-tag>
    <c-tag checkable status="primary" :default-value="false">点击选中</c-tag>
    <c-tag checkable status="warning" variant="outline">描边状态</c-tag>
    <c-tag checkable status="success" loading>加载中</c-tag>
    <c-tag checkable color="red" :default-value="true">Toutiao</c-tag>
    <c-tag checkable color="brand" :default-value="true">Lark</c-tag>
  </c-space>
</template>

<script lang="ts" setup>
</script>
```

### 带图标的标签

可通过 `icon` 插槽在标签中加入图标。

Example source: src/tag/__demos__/icon.vue

```vue
<template>
  <c-space wrap>
    <c-tag color="gray">
      <template #icon>
        <c-icon-github />
      </template>
      Github
    </c-tag>
    <c-tag color="orangered">
      <template #icon>
        <c-icon-gitlab />
      </template>
      Gitlab
    </c-tag>
    <c-tag color="blue">
      <template #icon>
        <c-icon-twitter />
      </template>
      Twitter
    </c-tag>
    <c-tag color="brand">
      <template #icon>
        <c-icon-facebook />
      </template>
      Facebook
    </c-tag>
  </c-space>
</template>

<script lang="ts" setup>
</script>
```

## 交互与控制

### 可关闭标签

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `closable` | 标签是否可关闭 | 可关闭标签、动态编辑标签 |
| `loading` | 标签是否为加载中状态 | 加载中状态 |
<!-- demo-config-notes:end -->

通过 `closable` 属性控制标签是否可关闭。可关闭标签可通过 `close` 事件执行一些关闭后操作，也可通过 `show` 属性控制标签的显示或隐藏。

Example source: src/tag/__demos__/closable.vue

```vue
<template>
  <c-space wrap>
    <c-tag closable>Tag</c-tag>
    <c-tag closable>
      <template #icon>
        <c-icon-star />
      </template>
      Tag
    </c-tag>
  </c-space>
</template>

<script lang="ts" setup>
</script>
```

### 动态编辑标签

可动态添加和删除标签。

Example source: src/tag/__demos__/dynamic-tag.vue

```vue
<template>
  <c-space wrap>
    <c-tag v-for="(tag, index) of tags" :key="tag" :closable="index !== 0" @close="handleRemove(tag)">
      {{ tag }}
    </c-tag>

    <c-input
      v-if="showInput"
      ref="inputRef"
      :style="{ width: '90px' }"
      size="xs"
      v-model.trim="inputVal"
      @keyup.enter="handleAdd"
      @blur="handleAdd" />
    <c-tag
      v-else
      :style="{
        width: '90px',
        backgroundColor: 'var(--color-fill-2)',
        border: '1px dashed var(--color-fill-3)',
        cursor: 'pointer',
      }"
      @click="handleEdit"
    >
      <template #icon>
        <c-icon-plus />
      </template>
      Add Tag
    </c-tag>
  </c-space>
</template>

<script lang="ts" setup>
import { ref, nextTick } from 'vue'
const tags = ref(['Tag 1', 'Tag 2', 'Tag 3'])
const inputRef = ref(null)
const showInput = ref(false)
const inputVal = ref('')

const handleEdit = () => {
  showInput.value = true

  nextTick(() => {
    if (inputRef.value) {
      inputRef.value.focus()
    }
  })
}

const handleAdd = () => {
  if (inputVal.value) {
    tags.value.push(inputVal.value)
    inputVal.value = ''
  }
  showInput.value = false
}

const handleRemove = (key) => {
  tags.value = tags.value.filter((tag) => tag !== key)
}
</script>
```

### 加载中状态

标签的加载中状态。

Example source: src/tag/__demos__/loading.vue

```vue
<template>
  <c-tag loading>Loading</c-tag>
</template>

<script lang="ts" setup>
</script>
```

## API

### 主值与默认值

使用普通 `v-model`。`modelValue` 表示可选标签是否选中，布尔值；`defaultValue` 仅在创建时初始化非受控值，后续修改不会重置当前状态。显式绑定值优先，初始化不发出 `update:modelValue`。

### `<Tag>` Props

| 属性                  | 说明                                 | 类型                                                                                                                                                   | 默认值  |
| --------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- |
| color                 | 自定义背景色（outline 时为边框色）   | `string`                                                                                                                                               | -       |
| text-color            | 自定义文字色                         | `string`                                                                                                                                               | -       |
| status                | 标签状态色（与 `color` 互斥，`color` 优先） | `'default' \| 'primary' \| 'secondary' \| 'tertiary' \| 'info' \| 'success' \| 'warning' \| 'danger'` | `'default'` |
| variant               | 标签变体（与 Button 对齐）           | `'default' \| 'outline'`                                                                                                                               | `'default'` |
| size                  | 标签的大小                           | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'`                                                                                                                 | `'md'`  |
| show **(v-model)**    | 标签是否可见                         | `boolean`                                                                                                                                              | -       |
| default-show          | 标签默认是否可见                     | `boolean`                                                                                                                                              | `true`  |
| loading               | 标签是否为加载中状态                 | `boolean`                                                                                                                                              | `false` |
| closable              | 标签是否可关闭                       | `boolean`                                                                                                                                              | `false` |
| checkable             | 标签是否可选中                       | `boolean`                                                                                                                                              | `false` |
| model-value **(v-model)** | 标签是否选中（标签可选中时可用）     | `boolean`                                                                                                                                              | -       |
| default-value       | 标签默认选中状态（标签可选中时可用） | `boolean`                                                                                                                                              | `true`  |
| nowrap                | 内容是否不换行（超出省略）           | `boolean`                                                                                                                                              | `false` |
| round                 | 是否为圆角胶囊形                     | `boolean`                                                                                                                                              | `false` |

### `<Tag>` Events

| 事件名 | 说明                                   | 参数                                          |
| ------ | -------------------------------------- | --------------------------------------------- |
| close  | 点击关闭按钮时触发                     | `(event: MouseEvent) => void`                 |
| check  | 用户选中时触发（仅在可选中模式下触发） | `(check: boolean, event: MouseEvent) => void` |
| update:show | 可见状态变化                       | `(show: boolean) => void`                     |
| update:model-value | 选中状态变化                     | `(checked: boolean) => void`                  |

### `<Tag>` Slots

| 插槽名     | 说明           | 参数 |
| ---------- | -------------- | ---- |
| default    | 标签内容       | -    |
| icon       | 图标           | -    |
| close-icon | 关闭按钮的图标 | -    |

### 类型定义

组件导出以下类型定义

```ts
import type { TagProps } from '@cedar-design/ui'
```

## 同源实现与平台边界

两端各自保存完整源码，不引用公共核心，不共享组件实例或响应式状态；修改时同步维护两份实现。主体、Props、关键样式及配对测试纳入只读源码一致性检查，主题 token 和安装入口各自维护。

两端保留独立的 show/checked 状态，受控值由调用方更新；保留淡出效果，class/style 显式透传给实际标签。尺寸配置、RTL 上下文及图标资源由各库本地适配，移动端触控尺寸保留在 token 中。

### 完整变量默认值与使用边界

状态文字与 outline 描边使用可读 system content，彩色填充使用对应色板第 1 阶。未选中保持中性，已选中状态色优先于通用 hover；默认中性填充为 fill-2 → fill-3。color 优先于 status；预设色不属于本批对比度保证范围。自定义背景需要调用方验证文字对比度，必要时传 text-color。尺寸保留平台差异。以下列出全部公开声明；15 项无消费的预设图标 hover 背景／尺寸变量已移除。custom-icon-bg-hover 及 InputTag 的旧引用也已移除，不保留兼容别名。

| 变量 | 默认值 |
| --- | --- |
| `--c-tag-status-primary-bg-color` | `rgb(var(--c-primary-1))` |
| `--c-tag-status-primary-text-color` | `var(--c-sys-color-content-brand)` |
| `--c-tag-status-secondary-bg-color` | `rgb(var(--c-gray-2))` |
| `--c-tag-status-secondary-text-color` | `var(--c-sys-color-content-secondary)` |
| `--c-tag-status-tertiary-bg-color` | `rgb(var(--c-gray-1))` |
| `--c-tag-status-tertiary-text-color` | `var(--c-sys-color-content-secondary)` |
| `--c-tag-status-info-bg-color` | `rgb(var(--c-blue-1))` |
| `--c-tag-status-info-text-color` | `var(--c-sys-color-content-info)` |
| `--c-tag-status-success-bg-color` | `rgb(var(--c-success-1))` |
| `--c-tag-status-success-text-color` | `var(--c-sys-color-content-success)` |
| `--c-tag-status-warning-bg-color` | `rgb(var(--c-warning-1))` |
| `--c-tag-status-warning-text-color` | `var(--c-sys-color-content-warning)` |
| `--c-tag-status-danger-bg-color` | `rgb(var(--c-danger-1))` |
| `--c-tag-status-danger-text-color` | `var(--c-sys-color-content-danger)` |
| `--c-tag-variant-outline-status-primary-color` | `var(--c-sys-color-content-brand)` |
| `--c-tag-variant-outline-status-secondary-color` | `var(--c-sys-color-content-secondary)` |
| `--c-tag-variant-outline-status-tertiary-color` | `var(--c-sys-color-content-secondary)` |
| `--c-tag-variant-outline-status-info-color` | `var(--c-sys-color-content-info)` |
| `--c-tag-variant-outline-status-success-color` | `var(--c-sys-color-content-success)` |
| `--c-tag-variant-outline-status-warning-color` | `var(--c-sys-color-content-warning)` |
| `--c-tag-variant-outline-status-danger-color` | `var(--c-sys-color-content-danger)` |
| `--c-tag-variant-outline-default-color` | `var(--c-sys-color-content-primary)` |
| `--c-tag-variant-outline-default-border-color` | `var(--c-sys-color-border-default)` |
| `--c-tag-border-width` | `1px` |
| `--c-tag-border-type` | `solid` |
| `--c-tag-padding-horizontal` | `var(--c-spacing-4)` |
| `--c-tag-padding-vertical` | `0` |
| `--c-tag-icon-margin-right` | `var(--c-spacing-2)` |
| `--c-tag-text-font-weight` | `var(--c-font-weight-500)` |
| `--c-tag-border-radius` | `var(--c-sys-radius-sm)` |
| `--c-tag-round-radius` | `100px` |
| `--c-tag-size-xs` | `var(--c-size-4)` |
| `--c-tag-size-sm` | `var(--c-size-5)` |
| `--c-tag-size-md` | `var(--c-size-6)` |
| `--c-tag-size-lg` | `var(--c-size-7)` |
| `--c-tag-size-xl` | `var(--c-size-8)` |
| `--c-tag-size-xs-font-size` | `var(--c-sys-font-size-xs)` |
| `--c-tag-size-sm-font-size` | `var(--c-sys-font-size-xs)` |
| `--c-tag-size-md-font-size` | `var(--c-sys-font-size-xs)` |
| `--c-tag-size-lg-font-size` | `var(--c-sys-font-size-md)` |
| `--c-tag-size-xl-font-size` | `var(--c-sys-font-size-md)` |
| `--c-tag-bg-not-checked-hover` | `var(--c-sys-color-state-hover)` |
| `--c-tag-custom-text-color` | `var(--c-sys-color-content-on-dark)` |
| `--c-tag-default-bg` | `var(--c-sys-color-state-hover)` |
| `--c-tag-default-bg-hover` | `var(--c-color-fill-3)` |
| `--c-tag-default-icon-color` | `var(--c-sys-color-content-secondary)` |
| `--c-tag-default-text-color` | `var(--c-sys-color-content-primary)` |
| `--c-tag-default-border-color` | `transparent` |
| `--c-tag-default-border-color-hover` | `transparent` |
| `--c-tag-red-bg` | `rgb(var(--c-red-1))` |
| `--c-tag-red-bg-hover` | `rgb(var(--c-red-2))` |
| `--c-tag-red-border-color` | `transparent` |
| `--c-tag-red-border-color-hover` | `transparent` |
| `--c-tag-red-icon-color` | `rgb(var(--c-red-9))` |
| `--c-tag-red-text-color` | `rgb(var(--c-red-9))` |
| `--c-tag-orangered-bg` | `rgb(var(--c-orangered-1))` |
| `--c-tag-orangered-bg-hover` | `rgb(var(--c-orangered-2))` |
| `--c-tag-orangered-border-color` | `transparent` |
| `--c-tag-orangered-border-color-hover` | `transparent` |
| `--c-tag-orangered-icon-color` | `rgb(var(--c-orangered-9))` |
| `--c-tag-orangered-text-color` | `rgb(var(--c-orangered-9))` |
| `--c-tag-orange-bg` | `rgb(var(--c-orange-1))` |
| `--c-tag-orange-bg-hover` | `rgb(var(--c-orange-2))` |
| `--c-tag-orange-border-color` | `transparent` |
| `--c-tag-orange-border-color-hover` | `transparent` |
| `--c-tag-orange-icon-color` | `rgb(var(--c-orange-9))` |
| `--c-tag-orange-text-color` | `rgb(var(--c-orange-9))` |
| `--c-tag-gold-bg` | `rgb(var(--c-gold-1))` |
| `--c-tag-gold-bg-hover` | `rgb(var(--c-gold-2))` |
| `--c-tag-gold-border-color` | `transparent` |
| `--c-tag-gold-border-color-hover` | `transparent` |
| `--c-tag-gold-icon-color` | `rgb(var(--c-gold-9))` |
| `--c-tag-gold-text-color` | `rgb(var(--c-gold-9))` |
| `--c-tag-lime-bg` | `rgb(var(--c-lime-1))` |
| `--c-tag-lime-bg-hover` | `rgb(var(--c-lime-2))` |
| `--c-tag-lime-border-color` | `transparent` |
| `--c-tag-lime-border-color-hover` | `transparent` |
| `--c-tag-lime-icon-color` | `rgb(var(--c-lime-9))` |
| `--c-tag-lime-text-color` | `rgb(var(--c-lime-9))` |
| `--c-tag-green-bg` | `rgb(var(--c-green-1))` |
| `--c-tag-green-bg-hover` | `rgb(var(--c-green-2))` |
| `--c-tag-green-border-color` | `transparent` |
| `--c-tag-green-border-color-hover` | `transparent` |
| `--c-tag-green-icon-color` | `rgb(var(--c-green-9))` |
| `--c-tag-green-text-color` | `rgb(var(--c-green-9))` |
| `--c-tag-cyan-bg` | `rgb(var(--c-cyan-1))` |
| `--c-tag-cyan-bg-hover` | `rgb(var(--c-cyan-2))` |
| `--c-tag-cyan-border-color` | `transparent` |
| `--c-tag-cyan-border-color-hover` | `transparent` |
| `--c-tag-cyan-icon-color` | `rgb(var(--c-cyan-9))` |
| `--c-tag-cyan-text-color` | `rgb(var(--c-cyan-9))` |
| `--c-tag-blue-bg` | `rgb(var(--c-blue-1))` |
| `--c-tag-blue-bg-hover` | `rgb(var(--c-blue-2))` |
| `--c-tag-blue-border-color` | `transparent` |
| `--c-tag-blue-border-color-hover` | `transparent` |
| `--c-tag-blue-icon-color` | `rgb(var(--c-blue-9))` |
| `--c-tag-blue-text-color` | `rgb(var(--c-blue-9))` |
| `--c-tag-brand-bg` | `rgb(var(--c-brand-1))` |
| `--c-tag-brand-bg-hover` | `rgb(var(--c-brand-2))` |
| `--c-tag-brand-border-color` | `transparent` |
| `--c-tag-brand-border-color-hover` | `transparent` |
| `--c-tag-brand-icon-color` | `rgb(var(--c-brand-9))` |
| `--c-tag-brand-text-color` | `rgb(var(--c-brand-9))` |
| `--c-tag-purple-bg` | `rgb(var(--c-purple-1))` |
| `--c-tag-purple-bg-hover` | `rgb(var(--c-purple-2))` |
| `--c-tag-purple-border-color` | `transparent` |
| `--c-tag-purple-border-color-hover` | `transparent` |
| `--c-tag-purple-icon-color` | `rgb(var(--c-purple-9))` |
| `--c-tag-purple-text-color` | `rgb(var(--c-purple-9))` |
| `--c-tag-pinkpurple-bg` | `rgb(var(--c-pinkpurple-1))` |
| `--c-tag-pinkpurple-bg-hover` | `rgb(var(--c-pinkpurple-2))` |
| `--c-tag-pinkpurple-border-color` | `transparent` |
| `--c-tag-pinkpurple-border-color-hover` | `transparent` |
| `--c-tag-pinkpurple-icon-color` | `rgb(var(--c-pinkpurple-9))` |
| `--c-tag-pinkpurple-text-color` | `rgb(var(--c-pinkpurple-9))` |
| `--c-tag-magenta-bg` | `rgb(var(--c-magenta-1))` |
| `--c-tag-magenta-bg-hover` | `rgb(var(--c-magenta-2))` |
| `--c-tag-magenta-border-color` | `transparent` |
| `--c-tag-magenta-border-color-hover` | `transparent` |
| `--c-tag-magenta-icon-color` | `rgb(var(--c-magenta-9))` |
| `--c-tag-magenta-text-color` | `rgb(var(--c-magenta-9))` |
| `--c-tag-gray-bg` | `rgb(var(--c-gray-2))` |
| `--c-tag-gray-bg-hover` | `rgb(var(--c-gray-3))` |
| `--c-tag-gray-border-color` | `transparent` |
| `--c-tag-gray-border-color-hover` | `transparent` |
| `--c-tag-gray-icon-color` | `var(--c-sys-color-content-secondary)` |
| `--c-tag-gray-text-color` | `var(--c-sys-color-content-secondary)` |
| `--c-tag-close-margin-left` | `var(--c-spacing-2)` |
| `--c-tag-close-font-size` | `var(--c-sys-font-size-xs)` |

### 颜色覆盖边界

预设色 outline 保持透明；loading 不触发预设填充 hover。暗色背景消费 bg/bg-hover 变量，实例覆盖同样生效。预设 icon-color 与 text-color 分开。未选中预设保持中性，但自定义 color 属性仍生效。预设／自定义色不保证任意背景上的对比度。

### 动效变量

内置动效遵循 `prefers-reduced-motion: reduce`；减少动效不会阻止加载状态或关闭事件更新。

| Token | Default |
| --- | --- |
| `--c-tag-fade-duration` | `var(--c-sys-motion-duration-fast)` |

---

Document: llms/zh-CN/components/textarea.md

<!-- Source: src/textarea/README.md; locale: zh-CN; page: /components/textarea/ -->

# Textarea

Textarea 是用于多行纯文本编辑的基础表单控件，适合评论、反馈和说明等较长内容。

默认长度按 UTF-16 码元计算（emoji 通常占 2）；默认截断不会拆开有效的代理对，边界不足时舍去整个字符。若需按用户感知字符（字素簇）计数和裁剪，请配套提供 `word-length` 与 `word-slice`；自定义裁剪结果由业务负责。

## 阅读方向

多行输入继承来源 `dir`，文字默认按阅读起点对齐，计数按阅读终点排列。切换方向保留原生编辑器、焦点与选区，不交换原生光标或换行键。

## 基础示例

### 基础用法与值模型

`v-model` 用于受控值；`default-value` 只提供非受控初始值。`v-model.trim` 会在失焦提交时去除首尾空白。

Example source: src/textarea/__demos__/basic.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const value = ref('')
const trimmed = ref('')
</script>
<template>
  <c-space direction="column">
    <c-textarea v-model="value" clearable placeholder="请输入多行文本" aria-label="受控文本" />
    <p role="status">当前值：{{ value || '（空）' }}</p>
    <c-textarea default-value="这是一段非受控初始文本" aria-label="非受控文本" />
    <c-textarea v-model.trim="trimmed" placeholder="输入首尾空白，失焦后去除" aria-label="去除首尾空白" />
    <p role="status">去除空白后的值：{{ JSON.stringify(trimmed) }}</p>
  </c-space>
</template>
```

## 外观与状态

### 状态与外观

<!-- demo-config-notes:start -->

#### 本组配置对照

| 配置            | 作用                              | 相关示例   |
| --------------- | --------------------------------- | ---------- |
| `placeholder`   | 占位提示文字                      | 状态与外观 |
| `variant`       | `filled` / `outline` / `standard` | 状态与外观 |
| `default-value` | 非受控模式初始值                  | 状态与外观 |
| `readonly`      | 是否只读                          | 状态与外观 |
| `disabled`      | 是否禁用                          | 状态与外观 |
| `error`         | 是否显示错误状态                  | 状态与外观 |

<!-- demo-config-notes:end -->

支持 `filled`、`outline`、`standard` 三种外观和 `xs`、`sm`、`md`、`lg`、`xl` 五种尺寸。

Example source: src/textarea/__demos__/status.vue

```vue
<template>
  <c-space direction="column" size="lg" fill>
    <c-textarea placeholder="默认描边外观" />
    <c-textarea variant="filled" placeholder="填充外观" />
    <c-textarea variant="standard" placeholder="标准外观" />
    <c-textarea default-value="Readonly value" readonly />
    <c-textarea placeholder="Disabled status" disabled />
    <c-textarea placeholder="Error status" error />
  </c-space>
</template>
```

### 外观组合

适用于备注、说明等多行输入。调整变体、尺寸，用相同数据观察变化。内容保持一致，便于比较不同设置的实际效果。

Example source: src/textarea/__demos__/appearance-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref("这是一段可以编辑的多行内容。");
const __demoAppearance = __demoReactive({ variant: "filled", size: "md" });

import { computed as demoComputed, ref as demoRef } from 'vue'
const demoCompareFields = [{"name":"variant","values":["filled","outline","standard"]},{"name":"size","values":["xs","sm","md","lg","xl"]}]
const demoCompareAxis = demoRef("variant")
const demoComparedOptions = demoComputed(() => demoCompareFields.find(field => field.name === demoCompareAxis.value)?.values ?? [])
</script>
<template>
  <c-space direction="column" :size="16">
    <c-form layout="vertical">
      <c-form-item layout="vertical" size="sm" label="variant">
        <c-radio-group
          v-model="__demoAppearance['variant']"
          aria-label="variant"
          :options="[
            { label: 'filled', value: 'filled' },
            { label: 'outline', value: 'outline' },
            { label: 'standard', value: 'standard' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
      <c-form-item layout="vertical" size="sm" label="size">
        <c-radio-group
          v-model="__demoAppearance['size']"
          aria-label="size"
          :options="[
            { label: 'xs', value: 'xs' },
            { label: 'sm', value: 'sm' },
            { label: 'md', value: 'md' },
            { label: 'lg', value: 'lg' },
            { label: 'xl', value: 'xl' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
    </c-form>
    <p class="demo-config-comparison-hint"><span lang="zh-CN">选择一个对比维度；其他配置和内容保持一致。输入类示例共享同一个值，便于比较外观。</span><span lang="en-US">Compare one dimension while keeping the other settings and content identical. Input specimens share the same value.</span></p>
<c-radio-group v-model="demoCompareAxis" aria-label="Compare configuration" :options="demoCompareFields.map(field => ({ label: field.name, value: field.name }))" />
<div class="demo-config-comparison">
<section v-for="sample in demoComparedOptions" :key="String(sample)">
<p><code>{{ demoCompareAxis }}={{ sample }}</code></p>
<c-textarea v-model="value" v-bind="{ ...__demoAppearance, [demoCompareAxis]: sample }"></c-textarea>
</section>
</div>
  </c-space>
</template>

<style scoped>
.demo-config-comparison { display: grid; grid-template-columns: repeat(auto-fit, minmax(min(100%, 220px), 1fr)); gap: 20px; min-width: 0; max-width: 100%; }
.demo-config-comparison > section { min-width: 0; }
.demo-config-comparison p { margin: 0 0 8px; }
html:not([lang='en-US']) .demo-config-comparison-hint > [lang='en-US'],
html[lang='en-US'] .demo-config-comparison-hint > [lang='zh-CN'] { display: none; }
</style>
```

## 内容与展示

### 字数限制

<!-- demo-config-notes:start -->

#### 本组配置对照

| 配置              | 作用                                     | 相关示例         |
| ----------------- | ---------------------------------------- | ---------------- |
| `placeholder`     | 占位提示文字                             | 字数限制         |
| `max-length`      | 最大长度；对象形式可启用仅错误模式       | 字数限制         |
| `clearable`       | 是否允许清空                             | 字数限制         |
| `show-word-limit` | 是否显示字数统计                         | 字数限制         |
| `aria-label`      | 无可见标签时提供的可访问名称             | 原生属性与无障碍 |
| `rows`            | 原生可见行数，仍受 min-height Token 约束 | 原生属性与无障碍 |

<!-- demo-config-notes:end -->

数字形式会在用户编辑时截断；`errorOnly: true` 会保留超长内容并显示错误状态。外部受控值不会仅因超长而被组件反向改写。

Example source: src/textarea/__demos__/max-length.vue

```vue
<template>
  <c-space direction="column" size="lg" fill>
    <p>长度按 UTF-16 码元计算；试着输入 123456789😀Z，默认截断保留 123456789，不拆开 emoji。</p>
    <c-textarea
      v-model="limited"
      placeholder="超过 10 个字符会截断"
      :max-length="10"
      clearable
      show-word-limit
    />
    <c-textarea
      v-model="errorOnly"
      placeholder="超过 10 个字符后保留内容并显示错误"
      :max-length="{ length: 10, errorOnly: true }"
      clearable
      show-word-limit
    />
  </c-space>
</template>

<script lang="ts" setup>
import { ref } from "vue";

const limited = ref("");
const errorOnly = ref("超过长度的内容会保留");
</script>
```

### 原生属性与无障碍

通过 `textarea-attrs` 补充 `name`、`autocomplete`、`inputmode`、`aria-describedby` 等原生属性。组件管理的值、禁用、只读、行数、长度、核心事件和错误态具有更高优先级。

Example source: src/textarea/__demos__/native-attrs.vue

```vue
<template>
  <label for="feedback">反馈内容</label>
  <c-textarea
    v-model="value"
    aria-label="反馈内容"
    :rows="4"
    :textarea-attrs="{
      id: 'feedback',
      name: 'feedback',
      autocomplete: 'off',
      'aria-describedby': 'feedback-help',
    }"
  />
  <p id="feedback-help">请勿填写密码或其他敏感信息。</p>
</template>

<script lang="ts" setup>
import { ref } from "vue";

const value = ref("");
</script>
```

## 自定义与插槽

### 前缀、后缀和清除图标

<!-- demo-config-notes:start -->

#### 本组配置对照

| 配置          | 作用         | 相关示例             |
| ------------- | ------------ | -------------------- |
| `clearable`   | 是否允许清空 | 前缀、后缀和清除图标 |
| `placeholder` | 占位提示文字 | 前缀、后缀和清除图标 |

<!-- demo-config-notes:end -->

Example source: src/textarea/__demos__/slots.vue

```vue
<template>
  <c-textarea v-model="value" clearable placeholder="带前后缀和自定义清除按钮">
    <template #prefix>说明</template>
    <template #suffix>Markdown</template>
    <template #clear-icon="{ clear }">
      <c-button html-type="button" aria-label="清空文本" @click="clear"
        >×</c-button
      >
    </template>
  </c-textarea>
</template>

<script lang="ts" setup>
import { ref } from "vue";

const value = ref("可清空内容");
</script>
```

自定义 `clear-icon` 会收到 `clear(event?)` 方法。自定义交互元素需要保留可访问名称和键盘操作。

## 交互与控制

### 交互状态切换

<!-- demo-config-notes:start -->

#### 本组配置对照

| 配置          | 作用                                     | 相关示例                                           |
| ------------- | ---------------------------------------- | -------------------------------------------------- |
| `placeholder` | 占位提示文字                             | 行数、自动高度与手动调整、事件语义、主体与事件契约 |
| `rows`        | 原生可见行数，仍受 min-height Token 约束 | 行数、自动高度与手动调整、主体与事件契约           |
| `auto-size`   | 是否自动高度，可设置最小/最大行数        | 行数、自动高度与手动调整、主体与事件契约           |
| `clearable`   | 是否允许清空                             | 事件语义、主体与事件契约                           |
| `disabled`    | 是否禁用                                 | 交互状态切换                                       |
| `readonly`    | 是否只读                                 | 交互状态切换                                       |

<!-- demo-config-notes:end -->

适用于备注、说明等多行输入。调整禁用、只读、错误反馈，用相同数据观察变化。控制区始终可用，可以随时恢复编辑；错误外观本身不会触发表单校验。

Example source: src/textarea/__demos__/state-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref("这是一段可以编辑的多行内容。");
const __demoState = __demoReactive({
  disabled: false,
  readonly: false,
  error: false,
});
</script>
<template>
  <c-space direction="column" :size="16">
    <c-space wrap>
      <c-checkbox v-model="__demoState['disabled']">disabled</c-checkbox>
      <c-checkbox v-model="__demoState['readonly']">readonly</c-checkbox>
      <c-checkbox v-model="__demoState['error']">error</c-checkbox>
    </c-space>
    <c-textarea v-model="value" v-bind="__demoState"></c-textarea>
  </c-space>
</template>
```

### 行数、自动高度与手动调整

`rows` 使用原生可见行数，仍受 min-height Token 约束语义。Cedar 默认允许纵向拖动；开启 `auto-size` 后关闭手动调整，并可使用 `minRows`、`maxRows` 约束高度。

在 Form/FormItem 内未显式设置时，`size`、`disabled`、`readonly` 和 `error` 会继承表单状态；组件本地传入的值（包括 `false`）优先。

Example source: src/textarea/__demos__/auto-size.vue

```vue
<template>
  <c-space direction="column" size="lg" fill>
    <c-textarea default-value="原生三行，可纵向拖动" :rows="3" />
    <c-textarea v-model="content" auto-size placeholder="随内容自动增高" />
    <c-textarea
      v-model="boundedContent"
      :auto-size="{ minRows: 2, maxRows: 5 }"
      placeholder="自动高度限制在 2 到 5 行"
    />
  </c-space>
</template>

<script lang="ts" setup>
import { ref } from "vue";

const content = ref("第一行");
const boundedContent = ref("第一行\n第二行");
</script>
```

### 事件语义

`input` 先于 `update:model-value`。IME 完成后处理一次；失焦提交 `change`。清空按 `clear → input → update:model-value → change` 通知，各一次，后续失焦不重复提交。

Example source: src/textarea/__demos__/interaction.vue

```vue
<template>
  <c-space direction="column" size="lg" fill>
    <c-textarea
      v-model="value"
      clearable
      placeholder="输入、换行并失焦以观察事件"
      @input="record('input', $event)"
      @change="record('change', $event)"
      @keydown="record('keydown')"
      @clear="record('clear')"
      @blur="record('blur')"
    />
    <span>最近事件：{{ latest || "-" }}</span>
  </c-space>
</template>

<script lang="ts" setup>
import { ref } from "vue";

const value = ref("Cedar");
const latest = ref("");

const record = (name: string, value?: string) => {
  latest.value = value === undefined ? name : `${name}: ${value}`;
};
</script>
```

### 主体与事件契约

两端维护独立复制的主体。输入按 input → update:modelValue 通知；清空按 clear → input → update:modelValue → change 通知，各一次，Form 对应语义也各接收一次。只读、禁用和组合输入期间禁止清空。受控提议被拒绝后恢复原生内容，包括不支持光标 API 的输入类型。

Example source: src/textarea/__demos__/body-contract.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const value = ref('可编辑内容')
const events = ref<string[]>([])
const record = (name: string) => { events.value = [...events.value.slice(-7), name] }
</script>
<template>
  <div class="textarea-body-demo">
    <c-textarea v-model="value" hint clearable placeholder="工作备注" :auto-size="{ minRows: 2, maxRows: 5 }" :max-length="100" show-word-limit @clear="record('clear')" @input="record('input')" @update:model-value="record('update:modelValue')" @change="record('change')" />
    <c-textarea :line="false" hint placeholder="无边框提示" focus-color="#137547" :rows="2" />
    <p>Enter 保持换行；失焦提交 change；清空完整通知一次。</p>
    <output>{{ events.join(' → ') || '等待操作' }}</output>
  </div>
</template>
<style scoped>
.textarea-body-demo { display: flex; flex-direction: column; gap: 16px; }
.textarea-body-demo p { margin: 0; }
</style>
```

## 设计要点

- 默认使用 `outline` 外观，`clearable` 默认关闭。
- `input` 表示实时编辑，`change` 在失焦值变化或清空时提交；Enter 保持换行语义。
- `auto-size` 开启后由内容决定高度，并覆盖 `rows` 与手动 `resize` 的视觉结果。
- Form/FormItem 负责业务校验规则和消息，Textarea 只提供事件信号和错误视觉状态。

### 共享字段加载

`loading` 控制共享字段加载状态；`loading-mode` 为 `default`（指示器）或 `line`（底部不定进度线），默认 `default`。渲染统一由 FieldDecorator 负责，不隐式改变 disabled/readonly；需要禁止编辑时单独设置。

## API

### 空值识别与阅读空文案

`empty-values` 用于空值识别，`empty-value` 保留原清空输出；`empty-text` 仅在 `read-pretty` 空内容下展示，默认 `'-'`，字段 > FormItem > Form，自定义 read 插槽优先。显式配置 empty-values 后，内置 required 接入该策略，自定义校验仍收到原值。详见[统一说明](llms/zh-CN/guide/empty-values.md)。

| 参数         | 类型               | 缺省与范围                                            |
| ------------ | ------------------ | ----------------------------------------------------- |
| empty-values | readonly unknown[] | 字段 > FormItem > Form > 组件族默认；完整覆盖，不合并 |
| empty-text   | string             | 字段 > FormItem > Form > '-'；显式 '' 有效            |

以上是字段展示层 API；纯面板不因此新增阅读模式。Form 与 FormItem 提供继承配置。empty-value 的现有类型与默认输出仍按该组件原 API 执行。

### Textarea Props

支持与 Input 一致的 hint、line、text-color、focus-color、blur-color；hint 未设置时继承 InputGroup/库默认值。外层 FormItem 有标签时隐藏内部浮动提示。

| 属性                    | 说明                                     | 类型                                                | 默认值    |
| ----------------------- | ---------------------------------------- | --------------------------------------------------- | --------- |
| model-value (`v-model`) | 受控绑定值                               | `string`                                            | `-`       |
| default-value           | 非受控模式初始值                         | `string`                                            | `''`      |
| model-modifiers         | v-model 修饰符；支持 `trim`              | `{ trim?: boolean }`                                | `{}`      |
| placeholder             | 占位提示文字                             | `string`                                            | `-`       |
| variant                 | `filled` / `outline` / `standard`        | `FormControlVariant`                                | `outline` |
| size                    | `xs` / `sm` / `md` / `lg` / `xl`         | `ComponentSize`                                     | `md`      |
| clearable               | 是否允许清空                             | `boolean`                                           | `false`   |
| disabled                | 是否禁用                                 | `boolean`                                           | `false`   |
| readonly                | 是否只读                                 | `boolean`                                           | `false`   |
| error                   | 是否显示错误状态                         | `boolean`                                           | `false`   |
| rows                    | 原生可见行数，仍受 min-height Token 约束 | `string \| number`                                  | `-`       |
| resize                  | 是否允许纵向拖动调整尺寸                 | `boolean`                                           | `true`    |
| auto-size               | 是否自动高度，可设置最小/最大行数        | `boolean \| { minRows?: number; maxRows?: number }` | `false`   |
| max-length              | 最大长度；对象形式可启用仅错误模式       | `number \| { length: number; errorOnly?: boolean }` | `0`       |
| show-word-limit         | 是否显示字数统计                         | `boolean`                                           | `false`   |
| word-length             | 自定义长度计算方法                       | `(value: string) => number`                         | `-`       |
| word-slice              | 自定义截取方法                           | `(value: string, maxLength: number) => string`      | `-`       |
| aria-label              | 无可见标签时提供的可访问名称             | `string`                                            | `-`       |
| autofocus               | 是否自动聚焦                             | `boolean`                                           | `false`   |
| enterkeyhint            | 虚拟键盘回车键提示                       | `string`                                            | `-`       |
| textarea-attrs          | 内部 textarea 元素的补充原生属性         | `Record<string, unknown>`                           | `-`       |
| hint                    | 浮动提示，未设置时继承 InputGroup/库默认 | boolean                                             | undefined |
| line                    | 显示边框/底线                            | boolean                                             | true      |
| text-color              | 实例文字颜色                             | string                                              | undefined |
| focus-color             | 实例聚焦颜色                             | string                                              | undefined |
| blur-color              | 实例失焦提示颜色                         | string                                              | undefined |

### Textarea Events

| 事件名  | 说明                                                                | 参数                       |
| ------- | ------------------------------------------------------------------- | -------------------------- |
| input   | IME 完成后的用户输入                                                | `value: string, ev: Event` |
| change  | 失焦提交且值变化时触发                                              | `value: string, ev: Event` |
| keydown | 用户按键时触发；Enter 不提交 change                                 | `ev: KeyboardEvent`        |
| clear   | 用户清空时触发，按 clear → input → update:model-value → change 通知 | `ev: Event`                |
| focus   | 获得焦点时触发                                                      | `ev: FocusEvent`           |
| blur    | 失去焦点时触发                                                      | `ev: FocusEvent`           |

### Textarea Slots

| 插槽名     | 说明           | 参数                          |
| ---------- | -------------- | ----------------------------- |
| prefix     | 前缀元素       | `-`                           |
| suffix     | 后缀元素       | `-`                           |
| clear-icon | 清除图标或按钮 | `clear: (ev?: Event) => void` |

### Textarea Methods

| 方法名 | 说明                     |
| ------ | ------------------------ |
| focus  | 使内部 textarea 获取焦点 |
| blur   | 使内部 textarea 失去焦点 |

## 类型定义

```ts
import type {
  TextareaAutoSize,
  TextareaMaxLength,
  TextareaProps,
  WordLength,
  WordSlice,
} from "@cedar-design/ui";
```

## 样式变量

| 变量名                            | 默认值                            |
| --------------------------------- | --------------------------------- |
| `--c-textarea-height`             | `auto`                            |
| `--c-textarea-min-height`         | `--c-sys-control-height-xl`       |
| `--c-textarea-font-size`          | `--c-sys-font-size-md`            |
| `--c-textarea-line-height`        | `--c-line-height`                 |
| `--c-textarea-padding-horizontal` | `--c-sys-space-3`                 |
| `--c-textarea-padding-vertical`   | `--c-sys-space-1`                 |
| `--c-textarea-placeholder-color`  | `--c-sys-color-content-secondary` |
| `--c-textarea-counter-color`      | `--c-sys-color-content-secondary` |
| `--c-textarea-counter-font-size`  | `--c-sys-font-size-xs`            |
| `--c-textarea-counter-margin-top` | `var(--c-sys-space-2)`            |

两端计数器均在外侧，使用 counter-margin-top 控制顶部间距，避免覆盖文本。

### 原生布局与公开类型

size 支持 xs/sm/md/lg/xl 的 FieldDecorator 外壳密度；文本域高度/文字度量仍由 rows、auto-size 和 Textarea Token 控制。Cedar 默认允许手动 resize，Maple 默认关闭。继承 InputGroup 与 Form 状态，子项显式值优先；提供 focus(options?)、blur()、select() 和 textareaRef。

`TextareaProps`、`TextareaVariant`、`TextareaMaxLength`、`TextareaAutoSize`、`TextareaEmits`、`TextareaSlots`、`TextareaExpose`、`TextareaInstance`。

原生方法：`focus(options?: FocusOptions)`、`blur()`、`select()`；`textareaRef` 为原生元素。

### Form 字段展示与确认

本组件支持 `edit-mode`，字段 > FormItem > Form 逐层继承；未指定时为 `direct`，保留原有交互。支持值：`direct / click / dblclick`。非 direct 编辑模式通过字段值入口打开编辑面板，并维护单份草稿；确认后才更新 v-model，取消、重置或启用 readPretty 时丢弃草稿。

Cedar 使用 edit-mode="click" / "dblclick" 在字段附近打开编辑浮层，Enter/F2 也可进入；取消/Escape 丢弃草稿，确认后提交。readPretty 为独立阅读属性，与 readonly、disabled 分开。

`before-commit(value, { previousValue, signal })` 可拦截弹层保存；FormItem 先校验候选值，失败保持编辑。`open / default-open / update:open` 控制编辑层。`#read="{ value, text }"` 可自定义阅读内容。集中示例见 Form 的“各类字段统一展示”。

`read-pretty` 为独立布尔属性，与 `readonly`、`disabled` 同级；字段 > FormItem > Form 继承，显式 `false` 覆盖父级。默认 `false`。纯阅读不显示编辑器。

统一光标色通过 `--c-field-caret-color` 设置（默认 `currentColor`）；本组件可用 `--c-textarea-caret-color` 单独覆盖，默认 `var(--c-field-caret-color)`。

## 配置清空后的值

`empty-value` 指定当前组件已有清空动作的输出；省略时采用该组件默认返回。具体类型以组件 API 为准。它不改变 empty-values 的识别规则，也不改变 Form reset 的初始值。

`empty-value` 可显式设为 `null`（或 `() => null`），清空时原样提交 null；省略时保留组件原默认值。界面把 null 显示为空，不会把普通输入的空字符串自动转成 null。支持弹出编辑的字段中，清空先修改草稿，确认后提交，取消则保留原值。

---

Document: llms/zh-CN/components/time-picker.md

<!-- Source: src/time/picker/README.md; locale: zh-CN; page: /components/time-picker/ -->

# TimePicker

时间选择**面板**（默认无触发器）。

### 列表滚动任务审计（2026-10-16）

私有工具保留正时长线性滚动（列选择100ms）；零／负／非有限时长及owner减弱动态直接到位，动态reduce下一帧收束。同元素新请求取消旧任务，旧帧／重复帧不覆盖新偏移。工具取消保持当前偏移，不触发选择提交；无新增公开API或CSS Token。

表单字段请使用 [`Time`](llms/zh-CN/components/time.md)；时间范围字段请使用 [`TimeRange`](llms/zh-CN/components/time-range.md)；范围面板请使用 [`TimeRangePicker`](components/time-range-picker)。

## 基础示例

### 基本用法

默认只渲染面板。

Example source: src/time/picker/__demos__/basic.vue

```vue
<template>
  <c-time-picker default-value="09:09:06" />
</template>
```

## 格式与展示

### 定制格式

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `format` | 展示格式 | 定制格式、十二小时制 |
| `use12-hours` | 12 小时制 | 十二小时制 |
<!-- demo-config-notes:end -->

Example source: src/time/picker/__demos__/format.vue

```vue
<template>
  <c-time-picker format="HH:mm" default-value="09:24" />
</template>
```

### 十二小时制

Example source: src/time/picker/__demos__/use12Hours.vue

```vue
<template>
  <c-space>
    <c-time-picker use12-hours default-value="12:20:20 AM" format="hh:mm:ss A" />
    <c-time-picker use12-hours default-value="09:20:20 pm" format="hh:mm:ss a" />
    <c-time-picker use12-hours default-value="2:20 AM" format="h:mm A" />
  </c-space>
</template>
```

## 选择规则与交互

### 禁用部分时间选项

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `format` | 展示格式 | 禁用部分时间选项、时间上下限、纯面板确认与禁用选项 |
| `disable-confirm` | 跳过确认 | 跳过确认、纯面板确认与禁用选项 |
| `use12-hours` | 12 小时制 | 禁用部分时间选项 |
| `step` | 时分秒步长 | 定制步长 |
| `hide-disabled-options` | 隐藏禁用时间选项 | 纯面板确认与禁用选项 |
<!-- demo-config-notes:end -->

禁用回调中的小时始终为 0–23，与面板是否使用十二小时制无关：午夜为 0，中午为 12，下午 1 点为 13。切换 AM/PM 后会重新计算禁用选项。

Example source: src/time/picker/__demos__/disabled-parts.vue

```vue
<template>
  <p>12 小时显示；禁用回调始终使用 0–23 小时。下午 1 点禁用，下午 2 点的第 30 分钟禁用。</p>
  <c-time-picker
    default-value="02:20:00 pm"
    format="hh:mm:ss a"
    use12-hours
    :disabled-hours="() => [0, 13]"
    :disabled-minutes="(hour) => hour === 14 ? [30] : []"
    :disabled-seconds="(hour, minute) => hour === 14 && minute === 20 ? [15, 30, 45] : []"
  />
</template>
```

### 定制步长

Example source: src/time/picker/__demos__/step.vue

```vue
<template>
  <c-time-picker
    default-value="10:25:30"
    :step="{
      hour: 2,
      minute: 5,
      second: 10,
    }"
  />
</template>
```

### 时间上下限

`min` / `max` 的类型为 `string`，默认不限制；格式固定为 24 小时制 `HH:mm` 或 `HH:mm:ss`，不受 `format` 或 `use12Hours` 影响，包含端点。`HH:mm` 的秒视为 00。范围的两个端点分别校验；`showNextDay` 不把边界变成跨午夜区间。`min > max` 时没有可提交时间。无法解析的边界按未设置处理。

动态修改边界不会改写外部模型。提交须同时满足边界、步长和禁用回调；不显示秒时按秒为 00 校验。列表粗粒度列在整个小时/分钟都越界时禁用，最终确认仍校验完整时间。隐藏禁用项使用 `hide-disabled-options`。

Example source: src/time/__demos__/bounds.vue

```vue
<script setup>
import { ref } from "vue";

const value = ref("10:30:38");
const narrow = ref(false);
</script>

<template>
  <c-space direction="column" :size="12" style="width: 100%">
    <p>
      包含边界：10:30:38–10:31:02。收紧边界不会改写已有模型，但越界值无法确认。
    </p>
    <c-checkbox v-model="narrow"> 将下限调整为 10:30:40</c-checkbox>
    <c-time
      v-model="value"
      format="HH:mm:ss"
      :min="narrow ? '10:30:40' : '10:30:38'"
      max="10:31:02"
    />
    <c-time-picker
      v-model="value"
      format="HH:mm:ss"
      :min="narrow ? '10:30:40' : '10:30:38'"
      max="10:31:02"
    />
    <span>{{ value }}</span>
  </c-space>
</template>
```

### 跳过确认

Example source: src/time/picker/__demos__/no-confirm.vue

```vue
<template>
  <c-time-picker disable-confirm />
</template>
```

### 纯面板确认与禁用选项

纯面板默认确认后提交：选择时仅发 select，确认后才更新模型并发 change；disable-confirm 开启后有效选择立即提交。hide-disabled-options 默认 false，开启后隐藏禁用项；时钟保留原刻度角度。字段和日期组件内部显式跳过子面板确认，由外层负责提交。外部模型替换会重置草稿，不主动派发事件。

单值面板未确认草稿中打开只读、隐藏禁用小时或切立即提交，不会隐式提交旧草稿；解除只读也不提交，下一次有效选择才提交一次。Maple滚轮/时钟展示切换保留同一草稿，不回写父模型；鼠标/键盘验收不等于物理触屏惯性行为通过。

Example source: src/time/picker/__demos__/panel-behavior.vue

```vue
<script setup>
import { ref } from "vue";

const value = ref("09:30");
const immediate = ref(false);
const confirmations = ref(0);
const hideDisabled = ref(false);
const readonly = ref(false);
const disabledHours = () => [0, 1, 2, 3, 4, 5, 6, 7];
</script>

<template>
  <c-space direction="column" size="12px" style="width: 100%">
    <c-checkbox v-model="immediate"> 跳过确认，选择即提交</c-checkbox>
    <c-checkbox v-model="hideDisabled"> 隐藏禁用小时（00–07）</c-checkbox>
    <c-checkbox v-model="readonly"> 只读（包括确认）</c-checkbox>
    <c-button variant="outline" @click="value = '13:45'"
      >外部更新为 13:45，覆盖未提交草稿</c-button
    >
    <c-time-picker
      v-model="value"
      @confirm="confirmations++"
      format="HH:mm"
      :disable-confirm="immediate"
      :hide-disabled-options="hideDisabled"
      :readonly="readonly"
      :disabled-hours="disabledHours"
    >
      <template #extra
        ><p>附加说明使用 extra 插槽；选择草稿后点击确认提交。</p></template
      >
    </c-time-picker>
    <span>有效确认次数: {{ confirmations }}</span>
    <span>已提交值: {{ value }}</span>
    <p>默认选择只修改草稿，点击确认后上方的已提交值才会更新。</p>
  </c-space>
</template>
```

独立面板直接管理自己的草稿与提交状态。外部替换模型会重置草稿，不触发选择或变更事件；只读、禁用均阻止选择和确认。Cedar 使用列表，Maple 使用滚轮或时钟，展示层不另建一份草稿。

## 阅读方向

继承最近的 `dir="ltr|rtl"`，方向切换不修改时间或提交草稿。小时、分钟、秒等列按阅读顺序排列；左右键沿视觉方向跨列移动焦点。Cedar 的上下键与 Home/End 在当前时间列移动焦点，Enter/Space 选择，禁用项跳过；Maple 滚轮保留上下键和 Home/End 的选值行为。是否即时提交仍由原有确认配置决定。弹层继承字段来源方向。

## API

面板主体统一管理草稿和确认，展示内容只渲染这一份状态。上方示例展示 extra 插槽及有效确认次数；重复确认相同值会触发 confirm，不会重复触发 change。

### 纯面板事件与插槽边界

`TimePicker` / `TimeRangePicker` 不管理字段或弹层；`open`、`size`、`variant`、清除和浮层配置应传给 `Time` / `TimeRange`。

- `select(value, date)`：修改草稿。
- `change(value, date)`：有效确认且值变化时触发，并更新模型。
- `confirm(value, date)`：每次有效确认均触发，包括值未变化；`disableConfirm` 模式在有效选择提交时也触发。禁用、只读或无效草稿不会触发。
- `extra`：附加说明内容。
- `actions({ confirm, canConfirm, value })`：替换默认操作栏；`value` 是草稿，调用 `confirm()` 提交，并根据 `canConfirm` 禁用按钮。

单时间事件值为格式化字符串及 Date；范围事件值为对应数组。纯面板不再派发 `open-change`、`update:open` 或 `clear`。

### Props

| 参数 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| `model-value` | 绑定值 | `string \| number \| Date` | `-` |
| `format` | 展示格式 | `string` | `-` |
| `use12-hours` | 12 小时制 | `boolean` | `false` |
| `hide-disabled-options` | 隐藏禁用时间选项 | `boolean` | `false` |
| `disable-confirm` | 跳过确认 | `boolean` | `false` |
| `disabled` | 禁用 | `boolean` | `false` |
| `step` | 时分秒步长 | `object` | `-` |

---

Document: llms/zh-CN/components/time-range.md

<!-- Source: src/time-range/README.md; locale: zh-CN; page: /components/time-range/ -->

# TimeRange

表单时间范围字段（带触发器）。内部使用 `TimeRangePicker`。

纯面板请使用 [`TimeRangePicker`](components/time-range-picker)（默认无触发器）。

## 基础示例

### 基本用法

Example source: src/time-range/__demos__/basic.vue

```vue
<template>
  <c-time-range v-model="range" style="width: 252px" clearable />
</template>

<script setup>
import { ref } from 'vue'

const range = ref()
</script>
```

## 外观与展示

### 尺寸

<!-- demo-config-notes:start -->

#### 本组配置对照

| 配置            | 作用                                                                   | 相关示例                                           |
| --------------- | ---------------------------------------------------------------------- | -------------------------------------------------- |
| `format`        | 展示格式                                                               | 字段外壳与配置边界、范围格式与十二小时制、次日标记 |
| `clearable`     | 可清除                                                                 | 范围格式与十二小时制、自定义占位、次日标记         |
| `placeholder`   | 占位                                                                   | 字段外壳与配置边界、自定义占位                     |
| `show-next-day` | 允许结束早于开始并显示「次日」；关闭时倒序范围不能提交，起止始终不交换 | 范围格式与十二小时制、次日标记                     |
| `size`          | 尺寸                                                                   | 尺寸                                               |
| `variant`       | 输入框变体                                                             | 字段外壳与配置边界                                 |

<!-- demo-config-notes:end -->

Example source: src/time-range/__demos__/size.vue

```vue
<template>
  <c-space direction="column" fill>
    <c-time-range style="width: 252px" size="xs" />
    <c-time-range style="width: 252px" size="sm" />
    <c-time-range style="width: 252px" size="md" />
    <c-time-range style="width: 252px" size="lg" />
    <c-time-range style="width: 252px" size="xl" />
  </c-space>
</template>
```

### 字段外壳与配置边界

`hint` 控制浮动提示（Cedar 默认 false，Maple 默认 true），有 Form 外置标签时不启用。`line` 默认 true；`text-color / focus-color / blur-color` 为可选颜色字符串。`error` 未设置时继承 Form，显式 false 覆盖错误态。TimeRange 的 `separator` 默认 `~`，允许空字符串。默认 variant 保留 Cedar filled、Maple standard，可显式指定同一变体。

字段顶层负责值、默认值、展开、格式、步长、边界、禁用规则和只读/禁用状态。请直接在字段上设置这些属性，不放进 timePickerProps/timeRangePickerProps。嵌套配置只允许对应面板的展示属性；不能通过模型/确认/选择事件替换字段流程。类型会拒绝此类配置，运行时也过滤，且不会把嵌套规则作为顶层未设置时的回退。

Maple 的 pickerProps 可配置 optionHeight/optionCount 等外观，不可替换 columns、fieldNames、选中值、toolbar 或展开状态。popupProps 可设置定位、外观和生命周期回调，但不能设置 open/defaultOpen 或覆盖展开更新事件；顶层 popupContainer（包括 false）优先。纯时间面板内部的嵌套配置遵循相同规则。

Example source: src/time-range/__demos__/field-appearance.vue

```vue
<script setup>
import { ref } from "vue";

const value = ref(["09:00", "18:00"]);
const hint = ref(true);
const error = ref(false);
const line = ref(true);
</script>

<template>
  <c-space direction="column" :size="12" style="width: 100%">
    <c-checkbox v-model="hint"> 浮动提示</c-checkbox>
    <c-checkbox v-model="error"> 显式错误状态</c-checkbox>
    <c-checkbox v-model="line"> 边框 / 底线</c-checkbox>
    <c-time-range
      v-model="value"
      format="HH:mm"
      variant="outline"
      :placeholder="['开始时间', '结束时间']"
      :hint="hint"
      :error="error"
      :line="line"
      focus-color="#6750a4"
      separator=" → "
    />
    <span>{{ value }}</span>
  </c-space>
</template>
```

字段交互由本库的一份实例控制器编排：select 暂存草稿，确认时按当前规则校验后提交并通知 Form。清除通过相同提交路径写入 undefined，再通知 clear；只读、禁用或未开启 clearable 时不能清除。只读仍可聚焦，focus/blur 去重；受控关闭请求尚未被接受时，不会重复提交。

### 范围格式与十二小时制

比较范围的分钟、秒与十二小时制显示，操作起止端点观察格式；跨日判断和值格式独立展示。

<details>
<summary>配置说明与使用限制</summary>

#### 显示格式

未设置 `format` 时默认 `HH:mm:ss`；开启 `use12-hours` 后默认 `hh:mm:ss a`，字段与纯面板一致。显式 `format` 决定字符串值的解析和输出格式，`use12-hours` 还可独立控制面板小时列；建议十二小时格式包含 `a` 或 `A`，以区分上午与下午。

使用方括号包裹固定文字，例如 `[Time] HH:mm`。固定文字不参与时间列识别，不会因为包含 `s` 或 `A` 而额外显示秒或 AM/PM 列。空格式或没有时、分、秒 token 的格式回退到上述默认格式。

</details>

Example source: src/time-range/__demos__/format-comparison.vue

```vue
<script setup lang="ts">
import { ref } from "vue"
import { proxyRefs as demoProxyRefs } from 'vue'

const scene1 = demoProxyRefs((() => {


const range = ref(['09:30', '18:00'])

const literalRange = ref(['Time 09:30', 'Time 18:00'])

const rangeSeconds = ref(['09:30:20', '18:00:00'])
return { range, literalRange, rangeSeconds }
})())

const scene2 = demoProxyRefs((() => {

const value = ref(['11:30:00 pm', '12:30:00 am'])
return { value }
})())
</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="format">
    <h4><span lang="zh-CN">显示格式</span><span lang="en-US">format</span></h4>
    <c-space direction="column" fill>
        <c-time-range v-model="scene1.range" format="HH:mm" style="width: 100%; max-width: 360px" clearable />
        <c-time-range v-model="scene1.literalRange" format="[Time] HH:mm" style="width: 100%; max-width: 360px" clearable />
        <c-time-range
          v-model="scene1.rangeSeconds"
          format="HH:mm:ss"
          style="width: 100%; max-width: 360px"
          clearable
        />
      </c-space>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="ampm">
    <h4><span lang="zh-CN">十二小时制</span><span lang="en-US">ampm</span></h4>
    <c-space direction="column" :size="12" style="width: 100%">
        <p>分别切换起止端的 AM/PM；12 AM 是午夜，12 PM 是中午。</p>
        <c-time-range v-model="scene2.value" use12-hours show-next-day style="width: 100%; max-width: 360px" />
        
        <span>当前值: {{ scene2.value }}</span>
      </c-space>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

### 自定义占位

Example source: src/time-range/__demos__/placeholder.vue

```vue
<template>
  <c-time-range
    v-model="range"
    style="width: 280px"
    :placeholder="['开始时间', '结束时间']"
    clearable
  />
</template>

<script setup>
import { ref } from 'vue'

const range = ref()
</script>
```

### 次日标记

结束时间早于开始时间时，开启 `show-next-day` 会在字段与面板结束侧显示「次日」并允许提交；关闭时倒序范围不能提交。起止端点始终不自动交换。

Example source: src/time-range/__demos__/show-next-day.vue

```vue
<script setup lang="ts">
import { ref } from "vue";

const range = ref<string[] | undefined>(["22:00", "06:00"]);
const reset = () => {
  range.value = ["22:00", "06:00"];
};
</script>

<template>
  <section class="time-overnight-demo">
    <c-time-range
      v-model="range"
      format="HH:mm"
      input-editable
      show-next-day
      clearable
    />
    <output aria-label="Overnight model">{{
      range === undefined ? "undefined" : JSON.stringify(range)
    }}</output>
    <c-button @click="reset">重置</c-button>
  </section>
</template>

<style scoped>
.time-overnight-demo {
  display: flex;
  flex-direction: column;
  gap: 12px;
  max-width: 360px;
}
</style>
```

此示例开启文本编辑并显示模型，保留 22:00→次日06:00 的端点顺序；清除为 `undefined`，可通过重置按钮恢复。`show-next-day` 表示时间顺序与标签，不将模型自动转换为下一日日期。

## 值模型与选择规则

### 模型类型与固定文字

<!-- demo-config-notes:start -->

#### 本组配置对照

| 配置          | 作用      | 相关示例                                     |
| ------------- | --------- | -------------------------------------------- |
| `format`      | 展示格式  | 模型类型与固定文字、独立步长示例、时间上下限 |
| `use12-hours` | 12 小时制 | 独立步长示例                                 |

<!-- demo-config-notes:end -->

字符串按 `format` 严格解析，不接受溢出时间或不匹配的格式；Date 和毫秒时间戳按本地时间反显。提交值始终为格式化字符串（范围为数组）。

Example source: src/time-range/__demos__/format-model.vue

```vue
<script setup>
import { ref } from 'vue'

const date = new Date(2026, 8, 23, 13, 5, 9)
const later = new Date(2026, 8, 23, 18, 30, 0)
const value = ref([date, later.getTime()])
const literal = ref(['Time 09:30', 'Time 18:00'])
</script>

<template>
  <c-space direction="column" fill style="width: 100%">
    <p>Date 和时间戳按本地时间反显；选择后返回格式化字符串。</p>
    <c-time-range v-model="value" format="hh:mm A" style="width: 100%; max-width: 360px" />
    <span>当前模型: {{ value }}</span>
    <c-time-range v-model="literal" format="[Time] HH:mm" style="width: 100%; max-width: 360px" />
    <span>固定文字格式: {{ literal }}</span>
  </c-space>
</template>
```

### 独立步长示例

小时候选以 0 点为起点，十二小时制只改变显示；无效步长回退为 1。

Example source: src/time-range/__demos__/step.vue

```vue
<script setup>
import { ref } from "vue";
const value = ref(["09:30:00", "17:00:00"]);
const step = { hour: 1, minute: 15, second: 10 };
const use12Hours = ref(false);
</script>

<template>
  <c-space direction="column" :size="12" style="width: 100%">
    <p>小时步长 1，分钟步长 15，秒步长 10。</p>
    <c-checkbox v-model="use12Hours">
      12 小时面板，模型仍为 HH:mm:ss</c-checkbox
    >
    <c-time-range
      v-model="value"
      format="HH:mm:ss"
      :use12-hours="use12Hours"
      :step="step"
      style="width: 100%; max-width: 360px"
    />
    <span>{{ value }}</span>
  </c-space>
</template>
```

可切换十二小时面板，分钟/秒步长保持不变；显式 `HH:mm:ss` 仍决定模型格式，AM/PM 选择转换为对应的 24 小时值。

### 时间上下限

`min` / `max` 的类型为 `string`，默认不限制；格式固定为 24 小时制 `HH:mm` 或 `HH:mm:ss`，不受 `format` 或 `use12Hours` 影响，包含端点。`HH:mm` 的秒视为 00。范围的两个端点分别校验；`showNextDay` 不把边界变成跨午夜区间。`min > max` 时没有可提交时间。无法解析的边界按未设置处理。

动态修改边界不会改写外部模型。提交须同时满足边界、步长和禁用回调；不显示秒时按秒为 00 校验。列表粗粒度列在整个小时/分钟都越界时禁用，最终确认仍校验完整时间。隐藏禁用项使用 `hide-disabled-options`。

Example source: src/time-range/__demos__/bounds.vue

```vue
<script setup>
import { ref } from "vue";

const value = ref(["10:30:38", "10:31:02"]);
const narrow = ref(false);
</script>

<template>
  <c-space direction="column" :size="12" style="width: 100%">
    <p>
      包含边界：10:30:38–10:31:02。收紧边界不会改写已有模型，但越界值无法确认。
    </p>
    <c-checkbox v-model="narrow"> 将下限调整为 10:30:40</c-checkbox>
    <c-time-range
      v-model="value"
      format="HH:mm:ss"
      :min="narrow ? '10:30:40' : '10:30:38'"
      max="10:31:02"
    />
    <c-time-range-picker
      v-model="value"
      format="HH:mm:ss"
      :min="narrow ? '10:30:40' : '10:30:38'"
      max="10:31:02"
    />
    <span>{{ value }}</span>
  </c-space>
</template>
```

## 输入与状态控制

### 交互状态对比

<!-- demo-config-notes:start -->

#### 本组配置对照

| 配置             | 作用             | 相关示例                                     |
| ---------------- | ---------------- | -------------------------------------------- |
| `format`         | 展示格式         | 交互状态对比、手输与面板选择、默认值与受控值 |
| `clearable`      | 可清除           | 手输与面板选择、默认值与受控值、选择与提交   |
| `disabled`       | 禁用             | 交互状态对比、选择与提交                     |
| `readonly`       | 只读             | 交互状态对比、选择与提交                     |
| `input-editable` | 允许桌面文本输入 | 手输与面板选择、复制与编辑                   |
| `model-value`    | 绑定值           | 默认值与受控值                               |

<!-- demo-config-notes:end -->

在同一实例上切换禁用、只读和错误状态后再操作控件，比较可编辑性和交互反馈。恢复开关位于目标控件外；错误外观本身不会执行校验。

<details>
<summary>配置说明与使用限制</summary>

#### 交互状态切换

适用于营业时段等时间范围。调整禁用、只读、错误反馈，用相同数据观察变化。控制区始终可用，可以随时恢复编辑；错误外观本身不会触发表单校验。

</details>

Example source: src/time-range/__demos__/state-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref(["09:30", "18:00"]);
const __demoState = __demoReactive({
  disabled: false,
  readonly: false,
  error: false,
});
</script>
<template>
  <c-space direction="column" :size="16">
    <c-space wrap>
      <c-checkbox v-model="__demoState['disabled']">disabled</c-checkbox>
      <c-checkbox v-model="__demoState['readonly']">readonly</c-checkbox>
      <c-checkbox v-model="__demoState['error']">error</c-checkbox>
    </c-space>
    <c-time-range
      v-model="value"
      format="HH:mm"
      v-bind="__demoState"
    ></c-time-range>
  </c-space>
</template>
```

### 手输与面板选择

`inputEditable` 默认为 `true`（Maple 默认为 `false`）。回车或失焦提交，Esc 撤销；格式、步长、边界和禁用规则与面板一致。无效输入或父级拒绝受控更新时回到模型值；切换为不可编辑、只读或禁用会丢弃未提交输入。输入法组合期间不提交。范围两端之间移动焦点不提交。

Example source: src/time-range/__demos__/text-entry.vue

```vue
<script setup>
import { ref } from "vue";

const value = ref(["09:00", "10:00"]);
const editable = ref(true);
</script>

<template>
  <c-space direction="column" :size="12" style="width: 100%">
    <c-checkbox v-model="editable"> 允许手输</c-checkbox>
    <p>回车或失焦提交，Esc 撤销。合法范围为 08:00–18:00。</p>
    <c-time-range
      v-model="value"
      :input-editable="editable"
      format="HH:mm"
      min="08:00"
      max="18:00"
      clearable
    />
    <span>{{ value }}</span>
  </c-space>
</template>
```

### 默认值与受控值

`defaultValue` 初始化字段/纯面板的非受控值，仅读取一次；后续选择保存在各自实例。传入 `modelValue` 后以父级值为准。字段 `defaultOpen` 只初始化一次；受控 `open` 需父级接收 `update:open`，`open-change(open: boolean)` 通知显隐请求。`clear` 不携带参数。纯面板支持 `disabled`，同时禁用范围两端。

Example source: src/time-range/__demos__/default-state.vue

```vue
<script setup>
import { ref } from "vue";
const value = ref(["09:00", "10:00"]);
const open = ref(false);
const acceptValue = ref(true);
const acceptOpen = ref(true);
const acceptClose = ref(true);
const commits = ref(0);
const proposal = ref();
const openProposal = ref();
const updateValue = (next) => {
  proposal.value = next;
  if (acceptValue.value) {
    value.value = next;
  }
};
const updateOpen = (next) => {
  openProposal.value = next;
  if (acceptOpen.value && (next || acceptClose.value)) {
    open.value = next;
  }
};
</script>

<template>
  <c-space direction="column" size="12px" style="width: 100%">
    <p>非受控初始值，无需绑定 v-model</p>
    <c-time-range
      :default-value="['09:00', '10:00']"
      format="HH:mm"
      clearable
    />
    <p>受控值与展开状态</p>
    <c-checkbox v-model="acceptValue"> 接受值更新</c-checkbox>
    <c-checkbox v-model="acceptOpen"> 接受展开更新</c-checkbox>
    <c-time-range
      :model-value="value"
      :open="open"
      format="HH:mm"
      clearable
      @update:model-value="updateValue"
      @update:open="updateOpen"
      @change="commits++"
    />
    <span>{{ value }} / {{ open }}</span>
    <c-checkbox v-model="acceptClose"> 接受关闭请求</c-checkbox>
    <output aria-label="Commit count">{{ commits }}</output>
    <output aria-label="Controlled proposals">{{
      JSON.stringify({ value: proposal, open: openProposal })
    }}</output>
  </c-space>
</template>
```

示例可分别拒绝值更新与展开更新：拒绝时保留父级模型/显隐，提案单独显示；重新打开从父级模型恢复。关闭请求不代表父级已接受。

父级拒绝关闭、面板保持展开时，没有新选择的重复确认不会重复提交；再次选择新时间会开启新事务，可重新确认提交。

### 选择与提交

字段的 `focus` / `blur` 事件均无参数，同一次聚焦或失焦只通知一次；范围两端切换不产生额外整字段事件。只读字段仍可聚焦，但不能展开修改；禁用字段不能聚焦，已聚焦时动态禁用会释放焦点状态并通知失焦。

字段和纯面板提交时按当前格式、步长及禁用规则重新校验；Cedar 手动输入也遵守相同规则。规则变化不会自动改写已提交值。起止端点始终不自动交换；关闭 `show-next-day` 时倒序范围不能提交，开启后允许结束早于开始。清空仍提交 `undefined`，不受候选时间限制，但遵守只读/禁用状态。

`select(value, date)` 表示用户选择草稿，`change(value, date)` 表示提交。单值和范围字段清除均返回 `undefined`，对应 Date 参数也为 `undefined`，`clear` 不带参数。Date 参数是本地时间表示（不自动进行次日日期运算）。字段默认确认后提交；`disable-confirm` 开启后仅有效选择立即提交并请求关闭，不允许次日时的倒序草稿仍不能提交。受控 `open` 仍需父级接受更新。独立纯面板同样默认确认后提交；开启 disable-confirm 后有效选择立即提交，但不会关闭面板。

Example source: src/time-range/__demos__/selection-events.vue

```vue
<script setup>
import { ref } from "vue";

const value = ref(["09:00", "18:00"]);
const immediate = ref(false);
const readonly = ref(false);
const disabled = ref(false);
const events = ref([]);
function record(name, value, dates) {
  const times = Array.isArray(dates)
    ? dates.map((date) => date?.toLocaleTimeString())
    : dates?.toLocaleTimeString();
  events.value = [
    JSON.stringify({ event: name, value: value ?? null, time: times ?? null }),
    ...events.value,
  ].slice(0, 5);
}
</script>

<template>
  <c-space direction="column" size="12px" style="width: 100%">
    <c-checkbox v-model="readonly"> 只读：可聚焦，不可修改</c-checkbox>
    <c-checkbox v-model="disabled"> 禁用：释放焦点，不可修改</c-checkbox>
    <c-checkbox v-model="immediate"> 选择后立即提交</c-checkbox>
    <p>select 记录草稿，change 记录提交；取消不改模型，清除返回 undefined。</p>
    <c-time-range
      v-model="value"
      :disable-confirm="immediate"
      :readonly="readonly"
      :disabled="disabled"
      format="HH:mm"
      clearable
      @select="(value, dates) => record('select', value, dates)"
      @change="(value, dates) => record('change', value, dates)"
      @clear="record('clear')"
      @click="record('click')"
      @open-change="(open) => record('open-change', open)"
      @focus="record('focus')"
      @blur="record('blur')"
    />
    <span>模型: {{ value === undefined ? "undefined" : value }}</span>
    <c-button variant="outline" @click="value = ['15:30', '18:00']"
      >从外部替换模型</c-button
    >
    <small>外部替换会更新反显，不触发 select 或 change。</small>
    <div
      v-for="(event, index) in events"
      :key="index"
      style="overflow-wrap: anywhere"
    >
      {{ event }}
    </div>
  </c-space>
</template>
```

父级直接替换模型会重置草稿，但不会触发 `select` 或 `change`。示例提供“外部更新”按钮，可与用户选择、确认提交分别观察。

起止输入使用同一字段焦点：Tab 在两端间切换时保留草稿，不触发 blur 校验或提交；Enter 或离开整个字段才提交，Escape 丢弃草稿。点击结束输入会激活时间面板的结束端。

字段使用 PickerField → FieldDecorator；面板只负责选择，不注入表单。有效文本在回车或失焦时提交，Escape 或外部关闭丢弃未确认草稿，清除立即提交空值。四类字段的统一示例见 [Date](llms/zh-CN/components/date.md#统一字段与提交)。

### 复制与编辑

open-trigger-target="icon" 时，输入区可以编辑或复制，只有右侧选择按钮响应点击打开。关闭手输或搜索后，已有文本仍可复制。

Example source: src/time-range/__demos__/open-trigger-target.vue

```vue
<template>
  <c-space direction="column">
    <c-radio-group
      v-model="target"
      :options="[
        { label: '整个字段', value: 'field' },
        { label: '仅右侧图标', value: 'icon' },
      ]"
    />
    <label><c-switch v-model="editable" /> 允许编辑 / 搜索</label>
    <c-time-range
      v-model="value"
      edit-mode="direct"
      :open-trigger-target="target"
      :input-editable="editable"
    />
    <p>关闭编辑后，可以复制已有文本；仅图标模式下编辑不会展开。</p>
  </c-space>
</template>
<script setup lang="ts">
import { ref } from "vue";
const target = ref<"field" | "icon">("icon");
const editable = ref(true);
const value = ref(["09:30:00", "10:30:00"]);
</script>
```

### 共享字段加载

`loading` 控制共享字段加载状态；`loading-mode` 为 `default`（指示器）或 `line`（底部不定进度线），默认 `default`。渲染统一由 FieldDecorator 负责，不隐式改变 disabled/readonly；需要禁止编辑时单独设置。

## 阅读方向

范围值始终保持 `[开始, 结束]`，LTR/RTL 切换只调整布局，不交换端点或修改跨日语义。时间列与起止面板按阅读顺序排列，左右键沿视觉方向移动焦点，可跨起止时间列；Cedar 上下键移动焦点、Enter/Space 选择，Maple 上下键保留滚轮选值语义。草稿与确认行为沿用原有配置，弹层继承字段来源方向。

## API

### 空值识别与阅读空文案

`empty-values` 用于空值识别，`empty-value` 保留原清空输出；`empty-text` 仅在 `read-pretty` 空内容下展示，默认 `'-'`，字段 > FormItem > Form，自定义 read 插槽优先。显式配置 empty-values 后，内置 required 接入该策略，自定义校验仍收到原值。详见[统一说明](llms/zh-CN/guide/empty-values.md)。

| 参数         | 类型               | 缺省与范围                                            |
| ------------ | ------------------ | ----------------------------------------------------- |
| empty-values | readonly unknown[] | 字段 > FormItem > Form > 组件族默认；完整覆盖，不合并 |
| empty-text   | string             | 字段 > FormItem > Form > '-'；显式 '' 有效            |

以上是字段展示层 API；纯面板不因此新增阅读模式。Form 与 FormItem 提供继承配置。empty-value 的现有类型与默认输出仍按该组件原 API 执行。

### 浮层配置与字段通知

`popup-props` 显式配置本地 Trigger 的定位和外观，例如 `{ placement: 'top-start' }`；不能覆盖 open、disabled、trigger 等字段状态或交互。顶层 `popup-container`（包括 false）优先。`input-editable` 默认 true，可关闭桌面文本输入。面板外观使用 `time-range-picker-props`（支持 class/style），不再从未声明的 attrs 读取面板/浮层参数；id、aria-* 等属性透传给字段。

`click(event)` 只通知非禁用字段的点击；只读字段可通知但不展开。关闭统一监听 `open-change(false)`，它表示关闭请求，受控 open 仍需父级接受。两端不提供字段 close 事件；不要把关闭请求当作值提交。

字段图标插槽为 `suffix-icon`，参数为 `focus: boolean`、`popupOpen: boolean`。实例方法 `focus(index = 0)` 聚焦起点（0）或终点（1）而不提交值；`blur()` 失焦并请求关闭。

`placeholder` 字符串用于两端；数组分别指定起止文案，缺项为空；显式空字符串不会回退默认文案。

### Props

| 参数                      | 说明                                                                                   | 类型                                                | 默认值    |
| ------------------------- | -------------------------------------------------------------------------------------- | --------------------------------------------------- | --------- |
| `open-trigger-target`     | 打开面板的点击区域；field 为整个字段，icon 仅右侧选择按钮。不影响键盘展开及受控 open。 | `'field' \| 'icon'`                                 | `'field'` |
| `model-value`             | 绑定值                                                                                 | `(string \| number \| Date)[]`                      | `-`       |
| `open`                    | 弹层显隐                                                                               | `boolean`                                           | `-`       |
| `popup-props`             | 本地 Trigger 的展示配置，不控制字段状态                                                | `TimePopupPresentationProps<Partial<TriggerProps>>` | `{}`      |
| `input-editable`          | 允许桌面文本输入                                                                       | `boolean`                                           | `true`    |
| `clearable`               | 可清除                                                                                 | `boolean`                                           | `true`    |
| `disabled`                | 禁用                                                                                   | `boolean`                                           | `false`   |
| `readonly`                | 只读                                                                                   | `boolean`                                           | `false`   |
| `size`                    | 尺寸                                                                                   | `xs \| sm \| md \| lg \| xl`                        | `-`       |
| `variant`                 | 输入框变体                                                                             | `filled \| outline \| standard`                     | `filled`  |
| `placeholder`             | 占位                                                                                   | `string \| string[]`                                | `-`       |
| `format`                  | 展示格式                                                                               | `string`                                            | `-`       |
| `use12-hours`             | 12 小时制                                                                              | `boolean`                                           | `false`   |
| `hide-disabled-options`   | 隐藏禁用时间选项                                                                       | `boolean`                                           | `false`   |
| `disable-confirm`         | 跳过确认，有效选择立即提交并请求关闭                                                   | `boolean`                                           | `false`   |
| `show-next-day`           | 允许结束早于开始并显示「次日」；关闭时倒序范围不能提交，起止始终不交换                 | `boolean`                                           | `false`   |
| `time-range-picker-props` | 透传给 TimeRangePicker                                                                 | `object`                                            | `{}`      |

### Form 字段展示与确认

本组件支持 `edit-mode`，字段 > FormItem > Form 逐层继承；未指定时为 `direct`，保留原有交互。支持值：`direct / click / dblclick`。非 direct 编辑模式通过字段值入口打开编辑面板，并维护单份草稿；确认后才更新 v-model，取消、重置或启用 readPretty 时丢弃草稿。

Cedar 使用 edit-mode="click" / "dblclick" 在字段附近打开编辑浮层，Enter/F2 也可进入；取消/Escape 丢弃草稿，确认后提交。readPretty 为独立阅读属性，与 readonly、disabled 分开。

`before-commit(value, { previousValue, signal })` 可拦截弹层保存；FormItem 先校验候选值，失败保持编辑。`open / default-open / update:open` 控制编辑层。`#read="{ value, text }"` 可自定义阅读内容。集中示例见 Form 的“各类字段统一展示”。

日期／时间字段在 inline 下沿用原确认策略；在 click/dblclick 编辑展示中，内部纯面板隐藏确认工具栏，由编辑层提供唯一一组确认／取消。独立 DatePicker、DateRangePicker、TimePicker、TimeRangePicker 保留原有面板 API 和确认行为，不继承 Form 的字段展示。

`read-pretty` 为独立布尔属性，与 `readonly`、`disabled` 同级；字段 > FormItem > Form 继承，显式 `false` 覆盖父级。默认 `false`。纯阅读不显示编辑器。

### 透传配置边界核对（F07）

现有 TimePopupPresentationProps 与运行时过滤保持；open/defaultOpen、disabled、trigger、closeOnClickReference、preventFocus 和对应展开更新归字段管理。顶层 popup-container 明确设置时优先，否则嵌套回退，popupClass 合并内部类。inline 展示层固定 popupOffset=4；Maple 还固定 unmountOnClose=true，这些旧类型中的字段不保证能控制最终值。本轮不收窄既有 Time 类型，也不改变运行行为。

## 配置清空后的值

`empty-value` 指定当前组件已有清空动作的输出；省略时采用该组件默认返回。具体类型以组件 API 为准。它不改变 empty-values 的识别规则，也不改变 Form reset 的初始值。

`empty-value` 可显式设为 `null`（或 `() => null`），清空时原样提交 null；省略时保留组件原默认值。界面把 null 显示为空，不会把普通输入的空字符串自动转成 null。支持弹出编辑的字段中，清空先修改草稿，确认后提交，取消则保留原值。

---

Document: llms/zh-CN/components/time.md

<!-- Source: src/time/README.md; locale: zh-CN; page: /components/time/ -->

# Time

父级在确认后保持弹层展开时，没有新选择的重复确认不会重复提交；新的时间选择会开启新事务，可以再次确认。

展开时，原生 combobox 通过 `aria-controls` 关联当前实例的命名弹层；关闭后同步更新状态并移除关联。`aria-label`、`aria-describedby` 可传递给原生控件。自定义 selected/触发插槽需自行保留可访问名称、键盘操作和状态关联。

表单时间字段（带触发器）。内部使用 `TimePicker`。

纯面板请使用 [`TimePicker`](llms/zh-CN/components/time-picker.md)（默认无触发器）。时间范围字段请使用 [`TimeRange`](llms/zh-CN/components/time-range.md)。

## 基础示例

### 基本用法

Example source: src/time/__demos__/basic.vue

```vue
<template>
  <c-time v-model="value" style="width: 200px" />
</template>

<script setup>
import { ref } from 'vue'

const value = ref()
</script>
```

## 外观与展示

### 尺寸

<!-- demo-config-notes:start -->

#### 本组配置对照

| 配置          | 作用       | 相关示例                                 |
| ------------- | ---------- | ---------------------------------------- |
| `size`        | 尺寸       | 尺寸、表单控件尺寸对照                   |
| `variant`     | 输入框变体 | 表单控件尺寸对照、字段外壳与配置边界     |
| `placeholder` | 占位       | 表单控件尺寸对照、字段外壳与配置边界     |
| `format`      | 展示格式   | 字段外壳与配置边界、时间格式与十二小时制 |
| `use12-hours` | 12 小时制  | 时间格式与十二小时制                     |

<!-- demo-config-notes:end -->

Example source: src/time/__demos__/size.vue

```vue
<template>
  <c-space direction="column" fill>
    <c-time style="width: 200px" size="xs" />
    <c-time style="width: 200px" size="sm" />
    <c-time style="width: 200px" size="md" />
    <c-time style="width: 200px" size="lg" />
    <c-time style="width: 200px" size="xl" />
  </c-space>
</template>
```

### 表单控件尺寸对照

切换五档 size 和三种字段变体，比较 Input、Button、Select、日期时间及其他单行表单控件的高度。Button 在这里固定使用 outline。DatePicker/TimePicker 是面板，此处使用带输入框的 Date/Time 字段。示例同时展示有值、可清空、标签删除与长标签多选；Select/Cascader 设置 tag-nowrap 时保持同档高度，长标签文字省略、删除图标保留；标签行可横向滚动，清空按钮和箭头固定在外侧。被省略的标签正文支持悬停、键盘聚焦或点按查看完整文字，点外部或按 Esc 关闭，不改变选中值。可清空后恢复选中值重复比较。多行文本和允许换行的多选内容按内容撑高。

Example source: src/field-decorator/__demos__/control-sizes.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
const sizes = ["xs", "sm", "md", "lg", "xl"] as const;
const variants = ["outline", "filled", "standard"] as const;
const size = ref<(typeof sizes)[number]>("md");
const variant = ref<(typeof variants)[number]>("outline");
const options = [
  { value: "beijing", label: "Beijing" },
  { value: "shanghai", label: "Shanghai" },
];
const cascaderOptions = [{ value: "china", label: "China", children: options }];

const inputValue = ref("Beijing");
const selectValue = ref("beijing");
const cascaderValue = ref("beijing");
const selectMultiple = ref(["beijing", "shanghai"]);
const cascaderMultiple = ref(["beijing", "shanghai"]);
const selectOverflow = ref(["long", "beijing", "shanghai"]);
const cascaderOverflow = ref(["long", "beijing", "shanghai"]);
const selectedOptions = [
  ...options,
  {
    value: "long",
    label:
      "A very long selected option label for overflow comparison — full text preview keeps the selected value unchanged.",
  },
];
const selectedCascaderOptions = [
  { value: "china", label: "China", children: selectedOptions },
];
function resetSelections() {
  inputValue.value = "Beijing";
  selectValue.value = "beijing";
  cascaderValue.value = "beijing";
  selectMultiple.value = ["beijing", "shanghai"];
  cascaderMultiple.value = ["beijing", "shanghai"];
  selectOverflow.value = ["long", "beijing", "shanghai"];
  cascaderOverflow.value = ["long", "beijing", "shanghai"];
}
</script>
<template>
  <section
    aria-label="Form control size comparison"
    class="control-size-comparison"
  >
    <c-space wrap :size="12">
      <c-radio-group v-model="size" aria-label="Comparison size">
        <c-radio v-for="item in sizes" :key="item" :value="item">{{
          item
        }}</c-radio>
      </c-radio-group>
      <c-radio-group v-model="variant" aria-label="Comparison variant">
        <c-radio v-for="item in variants" :key="item" :value="item">{{
          item
        }}</c-radio>
      </c-radio-group>
    </c-space>
    <div class="control-size-comparison__grid">
      <div data-control="Input">
        <p>Input</p>
        <c-input :size="size" :variant="variant" placeholder="Input" />
      </div>
      <div data-control="Button">
        <p>Button</p>
        <c-button :size="size" variant="outline">Button</c-button>
      </div>
      <div data-control="Select">
        <p>Select</p>
        <c-select
          :size="size"
          :variant="variant"
          :options="options"
          placeholder="Select"
        />
      </div>
      <div data-control="Date">
        <p>Date</p>
        <c-date :size="size" :variant="variant" placeholder="Date" />
      </div>
      <div data-control="Time">
        <p>Time</p>
        <c-time :size="size" :variant="variant" placeholder="Time" />
      </div>
      <div data-control="InputNumber">
        <p>InputNumber</p>
        <c-input-number :size="size" :variant="variant" placeholder="Number" />
      </div>
      <div data-control="AutoComplete">
        <p>AutoComplete</p>
        <c-auto-complete
          :size="size"
          :variant="variant"
          :options="options"
          placeholder="AutoComplete"
        />
      </div>
      <div data-control="Cascader">
        <p>Cascader</p>
        <c-cascader
          :size="size"
          :variant="variant"
          :options="cascaderOptions"
          placeholder="Cascader"
        />
      </div>
      <div data-control="DateRange">
        <p>DateRange</p>
        <c-date-range
          :size="size"
          :variant="variant"
          :placeholder="['Start', 'End']"
        />
      </div>
      <div data-control="TimeRange">
        <p>TimeRange</p>
        <c-time-range
          :size="size"
          :variant="variant"
          :placeholder="['Start', 'End']"
        />
      </div>
    </div>

    <section
      aria-label="Selected control size comparison"
      class="control-size-comparison__states"
    >
      <c-space wrap align="center" :size="12">
        <span>Selected / Clearable / Multiple — 有值、可清空与多选不换行</span>
        <span
          >Hover or focus truncated text; tap on touch screens /
          悬停或聚焦省略正文查看全文；触屏点按查看，点外部关闭</span
        >
        <c-button size="sm" variant="outline" @click="resetSelections"
          >Reset / 恢复选中值</c-button
        >
      </c-space>
      <div class="control-size-comparison__grid">
        <div data-control="InputValue">
          <p>Input · clearable</p>
          <c-input
            v-model="inputValue"
            :size="size"
            :variant="variant"
            clearable
            placeholder="Input value"
          />
        </div>
        <div data-control="ButtonReference">
          <p>Button · reference</p>
          <c-button :size="size" variant="outline">Button</c-button>
        </div>
        <div data-control="SelectValue">
          <p>Select · clearable</p>
          <c-select
            v-model="selectValue"
            :size="size"
            :variant="variant"
            :options="selectedOptions"
            clearable
            placeholder="Select value"
          />
        </div>
        <div data-control="CascaderValue">
          <p>Cascader · clearable</p>
          <c-cascader
            v-model="cascaderValue"
            :size="size"
            :variant="variant"
            :options="selectedCascaderOptions"
            clearable
            placeholder="Cascader value"
          />
        </div>
        <div data-control="SelectMultiple">
          <p>Select · multiple / nowrap</p>
          <c-select
            v-model="selectMultiple"
            :size="size"
            :variant="variant"
            :options="selectedOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Select multiple"
          />
        </div>
        <div data-control="CascaderMultiple">
          <p>Cascader · multiple / nowrap</p>
          <c-cascader
            v-model="cascaderMultiple"
            :size="size"
            :variant="variant"
            :options="selectedCascaderOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Cascader multiple"
          />
        </div>
        <div data-control="SelectOverflow">
          <p>Select · long values / nowrap</p>
          <c-select
            v-model="selectOverflow"
            edit-mode="direct"
            :size="size"
            :variant="variant"
            :options="selectedOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Select long values"
          />
        </div>
        <div data-control="CascaderOverflow">
          <p>Cascader · long values / nowrap</p>
          <c-cascader
            v-model="cascaderOverflow"
            edit-mode="direct"
            :size="size"
            :variant="variant"
            :options="selectedCascaderOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Cascader long values"
          />
        </div>
      </div>
    </section>
  </section>
</template>
<style scoped>
.control-size-comparison,
.control-size-comparison__states {
  display: grid;
  gap: 24px;
}
.control-size-comparison__grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
  align-items: start;
  gap: 24px 16px;
}
.control-size-comparison__grid > div {
  min-width: 0;
}
.control-size-comparison__grid p {
  margin: 0 0 12px;
  font-size: 14px;
  line-height: 20px;
}
.control-size-comparison__grid :deep(.c-input-number),
.control-size-comparison__grid :deep(.c-auto-complete) {
  width: 100%;
}
</style>
```

### 字段外壳与配置边界

`hint` 控制浮动提示（Cedar 默认 false，Maple 默认 true），有 Form 外置标签时不启用。`line` 默认 true；`text-color / focus-color / blur-color` 为可选颜色字符串。`error` 未设置时继承 Form，显式 false 覆盖错误态。TimeRange 的 `separator` 默认 `~`，允许空字符串。默认 variant 保留 Cedar filled、Maple standard，可显式指定同一变体。

字段顶层负责值、默认值、展开、格式、步长、边界、禁用规则和只读/禁用状态。请直接在字段上设置这些属性，不放进 timePickerProps/timeRangePickerProps。嵌套配置只允许对应面板的展示属性；不能通过模型/确认/选择事件替换字段流程。类型会拒绝此类配置，运行时也过滤，且不会把嵌套规则作为顶层未设置时的回退。

Maple 的 pickerProps 可配置 optionHeight/optionCount 等外观，不可替换 columns、fieldNames、选中值、toolbar 或展开状态。popupProps 可设置定位、外观和生命周期回调，但不能设置 open/defaultOpen 或覆盖展开更新事件；顶层 popupContainer（包括 false）优先。纯时间面板内部的嵌套配置遵循相同规则。

Example source: src/time/__demos__/field-appearance.vue

```vue
<script setup>
import { ref } from "vue";

const value = ref("09:00");
const hint = ref(true);
const error = ref(false);
const line = ref(true);
</script>

<template>
  <c-space direction="column" :size="12" style="width: 100%">
    <c-checkbox v-model="hint"> 浮动提示</c-checkbox>
    <c-checkbox v-model="error"> 显式错误状态</c-checkbox>
    <c-checkbox v-model="line"> 边框 / 底线</c-checkbox>
    <c-time
      v-model="value"
      format="HH:mm"
      variant="outline"
      placeholder="请选择时间"
      :hint="hint"
      :error="error"
      :line="line"
      focus-color="#6750a4"
    />
    <span>{{ value }}</span>
  </c-space>
</template>
```

字段交互由本库的一份实例控制器编排：select 暂存草稿，确认时按当前规则校验后提交并通知 Form。清除通过相同提交路径写入 undefined，再通知 clear；只读、禁用或未开启 clearable 时不能清除。只读仍可聚焦，focus/blur 去重；受控关闭请求尚未被接受时，不会重复提交。

### 时间格式与十二小时制

比较分钟、秒和十二小时显示；注意午夜 12 AM 与中午 12 PM 的区别。值格式和步长边界仍独立展示。

<details>
<summary>配置说明与使用限制</summary>

#### 显示格式

未设置 `format` 时默认 `HH:mm:ss`；开启 `use12-hours` 后默认 `hh:mm:ss a`，字段与纯面板一致。显式 `format` 决定字符串值的解析和输出格式，`use12-hours` 还可独立控制面板小时列；建议十二小时格式包含 `a` 或 `A`，以区分上午与下午。

使用方括号包裹固定文字，例如 `[Time] HH:mm`。固定文字不参与时间列识别，不会因为包含 `s` 或 `A` 而额外显示秒或 AM/PM 列。空格式或没有时、分、秒 token 的格式回退到上述默认格式。

</details>

Example source: src/time/__demos__/format-comparison.vue

```vue
<script setup lang="ts">
import { ref } from "vue"
import { proxyRefs as demoProxyRefs } from 'vue'

const scene1 = demoProxyRefs((() => {


const value = ref('09:30')

const valueSeconds = ref('09:30:20')

const literalValue = ref('Time 09:30')
return { value, valueSeconds, literalValue }
})())

const scene2 = demoProxyRefs((() => {

const value = ref('12:00:00 am')

const noon = ref('12:00:00 pm')
return { value, noon }
})())
</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="format">
    <h4><span lang="zh-CN">显示格式</span><span lang="en-US">format</span></h4>
    <c-space direction="column" fill>
        <c-time v-model="scene1.value" format="HH:mm" style="width: 100%; max-width: 320px" />
        <c-time v-model="scene1.valueSeconds" format="HH:mm:ss" style="width: 100%; max-width: 320px" />
        <c-time v-model="scene1.literalValue" format="[Time] HH:mm" style="width: 100%; max-width: 320px" />
      </c-space>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="ampm">
    <h4><span lang="zh-CN">十二小时制</span><span lang="en-US">ampm</span></h4>
    <c-space direction="column" :size="12" style="width: 100%">
        <p>12 AM 是午夜，12 PM 是中午。字段与面板联动展示。</p>
        <c-time v-model="scene2.value" use12-hours  style="width: 100%; max-width: 360px" />
        <c-time v-model="scene2.noon" use12-hours style="width: 100%; max-width: 360px" />
        <c-time-picker v-model="scene2.noon" use12-hours />
        <span>当前值: {{ scene2.value }}</span>
      </c-space>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

## 值模型与选择规则

### 模型类型与固定文字

<!-- demo-config-notes:start -->

#### 本组配置对照

| 配置              | 作用       | 相关示例                                     |
| ----------------- | ---------- | -------------------------------------------- |
| `format`          | 展示格式   | 模型类型与固定文字、独立步长示例、时间上下限 |
| `model-value`     | 绑定值     | 独立步长示例                                 |
| `use12-hours`     | 12 小时制  | 独立步长示例                                 |
| `step`            | 时分秒步长 | 独立步长示例                                 |
| `disable-confirm` | 跳过确认   | 跳过确认                                     |

<!-- demo-config-notes:end -->

字符串按 `format` 严格解析，不接受溢出时间或不匹配的格式；Date 和毫秒时间戳按本地时间反显。提交值始终为格式化字符串（范围为数组）。

Example source: src/time/__demos__/format-model.vue

```vue
<script setup>
import { ref } from 'vue'

const date = new Date(2026, 8, 23, 13, 5, 9)
const timestamp = ref(date.getTime())
const value = ref(date)
const literal = ref('Time 09:30')
</script>

<template>
  <c-space direction="column" fill style="width: 100%">
    <p>Date 和时间戳按本地时间反显；选择后返回格式化字符串。</p>
    <c-time v-model="value" format="hh:mm A" style="width: 100%; max-width: 360px" />
    <span>当前模型: {{ value }}</span>
    <c-time v-model="timestamp" format="HH:mm:ss" style="width: 100%; max-width: 360px" />
    <span>时间戳模型: {{ timestamp }}</span>
    <c-time v-model="literal" format="[Time] HH:mm" style="width: 100%; max-width: 360px" />
    <span>固定文字格式: {{ literal }}</span>
  </c-space>
</template>
```

### 独立步长示例

十二小时显示与5小时步长组合：步长仍以24小时的0点为起点，合法小时为0/5/10/15/20，而不是在中午重新起算。AM候选12/05/10，PM候选03/08；显示为03 PM时提交模型仍为15:30:00（示例format保持HH:mm:ss）。切换规则不改旧09:30:00，取消也不提交候选对齐值；确认合法候选后才写回。可再开启“禁用15点”叠加disabled-hours回调，此时03 PM不可选而08 PM仍对应20点。“父级接受更新”关闭时只记录提议，不改业务值；重新接受后确认才回写。提议次数不是模型接受次数。其他非整除步长和物理触屏仍需单独验收。

With 12-hour display and a 5-hour step, hours remain anchored to midnight: 0/5/10/15/20, not restarted at noon. AM offers 12/05/10 and PM offers 03/08. Selecting 03 PM commits 15:30:00 because this Demo retains HH:mm:ss as its model format. Changing the rules preserves the old 09:30:00; cancellation does not commit aligned candidates. Only confirmation writes the selected value. Enable Disable 15:00 to combine disabled-hours with the step: 03 PM is unavailable while 08 PM still means 20:00. Turning off Accept controlled updates records proposals without changing the business value; re-enable it before confirming an accepted value. Proposal counts are not acceptance counts. Other non-dividing steps and physical touch remain separate coverage.

小时候选以 0 点为起点，十二小时制只改变显示；无效步长回退为 1。

Example source: src/time/__demos__/step.vue

```vue
<script setup>
import { computed, ref } from "vue";
const value = ref("09:30:00");
const coarse = ref(false);
const fiveHours = ref(false);
const blockAfternoon = ref(false);
const accept = ref(true);
const proposals = ref(0);
const disabledHours = () => (blockAfternoon.value ? [15] : []);
function update(next) {
  proposals.value++;
  if (accept.value) value.value = next;
}
const step = computed(() => ({
  hour: fiveHours.value ? 5 : 1,
  minute: coarse.value ? 30 : 15,
  second: 10,
}));
</script>

<template>
  <c-space
    class="time-step-demo"
    direction="column"
    :size="12"
    style="width: 100%"
  >
    <c-checkbox v-model="fiveHours"> 十二小时显示 + 5 小时步长</c-checkbox>
    <c-checkbox v-model="coarse"> 切换为 30 分钟步长</c-checkbox>
    <c-checkbox v-model="blockAfternoon"> 禁用 15 点（03 PM）</c-checkbox>
    <c-checkbox v-model="accept"> 父级接受更新</c-checkbox>
    <p>确认时按当前步长重新校验；切换规则不会自动修改已提交值。</p>
    <c-time
      :model-value="value"
      format="HH:mm:ss"
      :use12-hours="fiveHours"
      :step="step"
      :disabled-hours="disabledHours"
      style="width: 100%; max-width: 360px"
      @update:model-value="update"
    />
    <span>{{ value }}</span>
    <span role="status">提议次数：{{ proposals }}</span>
  </c-space>
</template>
```

### 时间上下限

单值边界示例收紧下限至10:30:40后，字段仍反显已提交的10:30:38，纯面板不能确认。跨到31分钟后显式选择02秒，确认才将字段/模型更新为包含上界10:31:02；字段弹层改秒为00后Escape取消仍保持02。列表保留旧秒草稿时须自行选合法秒，不会把动态规则变化当作自动提交。

In the single-value bounds Demo, tightening the minimum retains committed 10:30:38 and prevents invalid confirmation. Explicitly selecting 10:31:02 and confirming commits the inclusive maximum. Editing the field popup draft to second 00 and canceling preserves second 02. Rule changes alone do not submit a new value.

`min` / `max` 的类型为 `string`，默认不限制；格式固定为 24 小时制 `HH:mm` 或 `HH:mm:ss`，不受 `format` 或 `use12Hours` 影响，包含端点。`HH:mm` 的秒视为 00。范围的两个端点分别校验；`showNextDay` 不把边界变成跨午夜区间。`min > max` 时没有可提交时间。无法解析的边界按未设置处理。

动态修改边界不会改写外部模型。提交须同时满足边界、步长和禁用回调；不显示秒时按秒为 00 校验。列表粗粒度列在整个小时/分钟都越界时禁用，最终确认仍校验完整时间。隐藏禁用项使用 `hide-disabled-options`。

Example source: src/time/__demos__/bounds.vue

```vue
<script setup>
import { ref } from "vue";

const value = ref("10:30:38");
const narrow = ref(false);
</script>

<template>
  <c-space direction="column" :size="12" style="width: 100%">
    <p>
      包含边界：10:30:38–10:31:02。收紧边界不会改写已有模型，但越界值无法确认。
    </p>
    <c-checkbox v-model="narrow"> 将下限调整为 10:30:40</c-checkbox>
    <c-time
      v-model="value"
      format="HH:mm:ss"
      :min="narrow ? '10:30:40' : '10:30:38'"
      max="10:31:02"
    />
    <c-time-picker
      v-model="value"
      format="HH:mm:ss"
      :min="narrow ? '10:30:40' : '10:30:38'"
      max="10:31:02"
    />
    <span>{{ value }}</span>
  </c-space>
</template>
```

### 跳过确认

Example source: src/time/__demos__/no-confirm.vue

```vue
<template>
  <c-time v-model="value" style="width: 200px" disable-confirm />
</template>

<script setup>
import { ref } from 'vue'

const value = ref()
</script>
```

## 输入与状态控制

### 交互状态对比

<!-- demo-config-notes:start -->

#### 本组配置对照

| 配置             | 作用             | 相关示例                                     |
| ---------------- | ---------------- | -------------------------------------------- |
| `format`         | 展示格式         | 交互状态对比、手输与面板选择、默认值与受控值 |
| `readonly`       | 只读             | 交互状态对比、选择与提交、多个字段与浮层切换 |
| `clearable`      | 可清除           | 手输与面板选择、默认值与受控值、选择与提交   |
| `disabled`       | 禁用             | 交互状态对比、选择与提交                     |
| `input-editable` | 允许桌面文本输入 | 手输与面板选择、复制与编辑                   |
| `open`           | 弹层显隐         | 默认值与受控值                               |

<!-- demo-config-notes:end -->

在同一实例上切换禁用、只读和错误状态后再操作控件，比较可编辑性和交互反馈。恢复开关位于目标控件外；错误外观本身不会执行校验。

<details>
<summary>配置说明与使用限制</summary>

#### 交互状态切换

适用于选择时间点。调整禁用、只读、错误反馈，用相同数据观察变化。控制区始终可用，可以随时恢复编辑；错误外观本身不会触发表单校验。

</details>

Example source: src/time/__demos__/state-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref("09:30");
const __demoState = __demoReactive({
  disabled: false,
  readonly: false,
  error: false,
});
</script>
<template>
  <c-space direction="column" :size="16">
    <c-space wrap>
      <c-checkbox v-model="__demoState['disabled']">disabled</c-checkbox>
      <c-checkbox v-model="__demoState['readonly']">readonly</c-checkbox>
      <c-checkbox v-model="__demoState['error']">error</c-checkbox>
    </c-space>
    <c-time v-model="value" format="HH:mm" v-bind="__demoState"></c-time>
  </c-space>
</template>
```

### 手输与面板选择

`inputEditable` 默认为 `true`（Maple 默认为 `false`）。回车或失焦提交，Esc 撤销；格式、步长、边界和禁用规则与面板一致。无效输入或父级拒绝受控更新时回到模型值；切换为不可编辑、只读或禁用会丢弃未提交输入。输入法组合期间不提交。范围两端之间移动焦点不提交。

Example source: src/time/__demos__/text-entry.vue

```vue
<script setup>
import { ref } from "vue";

const value = ref("09:00");
const editable = ref(true);
</script>

<template>
  <c-space direction="column" :size="12" style="width: 100%">
    <c-checkbox v-model="editable"> 允许手输</c-checkbox>
    <p>回车或失焦提交，Esc 撤销。合法范围为 08:00–18:00。</p>
    <c-time
      v-model="value"
      :input-editable="editable"
      format="HH:mm"
      min="08:00"
      max="18:00"
      clearable
    />
    <span>{{ value }}</span>
  </c-space>
</template>
```

### 默认值与受控值

`defaultValue` 初始化字段/纯面板的非受控值，仅读取一次；后续选择保存在各自实例。传入 `modelValue` 后以父级值为准。字段 `defaultOpen` 只初始化一次；受控 `open` 需父级接收 `update:open`，`open-change(open: boolean)` 通知显隐请求。`clear` 不携带参数。纯面板支持 `disabled`，同时禁用范围两端。

Example source: src/time/__demos__/default-state.vue

```vue
<script setup>
import { ref } from "vue";
const value = ref("09:00");
const open = ref(false);
</script>

<template>
  <c-space direction="column" size="12px" style="width: 100%">
    <p>非受控初始值，无需绑定 v-model</p>
    <c-time :default-value="'09:00'" format="HH:mm" clearable />
    <p>受控值与展开状态</p>
    <c-time v-model="value" v-model:open="open" format="HH:mm" clearable />
    <span>{{ value }} / {{ open }}</span>
  </c-space>
</template>
```

### 选择与提交

字段的 `focus` / `blur` 事件均无参数，同一次聚焦或失焦只通知一次；范围两端切换不产生额外整字段事件。只读字段仍可聚焦，但不能展开修改；禁用字段不能聚焦，已聚焦时动态禁用会释放焦点状态并通知失焦。

字段和纯面板提交时按当前格式、步长及禁用规则重新校验；Cedar 手动输入也遵守相同规则。规则变化不会自动改写已提交值。起止端点始终不自动交换；关闭 `show-next-day` 时倒序范围不能提交，开启后允许结束早于开始。清空仍提交 `undefined`，不受候选时间限制，但遵守只读/禁用状态。

`select(value, date)` 表示用户选择草稿，`change(value, date)` 表示提交。单值和范围字段清除均返回 `undefined`，对应 Date 参数也为 `undefined`，`clear` 不带参数。Date 参数是本地时间表示（不自动进行次日日期运算）。字段默认确认后提交；`disable-confirm` 开启后仅有效选择立即提交并请求关闭，不允许次日时的倒序草稿仍不能提交。受控 `open` 仍需父级接受更新。独立纯面板同样默认确认后提交；开启 disable-confirm 后有效选择立即提交，但不会关闭面板。

Example source: src/time/__demos__/selection-events.vue

```vue
<script setup>
import { ref } from "vue";

const value = ref("09:00");
const immediate = ref(false);
const readonly = ref(false);
const disabled = ref(false);
const events = ref([]);
function record(name, value, dates) {
  const times = Array.isArray(dates)
    ? dates.map((date) => date?.toLocaleTimeString())
    : dates?.toLocaleTimeString();
  events.value = [
    JSON.stringify({ event: name, value: value ?? null, time: times ?? null }),
    ...events.value,
  ].slice(0, 5);
}
</script>

<template>
  <c-space direction="column" size="12px" style="width: 100%">
    <c-checkbox v-model="readonly"> 只读：可聚焦，不可修改</c-checkbox>
    <c-checkbox v-model="disabled"> 禁用：释放焦点，不可修改</c-checkbox>
    <c-checkbox v-model="immediate"> 选择后立即提交</c-checkbox>
    <p>select 记录草稿，change 记录提交；取消不改模型，清除返回 undefined。</p>
    <c-time
      v-model="value"
      :disable-confirm="immediate"
      :readonly="readonly"
      :disabled="disabled"
      format="HH:mm"
      clearable
      @select="(value, dates) => record('select', value, dates)"
      @change="(value, dates) => record('change', value, dates)"
      @clear="record('clear')"
      @click="record('click')"
      @open-change="(open) => record('open-change', open)"
      @focus="record('focus')"
      @blur="record('blur')"
    />
    <span>模型: {{ value === undefined ? "undefined" : value }}</span>
    <c-button variant="outline" @click="value = '15:30'"
      >从外部替换模型</c-button
    >
    <small>外部替换会更新反显，不触发 select 或 change。</small>
    <div
      v-for="(event, index) in events"
      :key="index"
      style="overflow-wrap: anywhere"
    >
      {{ event }}
    </div>
  </c-space>
</template>
```

父级直接替换模型会重置草稿，但不会触发 `select` 或 `change`。示例提供“外部更新”按钮，可与用户选择、确认提交分别观察。

字段使用 PickerField → FieldDecorator；面板只负责选择，不注入表单。有效文本在回车或失焦时提交，Escape 或外部关闭丢弃未确认草稿，清除立即提交空值。四类字段的统一示例见 [Date](llms/zh-CN/components/date.md#统一字段与提交)。

### 多个字段与浮层切换

示例分别展示单时间与范围的模型值。取消只丢弃当前字段的草稿，清除只影响当前字段；切换到其他字段不会提交尚未确认的选择。

Example source: src/time/__demos__/multiple-fields.vue

```vue
<script setup>
import { ref } from "vue";
const lastEvent = ref("—");
const readonly = ref(false);
const start = ref("09:00:00");
const end = ref("18:00:00");
const range = ref(["09:00:00", "18:00:00"]);
</script>
<template>
  <c-space direction="column" :size="12" style="width: 100%">
    <c-checkbox v-model="readonly">
      只读字段仍可聚焦，但不能展开修改</c-checkbox
    >
    <c-input placeholder="在这里按 Enter，不会打开时间面板" />
    <small aria-live="polite">{{ lastEvent }}</small>
    <div aria-live="polite">
      <div>开始模型: {{ start ?? "undefined" }}</div>
      <div>结束模型: {{ end ?? "undefined" }}</div>
      <div>范围模型: {{ range ?? "undefined" }}</div>
    </div>
    <p>依次点击各个字段，之前的面板会关闭，不提交未确认草稿。</p>
    <c-time
      v-model="start"
      :readonly="readonly"
      @focus="lastEvent = 'start: focus'"
      @blur="lastEvent = 'start: blur'"
      format="HH:mm:ss"
      placeholder="开始时间"
      style="width: 100%; max-width: 360px"
    />
    <c-time
      v-model="end"
      :readonly="readonly"
      @focus="lastEvent = 'end: focus'"
      @blur="lastEvent = 'end: blur'"
      format="HH:mm:ss"
      placeholder="结束时间"
      style="width: 100%; max-width: 360px"
    />
    <c-time-range
      v-model="range"
      :readonly="readonly"
      @focus="lastEvent = 'range: focus'"
      @blur="lastEvent = 'range: blur'"
      format="HH:mm:ss"
      style="width: 100%; max-width: 360px"
    />
  </c-space>
</template>
```

### 复制与编辑

open-trigger-target="icon" 时，输入区可以编辑或复制，只有右侧选择按钮响应点击打开。关闭手输或搜索后，已有文本仍可复制。

Example source: src/time/__demos__/open-trigger-target.vue

```vue
<template>
  <c-space direction="column">
    <c-radio-group
      v-model="target"
      :options="[
        { label: '整个字段', value: 'field' },
        { label: '仅右侧图标', value: 'icon' },
      ]"
    />
    <label><c-switch v-model="editable" /> 允许编辑 / 搜索</label>
    <c-time
      v-model="value"
      edit-mode="direct"
      :open-trigger-target="target"
      :input-editable="editable"
    />
    <p>关闭编辑后，可以复制已有文本；仅图标模式下编辑不会展开。</p>
  </c-space>
</template>
<script setup lang="ts">
import { ref } from "vue";
const target = ref<"field" | "icon">("icon");
const editable = ref(true);
const value = ref("09:30:00");
</script>
```

### 共享字段加载

`loading` 控制共享字段加载状态；`loading-mode` 为 `default`（指示器）或 `line`（底部不定进度线），默认 `default`。渲染统一由 FieldDecorator 负责，不隐式改变 disabled/readonly；需要禁止编辑时单独设置。

## 阅读方向

继承最近的 `dir="ltr|rtl"`，方向切换不修改时间或提交草稿。小时、分钟、秒等列按阅读顺序排列；左右键沿视觉方向跨列移动焦点。Cedar 的上下键与 Home/End 在当前时间列移动焦点，Enter/Space 选择，禁用项跳过；Maple 滚轮保留上下键和 Home/End 的选值行为。是否即时提交仍由原有确认配置决定。弹层继承字段来源方向。

## API

### 空值识别与阅读空文案

`empty-values` 用于空值识别，`empty-value` 保留原清空输出；`empty-text` 仅在 `read-pretty` 空内容下展示，默认 `'-'`，字段 > FormItem > Form，自定义 read 插槽优先。显式配置 empty-values 后，内置 required 接入该策略，自定义校验仍收到原值。详见[统一说明](llms/zh-CN/guide/empty-values.md)。

| 参数         | 类型               | 缺省与范围                                            |
| ------------ | ------------------ | ----------------------------------------------------- |
| empty-values | readonly unknown[] | 字段 > FormItem > Form > 组件族默认；完整覆盖，不合并 |
| empty-text   | string             | 字段 > FormItem > Form > '-'；显式 '' 有效            |

以上是字段展示层 API；纯面板不因此新增阅读模式。Form 与 FormItem 提供继承配置。empty-value 的现有类型与默认输出仍按该组件原 API 执行。

### 浮层配置与字段通知

`popup-props` 显式配置本地 Trigger 的定位和外观，例如 `{ placement: 'top-start' }`；不能覆盖 open、disabled、trigger 等字段状态或交互。顶层 `popup-container`（包括 false）优先。`input-editable` 默认 true，可关闭桌面文本输入。面板外观使用 `time-picker-props`（支持 class/style），不再从未声明的 attrs 读取面板/浮层参数；id、aria-* 等属性透传给字段。

`click(event)` 只通知非禁用字段的点击；只读字段可通知但不展开。关闭统一监听 `open-change(false)`，它表示关闭请求，受控 open 仍需父级接受。两端不提供字段 close 事件；不要把关闭请求当作值提交。

字段图标插槽为 `suffix-icon`，参数为 `focus: boolean`、`popupOpen: boolean`。实例方法 `focus(index = 0)` 聚焦指定端点而不提交值；`blur()` 失焦并请求关闭。

### Props

| 参数                    | 说明                                                                                   | 类型                                                | 默认值    |
| ----------------------- | -------------------------------------------------------------------------------------- | --------------------------------------------------- | --------- |
| `open-trigger-target`   | 打开面板的点击区域；field 为整个字段，icon 仅右侧选择按钮。不影响键盘展开及受控 open。 | `'field' \| 'icon'`                                 | `'field'` |
| `model-value`           | 绑定值                                                                                 | `string \| number \| Date`                          | `-`       |
| `open`                  | 弹层显隐                                                                               | `boolean`                                           | `-`       |
| `popup-props`           | 本地 Trigger 的展示配置，不控制字段状态                                                | `TimePopupPresentationProps<Partial<TriggerProps>>` | `{}`      |
| `input-editable`        | 允许桌面文本输入                                                                       | `boolean`                                           | `true`    |
| `clearable`             | 可清除                                                                                 | `boolean`                                           | `true`    |
| `disabled`              | 禁用                                                                                   | `boolean`                                           | `false`   |
| `readonly`              | 只读                                                                                   | `boolean`                                           | `false`   |
| `size`                  | 尺寸                                                                                   | `xs \| sm \| md \| lg \| xl`                        | `-`       |
| `variant`               | 输入框变体                                                                             | `filled \| outline \| standard`                     | `filled`  |
| `placeholder`           | 占位                                                                                   | `string`                                            | `-`       |
| `format`                | 展示格式                                                                               | `string`                                            | `-`       |
| `use12-hours`           | 12 小时制                                                                              | `boolean`                                           | `false`   |
| `hide-disabled-options` | 隐藏禁用时间选项                                                                       | `boolean`                                           | `false`   |
| `step`                  | 时分秒步长                                                                             | `object`                                            | `-`       |
| `disable-confirm`       | 跳过确认                                                                               | `boolean`                                           | `false`   |
| `time-picker-props`     | 透传给 TimePicker                                                                      | `object`                                            | `{}`      |

### Form 字段展示与确认

本组件支持 `edit-mode`，字段 > FormItem > Form 逐层继承；未指定时为 `direct`，保留原有交互。支持值：`direct / click / dblclick`。非 direct 编辑模式通过字段值入口打开编辑面板，并维护单份草稿；确认后才更新 v-model，取消、重置或启用 readPretty 时丢弃草稿。

Cedar 使用 edit-mode="click" / "dblclick" 在字段附近打开编辑浮层，Enter/F2 也可进入；取消/Escape 丢弃草稿，确认后提交。readPretty 为独立阅读属性，与 readonly、disabled 分开。

`before-commit(value, { previousValue, signal })` 可拦截弹层保存；FormItem 先校验候选值，失败保持编辑。`open / default-open / update:open` 控制编辑层。`#read="{ value, text }"` 可自定义阅读内容。集中示例见 Form 的“各类字段统一展示”。

日期／时间字段在 inline 下沿用原确认策略；在 click/dblclick 编辑展示中，内部纯面板隐藏确认工具栏，由编辑层提供唯一一组确认／取消。独立 DatePicker、DateRangePicker、TimePicker、TimeRangePicker 保留原有面板 API 和确认行为，不继承 Form 的字段展示。

`read-pretty` 为独立布尔属性，与 `readonly`、`disabled` 同级；字段 > FormItem > Form 继承，显式 `false` 覆盖父级。默认 `false`。纯阅读不显示编辑器。

### 透传配置边界核对（F07）

现有 TimePopupPresentationProps 与运行时过滤保持；open/defaultOpen、disabled、trigger、closeOnClickReference、preventFocus 和对应展开更新归字段管理。顶层 popup-container 明确设置时优先，否则嵌套回退，popupClass 合并内部类。inline 展示层固定 popupOffset=4；Maple 还固定 unmountOnClose=true，这些旧类型中的字段不保证能控制最终值。本轮不收窄既有 Time 类型，也不改变运行行为。

## 配置清空后的值

`empty-value` 指定当前组件已有清空动作的输出；省略时采用该组件默认返回。具体类型以组件 API 为准。它不改变 empty-values 的识别规则，也不改变 Form reset 的初始值。

`empty-value` 可显式设为 `null`（或 `() => null`），清空时原样提交 null；省略时保留组件原默认值。界面把 null 显示为空，不会把普通输入的空字符串自动转成 null。支持弹出编辑的字段中，清空先修改草稿，确认后提交，取消则保留原值。

---

Document: llms/zh-CN/components/timeline.md

<!-- Source: src/timeline/README.md; locale: zh-CN; page: /components/timeline/ -->

# Timeline

按照时间顺序或倒序规则的展示信息内容。

## 基础示例

### 基础用法

基本使用

Example source: src/timeline/__demos__/basic.vue

```vue
<template>
  <div :style="{ marginBottom: '40px' }">
    <c-typography-text :style="{ verticalAlign: 'middle', marginRight: '8px' }"> Reverse </c-typography-text>
    <c-radio-group @change="onChange" :style="{ marginBottom: '30px' }" v-model="isReverse">
      <c-radio :value="false">No Reverse</c-radio>
      <c-radio :value="true">Reverse</c-radio>
    </c-radio-group>
  </div>
  <c-timeline :reverse="isReverse">
    <c-timeline-item label="2017-03-10">The first milestone</c-timeline-item>
    <c-timeline-item label="2018-05-12">The second milestone</c-timeline-item>
    <c-timeline-item label="2020-09-30">The third milestone</c-timeline-item>
  </c-timeline>
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const isReverse = ref(false)

const onChange = (bool) => {
  isReverse.value = bool
}
</script>
```

## 外观与状态

### 自定义轴线样式

自定义轴线的示例。

Example source: src/timeline/__demos__/type.vue

```vue
<template>
  <c-timeline>
    <c-timeline-item label="2017-03-10" lineType="dashed">
      The first milestone
      <br />
      <c-typography-text type="secondary" :style="{ fontSize: '12px', marginTop: '4px' }">
        This is a descriptive message
      </c-typography-text>
    </c-timeline-item>
    <c-timeline-item label="2018-05-12" lineType="dashed">
      The second milestone
      <br />
      <c-typography-text type="secondary" :style="{ fontSize: '12px', marginTop: '4px' }">
        This is a descriptive message
      </c-typography-text>
    </c-timeline-item>
    <c-timeline-item label="2020-09-30" lineType="dashed">
      The third milestone
      <br />
      <c-typography-text type="secondary" :style="{ fontSize: '12px', marginTop: '4px' }">
        This is a descriptive message
      </c-typography-text>
    </c-timeline-item>
  </c-timeline>
</template>

<script lang="ts" setup>
</script>
```

## 布局与排列

### 时间线方向与标签

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `mode` | 时间轴的展示类型：时间轴在左侧，时间轴在右侧, 交替出现。 | 时间线方向与标签 |
| `label-position` | 设置标签文本的位置 | 时间线方向与标签 |
| `orientation` | 时间轴主线的横纵朝向，默认 vertical；约束节点侧别的可用方向 | 时间线方向与标签 |
| `pending` | 是否展示幽灵节点，设置为 true 时候只展示幽灵节点。传入ReactNode时，会作为节点内容展示。 | 时间线方向与标签 |
<!-- demo-config-notes:end -->

比较排列方向、顺序与标签位置；待完成状态和自定义节点不与布局混合。

<details>
<summary>配置说明与使用限制</summary>

#### 纵向时间轴

竖直方向的时间轴。

#### 横向时间轴

可以通过 `orientation` 设置展示横向时间轴

#### 标签文本位置

通过 `labelPosition` 可以设置标签文本的位置。

</details>

Example source: src/timeline/__demos__/layout-comparison.vue

```vue
<script setup lang="ts">
import { ref } from "vue"
import { proxyRefs as demoProxyRefs } from 'vue'

const scene1 = demoProxyRefs((() => {


const mode = ref('left')


const onChange = (_mode) => {
  mode.value = _mode
}
return { mode, onChange }
})())

const scene2 = demoProxyRefs((() => {


const mode = ref('top')


const onChange = (_mode) => {
  mode.value = _mode
}
return { mode, onChange }
})())

const scene3 = demoProxyRefs((() => {


const mode = ref('left')

const pos = ref('same')


const onLabelPositionChange = (_pos) => {
  pos.value = _pos
}


const onModeChange = (_mode) => {
  mode.value = _mode
}
return { mode, pos, onLabelPositionChange, onModeChange }
})())
</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="vertical">
    <h4><span lang="zh-CN">纵向时间轴</span><span lang="en-US">vertical</span></h4>
    <div>
        <c-row align="center" :style="{
      marginBottom: '24px'
    }">
          <c-typography-text>mode: &nbsp; &nbsp;</c-typography-text>
          <c-radio-group @change="scene1.onChange" :modelValue="scene1.mode">
            <c-radio value="left">left</c-radio>
            <c-radio value="right">right</c-radio>
            <c-radio value="alternate">alternate</c-radio>
          </c-radio-group>
        </c-row>
        <c-timeline :mode="scene1.mode" labelPosition="relative">
          <c-timeline-item label="2012-08">
            <c-row :style="{
      display: 'inline-flex',
      alignItems: 'center'
    }">
              <img
                width="40"
                :style="{
      marginRight: '16px',
      marginBottom: '12px'
    }"
                src="https://p1-arco.byteimg.com/tos-cn-i-uwbnlip3yd/b5d834b83708a269b4562924436eac48.png~tplv-uwbnlip3yd-png.png"
              />
              <div :style="{
      marginBottom: '12px'
    }">
                Toutiao
                <div :style="{
      fontSize: '12px',
      color: '#4E5969'
    }">Founded in 2012</div>
              </div>
            </c-row>
          </c-timeline-item>
          <c-timeline-item label="2017-05">
            <c-row :style="{
      display: 'inline-flex',
      alignItems: 'center'
    }">
              <img
                width="40"
                :style="{
      marginRight: '16px',
      marginBottom: '12px'
    }"
                src="https://p1-arco.byteimg.com/tos-cn-i-uwbnlip3yd/385ed540c359ec8a9b9ce2b5fe89b098.png~tplv-uwbnlip3yd-png.png"
              />
              <div :style="{
      marginBottom: '12px'
    }">
                Xigua Video
                <div :style="{
      fontSize: '12px',
      color: '#4E5969'
    }">Founded in 2017</div>
              </div>
            </c-row>
          </c-timeline-item>
          <c-timeline-item label="2018-07">
            <c-row :style="{
      display: 'inline-flex',
      alignItems: 'center'
    }">
              <img
                width="40"
                :style="{
      marginRight: '16px',
      marginBottom: '12px'
    }"
                src="https://p1-arco.byteimg.com/tos-cn-i-uwbnlip3yd/385ed540c359ec8a9b9ce2b5fe89b098.png~tplv-uwbnlip3yd-png.png"
              />
              <div :style="{
      marginBottom: '12px'
    }">
                Pipidance
                <div :style="{
      fontSize: '12px',
      color: '#4E5969'
    }">Founded in 2018</div>
              </div>
            </c-row>
          </c-timeline-item>
        </c-timeline>
      </div>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="direction">
    <h4><span lang="zh-CN">横向时间轴</span><span lang="en-US">direction</span></h4>
    <div>
        <c-row align="center" :style="{
      marginBottom: '24px'
    }">
          <c-typography-text>mode: &nbsp; &nbsp;</c-typography-text>
          <c-radio-group @change="scene2.onChange" :modelValue="scene2.mode">
            <c-radio value="top">top</c-radio>
            <c-radio value="bottom">bottom</c-radio>
            <c-radio value="alternate">alternate</c-radio>
          </c-radio-group>
        </c-row>
        <c-timeline orientation="horizontal" pending :mode="scene2.mode">
          <c-timeline-item label="2012-08">
            <c-row :style="{
      display: 'inline-flex',
      alignItems: 'center'
    }">
              <img
                width="40"
                :style="{
      marginRight: '16px',
      marginBottom: '12px'
    }"
                src="https://p1-arco.byteimg.com/tos-cn-i-uwbnlip3yd/b5d834b83708a269b4562924436eac48.png~tplv-uwbnlip3yd-png.png"
              />
              <div :style="{
      marginBottom: '12px'
    }">
                Toutiao
                <div :style="{
      fontSize: '12px',
      color: '#4E5969'
    }">Founded in 2012</div>
              </div>
            </c-row>
          </c-timeline-item>
          <c-timeline-item label="2017-05">
            <c-row :style="{
      display: 'inline-flex',
      alignItems: 'center'
    }">
              <img
                width="40"
                :style="{
      marginRight: '16px',
      marginBottom: '12px'
    }"
                src="https://p1-arco.byteimg.com/tos-cn-i-uwbnlip3yd/385ed540c359ec8a9b9ce2b5fe89b098.png~tplv-uwbnlip3yd-png.png"
              />
              <div :style="{
      marginBottom: '12px'
    }">
                Xigua Video
                <div :style="{
      fontSize: '12px',
      color: '#4E5969'
    }">Founded in 2017</div>
              </div>
            </c-row>
          </c-timeline-item>
          <c-timeline-item label="2018-07">
            <c-row :style="{
      display: 'inline-flex',
      alignItems: 'center'
    }">
              <img
                width="40"
                :style="{
      marginRight: '16px',
      marginBottom: '12px'
    }"
                src="https://p1-arco.byteimg.com/tos-cn-i-uwbnlip3yd/385ed540c359ec8a9b9ce2b5fe89b098.png~tplv-uwbnlip3yd-png.png"
              />
              <div :style="{
      marginBottom: '12px'
    }">
                Pipidance
                <div :style="{
      fontSize: '12px',
      color: '#4E5969'
    }">Founded in 2018</div>
              </div>
            </c-row>
          </c-timeline-item>
        </c-timeline>
      </div>
  </section>

  <section class="demo-comparison-case demo-comparison-case--3" data-comparison-scene="label">
    <h4><span lang="zh-CN">标签文本位置</span><span lang="en-US">label</span></h4>
    <div>
        <c-row align="center">
          <c-typography-text>labelPosition: &nbsp; &nbsp;</c-typography-text>
          <c-radio-group @change="scene3.onLabelPositionChange" :modelValue="scene3.pos">
            <c-radio value="same">same</c-radio>
            <c-radio value="relative">relative</c-radio>
          </c-radio-group>
        </c-row>
        <c-row align="center" :style="{
      margin: '20px 0px 24px'
    }">
          <c-typography-text>mode: &nbsp; &nbsp;</c-typography-text>
          <c-radio-group @change="scene3.onModeChange" :modelValue="scene3.mode">
            <c-radio value="left">left</c-radio>
            <c-radio value="right">right</c-radio>
            <c-radio value="alternate">alternate</c-radio>
          </c-radio-group>
        </c-row>
        <c-timeline :mode="scene3.mode" :labelPosition="scene3.pos">
          <c-timeline-item label="2017-03-10" dotColor="#52C419"> The first milestone </c-timeline-item>
          <c-timeline-item label="2018-05-12" dotColor="#F5222D" labelPosition="same"> The second milestone </c-timeline-item>
          <c-timeline-item label="2020-09-30" content-placement="bottom"> The third milestone </c-timeline-item>
        </c-timeline>
      </div>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

## 内容与展示

### 幽灵节点

当任务状态正在发生，还在记录过程中，可用幽灵节点来表示当前的时间节点，通过`slot#pending-dot`定制其轴点。
Example source: src/timeline/__demos__/pending.vue

```vue
<template>
  <c-row align="center" :style="{ marginBottom: '24px' }">
    <c-checkbox :checked="!!pendingProps.orientation" @change="(v) => onChange({ orientation: v ? 'horizontal' : '' })">
      horizontal &nbsp; &nbsp;
    </c-checkbox>
    <c-checkbox :checked="!!pendingProps.reverse" @change="(v) => onChange({ reverse: v })">
      reverse &nbsp; &nbsp;
    </c-checkbox>
    <c-checkbox
      :checked="!!pendingProps.pending"
      @change="(v) => onChange({ pending: v ? 'This is a pending dot' : false })"
    >
      pending &nbsp; &nbsp;
    </c-checkbox>
    <c-checkbox :checked="!!pendingProps.hasPendingDot" @change="(v) => onChange({ hasPendingDot: v })">
      custom pendingDot
    </c-checkbox>
  </c-row>
  <c-timeline v-bind="pendingProps">
    <template v-if="pendingProps.hasPendingDot" #dot>
      <c-icon-fire :style="{ color: '#e70a0a' }" />
    </template>
    <c-timeline-item label="2017-03-10" dotColor="#52C419"> The first milestone </c-timeline-item>
    <c-timeline-item label="2018-05-12" dotColor="#F5222D"> The second milestone </c-timeline-item>
    <c-timeline-item label="2020-09-30">The third milestone</c-timeline-item>
  </c-timeline>
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const pendingProps = ref({})

const onChange = (newProps) => {
  pendingProps.value = {
    ...pendingProps.value,
    ...newProps,
  }
}
</script>
```

### 时间轴展示类型

设置 `mode=alternate`时将会交替展示内容。同时可以通过设置 `TimelineItem` 的 `positon`属性控制时间轴节点的位置.

Example source: src/timeline/__demos__/mode.vue

```vue
<template>
  <c-row justify="space-between">
    <c-timeline mode="alternate" :style="{ flex: 1 }">
      <c-timeline-item label="2017-03-10">The first milestone</c-timeline-item>
      <c-timeline-item label="2018-05-12">The second milestone</c-timeline-item>
      <c-timeline-item label="2020-09-30" content-placement="bottom"> The third milestone </c-timeline-item>
    </c-timeline>
    <c-timeline mode="right" :style="{ flex: 1 }">
      <c-timeline-item label="2017-03-10">The first milestone</c-timeline-item>
      <c-timeline-item label="2018-05-12">The second milestone</c-timeline-item>
      <c-timeline-item label="2020-09-30" content-placement="bottom"> The third milestone </c-timeline-item>
    </c-timeline>
  </c-row>
</template>

<script lang="ts" setup>
</script>
```

## 自定义与插槽

### 自定义节点内容

自定义节点内容

Example source: src/timeline/__demos__/icon.vue

```vue
<template>
  <c-timeline>
    <c-timeline-item label="2017-03-10" dotColor="#00B42A"> The first milestone </c-timeline-item>
    <c-timeline-item label="2018-05-22">The second milestone</c-timeline-item>
    <c-timeline-item label="2020-06-22" dotColor="#F53F3F">
      The third milestone
      <c-icon-exclamation-circle-fill :style="{ color: '#F53F3F', fontSize: '12px', marginLeft: '4px' }" />
    </c-timeline-item>
    <c-timeline-item label="2020-09-30" dotColor="#C9CDD4"> The fourth milestone </c-timeline-item>
  </c-timeline>
</template>

<script lang="ts" setup>
</script>
```

### 自定义节点

可以通过属性 `dotColor`, `dotType` 设置节点的颜色以及节点类型。同时可通过 `dot` 直接传入 DOM

Example source: src/timeline/__demos__/dot.vue

```vue
<template>
  <div :style="{ display: 'flex' }">
    <c-timeline :style="{ marginRight: '40px' }">
      <c-timeline-item label="2020-04-12" dotColor="#00B42A"> The first milestone </c-timeline-item>
      <c-timeline-item label="2020-05-17"> The second milestone </c-timeline-item>
      <c-timeline-item label="2020-06-22">
        <template #dot>
          <c-icon-clock-circle :style="{ fontSize: '12px', color: '#F53F3F' }" />
        </template>
        The third milestone
      </c-timeline-item>
      <c-timeline-item label="2020-06-22" dotColor="var(--color-fill-4)"> The third milestone </c-timeline-item>
    </c-timeline>

    <c-timeline :style="{ marginRight: '40px' }">
      <c-timeline-item label="2020-04-12">
        <template #dot>
          <c-icon-check
            :style="{
              fontSize: '12px',
              padding: '2px',
              boxSizing: 'border-box',
              borderRadius: '50%',
              backgroundColor: 'var(--color-primary-light-1)',
            }"
          />
        </template>
        The first milestone
      </c-timeline-item>
      <c-timeline-item label="2020-05-17">
        <template #dot>
          <c-icon-check
            :style="{
              fontSize: '12px',
              padding: '2px',
              boxSizing: 'border-box',
              borderRadius: '50%',
              backgroundColor: 'var(--color-primary-light-1)',
            }"
          />
        </template>
      </c-timeline-item>
      <c-timeline-item label="2020-06-22">The third milestone</c-timeline-item>
      <c-timeline-item label="2020-06-22" dotColor="var(--color-fill-4)"> The third milestone </c-timeline-item>
    </c-timeline>

    <c-timeline>
      <c-timeline-item label="2020-04-12">The first milestone</c-timeline-item>
      <c-timeline-item label="2020-05-17" dotColor="var(--color-fill-4)"> The second milestone </c-timeline-item>
      <c-timeline-item label="2020-06-22" dotColor="var(--color-fill-4)"> The third milestone </c-timeline-item>
    </c-timeline>
  </div>
</template>

<script lang="ts" setup>
</script>
```

### 自定义标签

可以通过 `label` 插槽自定义标签

Example source: src/timeline/__demos__/custom.vue

```vue
<template>
  <c-timeline>
    <c-timeline-item>
      Code Review
      <template #label>
        <c-tag>
          <template #icon>
            <c-icon-check-circle-fill />
          </template>
          Passed
        </c-tag>
      </template>
    </c-timeline-item>
  </c-timeline>
</template>

<script lang="ts" setup>
</script>
```

## API

### `<timeline>` Props

| 参数名         | 描述                                                                                    | 类型                                                    |    默认值    |
| -------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------- | :----------: |
| reverse        | 是否倒序                                                                                | `boolean`                                               |   `false`    |
| orientation      | 时间轴主线的横纵朝向，默认 vertical；约束节点侧别的可用方向 | `'horizontal' \| 'vertical'`                            | `'vertical'` |
| mode           | 时间轴的展示类型：时间轴在左侧，时间轴在右侧, 交替出现。                                | `'left' \| 'right' \| 'top' \| 'bottom' \| 'alternate'` |   `'left'`   |
| pending        | 是否展示幽灵节点，设置为 true 时候只展示幽灵节点。传入ReactNode时，会作为节点内容展示。 | `boolean\|string`                                       |     `-`      |
| label-position | 设置标签文本的位置                                                                      | `'relative' \| 'same'`                                  |   `'same'`   |

### `<timeline>` Slots

| 插槽名 |   描述   | 参数 |
| ------ | :------: | ---- |
| dot    | 幽灵节点 | -    |

### `<timeline-item>` Props

| 参数名     | 描述                         | 类型                              |  默认值   |
| ---------- | ---------------------------- | --------------------------------- | :-------: |
| dot-color  | 节点颜色                     | `string`                          |    `-`    |
| dot-type   | 节点类型：空心圆/实心圆      | `'hollow' \| 'solid'`             | `'solid'` |
| line-type  | 时间轴类型：实线/虚线/点状线 | `'solid' \| 'dashed' \| 'dotted'` | `'solid'` |
| line-color | 时间轴颜色                   | `string`                          |    `-`    |
| label      | 标签文本                     | `string`                          |    `-`    |
| content-placement   | 当前单项在交替模式下相对时间轴的侧别，竖向为 left/right、横向为 top/bottom；受 mode 与 orientation 约束 | `TimelineItemContentPlacement`                    |    `-`    |

### `<timeline-item>` Slots

| 插槽名 |    描述    | 参数 | 版本   |
| ------ | :--------: | ---- | :----- |
| dot    | 自定义节点 | -    |        |
| label  | 自定义标签 | -    | 2.50.0 |

### 类型定义

组件导出以下类型定义

```ts
import type { MentionInstance } from '@cedar-design/ui'
```


## 阅读方向与键盘交互

Timeline 继承容器阅读方向，横向时间轴的节点和连接线随 LTR/RTL 排列。`reverse` 单独控制视觉倒序，切换阅读方向不会修改节点数据或自动切换 `reverse`。

纵向显式 `mode="left"` / `mode="right"` 及子项的物理侧别保持原意；`alternate` 继续在两侧交替。标签和自定义内容正常继承文字方向。

---

Document: llms/zh-CN/components/tooltip.md

<!-- Source: src/tooltip/README.md; locale: zh-CN; page: /components/tooltip/ -->

# Tooltip 文字气泡

用于补充说明按钮、图标或被截断的文字。默认同时响应鼠标悬停和键盘聚焦；需要承载可操作内容时使用 Popover。

## 基础示例

### 基础用法

Example source: src/tooltip/__demos__/basic.vue

```vue
<template>
  <c-space wrap>
    <c-tooltip content="This is tooltip content">
      <c-button>Mouse over to display tooltip</c-button>
    </c-tooltip>
    <c-tooltip content="This is a two-line tooltip content.This is a two-line tooltip content.">
      <c-button>Mouse over to display tooltip</c-button>
    </c-tooltip>
  </c-space>
</template>
<script lang="ts" setup>
</script>
```

## 外观与状态

### 主题色与自定义颜色

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `content` | 提示内容 | 主题色与自定义颜色、外观配置对比 |
| `color` | 自定义背景色 | 主题色与自定义颜色、外观配置对比 |
| `status` | 面板主题 | 主题色与自定义颜色 |
<!-- demo-config-notes:end -->

`status` 表示主题意图；`color` 和 `text-color` 覆盖背景色与文字色。

Example source: src/tooltip/__demos__/status.vue

```vue
<template>
  <c-space wrap>
    <c-tooltip v-for="status in statuses" :key="status" :status="status" :content="status">
      <c-button :status="status === 'default' ? undefined : status">{{ status }}</c-button>
    </c-tooltip>
  </c-space>
</template>

<script setup lang="ts">
import type { TooltipStatus } from '../props'

const statuses: TooltipStatus[] = ['default', 'primary', 'info', 'success', 'warning', 'danger']
</script>
```
Example source: src/tooltip/__demos__/color.vue

```vue
<template>
  <c-space wrap>
    <c-tooltip content="This is tooltip content" color="#3491FA">
      <c-button>#3491FA</c-button>
    </c-tooltip>
    <c-tooltip content="This is tooltip content" color="#165DFF">
      <c-button>#165DFF</c-button>
    </c-tooltip>
    <c-tooltip content="This is tooltip content" color="#722ED1">
      <c-button>#722ED1</c-button>
    </c-tooltip>
  </c-space>
</template>
<script lang="ts" setup>
</script>
```

### 外观配置对比

选择一个对比维度后，同屏展示它的全部可选值；其余配置和内容保持一致。可切换其他配置检查组合效果；输入类预览共享一个值。

<details>
<summary>配置说明与使用限制</summary>

#### 尺寸

Tooltip 只实现 `md` 和 `xs` 两档，默认 `md`。

#### 外观组合

适用于悬浮时的补充说明。调整状态、尺寸，用相同数据观察变化。内容保持一致，便于比较不同设置的实际效果。

</details>

Example source: src/tooltip/__demos__/appearance-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";

const __demoAppearance = __demoReactive({ status: "default", size: "md" });

import { computed as demoComputed, ref as demoRef } from 'vue'
const demoCompareFields = [{"name":"status","values":["default","primary","info","success","warning","danger"]},{"name":"size","values":["xs","md"]}]
const demoCompareAxis = demoRef("status")
const demoComparedOptions = demoComputed(() => demoCompareFields.find(field => field.name === demoCompareAxis.value)?.values ?? [])
</script>
<template>
  <c-space direction="column" :size="16">
    <c-form layout="vertical">
      <c-form-item layout="vertical" size="sm" label="status">
        <c-select
          v-model="__demoAppearance['status']"
          :clearable="false"
          :options="[
            { label: 'default', value: 'default' },
            { label: 'primary', value: 'primary' },
            { label: 'info', value: 'info' },
            { label: 'success', value: 'success' },
            { label: 'warning', value: 'warning' },
            { label: 'danger', value: 'danger' },
          ]"
          aria-label="status"
        />
      </c-form-item>
      <c-form-item layout="vertical" size="sm" label="size">
        <c-radio-group
          v-model="__demoAppearance['size']"
          aria-label="size"
          :options="[
            { label: 'xs', value: 'xs' },
            { label: 'md', value: 'md' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
    </c-form>
    <p class="demo-config-comparison-hint"><span lang="zh-CN">选择一个对比维度；其他配置和内容保持一致。输入类示例共享同一个值，便于比较外观。</span><span lang="en-US">Compare one dimension while keeping the other settings and content identical. Input specimens share the same value.</span></p>
<c-radio-group v-model="demoCompareAxis" aria-label="Compare configuration" :options="demoCompareFields.map(field => ({ label: field.name, value: field.name }))" />
<div class="demo-config-comparison">
<section v-for="sample in demoComparedOptions" :key="String(sample)">
<p><code>{{ demoCompareAxis }}={{ sample }}</code></p>
<c-tooltip
      content="This is tooltip content"
      color="#3491FA"
      v-bind="{ ...__demoAppearance, [demoCompareAxis]: sample }"
    >
      <c-button>#3491FA</c-button>
    </c-tooltip>
</section>
</div>
  </c-space>
</template>

<style scoped>
.demo-config-comparison { display: grid; grid-template-columns: repeat(auto-fit, minmax(min(100%, 220px), 1fr)); gap: 20px; min-width: 0; max-width: 100%; }
.demo-config-comparison > section { min-width: 0; }
.demo-config-comparison p { margin: 0 0 8px; }
html:not([lang='en-US']) .demo-config-comparison-hint > [lang='en-US'],
html[lang='en-US'] .demo-config-comparison-hint > [lang='zh-CN'] { display: none; }
</style>
```

## 布局与排列

### 位置

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `content` | 提示内容 | 位置 |
| `placement` | 浮层相对触发元素的首选方位，默认 top；启用默认的 auto-fit-position 时，空间不足会自动翻转并约束到可视区域，不保证最终停在该侧 | 位置 |
<!-- demo-config-notes:end -->

Example source: src/tooltip/__demos__/placement.vue

```vue
<template>
  <div :style="{ position: 'relative', width: '440px', height: '280px' }">
    <c-tooltip content="This is a Tooltip" placement="top-start">
      <c-button class="button" :style="{ position: 'absolute', top: '0', left: '70px' }">TL</c-button>
    </c-tooltip>
    <c-tooltip content="This is a Tooltip" placement="top">
      <c-button class="button" :style="{ position: 'absolute', top: '0', left: '180px' }">TOP</c-button>
    </c-tooltip>
    <c-tooltip content="This is a Tooltip" placement="top-end">
      <c-button class="button" :style="{ position: 'absolute', top: '0', left: '290px' }">TR</c-button>
    </c-tooltip>
    <c-tooltip content="This is a Tooltip" placement="bottom-start">
      <c-button class="button" :style="{ position: 'absolute', top: '240px', left: '70px' }">BL</c-button>
    </c-tooltip>
    <c-tooltip content="This is a Tooltip" placement="bottom">
      <c-button class="button" :style="{ position: 'absolute', top: '240px', left: '180px' }">BOTTOM</c-button>
    </c-tooltip>
    <c-tooltip content="This is a Tooltip" placement="bottom-end">
      <c-button class="button" :style="{ position: 'absolute', top: '240px', left: '290px' }">BR</c-button>
    </c-tooltip>
    <c-tooltip content="This is a Tooltip" placement="left-start">
      <c-button class="button" :style="{ position: 'absolute', top: '60px', left: '10px' }">LT</c-button>
    </c-tooltip>
    <c-tooltip content="This is a Tooltip" placement="left">
      <c-button class="button" :style="{ position: 'absolute', top: '120px', left: '10px' }">LEFT</c-button>
    </c-tooltip>
    <c-tooltip content="This is a Tooltip" placement="left-end">
      <c-button class="button" :style="{ position: 'absolute', top: '180px', left: '10px' }">LB</c-button>
    </c-tooltip>
    <c-tooltip content="This is a Tooltip" placement="right-start">
      <c-button class="button" :style="{ position: 'absolute', top: '60px', left: '350px' }">RT</c-button>
    </c-tooltip>
    <c-tooltip content="This is a Tooltip" placement="right">
      <c-button class="button" :style="{ position: 'absolute', top: '120px', left: '350px' }">RIGHT</c-button>
    </c-tooltip>
    <c-tooltip content="This is a Tooltip" placement="right-end">
      <c-button class="button" :style="{ position: 'absolute', top: '180px', left: '350px' }">RB</c-button>
    </c-tooltip>
  </div>
</template>
<script lang="ts" setup>
</script>
<style scoped>
.button {
  width: 100px;
}
</style>
```

## 内容与展示

### 指令与文本溢出

Example source: src/tooltip/__demos__/directive.vue

```vue
<template>
  <div :style="{ position: 'relative', width: '440px', height: '280px' }">
    <c-button v-tooltip:top-start="'This is a Tooltip'" :style="{ position: 'absolute', top: '0', left: '70px' }" class="button"
      >TL
    </c-button>
    <c-button
      v-tooltip:top="'This is a Tooltip'"
      :style="{ position: 'absolute', top: '0', left: '180px' }"
      class="button"
      >TOP
    </c-button>
    <c-button v-tooltip:top-end="'This is a Tooltip'" :style="{ position: 'absolute', top: '0', left: '290px' }" class="button"
      >TR
    </c-button>
    <c-button
      v-tooltip:bottom-start="'This is a Tooltip'"
      :style="{ position: 'absolute', top: '240px', left: '70px' }"
      class="button"
      >BL
    </c-button>
    <c-button
      v-tooltip:bottom="'This is a Tooltip'"
      :style="{ position: 'absolute', top: '240px', left: '180px' }"
      class="button"
      >BOTTOM
    </c-button>
    <c-button
      v-tooltip:bottom-end="'This is a Tooltip'"
      :style="{ position: 'absolute', top: '240px', left: '290px' }"
      class="button"
      >BR
    </c-button>
    <c-button
      v-tooltip:left-start="'This is a Tooltip'"
      :style="{ position: 'absolute', top: '60px', left: '10px' }"
      class="button"
      >LT
    </c-button>
    <c-button
      v-tooltip:left="'This is a Tooltip'"
      :style="{ position: 'absolute', top: '120px', left: '10px' }"
      class="button"
      >LEFT
    </c-button>
    <c-button
      v-tooltip:left-end="'This is a Tooltip'"
      :style="{ position: 'absolute', top: '180px', left: '10px' }"
      class="button"
      >LB
    </c-button>
    <c-button
      v-tooltip:right-start="'This is a Tooltip'"
      :style="{ position: 'absolute', top: '60px', left: '350px' }"
      class="button"
      >RT
    </c-button>
    <c-button
      v-tooltip:right="'This is a Tooltip'"
      :style="{ position: 'absolute', top: '120px', left: '350px' }"
      class="button"
      >RIGHT
    </c-button>
    <c-button
      v-tooltip:right-end="'This is a Tooltip'"
      :style="{ position: 'absolute', top: '180px', left: '350px' }"
      class="button"
      >RB
    </c-button>
  </div>
</template>
<script lang="ts" setup>
</script>

<style scoped>
.button {
  width: 100px;
}
</style>
```
Example source: src/tooltip/__demos__/text-ellipsis.vue

```vue
<template>
  <c-space wrap class="Home">
    <div v-tooltip:ellipsis class="text-container">
      相见时难别亦难，东风无力百花残。 春蚕到死丝方尽，蜡炬成灰泪始干。 晓镜但愁云鬓改，夜吟应觉月光寒。
      蓬山此去无多路，青鸟殷勤为探看。
    </div>
    <div v-tooltip:ellipsis class="text-container">没溢出</div>
  </c-space>
</template>
<style scoped>
.text-container {
  width: 100px;
}
</style>
```

## API

Tooltip 继承 Trigger 的定位、容器、受控状态、关闭策略和公开方法。

| 属性 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| content | 提示内容 | `string` | — |
| status | 面板主题 | `default \| primary \| info \| success \| warning \| danger` | `default` |
| size | 尺寸；只实现两档 | `xs \| md` | `md` |
| color | 自定义背景色 | `string` | — |
| text-color | 自定义文字色 | `string` | — |
| trigger | 触发方式 | `TriggerEvent \| TriggerEvent[]` | `['hover', 'focus']` |
| placement | 浮层相对触发元素的首选方位，默认 top；启用默认的 auto-fit-position 时，空间不足会自动翻转并约束到可视区域，不保证最终停在该侧 | `TriggerPlacement` | `top` |
| show-arrow | 是否显示箭头 | `boolean` | `true` |
| popup-offset | 沿方位主轴的距离 | `number` | `10` |
| unmount-on-close | 关闭后卸载内容 | `boolean` | `true` |

事件为 `update:open`、`open-change`、`open`、`opened`、`close`、`closed`、`click-outside`。插槽为 `default` 和 `content`。公开 `open`、`close`、`resize`、`allowClose`、`getReference`、`setReference`、`focusReference`。

Tooltip 内容具有 `role="tooltip"`，打开时会把内容 ID 写入实际触发元素的 `aria-describedby`；关闭、更换外部 reference 或卸载时会清理属性。

## 同源约定

Cedar 与 Maple 独立保存同一份主体、Props、外观映射和结构样式，只允许前缀、本地导入及主题 Token 值不同。不提供 `backgroundColor` 或布尔 `xs` 兼容入口。

## 公开 CSS 变量

以下为实际 :root 默认值。业务定制优先使用组件变量；内部定位变量不属于公开 API。

| 变量 | 默认值 | 意义与场景 |
| --- | --- | --- |
| `--c-tooltip-background` | `var(--c-sys-color-surface-tooltip)` | 内容与箭头背景 |
| `--c-tooltip-text-color` | `var(--c-sys-color-content-on-dark)` | 正文前景 |
| `--c-tooltip-status-primary-background` | `var(--c-sys-color-action-primary)` | primary 状态内容与箭头背景 |
| `--c-tooltip-status-info-background` | `var(--c-sys-color-status-info)` | info 状态内容与箭头背景 |
| `--c-tooltip-status-success-background` | `var(--c-sys-color-status-success)` | success 状态内容与箭头背景 |
| `--c-tooltip-status-warning-background` | `var(--c-sys-color-status-warning)` | warning 状态内容与箭头背景 |
| `--c-tooltip-status-danger-background` | `var(--c-sys-color-status-danger)` | danger 状态内容与箭头背景 |
| `--c-tooltip-status-primary-text-color` | `var(--c-sys-color-content-on-dark)` | primary 状态文字；与对应底色成对设置 |
| `--c-tooltip-status-info-text-color` | `var(--c-sys-color-content-on-dark)` | info 状态文字；与对应底色成对设置 |
| `--c-tooltip-status-success-text-color` | `var(--c-sys-color-content-on-dark)` | success 状态文字；与对应底色成对设置 |
| `--c-tooltip-status-warning-text-color` | `var(--c-sys-color-content-on-dark)` | warning 状态文字；与对应底色成对设置 |
| `--c-tooltip-status-danger-text-color` | `var(--c-sys-color-content-on-dark)` | danger 状态文字；与对应底色成对设置 |
| `--c-tooltip-padding-horizontal` | `var(--c-sys-space-6)` | 内容横向内边距 |
| `--c-tooltip-padding-vertical` | `var(--c-sys-space-4)` | 内容纵向内边距 |
| `--c-tooltip-font-size` | `var(--c-sys-font-size-md)` | 内容字号 |
| `--c-tooltip-line-height` | `var(--c-line-height)` | 内容行高 |
| `--c-tooltip-border-radius` | `var(--c-sys-radius-md)` | 内容圆角 |
| `--c-tooltip-max-width` | `350px` | 提示内容最大宽度 |
| `--c-tooltip-opacity` | `1` | 内容与箭头透明度；改动需重新检查对比度 |
| `--c-tooltip-size-xs-padding-horizontal` | `var(--c-sys-space-4)` | xs 尺寸：内容横向内边距 |
| `--c-tooltip-size-xs-padding-vertical` | `var(--c-sys-space-2)` | xs 尺寸：内容纵向内边距 |
| `--c-tooltip-size-xs-font-size` | `var(--c-sys-font-size-xs)` | xs 尺寸：内容字号 |
| `--c-tooltip-animation-duration` | `var(--c-sys-motion-duration-standard)` | 组件入退场时长；reduced-motion 可覆盖 |

所有内置主题 opacity 为 1。彩色实心状态文字遵循 Button，统一使用 on-dark，明暗模式一致。Maple 暗色保留圆角 4px、字号 14px、纵向／横向内边距 8px／16px。中性表面在明暗模式均保持深色。`color` 同时设置内容与箭头背景，`text-color` 设置文字；显式 content-style／arrow-style 覆盖各自节点。自定义颜色／透明度需重新验证。

使用 Teleport 时，变量需放在实际 popup 的作用域中（例如通过 `popup-style`）；触发按钮上的变量不会自动继承到浮层。

---

Document: llms/zh-CN/components/transfer.md

<!-- Source: src/transfer/README.md; locale: zh-CN; page: /components/transfer/ -->

# Transfer

两栏布局的多选组件。勾选左侧选项后会即时加入右侧，右侧选项可以直接移除。

## 基础示例

### 基础用法

数据穿梭框的基本用法。

Example source: src/transfer/__demos__/basic.vue

```vue
<template>
  <c-transfer :data="data" :default-value="value" />
</template>

<script lang="ts" setup>
const data = Array(8)
  .fill(undefined)
  .map((_, index) => ({
    value: `option${index + 1}`,
    label: `Option ${index + 1}`,
  }))
const value = [{ value: 'option1' }, { value: 'option3' }, { value: 'option5' }]
</script>
```

## 搜索与数据结构

### 搜索

<!-- demo-config-notes:start -->

#### 本组配置对照

| 配置                        | 作用                       | 相关示例                     |
| --------------------------- | -------------------------- | ---------------------------- |
| `data`                      | 穿梭框的数据               | 搜索、分组与拖拽、树型穿梭框 |
| `source-filterable`         | 是否显示源列表搜索框       | 搜索、分组与拖拽             |
| `default-value`             | 非受控状态下的右侧完整状态 | 搜索、树型穿梭框             |
| `source-filter-placeholder` | 源列表搜索框占位文本       | 搜索、分组与拖拽             |
| `target-filterable`         | 是否显示目标列表搜索框     | 搜索                         |
| `target-filter-placeholder` | 目标列表搜索框占位文本     | 搜索                         |

<!-- demo-config-notes:end -->

通过 `source-filterable`、`target-filterable` 分别开启两侧搜索，通过 `filter` 自定义过滤逻辑；也可使用 `show-search` 同时开启两侧搜索。

目标列表筛选后拖拽，只调整可见项在完整目标序列中的位置；隐藏的必选项、暂不在候选数据中的已选项及其自定义元数据都会保留。

Example source: src/transfer/__demos__/search.vue

```vue
<template>
  <c-transfer
    source-filterable
    target-filterable
    :data="data"
    v-model="value"
    target-draggable
    source-filter-placeholder="搜索待选项"
    target-filter-placeholder="搜索已选项"
  />
  <p role="status">当前顺序：{{ value.map(item => item.value).join(' → ') }}</p>
  <p>在已选项搜索 Option 后拖拽，隐藏的必选字段仍保留在完整列表中。</p>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
const data = Array(8)
  .fill(undefined)
  .map((_, index) => ({
    value: `option${index + 1}`,
    label: index === 2 ? '必选字段' : `Option ${index + 1}`,
    required: index === 2,
  }))
const value = ref([{ value: 'option1' }, { value: 'option3' }, { value: 'option5' }])
</script>
```

### 分组与拖拽

选项通过 `group` 分组、`tip` 展示说明。设置 `target-draggable` 后可以拖拽调整右侧顺序；设置
`target-operation="menu"` 后，右侧菜单支持重命名、左右冻结、取消冻结和删除，并可通过
`target-actions` 追加自定义弹窗操作。默认的 `remove` 模式仍显示删除图标。

Example source: src/transfer/__demos__/grouped.vue

```vue
<template>
  <div style="height: 520px">
    <c-transfer
      v-model="value"
      :data="data"
      :target-actions="targetActions"
      source-filterable
      target-draggable
      target-operation="menu"
      source-filter-placeholder="请输入关键词搜索"
      @target-action="handleTargetAction"
    />
  </div>
  <c-dialog v-model:open="customVisible" title="自定义操作" :width="420"> 当前操作项：{{ activeLabel }} </c-dialog>
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const data = [
  { value: 'gunId', label: '枪ID', group: '基本信息', disabled: true, tip: '系统必选字段' },
  { value: 'gunName', label: '枪名称', group: '基本信息' },
  { value: 'company', label: '区域公司区域公司区域公司', group: '基本信息', tip: '所属区域公司' },
  { value: 'deviceId', label: '设备ID', group: '设备信息' },
  { value: 'deviceName', label: '设备名称', group: '设备信息' },
  { value: 'lock', label: '地锁', group: '设备信息' },
  { value: 'workStatus', label: '工作状态', group: '设备信息' },
  { value: 'connectStatus', label: '连接状态', group: '设备信息' },
]

const value = ref([{ value: 'gunId' }, { value: 'gunName' }, { value: 'deviceName' }])
const customVisible = ref(false)
const activeLabel = ref('')
const targetActions = [{ key: 'custom', label: '自定义弹窗' }]

const handleTargetAction = (_key: string, item: (typeof data)[number]) => {
  activeLabel.value = item.label
  customVisible.value = true
}
</script>
```

右侧状态由一个有序对象数组完整表达：

```ts
const value = ref([
  { value: "id", label: "编号", fixed: "left" },
  { value: "name", label: "名称" },
]);
```

### 树型穿梭框

通过穿梭框自定义接口可以实现树型穿梭框。

Example source: src/transfer/__demos__/tree.vue

```vue
<template>
  <c-transfer :data="transferData" :default-value="value">
    <template #source="{ data, selectedKeys, onSelect }">
      <c-tree
        :checkable="true"
        checked-strategy="child"
        :checked-values="selectedKeys"
        :data="getTreeData(data)"
        @check="onSelect"
      />
    </template>
  </c-transfer>
</template>

<script lang="ts" setup>
const treeData = [
  {
    label: 'Trunk 0-0',
    value: '0-0',
    children: [
      {
        label: 'Leaf 0-0-1',
        value: '0-0-1',
      },
      {
        label: 'Branch 0-0-2',
        value: '0-0-2',
        children: [
          {
            label: 'Leaf 0-0-2-1',
            value: '0-0-2-1',
          },
          {
            label: 'Leaf 0-0-2-2',
            value: '0-0-2-2',
          },
        ],
      },
    ],
  },
  {
    label: 'Trunk 0-1',
    value: '0-1',
    children: [
      {
        label: 'Branch 0-1-1',
        value: '0-1-1',
        children: [
          {
            label: 'Leaf 0-1-1-1',
            value: '0-1-1-1',
          },
          {
            label: 'Leaf 0-1-1-2',
            value: '0-1-1-2',
          },
        ],
      },
      {
        label: 'Leaf 0-1-2',
        value: '0-1-2',
      },
    ],
  },
]

const getTransferData = (treeData = [], transferDataSource = []) => {
  treeData.forEach((item) => {
    if (item.children) getTransferData(item.children, transferDataSource)
    else transferDataSource.push({ label: item.label, value: item.value })
  })
  return transferDataSource
}

const getTreeData = (data = []) => {
  const values = data.map((item) => item.value)

  const travel = (_treeData = []) => {
    const treeDataSource = []
    _treeData.forEach((item) => {
      if (item.children || values.includes(item.value)) {
        treeDataSource.push({ label: item.label, value: item.value, children: travel(item.children) })
      }
    })
    return treeDataSource
  }

  return travel(treeData)
}

const transferData = getTransferData(treeData)

const value = [{ value: '0-0-2-1' }]
</script>
```

## 内容定制

### 自定义选项渲染

<!-- demo-config-notes:start -->

#### 本组配置对照

| 配置            | 作用                       | 相关示例                     |
| --------------- | -------------------------- | ---------------------------- |
| `data`          | 穿梭框的数据               | 自定义选项渲染、自定义标题栏 |
| `default-value` | 非受控状态下的右侧完整状态 | 自定义选项渲染、自定义标题栏 |

<!-- demo-config-notes:end -->

通过 `item` 插槽自定义选项的渲染内容。

Example source: src/transfer/__demos__/custom.vue

```vue
<template>
  <c-transfer :data="data" :default-value="value">
    <template #item="{ label }">
      <c-icon-up />
      {{ label }}
    </template>
  </c-transfer>
</template>

<script lang="ts" setup>
const data = Array(8)
  .fill(undefined)
  .map((_, index) => ({
    value: `option${index + 1}`,
    label: `Option ${index + 1}`,
  }))
const value = [{ value: 'option1' }, { value: 'option3' }, { value: 'option5' }]
</script>
```

### 自定义标题栏

通过 `source-title` ,`target-title` 插槽自定义标题栏的渲染内容

Example source: src/transfer/__demos__/custom-header.vue

```vue
<template>
  <c-transfer :data="data" :default-value="value">
    <template #source-title="{ countTotal, countSelected, checked, indeterminate, onSelectAllChange }">
      <div :style="styleHeader">
        Source Title {{ countSelected }}-{{ countTotal }}
        <c-checkbox :model-value="checked" :indeterminate="indeterminate" @change="onSelectAllChange" />
      </div>
    </template>

    <template #target-title="{ countTotal, countSelected, onClear }">
      <div :style="styleHeader">
        Target Title {{ countSelected }}-{{ countTotal }}
        <c-icon-delete @click="onClear" />
      </div>
    </template>
  </c-transfer>
</template>

<script lang="ts" setup>
const data = Array(8)
  .fill(undefined)
  .map((_, index) => ({
    value: `option${index + 1}`,
    label: `Option ${index + 1}`,
  }))
const value = [{ value: 'option1' }, { value: 'option3' }, { value: 'option5' }]

const styleHeader = {
  display: 'flex',
  alignItems: 'center',
  justifyContent: 'space-between',
  paddingRight: '8px',
}
</script>
```

## 大数据

### 大数据

<!-- demo-config-notes:start -->

#### 本组配置对照

| 配置                        | 作用                 | 相关示例 |
| --------------------------- | -------------------- | -------- |
| `data`                      | 穿梭框的数据         | 大数据   |
| `virtual-scroll`            | 是否启用虚拟滚动     | 大数据   |
| `source-filterable`         | 是否显示源列表搜索框 | 大数据   |
| `source-filter-placeholder` | 源列表搜索框占位文本 | 大数据   |

<!-- demo-config-notes:end -->

通过 `virtual-scroll` 开启虚拟滚动，可流畅处理大量选项。

Example source: src/transfer/__demos__/large-data.vue

```vue
<template>
  <c-transfer
    v-model="value"
    :data="data"
    virtual-scroll
    source-filterable
    source-filter-placeholder="搜索 42,000 项"
  />
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const data = Array.from({ length: 42000 }, (_, index) => ({
  value: index,
  label: `Option ${index}`,
  disabled: index % 5 === 0,
}))
const value = ref(Array.from({ length: 50 }, (_, index) => ({ value: index })))
</script>
```

## API

### 空值识别与阅读空文案

`empty-values` 用于空值识别，`empty-value` 保留原清空输出；`empty-text` 仅在 `read-pretty` 空内容下展示，默认 `'-'`，字段 > FormItem > Form，自定义 read 插槽优先。显式配置 empty-values 后，内置 required 接入该策略，自定义校验仍收到原值。详见[统一说明](llms/zh-CN/guide/empty-values.md)。

| 参数         | 类型               | 缺省与范围                                            |
| ------------ | ------------------ | ----------------------------------------------------- |
| empty-values | readonly unknown[] | 字段 > FormItem > Form > 组件族默认；完整覆盖，不合并 |
| empty-text   | string             | 字段 > FormItem > Form > '-'；显式 '' 有效            |

以上是字段展示层 API；纯面板不因此新增阅读模式。Form 与 FormItem 提供继承配置。empty-value 的现有类型与默认输出仍按该组件原 API 执行。

### `<transfer>` Props

| 参数名                    | 描述                             | 类型                                                        |         默认值         |
| ------------------------- | -------------------------------- | ----------------------------------------------------------- | :--------------------: |
| data                      | 穿梭框的数据                     | `TransferItem[]` / `(query, { signal }) => Array / Promise` |      `undefined`       |
| model-value **(v-model)** | 右侧有序完整状态                 | `TransferTargetItem[]`                                      |          `-`           |
| default-value             | 非受控状态下的右侧完整状态       | `TransferTargetItem[]`                                      |          `[]`          |
| disabled                  | 是否禁用                         | `boolean`                                                   |        `false`         |
| virtual-scroll            | 是否启用虚拟滚动                 | `boolean`                                                   |        `false`         |
| target-draggable          | 是否允许拖拽调整右侧顺序         | `boolean`                                                   |        `false`         |
| target-operation          | 右侧操作显示为删除图标或操作菜单 | `'remove' \| 'menu'`                                        |       `'remove'`       |
| clear-text                | 右侧清空按钮文本                 | `string`                                                    |         `清空`         |
| target-actions            | 追加到右侧菜单的自定义操作       | `TransferTargetAction[]`                                    |          `[]`          |
| source-filterable         | 是否显示源列表搜索框             | `boolean`                                                   |        `false`         |
| target-filterable         | 是否显示目标列表搜索框           | `boolean`                                                   |        `false`         |
| show-search               | 是否同时显示两侧搜索框           | `boolean`                                                   |        `false`         |
| filter                    | 自定义过滤函数                   | `TransferFilter`                                            |   标签忽略大小写匹配   |
| source-filter-placeholder | 源列表搜索框占位文本             | `string`                                                    |          `-`           |
| target-filter-placeholder | 目标列表搜索框占位文本           | `string`                                                    |          `-`           |
| show-selected             | 是否在源列表保留已选项           | `boolean`                                                   |         `true`         |
| source-title              | 源列表标题                       | `string`                                                    |          `-`           |
| target-title              | 目标列表标题                     | `string`                                                    |          `-`           |
| show-select-all           | 是否展示全选勾选框               | `boolean`                                                   |         `true`         |
| title                     | 源列表和目标列表标题             | `string[]`                                                  | `['Source', 'Target']` |
| source-search-props       | Cedar Search 的源搜索框配置      | `object`                                                    |          `-`           |
| target-search-props       | Cedar Search 的目标搜索框配置    | `object`                                                    |          `-`           |

### `<transfer>` Events

| 事件名        | 描述                 | 参数                                          |
| ------------- | -------------------- | --------------------------------------------- |
| change        | 右侧状态改变时触发   | value: `TransferTargetItem[]`                 |
| search        | 用户搜索时触发       | value: `string`<br>type: `'target'\|'source'` |
| rename        | 重命名确认时触发     | value: `TransferValue`, label: `string`       |
| target-action | 点击自定义操作时触发 | key: `string`, item: `TransferItem`           |

### `<transfer>` Slots

| 插槽名         |       描述       | 参数                                                                                                                                                                                                  | 版本   |
| -------------- | :--------------: | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----- |
| source         |      源面板      | data: `TransferItem[]`<br>selectedKeys: `string[]`<br>onSelect: `(value: string[]) => void`                                                                                                           | 2.39.0 |
| source-title   |    源标题插槽    | countTotal: `number`<br>countSelected: `number`<br>searchValue: `string`<br>checked: `boolean`<br>indeterminate: `boolean`<br>onSelectAllChange: `(checked:boolean) => void`<br>onClear: `() => void` | 2.45.0 |
| to-target-icon | 移至目标图标插槽 | -                                                                                                                                                                                                     | 2.52.0 |
| to-source-icon |  移至源图标插槽  | -                                                                                                                                                                                                     | 2.52.0 |
| target         |     目标面板     | data: `TransferItem[]`<br>selectedKeys: `string[]`<br>onSelect: `(value: string[]) => void`                                                                                                           | 2.39.0 |
| target-title   |   目标标题插槽   | countTotal: `number`<br>countSelected: `number`<br>searchValue: `string`<br>checked: `boolean`<br>indeterminate: `boolean`<br>onSelectAllChange: `(checked:boolean) => void`<br>onClear: `() => void` | 2.45.0 |
| item           |       选项       | value: `TransferValue`<br>label: `string`<br>item: `TransferItem`                                                                                                                                     |        |

### TransferItem

| 参数名   | 描述                         | 类型                           | 默认值  |
| -------- | ---------------------------- | ------------------------------ | :-----: |
| value    | 选项的值                     | `string \| number`             |   `-`   |
| label    | 选项的标签                   | `string`                       |   `-`   |
| disabled | 是否禁用                     | `boolean`                      | `false` |
| group    | 源列表分组标题               | `string`                       |   `-`   |
| tip      | 选项提示内容                 | `string \| (() => VNodeChild)` |   `-`   |
| required | 是否为必选项，必选项不可删除 | `boolean`                      | `false` |

### 类型定义

组件导出以下类型定义

```ts
import type {
  TransferFilter,
  TransferFixed,
  TransferInstance,
  TransferItem,
  TransferTargetAction,
  TransferTargetItem,
  TransferTargetOperation,
  TransferValue,
} from "@cedar-design/ui";
```

### Form 字段展示与确认

本组件支持 `edit-mode`，字段 > FormItem > Form 逐层继承；未指定时为 `direct`，保留原有交互。支持值：`direct / click / dblclick`。非 direct 编辑模式通过字段值入口打开编辑面板，并维护单份草稿；确认后才更新 v-model，取消、重置或启用 readPretty 时丢弃草稿。

Cedar 使用 edit-mode="click" / "dblclick" 在字段附近打开编辑浮层，Enter/F2 也可进入；取消/Escape 丢弃草稿，确认后提交。readPretty 为独立阅读属性，与 readonly、disabled 分开。

`before-commit(value, { previousValue, signal })` 可拦截弹层保存；FormItem 先校验候选值，失败保持编辑。`open / default-open / update:open` 控制编辑层。`#read="{ value, text }"` 可自定义阅读内容。集中示例见 Form 的“各类字段统一展示”。

`read-pretty` 为独立布尔属性，与 `readonly`、`disabled` 同级；字段 > FormItem > Form 继承，显式 `false` 覆盖父级。默认 `false`。纯阅读不显示编辑器。

候选属性 `data` 支持数组或 `(query, { signal }) => 数组/Promise`。加载、取消、过期结果隔离由组件内部处理，失败触发 load-error。单选/多选分组初始化以空字符串查询，搜索型字段在查询变化时调用；树形字段根数据与原有 load-more 子节点懒加载独立。

## 阅读方向与键盘交互

Transfer 通过候选列表复选框直接维护已选值。候选区位于阅读起点、已选区位于阅读结束侧；RTL 下候选在右、已选在左。标题、搜索、清空与操作按钮间距和拼接圆角随方向调整。

切换方向不会修改 `modelValue`、已选项顺序、搜索条件或冻结状态。列表内上下拖动的顺序语义保持不变。移除按钮可使用键盘操作，必选项和禁用项不会被移除。冻结的 `left/right` 值保持现有业务分组含义，不随阅读方向交换。

---

Document: llms/zh-CN/components/tree-select.md

<!-- Source: src/tree-select/README.md; locale: zh-CN; page: /components/tree-select/ -->

# TreeSelect

多选时，`inline` 下拉只显示选项；已选内容、单项移除和清空由输入框承担。确认式编辑面板保留“已选／清空”，选择为草稿，确认后提交。

可以对树形结构数据进行选择。

## 阅读方向

继承来源 dir；左右键按阅读方向展开、进入子级、返回或折叠，上下键及 Home/End 保持逻辑顺序。搜索使用实际匹配活动项，业务值和多选数组不随 RTL 反转。弹层在自定义挂载容器内也保留来源方向。

## 基础示例

### 基础用法

基础用法。

Example source: src/tree-select/__demos__/basic.vue

```vue
<template>
  <c-space direction="column">
    <c-tree-select v-model="value" :data="data" selectable placeholder="选择部门" />
    <p role="status">当前部门：{{ value || '未选择' }}</p>
  </c-space>
</template>
<script setup lang="ts">
import { ref } from 'vue'
const value = ref<string>()
const data = [
  { value: 'design', label: '设计部' },
  { value: 'engineering', label: '研发部' },
]
</script>
```

## 数据与选项

### 搜索大小写与匹配字段

<!-- demo-config-notes:start -->

#### 本组配置对照

| 配置                 | 作用                   | 相关示例                                         |
| -------------------- | ---------------------- | ------------------------------------------------ |
| `data`               | 树节点数据             | 搜索大小写与匹配字段、选择后保留搜索词是什么意思 |
| `filterable`         | 是否启用搜索           | 搜索大小写与匹配字段、选择后保留搜索词是什么意思 |
| `case-sensitive`     | 内置搜索是否区分大小写 | 搜索大小写与匹配字段                             |
| `multiple`           | 多选                   | 选择后保留搜索词是什么意思                       |
| `retain-input-value` | 选中后保留搜索文本     | 选择后保留搜索词是什么意思                       |

<!-- demo-config-notes:end -->

现在统一默认为 label、不区分大小写。` :search-fields="['value', 'label']"` 同时匹配两字段；字段通过 fieldNames 映射。自定义 filterTreeNode 优先，disableFilter=true 跳过本地筛选。匹配祖先时保留父子树路径，可见节点和键盘候选使用同一规则。

Example source: src/tree-select/__demos__/search-matching.vue

```vue
<script setup lang="ts">
import { computed, ref } from "vue";
const value = ref("");
const mode = ref("label");
const caseSensitive = ref(false);
const modes = [
  { value: "label", label: "默认：只匹配 label" },
  { value: "both", label: "配置：value 或 label" },
];
const options = [
  { value: "USER_A", label: "Apple" },
  { value: "USER_B", label: "Banana" },
];
const searchFields = computed<("label" | "value")[]>(() =>
  mode.value === "both" ? ["value", "label"] : ["label"],
);
</script>
<template>
  <c-space direction="column" align="stretch" fill>
    <c-form-item layout="vertical" size="sm" label="匹配字段">
      <c-radio-group
        v-model="mode"
        aria-label="匹配字段"
        :options="modes"
        variant="button"
        size="sm"
      />
    </c-form-item>
    <c-space
      ><c-switch v-model="caseSensitive" /><span>区分大小写</span></c-space
    >
    <c-tree-select
      v-model="value"
      :data="options"
      :case-sensitive="caseSensitive"
      :search-fields="searchFields"
      filterable
      placeholder="输入 Apple、apple 或 USER_A"
    />
    <p>
      默认搜索 label，不区分大小写；配置两字段后，USER_A 和 Apple
      都能找到同一个选项。
    </p>
  </c-space>
</template>
```

迁移：旧 TreeSelect 的 value + 大小写敏感默认行为，显式设置 `:search-fields="['value']" case-sensitive` 即可恢复。本次默认值变化标记为 major。

### 选择后保留搜索词是什么意思

输入 Al，再点 Alice：两种情况都已经选中 Alice。不开 retain-input-value 时搜索输入清成空字符串；开启后输入框里还保留 Al，方便接着选同样匹配 Al 的 Alan。它不控制选中人员的显示名称，也不负责开启搜索；filterable 才是允许输入搜索词。

Example source: src/tree-select/__demos__/retain-input-value.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const cleared = ref<string[]>([])
const retained = ref<string[]>([])
const clearQuery = ref('')
const retainedQuery = ref('')
const data = [{ key: 'alice', title: 'Alice' }, { key: 'alan', title: 'Alan' }, { key: 'bob', title: 'Bob' }]
</script>
<template>
  <c-space direction="column">
    <p>Type Al and select Alice. Both fields select Alice; only the remaining query text differs.</p>
    <c-tree-select v-model="cleared" v-model:input-value="clearQuery" :data="data" filterable multiple placeholder="Clear query after selecting" />
    <output>Selected: {{ cleared }}; query: {{ JSON.stringify(clearQuery) }}</output>
    <c-tree-select v-model="retained" v-model:input-value="retainedQuery" :data="data" filterable multiple retain-input-value placeholder="Keep query after selecting" />
    <output>Selected: {{ retained }}; query: {{ JSON.stringify(retainedQuery) }}</output>
  </c-space>
</template>
```

候选属性 `data` 支持数组或 `(query, { signal }) => 数组/Promise`。加载、取消、过期结果隔离由组件内部处理，失败触发 load-error。单选/多选分组初始化以空字符串查询，搜索型字段在查询变化时调用；树形字段根数据与原有 load-more 子节点懒加载独立。

## 生命周期与边界

### 透传配置边界与优先级

<!-- demo-config-notes:start -->

#### 本组配置对照

| 配置                  | 作用                                                                                   | 相关示例             |
| --------------------- | -------------------------------------------------------------------------------------- | -------------------- |
| `data`                | 树节点数据                                                                             | 透传配置边界与优先级 |
| `tree-props`          | 传给内部树的配置，选中状态仍由 TreeSelect 管理                                         | 透传配置边界与优先级 |
| `open-trigger-target` | 打开面板的点击区域；field 为整个字段，icon 仅右侧选择按钮。不影响键盘展开及受控 open。 | 复制与编辑           |
| `filterable`          | 是否启用搜索                                                                           | 复制与编辑           |

<!-- demo-config-notes:end -->

建议使用 `TreeSelectTriggerOptions`、`TreeSelectTreeOptions`。Trigger 的 open/defaultOpen、disabled、popupContainer、closeOnClickReference、autoFitTransformOrigin 由 TreeSelect 提供；这里 popup-container 只使用顶层值，没有嵌套容器回退。树的 data、选择/勾选集合、选择模式、fieldNames、加载、搜索、size、checkable/selectable 归顶层管理。Tree 普通配置覆盖默认展示配置，但随后会被顶层的托管字段覆盖；Panel 最后注入 selectedValues/checkedValues 和 disableSelectActionOnly。showLine、展开配置等未托管能力继续有效。通知监听不应代替 TreeSelect 的选择协议，使用顶层组件事件。

本次仅新增可主动选用的专用类型，不收窄已发布的宽属性类型，不增加运行时过滤、不改变覆盖顺序；旧业务写法继续可编译。若直接使用旧宽属性，内部托管字段仍可能通过类型检查，但不代表能控制内部状态。

```ts
import type {
  TreeSelectTreeOptions,
  TreeSelectTriggerOptions,
} from "@cedar-design/ui";
```

Example source: src/tree-select/__demos__/passthrough-options.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import type {
  TreeSelectTriggerOptions,
  TreeSelectTreeOptions,
} from "@cedar-design/ui";
const open = ref(false);
const triggerOptions: TreeSelectTriggerOptions = {
  placement: "top-start",
  popupOffset: 8,
};
const data = [
  {
    value: "fruit",
    label: "水果",
    children: [{ value: "apple", label: "Apple" }],
  },
];
const treeOptions: TreeSelectTreeOptions = {
  showLine: true,
  defaultExpandAll: false,
};
</script>
<template>
  <c-space direction="column" fill>
    <c-button @click="open = !open">{{
      open ? "关闭面板" : "打开面板"
    }}</c-button>
    <c-tree-select
      edit-mode="direct"
      v-model:open="open"
      :data="data"
      :tree-props="treeOptions"
      :trigger-props="triggerOptions"
      aria-label="透传配置示例"
    />
    <p role="status">顶层 open：{{ open }}；嵌套配置：向上展开并调整偏移。</p>
  </c-space>
</template>
```

### 复制与编辑

open-trigger-target="icon" 时，输入区可以编辑或复制，只有右侧选择按钮响应点击打开。关闭手输或搜索后，已有文本仍可复制。

Example source: src/tree-select/__demos__/open-trigger-target.vue

```vue
<template>
  <c-space direction="column">
    <c-radio-group
      v-model="target"
      :options="[
        { label: '整个字段', value: 'field' },
        { label: '仅右侧图标', value: 'icon' },
      ]"
    />
    <label><c-switch v-model="editable" /> 允许编辑 / 搜索</label>
    <c-tree-select
      v-model="value"
      edit-mode="direct"
      :open-trigger-target="target"
      :filterable="editable"
      :options="[
        { value: 'a', label: 'Alpha' },
        { value: 'b', label: 'Beta' },
      ]"
    />
    <p>关闭编辑后，可以复制已有文本；仅图标模式下编辑不会展开。</p>
  </c-space>
</template>
<script setup lang="ts">
import { ref } from "vue";
const target = ref<"field" | "icon">("icon");
const editable = ref(true);
const value = ref("a");
</script>
```

### 共享字段加载

`loading` 控制共享字段加载状态；`loading-mode` 为 `default`（指示器）或 `line`（底部不定进度线），默认 `default`。渲染统一由 FieldDecorator 负责，不隐式改变 disabled/readonly；需要禁止编辑时单独设置。

## API

### 空值识别与阅读空文案

`empty-values` 用于空值识别，`empty-value` 保留原清空输出；`empty-text` 仅在 `read-pretty` 空内容下展示，默认 `'-'`，字段 > FormItem > Form，自定义 read 插槽优先。显式配置 empty-values 后，内置 required 接入该策略，自定义校验仍收到原值。详见[统一说明](llms/zh-CN/guide/empty-values.md)。

| 参数         | 类型               | 缺省与范围                                            |
| ------------ | ------------------ | ----------------------------------------------------- |
| empty-values | readonly unknown[] | 字段 > FormItem > Form > 组件族默认；完整覆盖，不合并 |
| empty-text   | string             | 字段 > FormItem > Form > '-'；显式 '' 有效            |

以上是字段展示层 API；纯面板不因此新增阅读模式。Form 与 FormItem 提供继承配置。empty-value 的现有类型与默认输出仍按该组件原 API 执行。

### TreeSelect Props

| 属性                  | 说明                                                                                   | 类型                                                      | 默认值                |
| --------------------- | -------------------------------------------------------------------------------------- | --------------------------------------------------------- | --------------------- |
| `open-trigger-target` | 打开面板的点击区域；field 为整个字段，icon 仅右侧选择按钮。不影响键盘展开及受控 open。 | `'field' \| 'icon'`                                       | `'field'`             |
| model-value           | 选中业务值                                                                             | string / number / array                                   | undefined             |
| data                  | 树节点数据                                                                             | TreeNodeData[] / `(query, { signal }) => Array / Promise` | `undefined`           |
| multiple              | 多选                                                                                   | boolean                                                   | false                 |
| filterable            | 是否启用搜索                                                                           | boolean                                                   | 单选 false，多选 true |
| retain-input-value    | 选中后保留搜索文本                                                                     | boolean                                                   | false                 |
| case-sensitive        | 内置搜索是否区分大小写                                                                 | boolean                                                   | false                 |
| filter-tree-node      | 自定义节点过滤函数                                                                     | Function                                                  | undefined             |
| tree-props            | 传给内部树的配置，选中状态仍由 TreeSelect 管理                                         | TreeProps                                                 | undefined             |

`disabled`、`readonly` 支持字段显式设置及 Form / FormItem 继承。弹层确认期间不可编辑；校验失败保留草稿，表单重置关闭弹层并丢弃未完成提交。

### TreeSelect Events

| 事件名                                 | 说明             | 参数          |
| -------------------------------------- | ---------------- | ------------- |
| update:modelValue                      | 更新选中业务值   | value         |
| change                                 | 已提交选中值变化 | value         |
| search                                 | 搜索文本变化     | text: string  |
| update:inputValue / input-value-change | 更新输入文本     | text: string  |
| update:open / open-change              | 面板开关变化     | open: boolean |
| clear                                  | 清除选择         | 无            |

### TreeSelect Slots

| 插槽名  | 说明           |
| ------- | -------------- |
| default | 自定义默认内容 |

## 类型定义

组件导出以下类型定义

```ts
import type { TreeSelectProps } from "@cedar-design/ui";
```

### Form 字段展示与确认

Cedar 使用 edit-mode="click" / "dblclick" 在字段附近打开编辑浮层，Enter/F2 也可进入；取消/Escape 丢弃草稿，确认后提交。readPretty 为独立阅读属性，与 readonly、disabled 分开。

### 原位编辑与键盘优先级

`click` / `dblclick` 与 Form 继承同一编辑规则。悬浮或聚焦显示编辑图标，点击图标直接编辑；disabled、readonly、readPretty 不显示编辑入口。面板内点击仅修改草稿。

面板打开时，方向键导航可见且未禁用的节点，左右键展开/收起或移动到子/父节点，Home/End 定位首末节点；Enter 选择/勾选当前节点，不能选择的分支则展开或收起。搜索优先激活匹配节点，多选复用树的勾选规则。Esc 先关闭面板并保留草稿、恢复输入焦点；面板关闭后 Enter 保存字段，Esc 取消编辑。与 AutoComplete、PeopleSelect 的对比示例见 Form 的“各类字段统一展示”。

异步加载同一节点时合并重复展开操作；节点被替换、编辑器关闭或表单重置后，旧请求不再触发展开或勾选。加载完成后，方向键可立即进入新子节点。搜索词或候选变化时先清除旧过滤结果，避免 Enter 选中旧候选；字段确认仍先校验，再执行异步提交。

### 节点字段与业务值

节点默认使用 `{ value, label, children }`，`value` 是全树唯一的字符串或数字（支持 `0`），`label` 是展示内容。后端使用其他字段时可配置 `fieldNames: { value: 'id', label: 'text', children: 'items' }`，无需修改后端数据。声明式组件子项的 `name`、Vue 的 `:key` 和 Table 的 `rowKey` 保持各自含义。

Tree 的独立状态采用 `selectedValues/defaultSelectedValues`、`checkedValues/defaultCheckedValues`、`halfCheckedValues`、`expandedValues/defaultExpandedValues`，分别通过同名具名 v-model 更新；`check` 事件数据中的半选集合为 `halfCheckedValues`。节点内容插槽为 `label`，TreeSelect 对应透传插槽为 `tree-slot-label`。`scrollIntoView({ value })` 按业务值定位；显式 `index` 仍表示虚拟列表从 0 开始的数组下标。

### 搜索开关

统一使用 `filterable` 启用搜索，默认单选 false、多选 true。`retain-input-value` 独立控制选中后是否保留搜索文本，默认 false。

迁移：`allow-search` 改为 `filterable`；原 `{ retainInputValue: true }` 写法改为 `filterable` 加 `retain-input-value`。本次按要求移除旧入口，不保留兼容别名，须以 major 发布。

### 内置搜索字段配置

`searchFields` / `search-fields` 是只读 `('label' | 'value')[]`，默认 `['label']`；多字段为 OR 匹配，大小写默认不敏感。配置 `['value', 'label']` 可同时搜索编码和名称，fieldNames 将语义字段映射到业务字段；空数组对非空查询不匹配任何项。value 采用字符串比较，不做对象深层搜索，对象值或拼音等复杂规则仍用自定义回调。自定义回调优先并自行决定大小写；远程结果使用原有关闭本地过滤协议。Cascader 保留路径语义，会检查路径各节点的配置字段。

## 配置清空后的值

`empty-value` 指定当前组件已有清空动作的输出；省略时采用该组件默认返回。具体类型以组件 API 为准。它不改变 empty-values 的识别规则，也不改变 Form reset 的初始值。

---

Document: llms/zh-CN/components/tree.md

<!-- Source: src/tree/README.md; locale: zh-CN; page: /components/tree/ -->

# Tree

对于文件夹、分类目录、组织架构等层级较多的内容，树可以清楚显示他们的层级关系，并具有展开、收起、选择等交互功能。

## 基础示例

### 基础用法

为每个节点赋予全局唯一的 `value`（必填项），`label` 为该节点显示的内容。

Example source: src/tree/__demos__/basic.vue

```vue
<template>
  <c-tree :data="treeData" :default-expanded-values="['0-0-0']" :default-selected-values="['0-0-0', '0-0-1']" />
</template>

<script lang="ts" setup>
const treeData = [
  {
    label: 'Trunk 0-0',
    value: '0-0',
    children: [
      {
        label: 'Branch 0-0-0',
        value: '0-0-0',
        disabled: true,
        children: [
          {
            label: 'Leaf',
            value: '0-0-0-0',
          },
          {
            label: 'Leaf',
            value: '0-0-0-1',
          },
        ],
      },
      {
        label: 'Branch 0-0-1',
        value: '0-0-1',
        children: [
          {
            label: 'Leaf',
            value: '0-0-1-0',
          },
        ],
      },
    ],
  },
]
</script>
```

## 外观与布局

### 树节点密度与连接线

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `block-node` | 节点是否占据一行 | 树节点密度与连接线 |
| `checkable` | 是否在节点前添加复选框 | 树节点密度与连接线 |
| `size` | 尺寸 | 树节点密度与连接线 |
| `data` | 传入`data`,生成对应的树结构 | 树节点密度与连接线 |
| `default-selected-values` | 默认选中的树节点 | 树节点密度与连接线 |
| `show-line` | 是否展示连接线 | 树节点密度与连接线 |
<!-- demo-config-notes:end -->

比较节点尺寸、整行占位和连接线；选择策略、拖拽与异步子节点保持独立。

<details>
<summary>配置说明与使用限制</summary>

#### 不同尺寸

不同尺寸的树。

#### 节点占一行

节点占据一整行。

#### 显示连接线

为 `Tree` 添加 `showLine` 属性即可使树具有连接线

</details>

Example source: src/tree/__demos__/appearance-comparison.vue

```vue
<script setup lang="ts">
import { ref } from "vue"
import { proxyRefs as demoProxyRefs } from 'vue'

const scene1 = demoProxyRefs((() => {


const size = ref('md')

const treeData = [
  {
    label: 'Trunk 0-0',
    value: '0-0',
    children: [
      {
        label: 'Branch 0-0-0',
        value: '0-0-0',
        children: [
          {
            label: 'Leaf',
            value: '0-0-0-0',
          },
          {
            label: 'Leaf',
            value: '0-0-0-1',
          },
        ],
      },
      {
        label: 'Branch 0-0-1',
        value: '0-0-1',
        children: [
          {
            label: 'Leaf',
            value: '0-0-1-0',
          },
        ],
      },
    ],
  },
]
return { size, treeData }
})())

const scene2 = demoProxyRefs((() => {

const treeData = [
  {
    label: 'Trunk 0-0',
    value: '0-0',
    children: [
      {
        label: 'Branch 0-0-0',
        value: '0-0-0',
        children: [
          {
            label: 'Leaf',
            value: '0-0-0-0',
          },
          {
            label: 'Leaf',
            value: '0-0-0-1',
          },
        ],
      },
      {
        label: 'Branch 0-0-1',
        value: '0-0-1',
        children: [
          {
            label: 'Leaf',
            value: '0-0-1-0',
          },
        ],
      },
    ],
  },
]
return { treeData }
})())

const scene3 = demoProxyRefs((() => {


const showLine = ref(true)

const treeData = [
  {
    label: 'Trunk 1',
    value: '0-0',
    children: [
      {
        label: 'Trunk 1-0',
        value: '0-0-0',
        children: [
          { label: 'leaf', value: '0-0-0-0' },
          {
            label: 'leaf',
            value: '0-0-0-1',
            children: [{ label: 'leaf', value: '0-0-0-1-0' }],
          },
          { label: 'leaf', value: '0-0-0-2' },
        ],
      },
      {
        label: 'Trunk 1-1',
        value: '0-0-1',
      },
      {
        label: 'Trunk 1-2',
        value: '0-0-2',
        children: [
          { label: 'leaf', value: '0-0-2-0' },
          {
            label: 'leaf',
            value: '0-0-2-1',
          },
        ],
      },
    ],
  },
  {
    label: 'Trunk 2',
    value: '0-1',
  },
  {
    label: 'Trunk 3',
    value: '0-2',
    children: [
      {
        label: 'Trunk 3-0',
        value: '0-2-0',
        children: [
          { label: 'leaf', value: '0-2-0-0' },
          { label: 'leaf', value: '0-2-0-1' },
        ],
      },
    ],
  },
]
return { showLine, treeData }
})())
</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="size">
    <h4><span lang="zh-CN">不同尺寸</span><span lang="en-US">size</span></h4>
    <div style="margin-bottom: 20px">
        <c-radio-group v-model="scene1.size" type="button">
          <c-radio value="xs">xs</c-radio>
          <c-radio value="sm">sm</c-radio>
          <c-radio value="md">md</c-radio>
          <c-radio value="lg">lg</c-radio>
          <c-radio value="xl">xl</c-radio>
        </c-radio-group>
      </div>
      <c-tree style="margin-right: 20px" :blockNode="true" :checkable="true" :size="scene1.size" :data="scene1.treeData" />
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="block-node">
    <h4><span lang="zh-CN">节点占一行</span><span lang="en-US">block node</span></h4>
    <c-tree block-node :data="scene2.treeData" />
  </section>

  <section class="demo-comparison-case demo-comparison-case--3" data-comparison-scene="show-line">
    <h4><span lang="zh-CN">显示连接线</span><span lang="en-US">show line</span></h4>
    <div>
        <c-typography-text>showLine</c-typography-text>
        <c-switch v-model="scene3.showLine" style="margin-left: 12px" />
      </div>
      <c-tree :default-selected-values="['0-0-1']" :data="scene3.treeData" :show-line="scene3.showLine" />
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

## 节点选择与状态

### 多选

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `data` | 传入`data`,生成对应的树结构 | 多选、带复选框的树、双向绑定 |
| `checkable` | 是否在节点前添加复选框 | 带复选框的树、双向绑定、设置回填方式 |
| `multiple` | 是否支持多选 | 多选 |
| `check-strictly` | 是否取消父子节点关联 | 带复选框的树 |
| `checked-strategy` | 定制回填方式 <br/> all: 返回所有选中的节点 <br/> parent: 父子节点都选中时只返回父节点 <br/> child: 只返回子节点 | 设置回填方式 |
<!-- demo-config-notes:end -->

`Tree` 设置 `multiple` 属性为`true`，可以启用多选。

Example source: src/tree/__demos__/multiple.vue

```vue
<template>
  <c-checkbox
    style="margin-bottom: 24px"
    v-model="multiple"
    @change="
      () => {
        selectedValues = []
      }
    "
  >
    multiple
  </c-checkbox>
  <br />
  <c-typography-text> Current: {{ selectedValues?.join(' , ') }} </c-typography-text>
  <br />
  <c-tree v-model:selected-values="selectedValues" :multiple="multiple" :data="treeData" />
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const selectedValues = ref([])
const multiple = ref(true)
const treeData = [
  {
    label: 'Trunk 0-0',
    value: '0-0',
    children: [
      {
        label: 'Leaf',
        value: '0-0-1',
      },
      {
        label: 'Branch 0-0-2',
        value: '0-0-2',
        children: [
          {
            label: 'Leaf',
            value: '0-0-2-1',
          },
        ],
      },
    ],
  },
  {
    label: 'Trunk 0-1',
    value: '0-1',
    children: [
      {
        label: 'Branch 0-1-1',
        value: '0-1-1',
        children: [
          {
            label: 'Leaf',
            value: '0-1-1-1',
          },
          {
            label: 'Leaf',
            value: '0-1-1-2',
          },
        ],
      },
      {
        label: 'Leaf',
        value: '0-1-2',
      },
    ],
  },
]
</script>
```

### 带复选框的树

为 `Tree` 添加 `checkable` 属性即可使树具有复选框功能，可以用 `defaultCheckedValues` 指定复选框默认选中的节点。

Example source: src/tree/__demos__/checkable.vue

```vue
<template>
  <c-checkbox
    style="margin-bottom: 24px"
    v-model="checkStrictly"
    @change="
      () => {
        checkedValues = []
      }
    "
  >
    checkStrictly
  </c-checkbox>
  <c-tree :checkable="true" v-model:checked-values="checkedValues" :check-strictly="checkStrictly" :data="treeData" />
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const checkedValues = ref([])
const checkStrictly = ref(false)

const treeData = [
  {
    label: 'Trunk 0-0',
    value: '0-0',
    children: [
      {
        label: 'Leaf',
        value: '0-0-1',
      },
      {
        label: 'Branch 0-0-2',
        value: '0-0-2',
        disabled: true,
        children: [
          {
            label: 'Leaf',
            value: '0-0-2-1',
          },
          {
            label: 'Leaf',
            value: '0-0-2-2',
            disableCheckbox: true,
          },
        ],
      },
    ],
  },
  {
    label: 'Trunk 0-1',
    value: '0-1',
    children: [
      {
        label: 'Branch 0-1-1',
        value: '0-1-1',
        children: [
          {
            label: 'Leaf ',
            value: '0-1-1-1',
          },
          {
            label: 'Leaf ',
            value: '0-1-1-2',
          },
        ],
      },
      {
        label: 'Leaf',
        value: '0-1-2',
      },
    ],
  },
]
</script>
```

### 双向绑定

`selectedValues` 、 `checkedValues` 、 `expandedValues` 属性均可受控，不仅支持 `v-model` ，还可以在对应的 `select` / `check` /
`expand` 事件中自行控制如何更新属性值。

Example source: src/tree/__demos__/control.vue

```vue
<template>
  <c-button-group style="margin-bottom: 20px">
    <c-button status="primary" @click="toggleChecked">
      {{ checkedValues?.length ? 'deselect all' : 'select all' }}
    </c-button>
    <c-button status="primary" @click="toggleExpanded">
      {{ expandedValues?.length ? 'fold' : 'unfold' }}
    </c-button>
  </c-button-group>
  <c-tree
    :checkable="true"
    v-model:selected-values="selectedValues"
    v-model:checked-values="checkedValues"
    v-model:expanded-values="expandedValues"
    @select="onSelect"
    @check="onCheck"
    @expand="onExpand"
    :data="treeData" />
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const allCheckedValues = ['0-0', '0-0-1', '0-0-2', '0-0-2-1', '0-1', '0-1-1', '0-1-2']
const allExpandedValues = ['0-0', '0-1', '0-0-2']
const selectedValues = ref([])
const checkedValues = ref([])
const expandedValues = ref([])

function toggleChecked() {
  checkedValues.value = checkedValues?.value.length ? [] : allCheckedValues
}

function toggleExpanded() {
  expandedValues.value = expandedValues?.value.length ? [] : allExpandedValues
}

function onSelect(newSelectedValues, event) {
  console.log('select: ', newSelectedValues, event)
}

function onCheck(newCheckedValues, event) {
  console.log('check: ', newCheckedValues, event)
}

function onExpand(newExpandedValues, event) {
  console.log('expand: ', newExpandedValues, event)
}

const treeData = [
  {
    label: 'Trunk 0-0',
    value: '0-0',
    children: [
      {
        label: 'Leaf 0-0-1',
        value: '0-0-1',
      },
      {
        label: 'Branch 0-0-2',
        value: '0-0-2',
        children: [
          {
            label: 'Leaf 0-0-2-1',
            value: '0-0-2-1',
          },
        ],
      },
    ],
  },
  {
    label: 'Trunk 0-1',
    value: '0-1',
    children: [
      {
        label: 'Leaf 0-1-1',
        value: '0-1-1',
      },
      {
        label: 'Leaf 0-1-2',
        value: '0-1-2',
      },
    ],
  },
]
</script>
```

### 设置回填方式

为 `Tree` 添加 `checkedStrategy` 可以设置选中时的回填方式

Example source: src/tree/__demos__/checked-strategy.vue

```vue
<template>
  <c-radio-group
    type="button"
    v-model="checkedStrategy"
    @change="
      (value) => {
        checkedValues = []
      }
    "
  >
    <c-radio v-for="item in strategyOptions" :key="item?.value" :value="item?.value">
      {{ item?.label }}
    </c-radio>
  </c-radio-group>
  <br />
  <c-typography-text style="margin: 24px 0; display: inline-block">
    Current: {{ checkedValues?.join(' , ') }}
  </c-typography-text>
  <br />
  <c-tree :checkable="true" v-model:checked-values="checkedValues" :checked-strategy="checkedStrategy" :data="treeData" />
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const checkedValues = ref([])
const checkedStrategy = ref('all')

const treeData = [
  {
    label: 'Trunk 0-0',
    value: '0-0',
    children: [
      {
        label: 'Leaf',
        value: '0-0-1',
      },
      {
        label: 'Branch 0-0-2',
        value: '0-0-2',
        children: [
          {
            label: 'Leaf',
            value: '0-0-2-1',
          },
        ],
      },
    ],
  },
  {
    label: 'Trunk 0-1',
    value: '0-1',
    children: [
      {
        label: 'Branch 0-1-1',
        value: '0-1-1',
        children: [
          {
            label: 'Leaf',
            value: '0-1-1-1',
          },
          {
            label: 'Leaf',
            value: '0-1-1-2',
          },
        ],
      },
      {
        label: 'Leaf',
        value: '0-1-2',
      },
    ],
  },
]

const strategyOptions = [
  {
    value: 'all',
    label: 'show all',
  },
  {
    value: 'parent',
    label: 'show parent',
  },
  {
    value: 'child',
    label: 'show child',
  },
]
</script>
```

## 节点内容定制

### 定制节点图标

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `data` | 传入`data`,生成对应的树结构 | 定制节点图标、定制组件图标、定制额外节点 |
| `show-line` | 是否展示连接线 | 定制组件图标 |
| `block-node` | 节点是否占据一行 | 定制额外节点 |
| `checkable` | 是否在节点前添加复选框 | 定制额外节点 |
| `selectable` | 是否支持选择 | 定制额外节点 |
| `check-strictly` | 是否取消父子节点关联 | 定制额外节点 |
<!-- demo-config-notes:end -->

节点图标可以通过 `tree` 的 `icon` 插槽全局指定，也可以通过节点的 `icon` 属性单独指定。

Example source: src/tree/__demos__/node-icon.vue

```vue
<template>
  <c-tree :data="treeData">
    <template #icon>
      <c-icon-star />
    </template>
  </c-tree>
</template>

<script lang="ts" setup>
import { IconDriveFile } from '@cedar-design/icons-vue'
import { h } from 'vue'

const treeData = [
  {
    label: 'Trunk',
    value: 'node1',
    children: [
      {
        label: 'Leaf',
        value: 'node2',
      },
    ],
  },
  {
    label: 'Trunk',
    value: 'node3',
    children: [
      {
        label: 'Leaf',
        value: 'node4',
        icon: () => h(IconDriveFile),
      },
      {
        label: 'Leaf',
        value: 'node5',
        icon: () => h(IconDriveFile),
      },
    ],
  },
]
</script>
```

### 定制组件图标

节点的图标 `loadingIcon`, `switcherIcon`，同时支持在 `tree` 和 `node` 两个纬度上定制，其中 `node` 的优先级较高。

Example source: src/tree/__demos__/icons.vue

```vue
<template>
  <c-tree :data="treeData" show-line>
    <template #switcher-icon="{ children }">
      <c-icon-down v-if="children?.length" />
      <c-icon-star v-else />
    </template>
  </c-tree>
</template>

<script lang="ts" setup>
import { IconDriveFile } from '@cedar-design/icons-vue'
import { h } from 'vue'

const treeData = [
  {
    label: 'Trunk',
    value: 'node1',
    children: [
      {
        label: 'Leaf',
        value: 'node2',
      },
    ],
  },
  {
    label: 'Trunk',
    value: 'node3',
    children: [
      {
        label: 'Leaf',
        value: 'node4',
        switcherIcon: () => h(IconDriveFile),
      },
      {
        label: 'Leaf',
        value: 'node5',
        switcherIcon: () => h(IconDriveFile),
      },
    ],
  },
]
</script>
```

### 定制额外节点

`Tree` 提供了名为 `extra` 的 `Slot`, 可以在节点上定制额外的内容。

Example source: src/tree/__demos__/render-extra.vue

```vue
<template>
  <div style="width: 500px; padding: 2px; overflow: auto">
    <c-space wrap>
      <c-checkbox v-model="leafChecksOnly">Leaf checkboxes only</c-checkbox>
      <c-checkbox v-model="leafSelectionOnly">Leaf selection only</c-checkbox>
      <c-checkbox v-model="strict">Strict checks</c-checkbox>
      <c-tag>Checked: {{ checkedValues.join(', ') || '-' }}</c-tag>
      <c-tag>Selected: {{ selectedValues.join(', ') || '-' }}</c-tag>
    </c-space>
    <c-tree
      :block-node="true"
      :checkable="leafChecksOnly ? isLeafNode : true"
      :selectable="leafSelectionOnly ? isLeafNode : true"
      :check-strictly="strict"
      :data="treeData"
      @check="keys => checkedValues = keys"
      @select="keys => selectedValues = keys"
    >
      <template #extra="nodeData">
        <c-button
          variant="text"
          size="xs"
          :aria-label="'Add child to ' + nodeData.title + ' (' + nodeData.key + ')'"
          style="position: absolute; right: 8px; top: 2px"
          @click.stop="onIconClick(nodeData)"
        >
          <template #icon><c-icon-plus /></template>
        </c-button>
      </template>
    </c-tree>
  </div>
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const leafChecksOnly = ref(false)
const leafSelectionOnly = ref(false)
const strict = ref(false)
const checkedValues = ref<(string | number)[]>([])
const selectedValues = ref<(string | number)[]>([])
const isLeafNode = (_node: unknown, info: { isLeaf: boolean }) => info.isLeaf

function onIconClick(nodeData) {
  const children = nodeData.children || []
  children.push({
    label: 'new tree node',
    value: nodeData.key + '-' + (children.length + 1),
  })
  nodeData.children = children

  treeData.value = [...treeData.value]
}

const treeData = ref([
  {
    label: 'Trunk',
    value: '0-0',
    children: [
      {
        label: 'Leaf',
        value: '0-0-1',
      },
      {
        label: 'Branch',
        value: '0-0-2',
        children: [
          {
            label: 'Leaf',
            value: '0-0-2-1',
          },
        ],
      },
    ],
  },
  {
    label: 'Trunk',
    value: '0-1',
    children: [
      {
        label: 'Branch',
        value: '0-1-1',
        children: [
          {
            label: 'Leaf',
            value: '0-1-1-1',
          },
          {
            label: 'Leaf',
            value: '0-1-1-2',
          },
        ],
      },
      {
        label: 'Leaf',
        value: '0-1-2',
      },
    ],
  },
])
</script>
```

### 自定义 data 的字段名称

通过 `fieldNames` 字段可以自定义 data 的字段名。

Example source: src/tree/__demos__/field-names.vue

```vue
<template>
  <c-tree
    :default-selected-values="['0-0-2-1-0-0']"
    :fieldNames="{
      value: 'value',
      label: 'label',
      children: 'items',
      icon: 'customIcon',
    }"
    :data="treeData" />
</template>

<script lang="ts" setup>
import { IconDriveFile, IconStar } from '@cedar-design/icons-vue'
import { h } from 'vue'

const treeData = [
  {
    label: 'Trunk 0-0',
    value: '0-0',
    items: [
      {
        label: 'Branch 0-0-2',
        value: '0-0-2',
        selectable: false,
        customIcon: () => h(IconDriveFile),
        items: [
          {
            label: 'Leaf',
            value: '0-0-2-1',
            items: [
              {
                label: 'Leaf 0-0-2',
                value: '0-0-2-1-0',
                items: [
                  {
                    label: 'Leaf',
                    customIcon: () => h(IconStar),
                    value: '0-0-2-1-0-0',
                  },
                ],
              },
            ],
          },
        ],
      },
    ],
  },
  {
    label: 'Trunk 0-1',
    value: '0-1',
    items: [
      {
        label: 'Branch 0-1-1',
        value: '0-1-1',
        items: [
          {
            label: 'Leaf',
            value: '0-1-1-0',
          },
        ],
      },
    ],
  },
]
</script>
```

## 搜索与拖拽

### 搜索树

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `data` | 传入`data`,生成对应的树结构 | 搜索树、拖拽 |
| `draggable` | 是否可以拖拽 | 拖拽 |
| `block-node` | 节点是否占据一行 | 拖拽 |
| `checkable` | 是否在节点前添加复选框 | 拖拽 |
<!-- demo-config-notes:end -->

展示如何实现搜索树的效果。

Example source: src/tree/__demos__/search.vue

```vue
<template>
  <div>
    <c-search style="margin-bottom: 8px; max-width: 240px" v-model="searchKey" />
    <c-tree :data="treeData">
      <template #label="nodeData">
        <template v-if="(index = getMatchIndex(nodeData?.title)) < 0">
          {{ nodeData?.title }}
        </template>
        <span v-else>
          {{ nodeData?.label?.substr(0, index) }}
          <span style="color: var(--color-primary-light-4)">
            {{ nodeData?.label?.substr(index, searchKey.length) }} </span
          >{{ nodeData?.label?.substr(index + searchKey.length) }}
        </span>
      </template>
    </c-tree>
  </div>
</template>

<script lang="ts" setup>
import { computed, ref } from 'vue'

let index

const originTreeData = [
  {
    label: 'Trunk 0-0',
    value: '0-0',
    children: [
      {
        label: 'Branch 0-0-1',
        value: '0-0-1',
        children: [
          {
            label: 'Leaf 0-0-1-1',
            value: '0-0-1-1',
          },
          {
            label: 'Leaf 0-0-1-2',
            value: '0-0-1-2',
          },
        ],
      },
    ],
  },
  {
    label: 'Trunk 0-1',
    value: '0-1',
    children: [
      {
        label: 'Branch 0-1-1',
        value: '0-1-1',
        children: [
          {
            label: 'Leaf 0-1-1-0',
            value: '0-1-1-0',
          },
        ],
      },
      {
        label: 'Branch 0-1-2',
        value: '0-1-2',
        children: [
          {
            label: 'Leaf 0-1-2-0',
            value: '0-1-2-0',
          },
        ],
      },
    ],
  },
]
const searchKey = ref('')
const treeData = computed(() => {
  if (!searchKey.value) return originTreeData
  return searchData(searchKey.value)
})

function searchData(keyword) {
  const loop = (data) => {
    const result = []
    data.forEach((item) => {
      if (item.title.toLowerCase().indexOf(keyword.toLowerCase()) > -1) {
        result.push({ ...item })
      } else if (item.children) {
        const filterData = loop(item.children)
        if (filterData.length) {
          result.push({
            ...item,
            children: filterData,
          })
        }
      }
    })
    return result
  }

  return loop(originTreeData)
}

function getMatchIndex(title) {
  if (!searchKey.value) return -1
  return title.toLowerCase().indexOf(searchKey.value.toLowerCase())
}
</script>
```

### 拖拽

可拖拽的树节点。

Example source: src/tree/__demos__/draggable.vue

```vue
<template>
  <c-checkbox v-model="checked" style="margin-bottom: 20px"> checkable </c-checkbox>
  <c-tree class="tree-demo" draggable blockNode :checkable="checked" :data="treeData" @drop="onDrop" />
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const defaultTreeData = [
  {
    label: 'Trunk 0-0',
    value: '0-0',
    children: [
      {
        label: 'Leaf 0-0-1',
        value: '0-0-1',
      },
      {
        label: 'Branch 0-0-2',
        value: '0-0-2',
        disableCheckbox: true,
        children: [
          {
            draggable: false,
            label: 'Leaf 0-0-2-1 (Drag disabled)',
            value: '0-0-2-1',
          },
        ],
      },
    ],
  },
  {
    label: 'Trunk 0-1',
    value: '0-1',
    children: [
      {
        label: 'Branch 0-1-1',
        value: '0-1-1',
        checkable: false,
        children: [
          {
            label: 'Leaf 0-1-1-1',
            value: '0-1-1-1',
          },
          {
            label: 'Leaf 0-1-1-2',
            value: '0-1-1-2',
          },
        ],
      },
      {
        label: 'Leaf 0-1-2',
        value: '0-1-2',
      },
    ],
  },
]

const treeData = ref(defaultTreeData)
const checkedValues = ref([])
const checked = ref(false)

function onDrop({ dragNode, dropNode, dropPosition }) {
  const data = treeData.value
  const loop = (data, key, callback) => {
    data.some((item, index, arr) => {
      if (item.key === key) {
        callback(item, index, arr)
        return true
      }
      if (item.children) {
        return loop(item.children, key, callback)
      }
      return false
    })
  }

  loop(data, dragNode.key, (_, index, arr) => {
    arr.splice(index, 1)
  })

  if (dropPosition === 0) {
    loop(data, dropNode.key, (item) => {
      item.children = item.children || []
      item.children.push(dragNode)
    })
  } else {
    loop(data, dropNode.key, (_, index, arr) => {
      arr.splice(dropPosition < 0 ? index : index + 1, 0, dragNode)
    })
  }
}
</script>
```

## 异步与虚拟滚动

### 动态加载

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `data` | 传入`data`,生成对应的树结构 | 动态加载、虚拟列表 |
| `load-more` | 异步加载数据的回调，返回一个 `Promise` | 动态加载 |
| `block-node` | 节点是否占据一行 | 虚拟列表 |
| `checkable` | 是否在节点前添加复选框 | 虚拟列表 |
| `virtual-list-props` | 传递虚拟列表属性，传入此参数以开启虚拟滚动，[VirtualListProps](#VirtualListProps) | 虚拟列表 |
<!-- demo-config-notes:end -->

动态加载节点。

Example source: src/tree/__demos__/load-more.vue

```vue
<template>
  <c-tree :data="treeData" :load-more="loadMore" />
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const treeData = ref([
  {
    label: 'Trunk 0-0',
    value: '0-0',
  },
  {
    label: 'Trunk 0-1',
    value: '0-1',
    children: [
      {
        label: 'Branch 0-1-1',
        value: '0-1-1',
      },
    ],
  },
])

const loadMore = (nodeData) => {
  return new Promise((resolve) => {
    setTimeout(() => {
      nodeData.children = [{ label: `leaf`, value: `${nodeData.key}-1`, isLeaf: true }]
      resolve()
    }, 1000)
  })
}
</script>
```

### 虚拟列表

通过指定 `virtualListProps` 来开启虚拟列表，在大量数据时获得高性能表现。

Example source: src/tree/__demos__/virtual.vue

```vue
<template>
  <c-button status="primary" :style="{ marginBottom: '20px' }" @click="scrollIntoView">
    Scroll to 0-0-2-2, i.e. the 26th.
  </c-button>
  <c-tree
    ref="treeRef"
    blockNode
    checkable
    :data="treeData"
    :virtualListProps="{
      height: 200,
    }" />
</template>

<script lang="ts" setup>
import { ref } from 'vue'

function loop(path = '0', level = 2) {
  const list = []
  for (let i = 0; i < 10; i += 1) {
    const key = `${path}-${i}`
    const treeNode: {
      label: string
      value: string
      children?: ReturnType<typeof loop>
    } = {
      label: key,
      key,
    }

    if (level > 0) {
      treeNode.children = loop(key, level - 1)
    }

    list.push(treeNode)
  }
  return list
}

const treeRef = ref()
const treeData = loop()
const scrollIntoView = () => {
  treeRef.value && treeRef.value.scrollIntoView({ value: '0-0-2-2' })
}
</script>
```

## API

### `<tree>` Props

| 参数名                          | 描述                                                                                                            | 类型                                                                                                           | 默认值  |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | :-----: |
| size                            | 尺寸                                                                                                            | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'`                                                                         | `'md'`  |
| block-node                      | 节点是否占据一行                                                                                                | `boolean`                                                                                                      | `false` |
| default-expand-all              | 是否默认展开父节点                                                                                              | `boolean`                                                                                                      | `true`  |
| multiple                        | 是否支持多选                                                                                                    | `boolean`                                                                                                      | `false` |
| checkable                       | 是否在节点前添加复选框                                                                                          | `boolean\| ((    node: TreeNodeData,    info: {      level: number;      isLeaf: boolean;    }  ) => boolean)` | `false` |
| selectable                      | 是否支持选择                                                                                                    | `boolean\| ((    node: TreeNodeData,    info: {      level: number;      isLeaf: boolean;    }  ) => boolean)` | `true`  |
| check-strictly                  | 是否取消父子节点关联                                                                                            | `boolean`                                                                                                      | `false` |
| checked-strategy                | 定制回填方式 <br/> all: 返回所有选中的节点 <br/> parent: 父子节点都选中时只返回父节点 <br/> child: 只返回子节点 | `'all' \| 'parent' \| 'child'`                                                                                 | `'all'` |
| default-selected-values           | 默认选中的树节点                                                                                                | `Array<string \| number>`                                                                                      |   `-`   |
| selected-values **(v-model)**     | 选中的树节点                                                                                                    | `Array<string \| number>`                                                                                      |   `-`   |
| default-checked-values            | 默认选中复选框的树节点                                                                                          | `Array<string \| number>`                                                                                      |   `-`   |
| checked-values **(v-model)**      | 选中复选框的树节点                                                                                              | `Array<string \| number>`                                                                                      |   `-`   |
| default-expanded-values           | 默认展开的节点                                                                                                  | `Array<string \| number>`                                                                                      |   `-`   |
| expanded-values **(v-model)**     | 展开的节点                                                                                                      | `Array<string \| number>`                                                                                      |   `-`   |
| data                            | 传入`data`,生成对应的树结构                                                                                     | `TreeNodeData[]`                                                                                               |  `[]`   |
| field-names                     | 指定节点数据中的字段名                                                                                          | `TreeFieldNames`                                                                                               |   `-`   |
| show-line                       | 是否展示连接线                                                                                                  | `boolean`                                                                                                      | `false` |
| load-more                       | 异步加载数据的回调，返回一个 `Promise`                                                                          | `(node: TreeNodeData) => Promise<void>`                                                                        |   `-`   |
| draggable                       | 是否可以拖拽                                                                                                    | `boolean`                                                                                                      | `false` |
| allow-drop                      | 拖拽时是否允许在某节点上释放                                                                                    | `(options: {  dropNode: TreeNodeData;  dropPosition: -1 \| 0 \| 1;}) => boolean`                               |   `-`   |
| virtual-list-props              | 传递虚拟列表属性，传入此参数以开启虚拟滚动，[VirtualListProps](#VirtualListProps)                               | `VirtualListProps`                                                                                             |   `-`   |
| default-expand-selected         | 是否默认展开已选中节点的父节点                                                                                  | `boolean`                                                                                                      | `false` |
| default-expand-checked          | 是否默认展开已选中复选框节点的父节点                                                                            | `boolean`                                                                                                      | `false` |
| auto-expand-parent              | 是否自动展开已展开节点的父节点                                                                                  | `boolean`                                                                                                      | `true`  |
| half-checked-values **(v-model)** | 半选状态的节点.仅在 checkable 且 checkStrictly 时生效                                                           | `Array<string \| number>`                                                                                      |   `-`   |
| only-check-leaf                 | 开启后 checkedValues 只处理叶子节点，父节点状态由子节点决定（仅在 checkable 且 checkStrictly 为 false 时生效）    | `boolean`                                                                                                      | `false` |
| animation                       | 是否开启展开时的过渡动效                                                                                        | `boolean`                                                                                                      | `true`  |
| action-on-node-click            | 点击节点的时候触发的动作                                                                                        | `'expand'`                                                                                                     |   `-`   |

### `<tree>` Events

| 事件名     | 描述                                                                                   | 参数                                                                                                                                                                                                            |
| ---------- | -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| select     | 点击树节点时触发                                                                       | selectedValues: `Array<string \| number>`<br>data: `{ selected?: boolean; selectedNodes: TreeNodeData[]; node?: TreeNodeData; e?: Event; }`                                                                       |
| check      | 点击树节点复选框时触发。`halfCheckedValues` 和 `halfCheckedNodes` 从 `2.19.0` 开始支持。 | checkedValues: `Array<string \| number>`<br>data: `{ checked?: boolean; checkedNodes: TreeNodeData[]; node?: TreeNodeData; e?: Event; halfCheckedValues: (string \| number)[]; halfCheckedNodes: TreeNodeData[]; }` |
| expand     | 展开/关闭                                                                              | expandKeys: `Array<string \| number>`<br>data: `{ expanded?: boolean; expandNodes: TreeNodeData[]; node?: TreeNodeData; e?: Event; }`                                                                           |
| drag-start | 节点开始拖拽                                                                           | ev: `DragEvent`<br>node: `TreeNodeData`                                                                                                                                                                         |
| drag-end   | 节点结束拖拽                                                                           | ev: `DragEvent`<br>node: `TreeNodeData`                                                                                                                                                                         |
| drag-over  | 节点被拖拽至可释放目标                                                                 | ev: `DragEvent`<br>node: `TreeNodeData`                                                                                                                                                                         |
| drag-leave | 节点离开可释放目标                                                                     | ev: `DragEvent`<br>node: `TreeNodeData`                                                                                                                                                                         |
| drop       | 节点在可释放目标上释放                                                                 | data: `{ e: DragEvent; dragNode: TreeNodeData; dropNode: TreeNodeData; dropPosition: number; }`                                                                                                                 |

### `<tree>` Methods

| 方法名              | 描述                                                                     | 参数                                                                                     | 返回值         |
| ------------------- | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- | -------------- |
| scrollIntoView      | 虚拟列表滚动某个元素                                                     | options: `{ index?: number; value?: number \| string; align: 'auto' \| 'top' \| 'bottom'}` | -              |
| getSelectedNodes    | 获取选中的节点                                                           | -                                                                                        | TreeNodeData[] |
| getCheckedNodes     | 获取选中复选框的节点。支持传入 `checkedStrategy`，没有传则取组件的配置。 | options: `checkedStrategy?: 'all' \| 'parent' \| 'child'; includeHalfChecked?: boolean;` | TreeNodeData[] |
| getHalfCheckedNodes | 获取复选框半选的节点                                                     | -                                                                                        | TreeNodeData[] |
| getExpandedNodes    | 获取展开的节点                                                           | -                                                                                        | TreeNodeData[] |
| checkAll            | 设置全部节点的复选框状态                                                 | checked: `boolean`                                                                       | -              |
| checkNode           | 设置指定节点的复选框状态                                                 | value: `TreeNodeValue \| TreeNodeValue[]`<br>checked: `boolean`<br>onlyCheckLeaf: `boolean`    | -              |
| selectAll           | 设置全部节点的选中状态                                                   | selected: `boolean`                                                                      | -              |
| selectNode          | 设置指定节点的选中状态                                                   | value: `TreeNodeValue \| TreeNodeValue[]`<br>selected: `boolean`                               | -              |
| expandAll           | 设置全部节点的展开状态                                                   | expanded: `boolean`                                                                      | -              |
| expandNode          | 设置指定节点的展开状态                                                   | value: `TreeNodeValue \| TreeNodeValue[]`<br>expanded: `boolean`                               | -              |

### `<tree>` Slots

| 插槽名        |        描述        | 参数                 |
| ------------- | :----------------: | -------------------- |
| label         | 节点内容 | node: `TreeNodeData` |
| extra         | 渲染额外的节点内容 | -                    |
| drag-icon     |   定制 drag 图标   | node: `TreeNodeData` |
| loading-icon  | 定制 loading 图标  | TreeNodeData |
| switcher-icon | 定制 switcher 图标 | TreeNodeData |
| icon          |    定制节点图标    | node: `TreeNodeData` |

### TreeNodeData

| 参数名          | 描述                                | 类型               | 默认值  |
| --------------- | ----------------------------------- | ------------------ | :-----: |
| value             | 唯一标示                            | `string \| number` |   `-`   |
| label           | 该节点显示的标题                    | `string`           |   `-`   |
| selectable      | 是否允许选中                        | `boolean`          | `false` |
| disabled        | 是否禁用节点                        | `boolean`          | `false` |
| disableCheckbox | 是否禁用复选框                      | `boolean`          | `false` |
| checkable       | 是否显示多选框                      | `boolean`          | `false` |
| draggable       | 是否可以拖拽                        | `boolean`          | `false` |
| isLeaf          | 是否是叶子节点。动态加载时有效      | `boolean`          | `false` |
| icon            | 节点的图标                          | `() => VNode`      |   `-`   |
| switcherIcon    | 定制 switcher 图标，优先级大于 tree | `() => VNode`      |   `-`   |
| loadingIcon     | 定制 loading 图标，优先级大于 tree  | `() => VNode`      |   `-`   |
| dragIcon        | 定制 drag 图标，优先级大于 tree     | `() => VNode`      |   `-`   |
| children        | 子节点                              | `TreeNodeData[]`   |   `-`   |

### TreeFieldNames

| 参数名          | 描述                                            | 类型     |      默认值       |
| --------------- | ----------------------------------------------- | -------- | :---------------: |
| value             | 指定 value 在 TreeNodeData 中的字段名             | `string` |       `value`       |
| label           | 指定 label 在 TreeNodeData 中的字段名           | `string` |      `label`      |
| disabled        | 指定 disabled 在 TreeNodeData 中的字段名        | `string` |    `disabled`     |
| children        | 指定 children 在 TreeNodeData 中的字段名        | `string` |    `children`     |
| isLeaf          | 指定 isLeaf 在 TreeNodeData 中的字段名          | `string` |     `isLeaf`      |
| disableCheckbox | 指定 disableCheckbox 在 TreeNodeData 中的字段名 | `string` | `disableCheckbox` |
| checkable       | 指定 checkable 在 TreeNodeData 中的字段名       | `string` |    `checkable`    |
| icon            | 指定 icon 在 TreeNodeData 中的字段名            | `string` |    `checkable`    |

### VirtualListProps

| 参数名             | 描述                                                               | 类型               | 默认值  |
| ------------------ | ------------------------------------------------------------------ | ------------------ | :-----: |
| height             | 可视区域高度                                                       | `number \| string` |   `-`   |
| threshold          | 开启虚拟滚动的元素数量阈值，当数据数量小于阈值时不会开启虚拟滚动。 | `number`           |   `-`   |
| isStaticItemHeight | （已废除）元素高度是否是固定的。请使用 `fixedSize`                 | `boolean`          | `false` |
| fixedSize          | 元素高度是否是固定的。                                             | `boolean`          | `false` |
| estimatedSize      | 元素高度不固定时的预估高度。                                       | `number`           |   `-`   |
| buffer             | 视口边界外提前挂载的元素数量。                                     | `number`           |  `10`   |

### 类型定义

组件导出以下类型定义

```ts
import type { TreeInstance } from '@cedar-design/ui'
```

### 五档密度与图标

xs/sm/md/lg/xl 分别消费各档 icon-size、font-size、line-height、title-padding-vertical。图标尺寸同时参与展开按钮与缩进计算；show-line 跟随对应行高。

| 变量 | 默认值 |
| --- | --- |
| `--c-tree-size-xl-icon-size` | `var(--c-size-4)` |
| `--c-tree-size-xl-font-size` | `var(--c-sys-font-size-lg)` |
| `--c-tree-size-xl-line-height` | `var(--c-size-xl)` |
| `--c-tree-size-xl-title-padding-vertical` | `12px` |

### 节点字段与业务值

节点默认使用 `{ value, label, children }`，`value` 是全树唯一的字符串或数字（支持 `0`），`label` 是展示内容。后端使用其他字段时可配置 `fieldNames: { value: 'id', label: 'text', children: 'items' }`，无需修改后端数据。声明式组件子项的 `name`、Vue 的 `:key` 和 Table 的 `rowKey` 保持各自含义。

Tree 的独立状态采用 `selectedValues/defaultSelectedValues`、`checkedValues/defaultCheckedValues`、`halfCheckedValues`、`expandedValues/defaultExpandedValues`，分别通过同名具名 v-model 更新；`check` 事件数据中的半选集合为 `halfCheckedValues`。节点内容插槽为 `label`，TreeSelect 对应透传插槽为 `tree-slot-label`。`scrollIntoView({ value })` 按业务值定位；显式 `index` 仍表示虚拟列表从 0 开始的数组下标。


| 焦点轮廓变量 | 默认值 |
| --- | --- |
| `--c-tree-focus-outline-width` | `2px` |

## 阅读方向与键盘交互

Tree 继承容器阅读方向，缩进、连接线和展开箭头随方向显示。键盘焦点与选中状态独立：上下键移动到上一/下一可用可见节点，Home/End 移动到首尾。LTR 右键展开或进入子级、左键收起或返回父级；RTL 左右互换。Enter 选中，Space 优先勾选可勾选节点，否则执行选中。

键盘跳过禁用节点，根节点通过 `aria-activedescendant` 标识当前焦点，虚拟滚动时保持根节点焦点。展开、过滤、删除节点后会修正活动节点。拖放的前/内/后仍由纵向位置决定，不因 RTL 反转。TreeSelect 内嵌使用时由组合框管理焦点。

---

Document: llms/zh-CN/components/trigger.md

<!-- Source: src/trigger/README.md; locale: zh-CN; page: /components/trigger/ -->

# Trigger

真实IAB default/light完成两端延迟取消／KeepAlive测量四组，包含重新挂载正向计时对照，最终面板节点0。入口按钮原生点击但mouseenter由夹具脚本发出，不称原生hover、跨窗口视觉或OS验收。

更换或清空popup ref、watcher刷新前卸载时，scroll监听在实际原绑定窗口解绑，不依赖当前ref反查。此模拟回归不涵盖同节点跨document adopt或真实浏览器视觉／OS验收。

定位／滚动关闭 RAF 在事件元素或浮层的所属窗口申请，并在原申请窗口取消。关闭／解绑后已出队旧帧不消费新的滚动任务。RAF是必要测量调度，不是CSS动效时长；旧监听原窗口解绑已完成后续模拟回归，同节点adopt与真实浏览器仍需单独验收。

mouse-enter-delay／mouse-leave-delay 是交互请求延迟，独立于CSS进出时长。取消、替换、KeepAlive停用或卸载后，旧已出队回调不会提交；停用或卸载后保留的请求方法不再调度。重新激活接受新请求、不重放旧延迟，受控open仍由调用方决定。

连续点击两个独立触发器时，先关闭之前的顶层浮层，再打开新的浮层；嵌套子浮层仍视为父层内部。受控 open 只发出关闭请求，调用方仍可决定是否接受。

无视觉样式的锚点浮层基础组件，统一负责触发、定位、挂载、层级和打开状态。业务提示优先使用 Tooltip，结构化内容使用 Popover，命令选择使用 Menu；只有构建新的浮层组件时才直接使用 Trigger。

## 基础示例

### 基础用法

Example source: src/trigger/__demos__/basic.vue

```vue
<template>
  <div class="trigger-demo">
    <c-trigger trigger="click" :popup-offset="10" show-arrow>
      <c-button>点击打开</c-button>
      <template #content>
        <div class="trigger-demo__panel">Trigger 只负责浮层行为，面板外观由使用者决定。</div>
      </template>
    </c-trigger>
  </div>
</template>

<style scoped>
.trigger-demo {
  display: flex;
  justify-content: center;
  padding: calc(var(--c-sys-space-8) * 2) var(--c-sys-space-6);
}

.trigger-demo__panel {
  max-width: 260px;
  padding: var(--c-sys-space-5) var(--c-sys-space-6);
  color: var(--c-sys-color-content-primary);
  background: var(--c-sys-color-surface-overlay);
  border: 1px solid var(--c-sys-color-border-default);
  border-radius: var(--c-sys-radius-md);
}
</style>
```

## 布局与排列

### 方位与箭头

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `trigger` | 触发方式，可组合 | 方位与箭头 |
| `placement` | 浮层相对触发元素的首选方位，默认 bottom；启用默认的 auto-fit-position 时，空间不足会自动翻转并约束到可视区域，不保证最终停在该侧 | 方位与箭头 |
| `popup-offset` | 沿 placement 主轴向外的距离 | 方位与箭头 |
| `show-arrow` | 渲染装饰箭头 | 方位与箭头 |
<!-- demo-config-notes:end -->

Example source: src/trigger/__demos__/placement.vue

```vue
<script setup lang="ts">
const placements = ['top', 'right', 'bottom', 'left'] as const
</script>

<template>
  <div class="trigger-placement-demo">
    <c-trigger v-for="placement in placements" :key="placement" trigger="click" :placement="placement" :popup-offset="10" show-arrow>
      <c-button variant="outline">{{ placement }}</c-button>
      <template #content><div class="trigger-placement-demo__panel">{{ placement }}</div></template>
    </c-trigger>
  </div>
</template>

<style scoped>
.trigger-placement-demo {
  display: grid;
  grid-template-columns: repeat(2, minmax(100px, 1fr));
  gap: calc(var(--c-sys-space-8) * 2);
  padding: calc(var(--c-sys-space-8) * 3);
}

.trigger-placement-demo__panel {
  padding: var(--c-sys-space-4) var(--c-sys-space-5);
  color: var(--c-sys-color-content-primary);
  background: var(--c-sys-color-surface-overlay);
  border: 1px solid var(--c-sys-color-border-default);
  border-radius: var(--c-sys-radius-sm);
}
</style>
```

## 交互与控制

### 受控状态与偏移

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `open` | 受控打开状态 | 受控状态与偏移 |
| `trigger` | 触发方式，可组合 | 受控状态与偏移 |
| `placement` | 浮层相对触发元素的首选方位，默认 bottom；启用默认的 auto-fit-position 时，空间不足会自动翻转并约束到可视区域，不保证最终停在该侧 | 受控状态与偏移 |
| `popup-offset` | 沿 placement 主轴向外的距离 | 受控状态与偏移 |
| `popup-translate` | 屏幕轴平移，或按 placement 配置平移 | 受控状态与偏移 |
<!-- demo-config-notes:end -->

`popup-offset` 是沿 placement 主轴向外的距离；`popup-translate` 是屏幕 x/y 轴上的附加平移。

本例通过 `v-model:open` 接受开关请求，面板显示父级实际值。外部打开/关闭按钮直接更新父级；触发元素上的 Enter/Space 会产生原生按钮点击，Escape 或外部点击请求关闭。示例没有拒绝请求，不代表受控拒绝场景已覆盖。

Example source: src/trigger/__demos__/controlled.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'

const open = ref(false)
</script>

<template>
  <div class="trigger-controlled-demo">
    <c-space>
      <c-button @click="open = true">外部打开</c-button>
      <c-button variant="outline" @click="open = false">外部关闭</c-button>
    </c-space>
    <c-trigger v-model:open="open" trigger="click" placement="bottom-start" :popup-offset="10" :popup-translate="[16, 0]">
      <c-button variant="text">受控触发元素</c-button>
      <template #content><div class="trigger-controlled-demo__panel">open = {{ open }}</div></template>
    </c-trigger>
  </div>
</template>

<style scoped>
.trigger-controlled-demo {
  display: flex;
  flex-wrap: wrap;
  align-items: center;
  gap: var(--c-sys-space-8);
  padding: calc(var(--c-sys-space-8) * 2) var(--c-sys-space-6);
}

.trigger-controlled-demo__panel {
  padding: var(--c-sys-space-5) var(--c-sys-space-6);
  color: var(--c-sys-color-content-primary);
  background: var(--c-sys-color-surface-overlay);
  border: 1px solid var(--c-sys-color-border-default);
  border-radius: var(--c-sys-radius-sm);
}
</style>
```

## API

### `<Trigger>` Props

| 属性 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| dir | 阅读方向；省略时继承来源作用域。物理 left/right 方位保持原意。 | `ReadingDirection` (`ltr` / `rtl`) | — |
| open | 受控打开状态 | `boolean` | `-` |
| default-open | 非受控初始状态 | `boolean` | `false` |
| trigger | 触发方式，可组合 | `hover \| click \| focus \| contextMenu \| manual \| TriggerEvent[]` | `hover` |
| disabled | 禁止打开 | `boolean` | `false` |
| reference | 外部参考元素；不传时使用默认插槽首个真实元素 | `string \| HTMLElement \| SVGElement` | `-` |
| placement | 浮层相对触发元素的首选方位，默认 bottom；启用默认的 auto-fit-position 时，空间不足会自动翻转并约束到可视区域，不保证最终停在该侧 | `TriggerPlacement` | `bottom` |
| strategy | 定位策略 | `absolute \| fixed` | `absolute` |
| cover | 沿主轴覆盖参考元素 | `boolean` | `false` |
| popup-offset | 沿 placement 主轴向外的距离 | `number` | `0` |
| popup-translate | 屏幕轴平移，或按 placement 配置平移 | `[number, number] \| Partial<Record<TriggerPlacement, [number, number]>>` | `-` |
| align-point | 以鼠标坐标作为虚拟参考点 | `boolean` | `false` |
| popup-container | 挂载容器；`false` 表示原地渲染 | `string \| HTMLElement \| false` | `body` |
| auto-fit-position | 空间不足时翻转并限制到可视区域 | `boolean` | `true` |
| auto-fit-popup-width | 浮层宽度等于参考元素宽度 | `boolean` | `false` |
| auto-fit-popup-min-width | 浮层最小宽度等于参考元素宽度 | `boolean` | `false` |
| auto-fix-position | 尺寸变化时自动重新定位 | `boolean` | `true` |
| update-at-scroll | 滚动时重新定位 | `boolean` | `false` |
| scroll-to-close | 滚动超过阈值时关闭 | `boolean` | `false` |
| scroll-to-close-distance | 滚动关闭阈值 | `number` | `0` |
| show-arrow | 渲染装饰箭头 | `boolean` | `false` |
| hide-empty | content 为空时不渲染浮层 | `boolean` | `false` |
| prevent-focus | 阻止定位层 mousedown 抢占焦点 | `boolean` | `false` |
| unmount-on-close | 离场结束后卸载内容 | `boolean` | `true` |
| animation-name | Vue Transition 名称 | `string` | `trigger-fade` |
| duration | 过渡时长 | `number \| { enter: number; leave: number }` | `-` |
| auto-fit-transform-origin | 根据最终方位设置动画原点 | `boolean` | `false` |
| opened-class | 打开时附加给首个参考节点的类名 | `ClassName` | `-` |
| popup-class / popup-style | 定位层类名和样式 | `ClassName / CSSProperties` | `-` |
| content-class / content-style | 内容层类名和样式 | `ClassName / CSSProperties` | `-` |
| arrow-class / arrow-style | 箭头类名和样式 | `ClassName / CSSProperties` | `-` |
| mouse-enter-delay / mouse-leave-delay | hover 打开和关闭延迟，毫秒 | `number` | `100 / 100` |
| focus-delay | focus 打开延迟，毫秒 | `number` | `0` |
| popup-hover-stay | 指针进入浮层后保持打开 | `boolean` | `true` |
| blur-to-close | 失焦时关闭 | `boolean` | `true` |
| close-on-click-reference | 再次点击参考元素时关闭 | `boolean` | `true` |
| click-outside-to-close | 点击外部关闭 | `boolean` | `true` |
| esc-to-close | Escape 关闭 | `boolean` | `true` |
| restore-focus | 关闭被接受后恢复参考元素焦点 | `boolean` | `true` |

### Events

| 事件 | 说明 | 参数 |
| --- | --- | --- |
| update:open | 用户交互发出的受控更新请求 | `open: boolean` |
| open-change | 用户交互请求通知 | `open: boolean` |
| open / close | 实际开始进入 / 离开 | `-` |
| opened / closed | 动画进入 / 离开完成 | `-` |
| click-outside | 最上层浮层收到外部点击 | `event: Event` |
| resize | 参考元素尺寸变化 | `-` |

### Slots

| 插槽 | 说明 |
| --- | --- |
| default | 参考节点 |
| content | 浮层内容 |

### Expose

`open()`、`close()`、`resize()`、`allowClose()`、`getReference()`、`setReference(reference?)`、`focusReference()`、`isTopLayer(event?)`。

## 键盘与可访问性

`trigger="focus"` 支持键盘聚焦；`esc-to-close` 只让最上层浮层响应 Escape。Trigger 不自行设置 `role`、`aria-describedby` 或业务标签，Tooltip、Popover、Menu 等上层组件必须根据语义补充。

## 公开 CSS 变量

以下为实际 :root 默认值。业务定制优先使用组件变量；内部定位变量不属于公开 API。

| 变量 | 默认值 | 意义与场景 |
| --- | --- | --- |
| `--c-trigger-arrow-background` | `var(--c-sys-color-surface-overlay)` | 独立 Trigger 箭头背景；包装组件用自己的变量 |
| `--c-trigger-arrow-size` | `var(--c-sys-space-4)` | 箭头正方形尺寸 |
| `--c-trigger-arrow-radius` | `var(--c-sys-radius-sm)` | 箭头圆角 |
| `--c-trigger-transition-duration` | `var(--c-sys-motion-duration-fast)` | 默认 Trigger 淡入淡出时长 |
| `--c-trigger-transition-easing` | `var(--c-sys-motion-easing-standard)` | 默认 Trigger 缓动曲线 |

Tooltip 与 Popover 自行定义箭头外观；应覆盖其组件变量，而不是 Trigger arrow-background。

使用 Teleport 时，变量需放在实际 popup 的作用域中（例如通过 `popup-style`）；触发按钮上的变量不会自动继承到浮层。

### 减少动态效果

内置 CSS 过渡遵循 `prefers-reduced-motion: reduce`。关闭过渡不改变最终显隐、选中／展开状态及事件语义；插槽内自定义动画由应用自行控制。


### 方位语义与配置入口

placement 是首选方位，auto-fit-position 默认 true 时最终方位可能变化；它不是 position 坐标。top-start 与 top-left 不是同一种枚举：前者是锚点方位及沿边对齐，后者是容器角落。当前 Trigger 的 start/end 由物理交叉轴几何解释，尚不应承诺 RTL 自动镜像。

## 参考元素的原生事件修饰符

`click`、`mouseenter`、`mouseleave`、`focusin`、`focusout`、`contextmenu` 的原生监听器和 `.once`、`.capture`、`.passive` 均绑定到实际参考元素，不会落到浮层。`.once` 按原生元素的监听生命周期执行；更新回调不重新启用已消费的监听，换参考元素或移除后重加监听才开始新的周期。停用和卸载会解绑。普通监听器只通知，返回 Promise 不驱动打开或加载，异常进入 Vue 的事件错误处理链。

---

Document: llms/zh-CN/components/typography.md

<!-- Source: src/typography/README.md; locale: zh-CN; page: /components/typography/ -->

# 排版 Typography

用于展示标题、段落、文本内容。

## 基础示例

### 基础用法

排版组件用于展示标题、段落、文本内容，这里展示了排版的组合使用。

Example source: src/typography/__demos__/basic.vue

```vue
<template>
  <c-typography>
    <c-typography-title>Design system</c-typography-title>
    <c-typography-paragraph>
      A design is a plan or specification for the construction of an object or system or for the
      implementation of an activity or process, or the result of that plan or specification in the
      form of a prototype, product or process. The verb to design expresses the process of developing
      a design.
    </c-typography-paragraph>
    <c-typography-paragraph>
      In some cases, the direct construction of an object without an explicit prior plan (such as in
      craftwork, some engineering, coding, and graphic design) may also be considered
      <c-typography-text bold>to be a design activity.</c-typography-text>
    </c-typography-paragraph>
    <c-typography-title :heading="2">Cedar Design</c-typography-title>
    <c-typography-paragraph>
      The component library defines a set of default particle variables, and a custom theme is to
      <c-typography-text mark>customize</c-typography-text> and
      <c-typography-text underline>overwrite</c-typography-text> this variable list.
    </c-typography-paragraph>
    <c-typography-paragraph blockquote>
      A design is a plan or specification for the construction of an object or system or for the
      implementation of an activity or process, or the result of that plan or specification in the
      form of a
      <c-typography-text code>prototype</c-typography-text>,
      <c-typography-text code>product</c-typography-text> or
      <c-typography-text code>process</c-typography-text>. The verb to design expresses the process of
      developing a design.
    </c-typography-paragraph>
    <c-typography-paragraph mark underline delete>
      A design is a plan or specification for the construction of an object or system or for the
      implementation of an activity or process.
    </c-typography-paragraph>
    <c-typography-paragraph>
      <ul>
        <li>
          Architectural blueprints
          <ul>
            <li>Architectural blueprints</li>
          </ul>
        </li>
        <li>Engineering drawings</li>
        <li>Business processes</li>
      </ul>
    </c-typography-paragraph>
    <c-typography-paragraph>
      <ol>
        <li>Architectural blueprints</li>
        <li>Engineering drawings</li>
        <li>Business processes</li>
      </ol>
    </c-typography-paragraph>
  </c-typography>
</template>
```

## 内容与展示

### 标题

展示不同级别的标题。

Example source: src/typography/__demos__/title.vue

```vue
<template>
  <c-typography>
    <c-typography-title>H1. The Pragmatic Romanticism</c-typography-title>
    <c-typography-title :heading="2">H2. The Pragmatic Romanticism</c-typography-title>
    <c-typography-title :heading="3">H3. The Pragmatic Romanticism</c-typography-title>
    <c-typography-title :heading="4">H4. The Pragmatic Romanticism</c-typography-title>
    <c-typography-title :heading="5">H5. The Pragmatic Romanticism</c-typography-title>
    <c-typography-title :heading="6">H6. The Pragmatic Romanticism</c-typography-title>
  </c-typography>
</template>
```

### 文本

不同样式的文本。

Example source: src/typography/__demos__/text.vue

```vue
<template>
  <c-space direction="column" :size="10">
    <c-typography-text>Cedar Design</c-typography-text>
    <c-typography-text status="secondary">Secondary</c-typography-text>
    <c-typography-text status="primary">Primary</c-typography-text>
    <c-typography-text status="success">Success</c-typography-text>
    <c-typography-text status="warning">Warning</c-typography-text>
    <c-typography-text status="danger">Danger</c-typography-text>
    <c-typography-text bold>Bold</c-typography-text>
    <c-typography-text disabled>Disabled</c-typography-text>
    <c-typography-text mark>Mark</c-typography-text>
    <c-typography-text underline>Underline</c-typography-text>
    <c-typography-text delete>Line through</c-typography-text>
    <c-typography-text code>Code snippet</c-typography-text>
  </c-space>
</template>
```

### 段落

文本段落样式。长文本推荐默认行高，短文本推荐 `spacing="close"`。

Example source: src/typography/__demos__/paragraph.vue

```vue
<template>
  <c-typography>
    <c-typography-title :heading="5">Default</c-typography-title>
    <c-typography-paragraph>
      A design is a plan or specification for the construction of an object or system or for the
      implementation of an activity or process, or the result of that plan or specification in the
      form of a prototype, product or process. The verb to design expresses the process of developing
      a design. In some cases, the direct construction of an object without an explicit prior plan
      (such as in craftwork, some engineering, coding, and graphic design) may also be considered to
      be a design activity.
    </c-typography-paragraph>
    <c-typography-title :heading="5">Secondary</c-typography-title>
    <c-typography-paragraph status="secondary">
      A design is a plan or specification for the construction of an object or system or for the
      implementation of an activity or process, or the result of that plan or specification in the
      form of a prototype, product or process. The verb to design expresses the process of developing
      a design. In some cases, the direct construction of an object without an explicit prior plan
      (such as in craftwork, some engineering, coding, and graphic design) may also be considered to
      be a design activity.
    </c-typography-paragraph>
    <c-typography-title :heading="5">Spacing default</c-typography-title>
    <c-typography-paragraph>
      A design is a plan or specification for the construction of an object or system or for the
      implementation of an activity or process, or the result of that plan or specification in the
      form of a prototype, product or process. The verb to design expresses the process of developing
      a design. In some cases, the direct construction of an object without an explicit prior plan
      (such as in craftwork, some engineering, coding, and graphic design) may also be considered to
      be a design activity.
    </c-typography-paragraph>
    <c-typography-title :heading="5">Spacing close</c-typography-title>
    <c-typography-paragraph status="secondary" spacing="close">
      A design is a plan or specification for the construction of an object or system or for the
      implementation of an activity or process, or the result of that plan or specification in the
      form of a prototype, product or process. The verb to design expresses the process of developing
      a design.
    </c-typography-paragraph>
  </c-typography>
</template>
```

### 省略

在空间不足时省略多行文本内容。支持 JS 测量省略、CSS 省略、Tooltip / Popover 以及展开折叠。

Example source: src/typography/__demos__/ellipsis.vue

```vue
<template>
  <div>
    <c-typography-title :heading="4" ellipsis>
      A design is a plan or specification for the construction of an object or system or for the
      implementation of an activity or process.
    </c-typography-title>
    <c-typography-paragraph
      :ellipsis="{
        rows: 2,
        showTooltip: true,
      }"
    >
      A design is a plan or specification for the construction of an object or system or for the
      implementation of an activity or process, or the result of that plan or specification in the
      form of a prototype, product or process. The verb to design expresses the process of developing
      a design. The verb to design expresses the process of developing a design. A design is a plan
      or specification for the construction of an object or system or for the implementation of an
      activity or process, or the result of that plan or specification in the form of a prototype,
      product or process. The verb to design expresses the process of developing a design. The verb
      to design expresses the process of developing a design.
    </c-typography-paragraph>
    <c-typography-paragraph
      :ellipsis="{
        rows: 2,
        showTooltip: true,
        css: true,
      }"
    >
      A design is a plan or specification for the construction of an object or system or for the
      implementation of an activity or process, or the result of that plan or specification in the
      form of a prototype, product or process. The verb to design expresses the process of developing
      a design. The verb to design expresses the process of developing a design. A design is a plan
      or specification for the construction of an object or system or for the implementation of an
      activity or process, or the result of that plan or specification in the form of a prototype,
      product or process. The verb to design expresses the process of developing a design. The verb
      to design expresses the process of developing a design.
    </c-typography-paragraph>
    <c-typography-paragraph
      :ellipsis="{
        suffix: '--Cedar Design',
        rows: 2,
        expandable: true,
        showTooltip: {
          type: 'popover',
          props: {
            style: { maxWidth: '500px' },
          },
        },
      }"
    >
      <template #expand-node="{ expanded }">
        {{ expanded ? '' : 'More' }}
      </template>
      A design is a plan or specification for the construction of an object or system or for the
      implementation of an activity or process, or the result of that plan or specification in the
      form of a prototype, product or process. The verb to design expresses the process of developing
      a design. The verb to design expresses the process of developing a design. A design is a plan
      or specification for the construction of an object or system or for the implementation of an
      activity or process, or the result of that plan or specification in the form of a prototype,
      product or process. The verb to design expresses the process of developing a design. The verb
      to design expresses the process of developing a design.
    </c-typography-paragraph>
    <c-typography-paragraph
      :ellipsis="{
        suffix: '--Cedar Design',
        rows: 3,
        expandable: true,
      }"
    >
      A design is a plan or specification for the construction of an object or system or for the
      implementation of an activity or process, or the result of that plan or specification in the
      form of a prototype, product or process. The verb to design expresses the process of developing
      a design. The verb to design expresses the process of developing a design. A design is a plan
      or specification for the construction of an object or system or for the implementation of an
      activity or process, or the result of that plan or specification in the form of a prototype,
      product or process. The verb to design expresses the process of developing a design. The verb
      to design expresses the process of developing a design.
    </c-typography-paragraph>
  </div>
</template>
```

## 交互与控制

### 可交互

提供复制、编辑文本等功能。

Example source: src/typography/__demos__/operations.vue

```vue
<template>
  <c-typography>
    <c-typography-paragraph copyable>Click the icon to copy this text.</c-typography-paragraph>
    <c-typography-paragraph editable v-model:edit-text="str">
      {{ str }}
    </c-typography-paragraph>
  </c-typography>
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const str = ref('Click the icon to edit this text.')
</script>
```

## 生命周期与边界

### 测量与复制反馈生命周期

Example source: src/typography/__demos__/scheduler-lifecycle.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import { TypographyText } from "../index";

const active = ref(true);
const mounted = ref(true);
const copies = ref(0);
</script>

<template>
  <div>
    <c-button html-type="button" @click="active = !active"
      >切换 KeepAlive</c-button
    >
    <c-button html-type="button" @click="mounted = !mounted"
      >卸载／挂载</c-button
    >
    <p>复制通知：{{ copies }}。连续复制后等待 3 秒，或复制后停用再激活。</p>
    <KeepAlive v-if="mounted">
      <TypographyText
        v-if="active"
        copyable
        :ellipsis="{ rows: 1, expandable: true }"
        @copy="copies++"
      >
        Typography
        测量调度与复制反馈生命周期示例：重复复制只保留最新反馈，停用和卸载取消待处理工作。
      </TypographyText>
    </KeepAlive>
  </div>
</template>
```

复制反馈使用现有 `copy-delay`（默认 3000ms），是交互反馈等待，不是 CSS 动效完成时间。重复复制替换旧等待；关闭复制、禁用或修改等待时长会清除当前反馈。停用／卸载取消反馈计时与省略测量 RAF，保留操作和旧回调不能继续写入；激活重新测量，不恢复旧任务。禁用态文字仍可测量省略，不允许复制／编辑／展开交互。省略关闭、展开或进入编辑会取消旧测量；完成后重放和测量重入不能覆盖新结果。

## API

### Common Props

`Typography.Title`、`Typography.Paragraph`、`Typography.Text` 共享以下属性。

| 属性名 | 描述 | 类型 | 默认值 |
| --- | --- | --- | :---: |
| status | 文本语义状态 | `SemanticStatus` | `-` |
| bold | 粗体 | `boolean` | `false` |
| mark | 添加标记样式 | `boolean \| { color: string }` | `false` |
| underline | 下划线样式 | `boolean` | `false` |
| delete | 删除线样式 | `boolean` | `false` |
| code | 代码块样式 | `boolean` | `false` |
| disabled | 禁用状态 | `boolean` | `false` |
| editable | 开启可编辑功能 | `boolean` | `false` |
| editing **(v-model)** | 是否在编辑状态 | `boolean` | `-` |
| default-editing | 默认的编辑状态 | `boolean` | `false` |
| edit-text **(v-model)** | 编辑的文字 | `string` | `-` |
| copyable | 开启复制功能 | `boolean` | `false` |
| copy-text | 复制的文字 | `string` | `-` |
| copy-delay | 复制成功后，复制按钮恢复到可点击状态的延迟时间，单位是毫秒 | `number` | `3000` |
| ellipsis | 自动溢出省略，具体参数配置看 [EllipsisConfig](#ellipsisconfig) | `boolean \| EllipsisConfig` | `false` |
| edit-tooltip-props | 编辑按钮 Tooltip 配置 | `object` | `-` |
| copy-tooltip-props | 拷贝按钮 Tooltip 配置 | `object` | `-` |

### Common Events

| 事件名 | 描述 | 参数 |
| --- | --- | --- |
| edit-start | 开始编辑 | `-` |
| change | 编辑内容变化 | `text: string` |
| edit-end | 编辑结束 | `-` |
| copy | 复制 | `text: string` |
| ellipsis | 省略变化事件 | `isEllipsis: boolean` |
| expand | 展开收起事件 | `expanded: boolean` |

### Common Slots

| 插槽名 | 描述 | 参数 |
| --- | --- | --- |
| expand-node | 自定义展开和折叠按钮 | `expanded: boolean` |
| copy-icon | 自定义复制按钮图标 | `copied: boolean` |
| copy-tooltip | 自定义复制按钮的 tooltip 内容 | `copied: boolean` |

### `<TypographyTitle>` Props

| 属性名 | 描述 | 类型 | 默认值 |
| --- | --- | --- | :---: |
| heading | 标题级别，相当于 `h1` `h2` `h3` `h4` `h5` `h6` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `1` |

### `<TypographyParagraph>` Props

| 属性名 | 描述 | 类型 | 默认值 |
| --- | --- | --- | :---: |
| blockquote | 长引用 | `boolean` | `false` |
| spacing | 段落行高；长文本推荐默认行高，短文本推荐 `close` | `'default' \| 'close'` | `'default'` |

### EllipsisConfig

| 属性名 | 描述 | 类型 | 默认值 |
| --- | --- | --- | :---: |
| rows | 显示省略的行数 | `number` | `1` |
| expandable | 是否支持展开/折叠 | `boolean` | `false` |
| ellipsisStr | 省略号 | `string` | `'...'` |
| suffix | 后缀 | `string` | `-` |
| showTooltip | 配置省略时的弹出框 | `boolean \| { type: 'tooltip' \| 'popover'; props: Record<string, any> }` | `false` |
| css | 是否使用 CSS 省略（此模式暂不支持展开、自定义省略号和后缀） | `boolean` | `false` |

### 类型定义

组件导出以下类型定义：

```ts
import type {
  TypographyInstance,
  TypographyParagraphInstance,
  TypographyTitleInstance,
  TypographyTextInstance,
  EllipsisConfig,
} from '@cedar-design/ui'
```

---

Document: llms/zh-CN/components/upload.md

<!-- Source: src/upload/README.md; locale: zh-CN; page: /components/upload/ -->

# Upload 上传

读取、队列和请求采用两端独立复制的同源实现；未配置 action/custom-request 时仅读取，供业务自行管理进度与结果。

## 基础示例

### 基础用法

选择本地文件后显示文件列表；未配置 action/custom-request 时仅读取，不发送请求。

Example source: src/upload/__demos__/read-only.vue

```vue
<script setup>
import { ref } from 'vue'
const files = ref([])
const last = ref('')
</script>
<template><div><p>不配置 action/custom-request：只读取文件，不发送请求。</p><c-upload v-model="files" multiple list-type="picture" @read="file => last = file.name" /><p>最近读取：{{ last }}</p></div></template>
```

## 外观与状态

### 动态只读与禁用

预置本地合成图片，启用 readPrettyonly 与 disabled，比较预览、删除和选择入口的行为。选择按钮只记录 request-choose 次数，不调用原生文件框或请求接口。只读保留预览，禁用同时阻止预览；解除限制后可重新操作。恢复示例由父级更新模型，不是 Upload 的公开重置方法。

Example source: src/upload/__demos__/state-controls.vue

```vue
<script setup>
import { ref } from "vue";

const readonly = ref(false);
const disabled = ref(false);
const chooseCount = ref(0);
const previewCount = ref(0);
const initialFile = {
  uid: "state-image",
  name: "state-example.svg",
  type: "image/svg+xml",
  url: "data:image/svg+xml,%3Csvg xmlns=%22http://www.w3.org/2000/svg%22 width=%22120%22 height=%22120%22%3E%3Crect width=%22120%22 height=%22120%22 fill=%22%236750a4%22/%3E%3C/svg%3E",
  status: "success",
  percent: 100,
};
const files = ref([{ ...initialFile }]);
function choose() {
  chooseCount.value++;
}
function restore() {
  files.value = [{ ...initialFile }];
}
</script>

<template>
  <section class="upload-state-demo">
    <div class="controls">
      <c-checkbox v-model="readonly"> Readonly upload</c-checkbox>
      <c-checkbox v-model="disabled"> Disabled upload</c-checkbox>
      <c-button html-type="button" @click="restore">Restore sample</c-button>
    </div>
    <p>Local selection callback only; no file chooser or network request.</p>
    <c-upload
      v-model="files"
      data-testid="state-upload"
      :readonly="readonly"
      :disabled="disabled"
      :request-choose="choose"
      @preview="previewCount++"
    />
    <p role="status">
      Files: {{ files.length }}; choose: {{ chooseCount }}; preview:
      {{ previewCount }}
    </p>
  </section>
</template>

<style scoped>
.controls {
  display: flex;
  flex-wrap: wrap;
  align-items: center;
  gap: 12px;
}
.controls label {
  display: inline-flex;
  align-items: center;
  gap: 4px;
}
</style>
```

### 交互状态切换

适用于附件列表展示与本地选取。调整禁用、只读，用相同数据观察变化。控制区始终可用，可以随时恢复编辑；错误外观本身不会触发表单校验。

Example source: src/upload/__demos__/state-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref([]);
const __demoState = __demoReactive({ disabled: false, readonly: false });
</script>
<template>
  <c-space direction="column" :size="16">
    <c-space wrap>
      <c-checkbox v-model="__demoState['disabled']">disabled</c-checkbox>
      <c-checkbox v-model="__demoState['readonly']">readonly</c-checkbox>
    </c-space>
    <c-upload
      v-model="value"
      :auto-upload="false"
      v-bind="__demoState"
    ></c-upload>
  </c-space>
</template>
```

### 图卡、插槽与自定义预览

Example source: src/upload/__demos__/custom-surface.vue

```vue
<script setup>
import { ref } from 'vue'
const files = ref([])
const message = ref('')
const preview = (file, event) => { event.preventDefault(); message.value = file.name }
</script>
<template><div><c-upload v-model="files" list-type="picture-card" multiple @preview="preview"><template #trigger><span>选择图片</span></template><template #remove-button="{ remove }"><c-button variant="text" @click="remove">删除</c-button></template></c-upload><p>自定义预览：{{ message }}</p></div></template>
```

## 文件来源与约束

### 目录选择与多文件回退

使用 directory 选择文件夹，普通多选入口可作为移动设备的替代路径。

Example source: src/upload/__demos__/directory.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
import type { UploadFileItem } from '@cedar-design/ui'
const files = ref<UploadFileItem[]>([])
</script>
<template>
  <c-space direction="column">
    <p>选择目录后查看文件列表；本例只读取本地文件，不发送请求。目录选择取决于浏览器与系统文件选择器，移动设备可使用普通多选入口。</p>
    <p>目录选择</p>
    <c-upload v-model="files" directory multiple />
    <p>普通文件多选</p>
    <c-upload multiple />
  </c-space>
</template>
```

### 剪贴板图片与读取校验

通过现有 useUploader.addFiles 接入 paste 事件，复用数量、大小和类型限制。这是应用层组合，不新增 Upload 的 paste 属性。

Example source: src/upload/__demos__/clipboard.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { useUploader, type UploadFileItem } from '@cedar-design/ui'
const files = ref<UploadFileItem[]>([])
const message = ref('')
const rejectionMessages: Record<string, string> = { 'max-files': '最多接收 3 张图片', 'max-file-size': '单张图片不能超过 1 MiB', accept: '仅支持图片文件' }
const uploader = useUploader({
  modelValue: () => files.value,
  onUpdateModelValue: value => { files.value = value },
  accept: () => 'image/*',
  maxFiles: () => 3,
  maxFileSize: () => 1024 * 1024,
  autoUpload: () => false,
  onRejected: rejected => { message.value = rejected.map(item => rejectionMessages[item.reason] ?? '文件未能读取，请重新选择').join(', ') },
})
function paste(event: ClipboardEvent) {
  const incoming = Array.from(event.clipboardData?.files ?? [])
  if (!incoming.length) return
  event.preventDefault()
  message.value = ''
  uploader.addFiles(incoming)
}
function addExample() {
  message.value = ''
  uploader.addFiles([new File(['<svg xmlns="http://www.w3.org/2000/svg" width="8" height="8"/>'], 'local-example.svg', { type: 'image/svg+xml' })])
}
function reset() { uploader.reset(); message.value = '' }
</script>
<template>
  <c-space direction="column">
    <p>将剪贴板图片粘贴到输入区。最多 3 张，每张不超过 1 MiB；只读取文件，不上传。普通文本粘贴仍按原生输入处理。</p>
    <c-textarea placeholder="在这里粘贴图片或文本" @paste="paste" />
    <c-space wrap>
      <c-button @click="addExample">加入本地示例图片</c-button>
      <c-button @click="reset">清空列表</c-button>
    </c-space>
    <p role="status">已接收 {{ files.length }} 个文件。{{ message }}</p>
    <ul><li v-for="file in files" :key="file.uid">{{ file.name }}</li></ul>
  </c-space>
</template>
```

### 替换后的约束校验

反向返回顺序：旧任务等待时重置并加入新文件，先点“返回最新缩略图”接受新项，再“拒绝最早缩略图”。旧失败只结清旧任务，不能再显示read-error、删除新项或增加解码数；最后重置清空列表和计数。这仍是本地回调竞争，不是原生读取器异常。

加入小图片前开启 FileReader/data-url 开关，接受的替换 File 会经过浏览器原生 FileReader。16px图片用于核对解码；Data URLs 是当前data-url项目数，Decoded images 是自上次重置以来累计load事件数。删除移除对应图片但不递减累计计数，重置清零两者；类型拒绝发生在读取前。使用本地生成File，不代表原生文件选择器或网络上传已验收。

开关仅影响后续新增项，不会重新读取既有项目；可按 file/data-url/file 顺序混合加入三项。满额后再加入会报告 max-files，图片和解码计数不变；删除 data-url 项后重新加入会读取新文件，累计解码数继续增加，重置清空整个混合队列。

Example source: src/upload/__demos__/replacement-validation.vue

```vue
<script setup>
import { onBeforeUnmount, onDeactivated, ref, shallowRef } from "vue";
import { useUploader } from "@cedar-design/ui";

const files = ref([]);
const readDataUrl = ref(false);
const readObjectUrl = ref(false);
const pauseThumbnail = ref(false);
const pendingThumbnails = shallowRef([]);
const decoded = ref(0);
const reasons = ref([]);
const replacements = new WeakMap();
const maxFileSize = 1048576;
const maxTotalSize = 2097152;
const maxFiles = 3;
const svg =
  '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"><rect width="16" height="16" fill="#4caf50"/></svg>';
let sequence = 0;

function replace(file) {
  const mode = replacements.get(file);
  if (mode === "type") {
    return new File(["text replacement"], file.name.replace(".svg", ".txt"), {
      type: "text/plain",
    });
  }
  if (mode === "size") {
    return new File([new Uint8Array(maxFileSize + 1)], file.name, {
      type: file.type,
    });
  }
  return new File([file], file.name, { type: file.type });
}

const uploader = useUploader({
  modelValue: () => files.value,
  onUpdateModelValue: (value) => {
    files.value = value;
  },
  accept: () => "image/*",
  maxFiles: () => maxFiles,
  createThumbnailUrl: () =>
    pauseThumbnail.value
      ? () =>
          new Promise((resolve, reject) => {
            pendingThumbnails.value = [
              ...pendingThumbnails.value,
              { resolve, reject },
            ];
          })
      : undefined,
  maxFileSize: () => maxFileSize,
  maxTotalSize: () => maxTotalSize,
  resolveType: () =>
    readObjectUrl.value
      ? "object-url"
      : readDataUrl.value
        ? "data-url"
        : "file",
  beforeRead: () => replace,
  onRejected: (items) => {
    reasons.value = items.map((item) => item.reason);
  },
});

function probe(mode) {
  reasons.value = [];
  const payload = mode === "total" ? svg.padEnd(786432, " ") : svg;
  const file = new File([payload], `sample-${++sequence}.svg`, {
    type: "image/svg+xml",
  });
  replacements.set(file, mode);
  return uploader.addFiles([file]);
}

function reset() {
  uploader.reset();
  decoded.value = 0;
  reasons.value = [];
}
function settleThumbnail(fail = false, latest = false) {
  const tasks = [...pendingThumbnails.value];
  const task = latest ? tasks.pop() : tasks.shift();
  if (!task) return;
  pendingThumbnails.value = tasks;
  if (fail) task.reject(new Error("Local thumbnail failure"));
  else task.resolve("data:image/svg+xml," + encodeURIComponent(svg));
}
function cleanupThumbnails() {
  const tasks = pendingThumbnails.value;
  pendingThumbnails.value = [];
  tasks.forEach((task) => task.resolve(undefined));
}
onBeforeUnmount(cleanupThumbnails);
onDeactivated(cleanupThumbnails);
</script>

<template>
  <div class="upload-read-demo">
    <p class="thumbnail-pending">
      Pending thumbnails: {{ pendingThumbnails.length }}
    </p>
    <c-button
      html-type="button"
      :disabled="!pendingThumbnails.length"
      @click="settleThumbnail(false, true)"
    >
      返回最新缩略图
    </c-button>
    <c-button
      html-type="button"
      :disabled="!pendingThumbnails.length"
      @click="settleThumbnail()"
      >返回最早缩略图</c-button
    >
    <c-button
      html-type="button"
      :disabled="!pendingThumbnails.length"
      @click="settleThumbnail(true)"
      >拒绝最早缩略图</c-button
    >
    <c-checkbox v-model="readDataUrl" edit-mode="direct"
      >使用原生 FileReader 读取为 data-url</c-checkbox
    >
    <c-checkbox v-model="readObjectUrl" edit-mode="direct"
      >使用原生 Blob/object-url（优先）</c-checkbox
    >
    <output
      >Blob URLs:
      {{ files.filter((file) => file.url?.startsWith("blob:")).length }}</output
    >
    <p role="status">
      Data URLs:
      {{ files.filter((file) => file.url?.startsWith("data:")).length }} ·
      Decoded images: {{ decoded }}
    </p>
    <img
      v-for="file in files.filter((file) =>
        /^(data:|blob:)/.test(file.thumbnailUrl || ''),
      )"
      :key="file.uid"
      :src="file.thumbnailUrl"
      :alt="file.name"
      width="16"
      height="16"
      @load="decoded++"
    />
    <p>
      仅接受图片；单文件 1 MiB、合计 2 MiB、最多 3 个。每个示例均经过
      before-read。
    </p>
    <c-space wrap>
      <c-button @click="probe('valid')">加入小图片</c-button>
      <c-button @click="probe('type')">替换为文本</c-button>
      <c-button @click="probe('size')">替换为超大图片</c-button>
      <c-button @click="probe('total')">加入 768 KiB 图片</c-button>
      <c-button @click="reset">重置队列</c-button>
    </c-space>
    <c-checkbox v-model="pauseThumbnail" edit-mode="direct"
      >暂停本地缩略图 Promise</c-checkbox
    >
    <c-upload
      v-model="files"
      edit-mode="direct"
      :show-upload-button="false"
      :preview="false"
    />
    <p>队列：{{ files.map((file) => file.name).join(", ") || "空" }}</p>
    <p>拒绝原因：{{ reasons.join(", ") || "无" }}</p>
  </div>
</template>
```

## 队列与进度

### 外部管理进度

可直接加入本地示例项观察 40% 的外部进度，再模拟完成。完成操作只更新仍在上传的项；取消项保持 canceled，已删除的项不会重新出现。外部托管模式隐藏内置请求重试按钮，使用“模拟外部重试”恢复取消或失败项，再由业务端完成。示例不发送网络请求。

Example source: src/upload/__demos__/external-state.vue

```vue
<script setup>
import { computed, ref } from "vue";

const files = ref([]);
const hasUploading = computed(() =>
  files.value.some((file) => file.status === "uploading"),
);
const hasRetryable = computed(() =>
  files.value.some((file) => ["error", "canceled"].includes(file.status)),
);
let sequence = 0;

function read(file) {
  file.status = "uploading";
  file.percent = 40;
}

function addExample() {
  const file = new File(
    ["Local external upload demo."],
    `external-${++sequence}.txt`,
    { type: "text/plain" },
  );
  const item = {
    uid: `external-${sequence}`,
    name: file.name,
    size: file.size,
    type: file.type,
    file,
    status: "ready",
    percent: 0,
  };
  read(item);
  files.value = [...files.value, item];
}

function complete() {
  files.value = files.value.map((file) =>
    file.status === "uploading"
      ? { ...file, status: "success", percent: 100 }
      : file,
  );
}

function retry() {
  files.value = files.value.map((file) =>
    ["error", "canceled"].includes(file.status)
      ? { ...file, status: "uploading", percent: 40 }
      : file,
  );
}
</script>

<template>
  <div>
    <p>业务端托管进度和结果；可加入本地示例项，无需选择文件，也不发送请求。</p>
    <c-space wrap>
      <c-button @click="addExample">加入外部上传项</c-button>
      <c-button :disabled="!hasUploading" @click="complete"
        >模拟外部完成</c-button
      >
      <c-button :disabled="!hasRetryable" @click="retry">模拟外部重试</c-button>
    </c-space>
    <c-upload
      v-model="files"
      edit-mode="direct"
      :show-retry-button="false"
      @read="read"
    />
    <p>
      队列状态：{{
        files
          .map((file) => `${file.name}: ${file.status} (${file.percent}%)`)
          .join("；") || "空"
      }}
    </p>
  </div>
</template>
```

### 手动队列和可取消请求

可直接“加入示例文件”，也可选择本地文件；两种方式均不访问网络。点击提交后观察进度，取消会停止活动请求，重试会重新上传。开启“首次请求失败”时，同一文件首次失败、重试成功。活动请求数在完成、取消、失败及离开 Demo 后清零。

Example source: src/upload/__demos__/queue-request.vue

```vue
<script setup lang="ts">
import { onBeforeUnmount, onDeactivated, ref } from "vue";
import type {
  UploadFileItem,
  UploadInstance,
  UploadProgressEvent,
  UploadRequestOptions,
} from "@cedar-design/ui";

const files = ref<UploadFileItem[]>([]);
const uploader = ref<UploadInstance>();
const failOnce = ref(false);
const activeRequests = ref(0);
const timers = new Set<ReturnType<typeof setInterval>>();
const attempts = new Map<string, number>();
const exampleUrls = new Set<string>();
let sequence = 0;

function addExample() {
  const file = new File(
    ["Local upload demo; no network."],
    `example-${++sequence}.txt`,
    { type: "text/plain" },
  );
  const url = URL.createObjectURL(file);
  exampleUrls.add(url);
  files.value = [
    ...files.value,
    {
      uid: `demo-queue-${sequence}`,
      name: file.name,
      size: file.size,
      type: file.type,
      file,
      url,
      status: "ready",
      percent: 0,
    },
  ];
}

function request({
  file,
  onProgress,
  onSuccess,
  onError,
}: UploadRequestOptions) {
  const attempt = (attempts.get(file.uid) ?? 0) + 1;
  attempts.set(file.uid, attempt);
  const reject = failOnce.value && attempt === 1;
  let percent = 0;
  const stop = () => {
    clearInterval(timer);
    timers.delete(timer);
    activeRequests.value = timers.size;
  };
  const timer = setInterval(() => {
    percent += 10;
    onProgress({ percent } as UploadProgressEvent);
    if (percent >= 100) {
      stop();
      if (reject) {
        onError(new Error("Simulated first-attempt failure"));
      } else {
        onSuccess({ ok: true, attempt });
      }
    }
  }, 200);
  timers.add(timer);
  activeRequests.value = timers.size;
  return { abort: stop };
}

function cleanup() {
  uploader.value?.abort();
  timers.forEach((timer) => clearInterval(timer));
  timers.clear();
  activeRequests.value = 0;
}
onBeforeUnmount(() => {
  cleanup();
  exampleUrls.forEach((url) => URL.revokeObjectURL(url));
  exampleUrls.clear();
});
onDeactivated(cleanup);
</script>

<template>
  <div>
    <p>本地模拟请求；支持取消、重试和手动提交，不访问网络。</p>
    <c-checkbox v-model="failOnce" edit-mode="direct"
      >首次请求失败（重试成功）</c-checkbox
    >
    <c-space wrap>
      <c-button @click="addExample">加入示例文件</c-button>
      <c-button @click="uploader?.submit()">提交队列</c-button>
    </c-space>
    <c-upload
      ref="uploader"
      v-model="files"
      edit-mode="direct"
      multiple
      :auto-upload="false"
      :custom-request="request"
    />
    <p>
      队列状态：{{
        files
          .map((file) => `${file.name}: ${file.status} (${file.percent}%)`)
          .join("；") || "空"
      }}
    </p>
    <p>活动请求：{{ activeRequests }}</p>
  </div>
</template>
```

## 异步钩子与请求

### 删除前确认

未勾选时，`before-remove` 拒绝移除并保留文件；勾选后再次删除才更新队列。示例使用本地预置数据，不访问网络。

开启“手动异步确认”后忽略同步允许开关，删除等待“确认删除 / 取消删除”。同一文件等待时重复点击不会新增钩子；取消保留文件，等待中禁用后再确认也不会删除，解除禁用后需重新发起。计数核对列表、等待任务、钩子和 remove 通知；停用或卸载结清本地等待。

With manual async confirmation enabled, the synchronous allow switch is ignored. Repeated removal of a pending file invokes one hook. Cancel keeps the file; resolving after disabling also keeps it, and a fresh removal is required after re-enabling. Counters expose the list, pending tasks, hook calls and remove notifications. Deactivation/unmount settles local tasks without network requests.

新增操作均不访问网络：“异常拒绝删除”拒绝本地Promise，文件保留且后续可重试；“替换同 UID 文件”生成新的本地File，旧删除确认不得移除替换项。“重置上传队列”调用公开reset，旧确认不再产生remove；“激活上传组件”通过KeepAlive停用/恢复Upload，等待任务保留在外层Demo用于手动返回，旧结果不得影响恢复后的实例。停用Upload不等于取消外部业务Promise；离开整个Demo才结清其本地等待。

All extra controls are local. Reject removal rejects the pending Promise, keeps the file and allows a fresh attempt. Replace same UID file creates a new local File; an old confirmation must not remove that replacement. Reset upload queue invokes public reset without a late remove notification. Activate upload suspends/restores Upload through KeepAlive; the outer Demo keeps pending jobs for manual completion, whose old results must stay invalid after activation. Suspending Upload does not physically cancel external business Promises; leaving the whole Demo settles its local jobs.

Example source: src/upload/__demos__/before-remove.vue

```vue
<script setup lang="ts">
import { onBeforeUnmount, onDeactivated, ref, shallowRef } from "vue";
import type { UploadFileItem } from "@cedar-design/ui";

const files = ref<UploadFileItem[]>([
  {
    uid: "sample",
    name: "sample.txt",
    type: "text/plain",
    status: "success",
    percent: 100,
  },
]);
const allow = ref(false);
const manual = ref(false);
const blocked = ref(false);
const attempts = ref(0);
const removed = ref(0);
const uploadRef = ref();
const mounted = ref(true);
const pending = shallowRef<
  Array<{
    resolve: (accepted: boolean) => void;
    reject: (error: Error) => void;
  }>
>([]);
const beforeRemove = () => {
  attempts.value++;
  if (!manual.value) return allow.value;
  return new Promise<boolean>((resolve, reject) => {
    pending.value = [...pending.value, { resolve, reject }];
  });
};
function settle(accepted: boolean | "reject") {
  const jobs = pending.value;
  pending.value = [];
  jobs.forEach((job) =>
    accepted === "reject"
      ? job.reject(new Error("Local removal rejection"))
      : job.resolve(accepted),
  );
}
function replace() {
  files.value = files.value.map((item) => ({
    ...item,
    name: "replacement.txt",
    type: "text/plain",
    file: new File(["local replacement"], "replacement.txt", {
      type: "text/plain",
    }),
  }));
}
function restore() {
  files.value = [
    {
      uid: "sample",
      name: "restored.txt",
      type: "text/plain",
      status: "success",
      percent: 100,
      file: new File(["local sample"], "restored.txt", { type: "text/plain" }),
    },
  ];
}
onBeforeUnmount(() => settle(false));
onDeactivated(() => settle(false));
</script>

<template>
  <section class="remove-confirm-demo">
    <c-checkbox v-model="allow"> 允许此操作</c-checkbox>
    <c-checkbox v-model="manual"> 手动异步确认</c-checkbox>
    <c-checkbox v-model="blocked"> 禁用上传组件</c-checkbox>
    <c-button
      html-type="button"
      :disabled="!pending.length"
      @click="settle(true)"
      >确认删除</c-button
    >
    <c-button
      html-type="button"
      :disabled="!pending.length"
      @click="settle(false)"
      >取消删除</c-button
    >
    <c-button
      html-type="button"
      :disabled="!pending.length"
      @click="settle('reject')"
      >异常拒绝删除</c-button
    >
    <c-button html-type="button" :disabled="!files.length" @click="replace"
      >替换同 UID 文件</c-button
    >
    <c-button html-type="button" @click="uploadRef?.reset()"
      >重置上传队列</c-button
    >
    <c-button html-type="button" @click="restore">恢复示例文件</c-button>
    <c-checkbox v-model="mounted"> 激活上传组件</c-checkbox>
    <KeepAlive>
      <c-upload
        v-if="mounted"
        ref="uploadRef"
        v-model="files"
        :before-remove="beforeRemove"
        :disabled="blocked"
        @remove="removed++"
      />
    </KeepAlive>
    <p role="status">
      文件：{{ files.length }}；等待：{{ pending.length }}；钩子：{{
        attempts
      }}；删除：{{ removed }}
    </p>
  </section>
</template>
```

### 上传前准备与取消竞争

取消后重试合计大小组合：双项进入准备后取消，再次提交会保留四个待返回任务（含两次已失效尝试）。统一返回时仍只启动一次有效请求；超限项保留取消前的原文件和 `canceled` 状态，不误算为新失败或自动恢复为 ready。删除成功项后可再次提交剩余项并成功；旧准备结果不占用额外容量。

合计大小组合：空队列选择“每项替换600B，合计上限1024B”，连续加入两个62B合成图片，再准备并统一完成。每项均满足单文件1024B限制，但两项替换后总量超限，因此只有一项发起本地请求，另一项保留ready原文件并报告max-total-size。删除成功项后，再准备剩余项可成功；重置清空队列、等待和请求计数。此处验证本地before-upload替换，不涉及原生文件选择或真实网络上传。

点击“准备并提交”后，`before-upload` 保持等待；重复提交不会重复创建同一尝试。取消准备后可以再次提交，再点击“完成准备”同时返回旧、新结果，只有当前有效尝试能发起请求。选择文本或超大图片替换时会再次检查类型和 1 KiB 大小限制，拒绝后保持 ready，可改为有效副本后重试。本示例使用公开 useUploader 和本地即时请求，不访问网络；重置、停用和卸载会释放等待任务。

Example source: src/upload/__demos__/prepare-request.vue

```vue
<script setup>
import { onBeforeUnmount, onDeactivated, ref } from 'vue'
import { useUploader } from '@cedar-design/ui'

const files = ref([])
const reasons = ref([])
const mode = ref('valid')
const preparing = ref(0)
const requestCount = ref(0)
const pending = new Set()
const modes = [
  { label: '有效副本', value: 'valid' },
  { label: '替换为文本', value: 'type' },
  { label: '替换为超大图片', value: 'size' },
  { label: '每项替换600B，合计上限1024B', value: 'total' },
]
let sequence = 0

function beforeUpload(file) {
  return new Promise((resolve) => {
    pending.add({ file, resolve })
    preparing.value = pending.size
  })
}

const uploader = useUploader({
  modelValue: () => files.value,
  onUpdateModelValue: (value) => {
    files.value = value
  },
  accept: () => 'image/*',
  maxFileSize: () => 1024,
  maxFiles: () => mode.value === 'total' ? 2 : 1,
  maxTotalSize: () => 1024,
  resolveType: () => 'file',
  autoUpload: () => false,
  beforeUpload: () => beforeUpload,
  customRequest:
    () =>
    ({ onSuccess }) => {
      requestCount.value++
      onSuccess({ ok: true })
    },
  onRejected: (items) => {
    reasons.value = items.map((item) => item.reason)
  },
})

function add() {
  const svg = '<svg xmlns="http://www.w3.org/2000/svg" width="1" height="1"/>'
  return uploader.addFiles([new File([svg], `prepare-${++sequence}.svg`, { type: 'image/svg+xml' })])
}

function submit() {
  reasons.value = []
  return uploader.submit()
}

function finish() {
  const jobs = [...pending]
  pending.clear()
  preparing.value = 0
  jobs.forEach(({ file, resolve }) => {
    const raw = file.file
    if (mode.value === 'type') {
      resolve(new File(['text'], 'replacement.txt', { type: 'text/plain' }))
    } else if (mode.value === 'size') {
      resolve(new File([new Uint8Array(1025)], raw.name, { type: raw.type }))
    } else if (mode.value === 'total') {
      resolve(new File([new Uint8Array(600)], raw.name, { type: raw.type }))
    } else {
      resolve(new File([raw], raw.name, { type: raw.type }))
    }
  })
}

function cleanup() {
  uploader.abort()
  pending.forEach(({ resolve }) => resolve(false))
  pending.clear()
  preparing.value = 0
}

function reset() {
  cleanup()
  uploader.reset()
  reasons.value = []
  requestCount.value = 0
}
onBeforeUnmount(cleanup)
onDeactivated(cleanup)
</script>

<template>
  <div class="upload-prepare-demo">
    <p>提交后暂停 before-upload；可取消后再次提交，再统一完成准备，只有当前有效尝试可以发起本地请求。</p>
    <c-radio-group v-model="mode" :options="modes" />
    <c-space wrap>
      <c-button :disabled="files.length >= (mode === 'total' ? 2 : 1)" @click="add">加入示例图片</c-button>
      <c-button :disabled="!files.some((file) => ['ready', 'error', 'canceled'].includes(file.status))" @click="submit"
        >准备并提交</c-button
      >
      <c-button :disabled="preparing === 0" @click="uploader.abort()">取消准备</c-button>
      <c-button :disabled="preparing === 0" @click="finish">完成准备</c-button>
      <c-button @click="reset">重置队列</c-button>
    </c-space>
    <c-upload v-model="files" :show-upload-button="false" :show-retry-button="false" :preview="false" />
    <p>待返回准备任务：{{ preparing }}</p>
    <p>请求次数：{{ requestCount }}</p>
    <p>队列状态：{{ files.map((file) => `${file.status} (${file.percent}%)`).join(', ') || '空' }}</p>
    <p>队列字节：{{ files.map((file) => file.size).join(', ') || '0' }}</p>
    <p>拒绝原因：{{ reasons.join(', ') || '无' }}</p>
  </div>
</template>
```

### 异步请求元数据

填写你控制的本地接收接口后，分别手动返回 headers 和 data，观察默认 XHR 的准备与取消。只返回一项时仍不发送；取消后再返回另一项不得启动请求。成功响应显示在示例下方，可由接收端核对 `X-Demo-Upload`、`auditMarker` 和 `attachment` 文件字段。接口地址默认留空，不预设外部上传服务；接收器必须允许文档站来源的 CORS。本例仅使用生成的合成文本，不选择真实文件。

使用“拒绝 headers / 拒绝 data”模拟准备失败，当前尝试只进入一次 error。可在另一项旧 Promise 未结清时重试，观察旧结果不会覆盖新尝试；取消后再拒绝不增加错误计数。返回/拒绝按钮会结清该类所有等待任务（包括旧尝试），便于验证竞争；重置会释放等待任务。准备失败不等同 HTTP 错误。

Example source: src/upload/__demos__/metadata-request.vue

```vue
<script setup>
import { onBeforeUnmount, onDeactivated, ref, shallowRef } from "vue";
import { useUploader } from "@cedar-design/ui";
const endpoint = ref("");
const files = ref([]);
const headers = shallowRef([]);
const data = shallowRef([]);
const successes = ref(0);
const errors = ref(0);
const response = ref(null);
let sequence = 0;
function wait(queue, file) {
  return new Promise((resolve, reject) => {
    queue.value = [...queue.value, { file, resolve, reject }];
  });
}
function finish(queue, kind) {
  const jobs = queue.value;
  queue.value = [];
  jobs.forEach((job) =>
    job.resolve(
      kind === "headers"
        ? { "X-Demo-Upload": job.file.name }
        : { auditMarker: "audit-local" },
    ),
  );
}
const uploader = useUploader({
  modelValue: () => files.value,
  onUpdateModelValue: (value) => {
    files.value = value;
  },
  action: () => endpoint.value,
  headers: () => (file) => wait(headers, file),
  data: () => (file) => wait(data, file),
  name: () => "attachment",
  autoUpload: () => false,
  resolveType: () => "file",
  onSuccess: (file) => {
    successes.value++;
    response.value = file.response;
  },
  onError: () => {
    errors.value++;
  },
});
function add() {
  return uploader.addFiles([
    new File(["Synthetic upload audit only."], `metadata-${++sequence}.txt`, {
      type: "text/plain",
    }),
  ]);
}
function cleanup() {
  uploader.abort();
  finish(headers, "headers");
  finish(data, "data");
}
function finishHeaders() {
  finish(headers, "headers");
}
function finishData() {
  finish(data, "data");
}
function rejectHeaders() {
  rejectPending(headers, "headers");
}
function rejectData() {
  rejectPending(data, "data");
}
function rejectPending(queue, kind) {
  const jobs = queue.value;
  queue.value = [];
  jobs.forEach((job) => job.reject(new Error(`Synthetic ${kind} rejection`)));
}
function reset() {
  cleanup();
  uploader.reset();
  successes.value = 0;
  errors.value = 0;
  response.value = null;
}
onBeforeUnmount(cleanup);
onDeactivated(cleanup);
</script>
<template>
  <section class="metadata-upload-demo">
    <p>
      默认 XHR 请求；先配置你控制的本地接口。headers 与 data
      分别等待手动返回，默认不访问任何地址。
    </p>
    <label
      >Local upload endpoint
      <c-input v-model="endpoint" placeholder="http://127.0.0.1:4197/upload"
    /></label>
    <c-space wrap>
      <c-button :disabled="files.length > 0" @click="add"
        >加入合成文件</c-button
      >
      <c-button
        :disabled="
          !endpoint ||
          !files.some((file) =>
            ['ready', 'error', 'canceled'].includes(file.status),
          )
        "
        @click="uploader.submit()"
        >提交元数据请求</c-button
      >
      <c-button
        :disabled="!files.some((file) => file.status === 'uploading')"
        @click="uploader.abort()"
        >取消元数据请求</c-button
      >
      <c-button :disabled="!headers.length" @click="finishHeaders"
        >返回 headers</c-button
      >
      <c-button :disabled="!data.length" @click="finishData"
        >返回 data</c-button
      >
      <c-button :disabled="!headers.length" @click="rejectHeaders"
        >拒绝 headers</c-button
      >
      <c-button :disabled="!data.length" @click="rejectData"
        >拒绝 data</c-button
      >
      <c-button @click="reset">重置元数据示例</c-button>
    </c-space>
    <c-upload
      v-model="files"
      :show-upload-button="false"
      :show-retry-button="false"
      :preview="false"
    />
    <p role="status">
      headers 等待：{{ headers.length }}；data 等待：{{ data.length }}；成功：{{
        successes
      }}；错误：{{ errors }}
    </p>
    <p>
      模型：{{
        files.map((file) => file.name + ": " + file.status).join(", ") || "空"
      }}
    </p>
    <pre>{{ response }}</pre>
  </section>
</template>
```

### 请求句柄迟到与取消

本地模拟 custom-request 返回 Promise。取消后再返回旧句柄会立即调用其 abort；返回旧成功回调不会恢复已取消项。取消后再次发起、统一返回句柄和成功回调时，只接受当前尝试一次。计数展示回调是否被内核接受，不代表真实传输；本例不访问网络，重置/停用/卸载释放本地等待。

Example source: src/upload/__demos__/late-request.vue

```vue
<script setup>
import { onBeforeUnmount, onDeactivated, ref, shallowRef } from 'vue'
import { useUploader } from '@cedar-design/ui'

const files = ref([])
const handles = shallowRef([])
const callbacks = shallowRef([])
const requests = ref(0)
const aborts = ref(0)
const accepted = ref(0)
let sequence = 0
let generation = 0
const uploader = useUploader({
  modelValue: () => files.value,
  onUpdateModelValue: value => { files.value = value },
  resolveType: () => 'file',
  autoUpload: () => false,
  customRequest: () => options => {
    const current = generation
    requests.value++
    callbacks.value = [...callbacks.value, options]
    return new Promise(resolve => {
      handles.value = [...handles.value, {
        resolve: () => resolve({ abort: () => { if (current === generation) aborts.value++ } }),
      }]
    })
  },
  onSuccess: () => { accepted.value++ },
})
function add() {
  return uploader.addFiles([new File(['Local delayed transport; no network.'], `late-${++sequence}.txt`, { type: 'text/plain' })])
}
function release() {
  const pending = handles.value
  handles.value = []
  pending.forEach(job => job.resolve())
}
function complete() {
  const pending = callbacks.value
  callbacks.value = []
  pending.forEach(options => options.onSuccess({ local: true }))
}
function cleanup() {
  generation++
  uploader.abort()
  release()
  callbacks.value = []
}
function reset() {
  cleanup()
  uploader.reset()
  requests.value = 0
  aborts.value = 0
  accepted.value = 0
}
onBeforeUnmount(cleanup)
onDeactivated(cleanup)
</script>

<template>
  <section class="late-upload-demo">
    <p>请求句柄延迟返回；先取消再返回句柄，旧句柄应立即 abort，迟到成功回调不能恢复取消项。不访问网络。</p>
    <c-space wrap>
      <c-button :disabled="files.length > 0" @click="add">加入本地文件</c-button>
      <c-button :disabled="!files.some(file => ['ready', 'error', 'canceled'].includes(file.status))" @click="uploader.submit()">发起模拟请求</c-button>
      <c-button :disabled="!files.some(file => file.status === 'uploading')" @click="uploader.abort()">取消模拟请求</c-button>
      <c-button :disabled="!handles.length" @click="release">返回所有句柄</c-button>
      <c-button :disabled="!callbacks.length" @click="complete">返回所有成功回调</c-button>
      <c-button @click="reset">重置模拟</c-button>
    </c-space>
    <c-upload v-model="files" :show-upload-button="false" :show-retry-button="false" :preview="false" />
    <p role="status">句柄等待：{{ handles.length }}；发起：{{ requests }}；abort：{{ aborts }}；有效成功：{{ accepted }}</p>
    <p>模型：{{ files.map(file => file.name + ': ' + file.status).join(', ') || '空' }}</p>
  </section>
</template>
```

## API

### 空值识别与阅读空文案

`empty-values` 用于空值识别，`empty-value` 保留原清空输出；`empty-text` 仅在 `read-pretty` 空内容下展示，默认 `'-'`，字段 > FormItem > Form，自定义 read 插槽优先。显式配置 empty-values 后，内置 required 接入该策略，自定义校验仍收到原值。详见[统一说明](llms/zh-CN/guide/empty-values.md)。

| 参数         | 类型               | 缺省与范围                                            |
| ------------ | ------------------ | ----------------------------------------------------- |
| empty-values | readonly unknown[] | 字段 > FormItem > Form > 组件族默认；完整覆盖，不合并 |
| empty-text   | string             | 字段 > FormItem > Form > '-'；显式 '' 有效            |

以上是字段展示层 API；纯面板不因此新增阅读模式。Form 与 FormItem 提供继承配置。empty-value 的现有类型与默认输出仍按该组件原 API 执行。

### Props

| 属性                                                         | 类型                                                     | 默认值/说明                                       |
| ------------------------------------------------------------ | -------------------------------------------------------- | ------------------------------------------------- |
| model-value / default-value                                  | UploadFileItem[]                                         | 受控值 / 非受控初值[]                             |
| accept / capture                                             | string / 原生capture                                     | 未指定                                            |
| multiple / directory / draggable                             | boolean                                                  | false                                             |
| disabled / readonly                                          | boolean                                                  | undefined，继承Form，显式false优先                |
| action / method                                              | string                                                   | 无 / post                                         |
| headers / data                                               | object 或 async(file) => object                          | 请求准备阶段仍可取消                              |
| name                                                         | string / (file) => string                                | file                                              |
| with-credentials                                             | boolean                                                  | false                                             |
| custom-request                                               | (UploadRequestOptions) => UploadRequest / Promise / void | 自定义transport，可返回abort                      |
| auto-upload                                                  | boolean                                                  | true；必须同时有action或custom-request才启动      |
| max-files / max-file-size / max-total-size                   | number                                                   | 未指定；大小单位字节，max-files>0生效             |
| resolve-type                                                 | file / data-url / object-url                             | object-url；所有文件生成url，图片生成thumbnailUrl |
| create-thumbnail-url                                         | (options) => string / Promise                            | 自定义URL归调用方所有，不自动回收                 |
| before-add                                                   | async(files) => File[]                                   | 批次筛选/替换                                     |
| before-read                                                  | async(file) => boolean / File                            | false/reject拒绝；替换后重新校验                  |
| before-upload                                                | async(item) => boolean / File / Blob                     | false/reject取消准备；替换后重新校验              |
| before-remove                                                | async(item,list) => boolean                              | false/reject不删除                                |
| is-success-response                                          | (xhr,item) => boolean                                    | 默认HTTP2xx                                       |
| request-choose                                               | (chooseFile,event) => void / Promise                     | 接管选择入口，异常不会自动打开文件框              |
| list-type                                                    | text / picture / picture-card                            | text，两端均支持                                  |
| image-fit                                                    | fill / contain / cover / none / scale-down               | cover；item.fit优先                               |
| preview                                                      | boolean                                                  | true                                              |
| show-file-list / show-upload-button / show-remove-button     | boolean                                                  | true                                              |
| show-retry-button / show-cancel-button / show-preview-button | boolean                                                  | true                                              |
| show-download-button                                         | boolean                                                  | false；禁用时不可操作                             |
| elevation / ripple                                           | boolean或number / boolean                                | false / true                                      |

UploadFileItem 的 uid、status、percent 必填，name/size/type/file/url/thumbnailUrl/fit/response/error 可选。status为ready/reading/uploading/success/error/canceled/removed。

### Events

- update:model-value(files)，change(files, changedFile?)：队列提议顺序，Form每次change仅一次。进度与状态更新也属于change。
- read(item)：读取完成，可自行接管业务上传；不是服务端成功。
- rejected(UploadRejectedFile[])：reason为accept/before-add/before-read/read-error/max-file-size/max-total-size/max-files。
- exceed(nativeFiles, acceptedList)：超过数量时通知。
- progress(item,event?)、success(item)、error(item)：当前有效请求通知；旧请求/取消回调不生效。
- remove(item)：通过删除钩子后的删除提议。
- preview(item, UploadPreviewEvent)：调用event.preventDefault()取消内建图片/视频预览；程序调用也可取消，originalEvent可选。

### Slots

- trigger({chooseFile,dragOver,disabled})：自定义选择入口。
- item({file,index,remove,retry,abort})：自定义整项。
- remove-button({file,index,remove,retry,abort})：自定义删除操作。

### Expose

chooseFile()、submit(file?)、abort(file?)、retry(file)、remove(file)、reset()、clearSuccess()、clearError()、getFiles(status?)、preview(file)、closePreview()。useUploader(options)提供同源无UI逻辑，另有addFiles(files)和input/drag处理接口。

### 受控与生命周期

受控父级拒绝新增时只发读取与列表提议，不自动上传；后续父级接受该uid才会自动上传一次。同tick提议事务合并，跨tick仍以实际父级列表为真源，拒绝项目不占总大小；父级负责迟到列表替换的一致性。显式remove未接受项、reset或卸载会释放其生成URL；任意外部URL不会被回收。内建预览保留自己的URL使用权至关闭，不关闭其他组件后来打开的预览。

取消覆盖before-upload、异步headers/data/name及异步custom-request句柄阶段；重试和外部同uid换File令旧回调失效。before-read和before-upload的替换会复查限制，max-total-size只累计已接受项及当前正在准备的合法批次/请求。禁用/只读禁止选择、移除、提交等更改；只读允许预览/下载。KeepAlive停用取消当前准备/请求，恢复后允许新操作。

## 类型定义

UploadProps、UploadEmits、UploadSlots、UploadExpose、UploadPublicMethods、UploadFileItem、UploadStatus、UploadListType、UploadResolveType、UploadImageFit、UploadCapture、UploadRejectedFile、UploadRejectedReason、UploadRequestOptions、UploadRequest、UploadCustomRequest、UploadProgressEvent、UploadData、UploadHeaders、UploadBeforeRead、UploadBeforeUpload、UploadBeforeRemove、UploadCreateThumbnailUrl、UploadIsSuccessResponse、UploadRequestChoose、UploadPreviewEvent、UseUploaderOptions、UploadInstance。

## 样式变量

两端公共后缀一致，所有默认值见下表（前缀分别为c/mp）。

| 变量                                    | 默认值                                   |
| --------------------------------------- | ---------------------------------------- |
| --c-upload-gap                          | var(--c-sys-space-4)                     |
| --c-upload-trigger-min-height           | var(--c-sys-control-height-md)           |
| --c-upload-trigger-padding-horizontal   | var(--c-sys-space-6)                     |
| --c-upload-trigger-draggable-min-height | calc(var(--c-sys-control-height-md) * 2) |
| --c-upload-card-size                    | calc(var(--c-sys-control-height-md) * 2) |
| --c-upload-item-min-height              | var(--c-sys-control-height-md)           |
| --c-upload-item-padding                 | var(--c-sys-space-4)                     |
| --c-upload-thumb-size                   | var(--c-sys-control-height-lg)           |
| --c-upload-border-radius                | var(--c-sys-radius-md)                   |
| --c-upload-border-color                 | var(--c-sys-color-border-default)        |
| --c-upload-background                   | var(--c-sys-color-surface-default)       |
| --c-upload-text-color                   | var(--c-sys-color-content-primary)       |
| --c-upload-secondary-text-color         | var(--c-sys-color-content-secondary)     |
| --c-upload-hover-background             | var(--c-sys-color-state-hover)           |
| --c-upload-active-color                 | var(--c-sys-color-action-primary)        |
| --c-upload-error-color                  | var(--c-sys-color-content-danger)        |
| --c-upload-action-size                  | var(--c-sys-control-touch-target)        |
| --c-upload-progress-height              | var(--c-sys-space-2)                     |
| --c-upload-disabled-opacity             | .56                                      |
| --c-upload-font-size                    | var(--c-sys-font-size-md)                |

### Form 字段展示与确认

本组件支持 `edit-mode`，字段 > FormItem > Form 逐层继承；未指定时为 `direct`，保留原有交互。支持值：`direct / click / dblclick`。非 direct 编辑模式通过字段值入口打开编辑面板，并维护单份草稿；确认后才更新 v-model，取消、重置或启用 readPretty 时丢弃草稿。

Cedar 使用 edit-mode="click" / "dblclick" 在字段附近打开编辑浮层，Enter/F2 也可进入；取消/Escape 丢弃草稿，确认后提交。readPretty 为独立阅读属性，与 readonly、disabled 分开。

`before-commit(value, { previousValue, signal })` 可拦截弹层保存；FormItem 先校验候选值，失败保持编辑。`open / default-open / update:open` 控制编辑层。`#read="{ value, text }"` 可自定义阅读内容。集中示例见 Form 的“各类字段统一展示”。

附件确认提交的是文件列表关系，无法撤销已经发生的远程上传或永久删除；需要延迟网络副作用时配置 `auto-upload="false"`，由业务在最终提交后执行上传。

`read-pretty` 为独立布尔属性，与 `readonly`、`disabled` 同级；字段 > FormItem > Form 继承，显式 `false` 覆盖父级。默认 `false`。纯阅读不显示编辑器。

## 覆盖附件和视频时长

`reupload` 默认 false，开启逐项替换。`replace(file, replacement?: File): Promise<void>` 打开单文件选择器或校验传入 File。替换先校验读取和限制，再调用 beforeRemove；数量/总大小扣除旧项。取消、校验失败、守卫拒绝与目标过期均保留旧项。通过后以新 UID 在原位提出模型更新，发出 `replace(next, previous)`、change，不发出 remove，不删除服务端文件。受控父级接纳后旧请求失效，新请求失败可重试。item 插槽暴露 replace()。

`UploadFileItem.duration?: number` 为秒，显示 mm:ss / h:mm:ss；未知或无效时隐藏。元数据仅尝试读取本地 File，最多等待 5 秒，并清理临时资源。远端回显由业务提供 duration。视频预览使用 popupContainer。

时长角标公开变量：`--c-upload-duration-background: var(--c-sys-color-surface-tooltip)`、`--c-upload-duration-color: var(--c-sys-color-content-on-dark)`、`--c-upload-duration-radius: var(--c-sys-radius-sm)`、`--c-upload-duration-padding: var(--c-sys-space-1) var(--c-sys-space-2)`、`--c-upload-duration-font-size: var(--c-sys-font-size-sm)`。

### 守卫等待反馈

before-* 等待期间显示加载反馈并标记 aria-busy；拒绝或失败后恢复，重复提交不再启动同一操作。普通事件返回的 Promise 不参与加载。不同文件保持并发，加载反馈汇总所有当前守卫任务，不把普通 change/progress 事件当成任务。

`useUploader()` 新增只读 `guardPending`，汇总当前 before 钩子的等待状态；它不代表文件上传进度。

---

Document: llms/zh-CN/components/verification-code.md

<!-- Source: src/verification-code/README.md; locale: zh-CN; page: /components/verification-code/ -->

# VerificationCode 验证码

独立维护的跨端同源验证码输入，支持短信自动填充、格式化和表单继承。

## 基础示例

### 基础输入

Example source: src/verification-code/__demos__/basic.vue

```vue
<script setup>
import { ref } from 'vue'

const code = ref('')
</script>
<template>
  <div class="verification-demo">
    <c-verification-code v-model="code" aria-label="验证码" />
    <p>当前值：{{ code || '未输入' }}</p>
  </div>
</template>
<style scoped>
.verification-demo {
  max-width: 420px;
}
</style>
```

## 外观与状态

### 变体与掩码

<!-- demo-config-notes:start -->

#### 本组配置对照

| 配置            | 作用                            | 相关示例                     |
| --------------- | ------------------------------- | ---------------------------- |
| `default-value` | `非受控初值`                    | 变体与掩码、只读、禁用和错误 |
| `length`        | `正整数格数（按 Unicode 码点）` | 变体与掩码、外观组合         |
| `aria-label`    | `组名和每格的序号名称`          | 变体与掩码、只读、禁用和错误 |
| `masked`        | `仅视觉隐藏字符，不是加密`      | 变体与掩码                   |
| `mask-symbol`   | `取首个 Unicode 码点`           | 变体与掩码                   |
| `variant`       | `输入外观`                      | 变体与掩码                   |

<!-- demo-config-notes:end -->

Example source: src/verification-code/__demos__/appearance.vue

```vue
<template>
  <div class="verification-demo">
    <c-verification-code
      default-value="1234"
      :length="4"
      masked
      mask-symbol="*"
      aria-label="掩码验证码"
    /><c-verification-code
      default-value="1234"
      :length="4"
      variant="filled"
      size="lg"
      align="start"
      :gutter="12"
      aria-label="填充验证码"
    /><c-verification-code
      default-value="12"
      :length="4"
      variant="standard"
      focus-color="#6750a4"
      aria-label="线条验证码"
    />
  </div>
</template>
<style scoped>
.verification-demo {
  display: flex;
  flex-direction: column;
  gap: 20px;
  max-width: 420px;
}
</style>
```

### 外观组合

适用于分格验证码输入。调整变体、尺寸，用相同数据观察变化。内容保持一致，便于比较不同设置的实际效果。

Example source: src/verification-code/__demos__/appearance-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref("123456");
const __demoAppearance = __demoReactive({ variant: "filled", size: "md" });

import { computed as demoComputed, ref as demoRef } from 'vue'
const demoCompareFields = [{"name":"variant","values":["filled","outline","standard"]},{"name":"size","values":["xs","sm","md","lg","xl"]}]
const demoCompareAxis = demoRef("variant")
const demoComparedOptions = demoComputed(() => demoCompareFields.find(field => field.name === demoCompareAxis.value)?.values ?? [])
</script>
<template>
  <c-space direction="column" :size="16">
    <c-form layout="vertical">
      <c-form-item layout="vertical" size="sm" label="variant">
        <c-radio-group
          v-model="__demoAppearance['variant']"
          aria-label="variant"
          :options="[
            { label: 'filled', value: 'filled' },
            { label: 'outline', value: 'outline' },
            { label: 'standard', value: 'standard' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
      <c-form-item layout="vertical" size="sm" label="size">
        <c-radio-group
          v-model="__demoAppearance['size']"
          aria-label="size"
          :options="[
            { label: 'xs', value: 'xs' },
            { label: 'sm', value: 'sm' },
            { label: 'md', value: 'md' },
            { label: 'lg', value: 'lg' },
            { label: 'xl', value: 'xl' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
    </c-form>
    <p class="demo-config-comparison-hint"><span lang="zh-CN">选择一个对比维度；其他配置和内容保持一致。输入类示例共享同一个值，便于比较外观。</span><span lang="en-US">Compare one dimension while keeping the other settings and content identical. Input specimens share the same value.</span></p>
<c-radio-group v-model="demoCompareAxis" aria-label="Compare configuration" :options="demoCompareFields.map(field => ({ label: field.name, value: field.name }))" />
<div class="demo-config-comparison">
<section v-for="sample in demoComparedOptions" :key="String(sample)">
<p><code>{{ demoCompareAxis }}={{ sample }}</code></p>
<c-verification-code
      v-model="value"
      :length="6"
      v-bind="{ ...__demoAppearance, [demoCompareAxis]: sample }"
    ></c-verification-code>
</section>
</div>
  </c-space>
</template>

<style scoped>
.demo-config-comparison { display: grid; grid-template-columns: repeat(auto-fit, minmax(min(100%, 220px), 1fr)); gap: 20px; min-width: 0; max-width: 100%; }
.demo-config-comparison > section { min-width: 0; }
.demo-config-comparison p { margin: 0 0 8px; }
html:not([lang='en-US']) .demo-config-comparison-hint > [lang='en-US'],
html[lang='en-US'] .demo-config-comparison-hint > [lang='zh-CN'] { display: none; }
</style>
```

### 只读、禁用和错误

Example source: src/verification-code/__demos__/states.vue

```vue
<template>
  <div class="verification-demo">
    <c-verification-code default-value="123456" readonly aria-label="只读验证码" /><c-verification-code
      default-value="123456"
      disabled
      aria-label="禁用验证码"
    /><c-verification-code default-value="12" error aria-label="错误验证码" />
  </div>
</template>
<style scoped>
.verification-demo {
  display: flex;
  flex-direction: column;
  gap: 20px;
  max-width: 420px;
}
</style>
```

## 数据与选项

### 粘贴、格式化和分隔符

<!-- demo-config-notes:start -->

#### 本组配置对照

| 配置              | 作用                                                                      | 相关示例             |
| ----------------- | ------------------------------------------------------------------------- | -------------------- |
| `type`            | `字符集合`                                                                | 粘贴、格式化和分隔符 |
| `paste-transform` | `粘贴预处理，先于 type 与 formatter`                                      | 粘贴、格式化和分隔符 |
| `formatter`       | `逐字符格式化，false 拒绝，true/undefined 保持；返回字符串取首个合法码点` | 粘贴、格式化和分隔符 |
| `aria-label`      | `组名和每格的序号名称`                                                    | 粘贴、格式化和分隔符 |

<!-- demo-config-notes:end -->

Example source: src/verification-code/__demos__/formatting.vue

```vue
<script setup>
import { ref } from 'vue'

const code = ref('')
const transform = (value) => value.replace(/[-\s]/g, '').toUpperCase()
</script>
<template>
  <div class="verification-demo">
    <p>可粘贴 ab-12-cd；从当前格开始写入。</p>
    <c-verification-code
      v-model="code"
      type="alphanumeric"
      :paste-transform="transform"
      :formatter="(char) => char.toUpperCase()"
      aria-label="字母数字验证码"
      ><template #separator="{ index }"><span v-if="index === 2">−</span></template></c-verification-code
    >
    <p>{{ code }}</p>
  </div>
</template>
<style scoped>
.verification-demo {
  max-width: 420px;
}
</style>
```

## 交互与控制

### 交互状态切换

适用于分格验证码输入。调整禁用、只读、错误反馈，用相同数据观察变化。控制区始终可用，可以随时恢复编辑；错误外观本身不会触发表单校验。

Example source: src/verification-code/__demos__/state-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref("123456");
const __demoState = __demoReactive({
  disabled: false,
  readonly: false,
  error: false,
});
</script>
<template>
  <c-space direction="column" :size="16">
    <c-space wrap>
      <c-checkbox v-model="__demoState['disabled']">disabled</c-checkbox>
      <c-checkbox v-model="__demoState['readonly']">readonly</c-checkbox>
      <c-checkbox v-model="__demoState['error']">error</c-checkbox>
    </c-space>
    <c-verification-code
      v-model="value"
      :length="6"
      v-bind="__demoState"
    ></c-verification-code>
  </c-space>
</template>
```

## 阅读方向

继承最近的 `dir="ltr|rtl"`，支持运行时切换与局部覆盖。验证码是 LTR 内容区域，按原字符串顺序展示、粘贴和移动焦点；外围 align 的 start/end 仍随阅读方向。RTL 不会将验证码字符倒序，数字与文字验证码使用相同的顺序契约。

## API

### 空值识别与阅读空文案

`empty-values` 用于空值识别，`empty-value` 保留原清空输出；`empty-text` 仅在 `read-pretty` 空内容下展示，默认 `'-'`，字段 > FormItem > Form，自定义 read 插槽优先。显式配置 empty-values 后，内置 required 接入该策略，自定义校验仍收到原值。详见[统一说明](llms/zh-CN/guide/empty-values.md)。

| 参数         | 类型               | 缺省与范围                                            |
| ------------ | ------------------ | ----------------------------------------------------- |
| empty-values | readonly unknown[] | 字段 > FormItem > Form > 组件族默认；完整覆盖，不合并 |
| empty-text   | string             | 字段 > FormItem > Form > '-'；显式 '' 有效            |

以上是字段展示层 API；纯面板不因此新增阅读模式。Form 与 FormItem 提供继承配置。empty-value 的现有类型与默认输出仍按该组件原 API 执行。

### Props

| 属性                                    | 说明                                                                      | 类型                                            | 默认值           |
| --------------------------------------- | ------------------------------------------------------------------------- | ----------------------------------------------- | ---------------- |
| `model-value`                           | `受控整码`                                                                | `string`                                        | `undefined`      |
| `default-value`                         | `非受控初值`                                                              | `string`                                        | `''`             |
| `length`                                | `正整数格数（按 Unicode 码点）`                                           | `number`                                        | `6`              |
| `type`                                  | `字符集合`                                                                | `digit / text / alphanumeric`                   | `digit`          |
| `size`                                  | `五档外壳尺寸`                                                            | `xs / sm / md / lg / xl`                        | `继承 / md`      |
| `variant`                               | `输入外观`                                                                | `filled / outline / standard`                   | `继承 / outline` |
| `disabled / readonly / error`           | `状态，显式值优先于 Form`                                                 | `boolean`                                       | `undefined`      |
| `masked`                                | `仅视觉隐藏字符，不是加密`                                                | `boolean`                                       | `false`          |
| `mask-symbol`                           | `取首个 Unicode 码点`                                                     | `string`                                        | `•`              |
| `autofocus`                             | `挂载后聚焦首个空格`                                                      | `boolean`                                       | `false`          |
| `gutter`                                | `格间距，number 为 px`                                                    | `number / string`                               | `组件 token`     |
| `align`                                 | `水平对齐`                                                                | `start / center / end`                          | `center`         |
| `allow-paste`                           | `是否允许粘贴，false 阻止原生粘贴`                                        | `boolean`                                       | `true`           |
| `paste-transform`                       | `粘贴预处理，先于 type 与 formatter`                                      | `(text: string) => string`                      | `undefined`      |
| `formatter`                             | `逐字符格式化，false 拒绝，true/undefined 保持；返回字符串取首个合法码点` | `(character, index, value) => string / boolean` | `undefined`      |
| `separator`                             | `非最后格后面的分隔内容`                                                  | `(index, character) => VNodeChild`              | `undefined`      |
| `aria-label`                            | `组名和每格的序号名称`                                                    | `string`                                        | `undefined`      |
| `text-color / focus-color / blur-color` | `逐实例动态颜色，静态主题优先 token`                                      | `string`                                        | `undefined`      |

### Events

| 事件               | 参数                    | 语义                                                                   |
| ------------------ | ----------------------- | ---------------------------------------------------------------------- |
| input              | character, index, event | 每次有效原生输入提议的起始字符与零基索引                               |
| update:model-value | value                   | 整码提议                                                               |
| change             | value                   | 每次有效编辑的整码提议，不等同于受控父级接受                           |
| finish             | value                   | 修改后的整码被接受且填满；已满后再次修改并接受也触发，不由外部赋值触发 |
| paste              | text, event             | 经 paste-transform 与 type 处理的粘贴文本                              |
| focus / blur       | FocusEvent              | 进入/离开整个组件，格间切换不重复通知                                  |
| click              | MouseEvent              | 非禁用点击                                                             |

有效输入顺序是 input → update:modelValue → change，父级在本轮渲染接受完整值后才发 finish。拒绝的受控值会恢复原生输入；若父级异步接受，后续单独的模型赋值不会补发 finish。reset() 提议空值，发 update:modelValue / change，不模拟原生 input。禁用、只读及组合输入时 reset 不修改值。

粘贴从当前格开始覆盖，根元素的粘贴从第 1 格开始；超出首个空格的输入会归到首个空格。短信自动填充一次输入整码也会分配到后续格。已填格中单字符键入总是替换当前格，即使光标位于旧字符末尾；输入法优先使用本次 compositionend 提交文本（支持多码点分配），事件缺失提交文本时才回退原生值。type 过滤 → formatter → 长度裁剪，拒绝字符不占格。text 按 Unicode 码点（不是字素簇）计数。修改外部值只影响显示，不自动格式化写回。

### Slots

| 插槽      | 参数                 | 说明                                      |
| --------- | -------------------- | ----------------------------------------- |
| separator | { index, character } | 优先于 separator Prop；不在最后一格后渲染 |

### Expose

- focus(index?)：零基索引；省略时定位首个空格，满码定位末格。disabled 时不聚焦，readonly 可聚焦复制。
- blur()：移出焦点。
- reset()：提议清空，仍遵守受控模型及禁用/只读状态。

### 键盘与表单

左右方向键切换格；Backspace 删除当前字符，空格时删除前一个；Delete 删除当前字符；删除后后续字符前移。IME 组合期间不裁剪、不删除、不跳焦。每个原生 input 有独立 SSR 稳定 id，第 1 格 autocomplete=one-time-code，其余 off。请提供 aria-label。

继承 InputGroup/Form 状态，显式 disabled/readonly/error/size 优先；内部每格 Input 不重复通知 Form，整体每次编辑仅通知一次 input/change。三种 variant 和五档 size 两端均实现；尺寸来自本库 FieldDecorator token。

## 类型定义

VerificationCodeProps、VerificationCodeType、VerificationCodeAlign、VerificationCodeVariant、VerificationCodeFormatter、VerificationCodeSeparator、VerificationCodeEmits、VerificationCodeSlots、VerificationCodeExpose、VerificationCodeInstance。

## 样式变量

| 变量                                  | 默认值               | 说明                                      |
| ------------------------------------- | -------------------- | ----------------------------------------- |
| --c-verification-code-gutter          | var(--c-sys-space-2) | 格间距                                    |
| --c-verification-code-cell-height     | initial              | 未覆盖时随 size 的 field-size-*-height    |
| --c-verification-code-cell-max-width  | initial              | 未覆盖时随 size 的 field-size-*-height    |
| --c-verification-code-input-font-size | initial              | 未覆盖时随 size 的 field-size-*-font-size |

initial 表示未指定公开覆盖，实际 CSS 在组件元素处读取尺寸 fallback；可直接在组件 style 或主题中覆盖。删除旧 Cedar column-gap，使用 gutter。

### Form 字段展示与确认

本组件支持 `edit-mode`，字段 > FormItem > Form 逐层继承；未指定时为 `direct`，保留原有交互。支持值：`direct / click / dblclick`。非 direct 编辑模式通过字段值入口打开编辑面板，并维护单份草稿；确认后才更新 v-model，取消、重置或启用 readPretty 时丢弃草稿。

Cedar 使用 edit-mode="click" / "dblclick" 在字段附近打开编辑浮层，Enter/F2 也可进入；取消/Escape 丢弃草稿，确认后提交。readPretty 为独立阅读属性，与 readonly、disabled 分开。

`before-commit(value, { previousValue, signal })` 可拦截弹层保存；FormItem 先校验候选值，失败保持编辑。`open / default-open / update:open` 控制编辑层。`#read="{ value, text }"` 可自定义阅读内容。集中示例见 Form 的“各类字段统一展示”。

`read-pretty` 为独立布尔属性，与 `readonly`、`disabled` 同级；字段 > FormItem > Form 继承，显式 `false` 覆盖父级。默认 `false`。纯阅读不显示编辑器。

---

Document: llms/zh-CN/components/watermark.md

<!-- Source: src/watermark/README.md; locale: zh-CN; page: /components/watermark/ -->

# Watermark

给页面或局部区域添加文字、图片水印。组件会自动响应属性和主题变化，无需手动刷新。

## 基础示例

### 基础用法

局部示例提供深色底、显示开关及合成文字输入；显式font.color在深色底用白色0.4透明度、浅色底用黑色0.25透明度。改变文字/颜色会重新生成PNG；水印层pointer-events:none，内容按钮支持点击和Enter。隐藏卸载该实例，恢复后只保留一层并保留示例计数。这是局部显式配色与清理验收，不代表默认主题Token、全站暗色或防篡改已验收，不提供正文文字对比度合规保证。

使用 `content` 设置文字水印，默认插槽放置被水印覆盖的内容。

Example source: src/watermark/__demos__/basic.vue

```vue
<script setup>
import { ref } from "vue";
const dark = ref(false);
const shown = ref(true);
const content = ref("LOCAL DEMO 200");
const clicks = ref(0);
</script>

<template>
  <section class="watermark-contrast-demo">
    <c-checkbox v-model="dark"> Dark surface / 深色底</c-checkbox>
    <c-checkbox v-model="shown"> Show watermark / 显示水印</c-checkbox>
    <label>Watermark text / 水印文字<c-input v-model="content" /></label>
    <c-watermark
      v-if="shown"
      :content="content"
      :font="{ color: dark ? 'rgba(255,255,255,0.4)' : 'rgba(0,0,0,0.25)' }"
      :style="{
        background: dark ? '#1f2937' : '#ffffff',
        color: dark ? '#ffffff' : '#111827',
      }"
    >
      <div class="watermark-contrast-surface">
        <p>Local synthetic content / 本地合成内容</p>
        <c-button html-type="button" @click="clicks++"
          >Click through / 点击内容</c-button
        >
      </div>
    </c-watermark>
    <p role="status">
      Visible: {{ shown }} · Dark: {{ dark }} · Clicks: {{ clicks }}
    </p>
  </section>
</template>
<style scoped>
.watermark-contrast-surface {
  min-height: 240px;
  display: grid;
  place-content: center;
  gap: 12px;
}
</style>
```

## 内容与展示

### 多行文本

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `content` | 单行或多行文字；图片加载失败时作为回退内容 | 多行文本、图片水印、全屏水印 |
| `image` | 图片地址，优先于文字 | 图片水印 |
| `width` | 单块水印宽度，默认按内容测量 | 图片水印 |
| `height` | 单块水印高度，默认按内容测量 | 图片水印 |
| `font` | 文字样式 | 图片水印 |
| `fullscreen` | 是否固定覆盖整个视口 | 全屏水印 |
<!-- demo-config-notes:end -->

通过字符串数组设置多行文字水印。

Example source: src/watermark/__demos__/multiline.vue

```vue
<template>
  <c-watermark :content="['Cedar Design', dayjs().format('YYYY-MM-DD')]">
    <div style="width: 100%; height: 300px" />
  </c-watermark>
</template>

<script lang="ts" setup>
import dayjs from "dayjs";
</script>
```

### 图片水印

图片示例只使用合成SVG data URL。“本地图片失败”切换为故意无效的data URL，原生Image错误通知source=image，并回退红色FALLBACK 201文字。聚焦“恢复图片”按Enter后恢复原图，错误历史保留但不追加、覆盖层仍一层；恢复按钮再次禁用。这不是外部网络、CORS、Canvas故障或图片加载竞争验收。

图片优先于文字；图片加载失败且存在文字时自动回退文字。

Example source: src/watermark/__demos__/image.vue

```vue
<script setup>
import { computed, ref } from "vue";
const failed = ref(false);
const errors = ref([]);
const localImage =
  "data:image/svg+xml," +
  encodeURIComponent(
    '<svg xmlns="http://www.w3.org/2000/svg" width="160" height="48"><rect width="160" height="48" rx="8" fill="#0284c7"/><circle cx="80" cy="24" r="14" fill="white"/></svg>',
  );
const image = computed(() =>
  failed.value ? "data:image/png;base64,invalid-local-image" : localImage,
);
</script>
<template>
  <section class="watermark-image-failure-demo">
    <c-checkbox v-model="failed"> Fail local image / 本地图片失败</c-checkbox>
    <c-button html-type="button" :disabled="!failed" @click="failed = false"
      >Restore image / 恢复图片</c-button
    >
    <c-watermark
      content="FALLBACK 201"
      :image="image"
      :width="160"
      :height="48"
      :font="{ color: '#be123c' }"
      style="background: white"
      @error="errors.push($event.source)"
    >
      <div style="height: 240px" />
    </c-watermark>
    <p role="status">
      Mode: {{ failed ? "failure" : "image" }} · Errors:
      {{ errors.join(",") || "-" }}
    </p>
  </section>
</template>
```

### 全屏水印

示例按钮可点击、Space 或 Enter 切换。全屏层固定覆盖视口且不拦截指针操作；退出后回到原局部容器，默认插槽内容不搬走。反复开启/退出不应累积全屏层，卸载会移除该实例的层。这里使用本地文字生成PNG，不代表图片加载失败、动态主题或防篡改组合均已浏览器验收。

开启后，水印层固定覆盖整个视口；默认插槽内容仍保留在原位置。

Example source: src/watermark/__demos__/fullscreen.vue

```vue
<script setup lang="ts">
import { ref } from "vue";

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

<template>
  <c-watermark content="Cedar Design" :fullscreen="fullscreen" :z-index="99">
    <div class="watermark-fullscreen-demo">
      <c-button status="primary" @click="fullscreen = !fullscreen">
        {{ fullscreen ? "退出全屏水印" : "开启全屏水印" }}
      </c-button>
    </div>
  </c-watermark>
</template>

<style scoped>
.watermark-fullscreen-demo {
  min-height: 160px;
  display: grid;
  place-items: center;
}
</style>
```

## 自定义与插槽

### 自定义

<!-- demo-config-notes:start -->
#### 本组配置对照

| 配置 | 作用 | 相关示例 |
| --- | --- | --- |
| `content` | 单行或多行文字；图片加载失败时作为回退内容 | 自定义 |
| `rotate` | 旋转角度 | 自定义 |
| `gap` | 水印间距 `[x, y]` | 自定义 |
| `offset` | 第一块水印相对容器的偏移，默认是间距的一半 | 自定义 |
| `font` | 文字样式 | 自定义 |
<!-- demo-config-notes:end -->

调整旋转、间距、偏移、字体、重复和错列方式。

Example source: src/watermark/__demos__/custom.vue

```vue
<template>
  <c-form size="sm" :model="form" auto-label-width>
    <c-row :gutter="16">
      <c-col :span="24">
        <c-form-item field="rotate" label="rotate">
          <c-slider v-model="form.rotate" :min="-180" :max="180" />
        </c-form-item>
      </c-col>
      <c-col :span="12">
        <c-form-item label="gap">
          <c-input-group>
            <c-input-number
              v-model="form.gap[0]"
              placeholder="gap[x]"
              :min="0"
            />
            <c-input-number
              v-model="form.gap[1]"
              placeholder="gap[y]"
              :min="0"
            />
          </c-input-group>
        </c-form-item>
      </c-col>
      <c-col :span="12">
        <c-form-item label="offset">
          <c-input-group>
            <c-input-number v-model="form.offset[0]" placeholder="offsetLeft" />
            <c-input-number v-model="form.offset[1]" placeholder="offsetTop" />
          </c-input-group>
        </c-form-item>
      </c-col>
      <c-col :span="12">
        <c-form-item label="fontSize">
          <c-input-number v-model="form.font.fontSize" mode="button" />
        </c-form-item>
      </c-col>
      <c-col :span="12">
        <c-form-item label="zIndex">
          <c-input-number v-model="form.zIndex" mode="button" />
        </c-form-item>
      </c-col>
      <c-col :span="6">
        <c-form-item label="repeat">
          <c-switch v-model="form.repeat" />
        </c-form-item>
      </c-col>
      <c-col :span="6">
        <c-form-item label="staggered">
          <c-switch v-model="form.staggered" />
        </c-form-item>
      </c-col>
    </c-row>
  </c-form>
  <c-watermark content="arco.design" v-bind="form">
    <div style="width: 100%; border: 1px solid #e5e6eb; box-sizing: border-box">
      <c-typography-title :heading="5"> Design system</c-typography-title>
      <c-typography>
        <c-typography-paragraph>
          A design is a plan or specification for the construction of an object
          or system or for the implementation of an activity or process, or the
          result of that plan or specification in the form of a prototype,
          product or process. The verb to design expresses the process of
          developing a design.
        </c-typography-paragraph>
        <c-typography-paragraph>
          A design is a plan or specification for the construction of an object
          or system or for the implementation of an activity or process, or the
          result of that plan or specification in the form of a prototype,
          product or process. The verb to design expresses the process of
          developing a design.
        </c-typography-paragraph>
      </c-typography>
      <img
        style="position: relative; z-index: 7"
        src="https://p1-arco.byteimg.com/tos-cn-i-uwbnlip3yd/24e0dd27418d2291b65db1b21aa62254.png~tplv-uwbnlip3yd-webp.webp"
      />
    </div>
  </c-watermark>
</template>

<script lang="ts" setup>
import { reactive } from "vue";

const form = reactive({
  rotate: 0,
  gap: [50, 50],
  offset: [],
  font: { fontSize: 16 },
  zIndex: 6,
  repeat: true,
  staggered: true,
});
</script>
```

## API

### Props

| 参数          | 说明                                       | 类型                 | 默认值                     |
| ------------- | ------------------------------------------ | -------------------- | -------------------------- |
| `content`     | 单行或多行文字；图片加载失败时作为回退内容 | `string \| string[]` | `-`                        |
| `image`       | 图片地址，优先于文字                       | `string`             | `-`                        |
| `width`       | 单块水印宽度，默认按内容测量               | `number`             | `-`                        |
| `height`      | 单块水印高度，默认按内容测量               | `number`             | `-`                        |
| `gap`         | 水印间距 `[x, y]`                          | `[number, number]`   | `[90, 90]`                 |
| `offset`      | 第一块水印相对容器的偏移，默认是间距的一半 | `[number, number]`   | `[gap[0] / 2, gap[1] / 2]` |
| `rotate`      | 旋转角度                                   | `number`             | `-22`                      |
| `font`        | 文字样式                                   | `WatermarkFont`      | `-`                        |
| `z-index`     | 水印层级                                   | `number`             | `6`                        |
| `alpha`       | 整体透明度，范围为 `0..1`                  | `number`             | `1`                        |
| `anti-tamper` | 水印节点被移除或修改后是否恢复             | `boolean`            | `true`                     |
| `grayscale`   | 是否灰阶渲染                               | `boolean`            | `false`                    |
| `repeat`      | 是否重复水印                               | `boolean`            | `true`                     |
| `staggered`   | 重复时是否错列                             | `boolean`            | `true`                     |
| `fullscreen`  | 是否固定覆盖整个视口                       | `boolean`            | `false`                    |

### WatermarkFont

| 参数         | 类型                                | 默认值                             |
| ------------ | ----------------------------------- | ---------------------------------- |
| `color`      | `string`                            | `var(--c-watermark-content-color)` |
| `fontSize`   | `number`                            | `16`                               |
| `fontFamily` | `string`                            | `sans-serif`                       |
| `fontStyle`  | `'normal' \| 'italic' \| 'oblique'` | `normal`                           |
| `fontWeight` | `string \| number`                  | `normal`                           |
| `textAlign`  | `CanvasTextAlign`                   | `center`                           |
| `lineHeight` | `number`                            | `fontSize × 1.4`                   |

### 事件

| 事件名  | 说明                       | 参数                                              |
| ------- | -------------------------- | ------------------------------------------------- |
| `error` | 图片加载或 Canvas 渲染失败 | `{ source: 'image' \| 'canvas'; error: unknown }` |

### 方法

| 方法名   | 说明                   | 返回值          |
| -------- | ---------------------- | --------------- |
| `redraw` | 按当前属性重新生成水印 | `Promise<void>` |

### 插槽

| 插槽名    | 说明                 |
| --------- | -------------------- |
| `default` | 被水印覆盖的页面内容 |

### CSS 变量

| 变量名                        | 默认值                |
| ----------------------------- | --------------------- |
| `--c-watermark-content-color` | `rgba(0, 0, 0, 0.15)` |

---

Document: llms/zh-CN/examples/task-calendar.md

<!-- Source: docs/practices/task-calendar-workbench.md; locale: zh-CN; page: /examples/task-calendar/ -->

<ClientOnly>

<demo inline src="../../src/scheduler/__demos__/task-calendar-workbench.vue"></demo>

</ClientOnly>

<style>
.scheduler-workbench-page { --content-width: 100%; }
.scheduler-workbench-page .theme-hope-content { width: auto; max-width: none; padding: 16px; }
.scheduler-workbench-page .vp-page-title, .scheduler-workbench-page .page-title, .scheduler-workbench-page .page-meta, .scheduler-workbench-page .page-nav { display: none; }
</style>

---

Document: llms/zh-CN/guide/component-reuse.md

<!-- Source: docs/guide/component-reuse.md; locale: zh-CN; page: /guide/component-reuse/ -->

# Cedar / Maple 跨端代码复用调研

审计日期：2026-10-09。基于当前工作区源码（包含正在进行的 API 对齐改动），不是发布版本保证。标记规则更新：2026-09-21；已完成的完整同源与逻辑同源均有独立源码门禁。

已同源 56 组；待同源 0 组；待适配 0 组；逻辑待同源 0 组；逻辑已同源 15 组；独立 1 组。按组件族计数，包含子组件及异名 Drawer / Popup；不等于菜单条目数量。

## 菜单标记

| 标记 | 含义 | 建议顺序 |
| --- | --- | --- |
| [已同源] | 已完成对应范围的源码对齐并纳入一致性检查；两端各自维护源码 | P0：保持检查，作为后续样板 |
| [逻辑已同源] | 稳定逻辑已独立复制并纳入一致性检查；端侧展示/交互按职责保留 | P0：保持检查 |
| [待同源] | 主体适合同源复制；尚待实现对齐与双端验证，不是已完成 | P1 |
| [待适配] | 先对齐 API 或适配依赖，再同源复制主体；尚未完成 | P2 |
| [逻辑待同源] | 计划将内部逻辑同源复制为两份，保留端侧展示/交互；尚未完成 | P3 |
| [独立] | 同名但语义层级不同，不要求主体同源 | 暂缓 |

未标记表示本次没有确认跨端对应关系，或是主题/指南/指令等页面；不表示无法复用。所有候选均采用独立复制、双端同步维护；不引用同一份核心，不建立跨库运行时依赖，不通过外部模板生成组件源码。各库内部工具复用不受影响。

## 调研依据和限制

重新运行 api-contract-inventory.mjs，从 TypeScript 根入口追踪得到 Cedar 129 / Maple 119 个运行时 Props 导出，97 个同名导出可比较（包含子组件）。Props 名称相同不能证明默认值、类型、事件、插槽、方法和行为完全一致。额外检查了主体模板/TSX、事件触发、插槽、计时与弹层依赖；详细 Props 键差异见下方附录。单独登记尚未收口的能力与主体差异，不把历史根导出不对称当作当前结论。

copied-components-check.mjs 覆盖完整同源主体；copied-foundations-check.mjs 覆盖逻辑同源控制器。安装入口、主题 token、图标及端侧视图仍由两库独立维护。新增检查不会自动升级分类，须完成双端验证后更新。

初轮完成调研、菜单和文档标记；后续已完成的复制重构按同源标记维护。后续严格遵循包内复制 + 一致性检查方式：先修改并验证一端，再复制自然一致的部分至另一端，仅调整前缀、本地导入与必要端侧实现，后续两边同步修改。不抽取两端共同引用的核心实现，不共享实例或状态。

## 逐组件建议

| Cedar | Maple | 标记 | 依据 / 同源对齐前置条件 |
| --- | --- | --- | --- |
| affix | affix | 已同源 | 现有 copied-components-check 已验证主体、Props、样式及契约测试的规范化一致性；保留各库 platform、命名空间及安装入口。 |
| badge | badge | 已同源 | 现有 copied-components-check 已验证主体、Props、样式及契约测试的规范化一致性；保留各库 platform、命名空间及安装入口。 |
| card | card | 已同源 | 现有 copied-components-check 已验证主体、Props、样式及契约测试的规范化一致性；保留各库 platform、命名空间及安装入口。 |
| switch | switch | 已同源 | 现有 copied-components-check 已验证主体、Props、样式及契约测试的规范化一致性；保留各库 platform、命名空间及安装入口。 |
| space | space | 已同源 | 独立同源复制已复核：主体、Props、子节点展开、主样式、五档尺寸 token 与配对测试一致。两端默认 wrap=false、size=md、block=true；Maple 内置主题同步 Cedar 间距。不共享核心或实例，仅保留本地安装和命名空间适配。 |
| divider | divider | 已同源 | 2026-09-08 完成独立源码复制；主体、Props、关键样式和配对测试纳入一致性检查，双端组件测试及 SSR 通过。动态增删默认插槽会同步更新带文字样式；opacity=0 生效；hairline 优先于 thickness，并输出 aria-orientation。 |
| alert | alert | 已同源 | 2026-09-08 完成独立源码复制；主体、Props、关键样式和配对测试纳入一致性检查，双端组件测试及 SSR 通过。关闭按钮支持键盘操作，close 只触发一次，closed 在离场动画完成后触发。Maple 内部关闭类由 __close-icon 调整为 __close-btn；默认图标资源由各库本地适配。 |
| tag | tag | 已同源 | 2026-09-08 完成独立源码复制；主体、Props、关键样式和配对测试纳入一致性检查，双端组件测试及 SSR 通过。两端保留独立的 show/checked 状态，受控值由调用方更新；保留淡出效果，class/style 显式透传给实际标签。尺寸配置、RTL 上下文及图标资源由各库本地适配，移动端触控尺寸保留在 token 中。 |
| count-to | count-to | 已同源 | 2026-09-08 完成独立源码复制；主体、Props、关键样式和配对测试纳入一致性检查，双端组件测试及 SSR 通过。动画在卸载及 KeepAlive 停用时暂停，重新激活后恢复；各实例的数值和动画状态独立。 |
| countdown | countdown | 已同源 | 2026-09-08 完成独立源码复制；主体、Props、关键样式和配对测试纳入一致性检查，双端组件测试及 SSR 通过。SSR 输出初始格式化时间。暂停时修改 format 会更新显示；结束事件每轮只触发一次，reset 后可开始新一轮；卸载清理动画帧。 |
| statistic | statistic | 已同源 | 2026-09-08 完成独立源码复制；主体、Props、关键样式和配对测试纳入一致性检查，双端组件测试及 SSR 通过。默认插槽动态出现/消失时同步切换占位文字；动画在卸载及 KeepAlive 停用时暂停。 |
| skeleton | skeleton | 已同源 | 2026-09-08 完成独立源码复制；主体、Props、关键样式和配对测试纳入一致性检查，双端组件测试及 SSR 通过。Skeleton、SkeletonLine、SkeletonShape 均采用独立复制的源码；各库骨架主题和尺寸 token 独立维护。 |
| steps | steps | 已同源 | 2026-09-08 完成独立源码复制；主体、Props、关键样式和配对测试纳入一致性检查，双端组件测试及 SSR 通过。Steps 和 Step 的主体、Props、上下文协议与样式同源复制；注入 Symbol 分别定义在各库，不跨库共享。保留四种 type 和原有状态/事件契约。 |
| page-header | page-header | 已同源 | 2026-09-08 完成独立源码复制；主体、Props、关键样式和配对测试纳入一致性检查，双端组件测试及 SSR 通过。返回按钮统一使用原生 button，支持键盘触发并派发 back(MouseEvent)。Cedar 内部类名由 c-page-header-xxx 调整为 c-page-header__xxx；图标资源仍由本库提供。 |
| icon | icon | 已同源 | 2026-09-08 完成独立源码复制；主体、Props、关键样式和配对测试纳入一致性检查，双端组件测试及 SSR 通过。只解析本应用已注册的图标；连续切换 name 会取消过期定时器，卸载后不再执行切换。各库注册前缀和历史 spin 类由本地适配保留，图标资源不跨库引用。 |
| avatar | avatar | 已同源 | 2026-09-11 完成独立源码复制；Avatar/AvatarGroup 主体、Props、图片 load/error、文字缩放与分组折叠纳入一致性检查。size 支持 CSS 长度；ObjectFit 更名为 AvatarObjectFit。图标、Popover、安装入口与 token 前缀由各库适配。 |
| button | button | 已同源 | 共同契约补齐后选择 Maple：Button/ButtonGroup、Props、交互逻辑、样式和 12 组 demo 已复制对齐并纳入检查；注册入口和命名空间各自保留。竞赛证据见 button-race.json。 |
| breadcrumb | breadcrumb | 已同源 | 2026-09-08 完成 Breadcrumb / BreadcrumbItem 独立源码复制；主体、Props、上下文、类型、关键样式及配对测试纳入一致性检查。双端组件测试与 SSR 通过；图标、安装入口、Menu 和主题 token 本地适配。统一非空 routes 优先、分隔符优先级与 select(route, event)，修复空 routes 和省略项菜单行为。 |
| collapse | collapse | 已同源 | 2026-09-15 完成独立源码复制；Collapse/CollapseItem 主体 SFC、9 项公共 Props、change/toggleAll、键盘与 destroyOnHide 纳入一致性检查。去掉 Maple elevation；默认图标与尺寸 token 由各库 platform 适配。 |
| pagination | pagination | 已同源 | 统一主体 SFC、23 项 Props、4 个事件、6 个插槽、分页状态与按钮和布局；12 组 demo 对齐。Locale、Input、Select 使用显式平台适配，480px 容器自动简洁模式；同源检查覆盖 13 个实现文件。 |
| empty | empty | 已同源 | 2026-09-15 完成独立源码复制；主体 SFC、6 项 Props、click、image/default/extra 插槽与尺寸档位纳入一致性检查。去掉 icon/inConfigProvider；ConfigProvider 空状态、默认图标、locale 与尺寸 token 由各库 platform 适配。 |
| result | result | 已同源 | 2026-09-20 完成独立源码复制：Result 主体渲染、公共 Props、状态图形、animation/imageSize、插槽与关键 token 已统一，并由 lightweight-feedback-same-source 门禁验证。两端仅保留图标资源和本地入口适配。 第二十五批：主体格式、图形及规范 Token 门禁复验，所有状态、imageSize/动画/插槽与 SSR 验证通过。 |
| link | link | 已同源 | 以 Cedar 原生链接与 hoverable 为基础，补齐键盘焦点、加载动画、动态图标插槽及禁用属性透传；主体、Props、主样式和配对测试独立复制并验证，保留本地图标和主题 token。 |
| loading | loading | 已同源 | 2026-09-20 完成独立源码复制：Loading 主体渲染、公共 Props、五类动画、数值尺寸、hideIcon、内容遮罩、插槽与关键 token 已统一，并由 lightweight-feedback-same-source 门禁验证。 第二十五批：统一格式并改为从规范 style/token.less 验证 Token，动画、数值尺寸、SSR 回归复验。 |
| grid | grid | 已同源 | Grid/GridItem/Row/Col 主体、Props、响应式逻辑、样式和契约测试已按包内复制统一；Row/Col 有独立源码、安装和样式入口，两端 demo 配对。 入口职责已分离：Grid 仅包含 Grid.Item；Row/Col 独立入口、注册、文档与 Demo，不再通过 Grid 转导出。 |
| input-number | input-number | 已同源 | 主体、19 项 Props、数值编辑/提交控制器、独立 Decimal 运算、触控长按、样式及 Token 已独立复制；14 对核心/视图/样式/测试文件和 7 对 Demo 纳入一致性门禁。两端分别接入本库表单与全局多语言，77 项测试及双端类型检查和包构建通过；Checkbox / Radio 另批处理。 |
| ellipsis | ellipsis | 已同源 | 主体、Props、样式/Token 与配对测试独立复制；统一受控 expand/defaultExpand、键盘展开、Tooltip 配置与内容回退，移除多余外壳。与 BackTop 共 12 对文件门禁，仅前缀/本地导入不同。 第二十五批：主体、样式和配对测试复验；模板与副作用导入仍严格比较，受控展开/键盘与 Tooltip 接入不漂移。 |
| progress | progress | 已同源 | 2026-10-09 主体/Props/样式/Token 独立复制，家族双端136项测试及14源/样式/测试对和5Demo门禁通过。Progress 保留 number|string size、0–100 percent，补齐 steps/buffer/track/rotate/渐变/未知进度与圆形状态图标；Group 统一 showText/#text、超额裁剪、键盘 Tooltip 和 SSR。本地安装/ConfigProvider 尺寸接线独立，真实浏览器视觉仍单列待验收。 |
| progress-group | progress-group | 已同源 | 2026-10-09 主体/Props/样式/Token 独立复制，家族双端136项测试及14源/样式/测试对和5Demo门禁通过。Progress 保留 number|string size、0–100 percent，补齐 steps/buffer/track/rotate/渐变/未知进度与圆形状态图标；Group 统一 showText/#text、超额裁剪、键盘 Tooltip 和 SSR。本地安装/ConfigProvider 尺寸接线独立，真实浏览器视觉仍单列待验收。 |
| back-top | back-top | 已同源 | 主体、Props、滚动控制器、样式/Token 和配对测试独立复制；默认监听页面，200ms/quartOut，支持动态目标、原生键盘、KeepAlive/卸载取消及 SSR。与 Ellipsis 共 12 对文件门禁，不共享运行时。 第二十五批：复制样式与规范格式，保留严格滚动/取消/SSR 契约；绑定导入排序与本地别名规范化不忽略主体。 |
| watermark | watermark | 已同源 | 2026-09-20 已完成独立同源：统一 Canvas renderer、Props/types、文字与图片、多行/自动测量、repeat/staggered、grayscale、antiTamper、fullscreen、error/redraw、SSR 和生命周期；Maple 已删除 foreignObject content 插槽及 resize 旧方法。两端主体仅保留前缀、本地 import 和主题标识差异，并纳入源码门禁。 |
| checkbox | checkbox | 已同源 | 2026-10-09 主体已独立复制：原生 input/label、Group、Props、Context、BEM 样式及图标/实例外观/原生属性补齐；15 对主体/公开类型/测试/样式门禁及既有组核心门禁通过。本库 Form/安装接线、契约登记的 PC/触控密度默认值独立保留；无共享运行时。逐组件行为/SSR/主题通过，真实浏览器视觉仍单列待验收。 |
| radio | radio | 已同源 | 2026-10-09 主体已独立复制：原生 input/label、Group、Props、Context、BEM 样式及图标/实例外观/原生属性补齐；15 对主体/公开类型/测试/样式门禁及既有组核心门禁通过。本库 Form/安装接线、契约登记的 PC/触控密度默认值独立保留；无共享运行时。逐组件行为/SSR/主题通过，真实浏览器视觉仍单列待验收。 |
| rate | rate | 已同源 | 2026-10-09 已完成主体、Props/公开类型、交互、样式规则及15公共Token后缀独立复制同源；错误/禁用/焦点使用系统角色，私有映射在组件根支持局部覆盖。金色/主色与几何默认差异纳入主题契约，仅Form/安装/图标接线本地维护；源码/类型/实际Less门禁与两端交互测试通过。 第二十五批：修复门禁失效起始标记，必须比较真实 rate-core 主体；Props/主体/交互测试重新验证，图标与 Form 本地接线保留。 |
| slider | slider | 已同源 | 2026-10-09 完成主体、Props/公开类型、值归一化、Pointer/键盘、范围/小数步长、marks/ticks/InputNumber、标签/颜色与样式Token独立复制同源；showTooltip统一false/true/always并移除labelVisible。Form/provider/安装接线留本库；成对交互测试、3组Demo与实际Less编译门禁覆盖。 |
| input | input | 已同源 | 2026-10-09 完成主体复核：Input/InputGroup/Password、Props/公开类型、值模型、原生属性和样式规则独立复制同源；输入及清空管线、受控拒绝、IME、表单/键盘回归已补齐，24对Input/Textarea门禁防漂移。保留本库Form/安装接线与FieldDecorator已登记的PC hover/移动常驻清空表现。 |
| textarea | textarea | 已同源 | 2026-10-09 以完善后的Cedar SFC独立复制至Maple；hint/line/实例颜色、原生attrs、清空/计数、IME/长度、自动高度及KeepAlive清理一致，公开Emits/Slots/Expose与Demo补齐。resize默认Cedar开启/Maple关闭及尺寸密度登记为平台差异；没有共享运行时。 |
| verification-code | verification-code | 已同源 | 2026-10-09：验证码主体、Props/Emits/Slots/Expose、四项Token、样式与四组Demo独立复制同源，11对保留类型声明的门禁通过。Cedar22/Maple27专项测试通过，覆盖受控拒绝、IME/Unicode、短信填入、粘贴、单格替换、Form单通知及KeepAlive取消；仅各库Form/安装接线保留独立。未宣称浏览器视觉全验。 |
| search | search | 逻辑已同源 | 2026-10-09：Search控制器、Props/Emits/Slots/Expose、历史内容及配对Demo独立复制，9对源码和25项公共Token门禁通过；Cedar30/Maple36测试通过。不可变model、受控拒绝、Form单通知、弹窗内外取消/焦点、全局语言、inputAttrs/error及实际variant效果已补齐；仅保留PC InputGroup/移动条、Drawer/Popup、本地接线和登记的默认密度/historyPopup/shape差异。 |
| infinite-scroll | infinite-scroll | 已同源 | 2026-09-21 完成独立源码复制：主体 SFC、Props 与关键样式纳入同源门禁，统一分页状态机、CSS length 阈值、滚动容器、可见性恢复、KeepAlive 与清理行为。两端 locale.ts 仅桥接各自的全局语言系统，不持有独立语言状态，也不共享运行时。 |
| list | list | 已同源 | 2026-10-09 完成List/ListItem SFC、Props/类型、样式规则及34公共Token后缀独立复制同源；Maple补maxHeight/scrollbar/virtualListProps/scrollIntoView。两端VirtualList修复align/数据缩小/threshold。render-adapter仅接本库Scrollbar与ConfigProvider空态，默认密度登记为平台差异；9对主体/API/样式/测试/Demo门禁覆盖。 |
| image | image | 已同源 | 2026-09-15 完成独立源码复制；Image/Preview/PreviewGroup 主体 SFC、加载回退、预览控制器与命令式 API 纳入一致性检查。去掉 platform.config；懒加载用原生 loading、图标/默认加载器/默认值由各库 platform 与 setPropsDefaults 适配。 |
| overlay | overlay | 已同源 | 2026-09-21 完成独立同源：主体 SFC、Props 和结构样式已复制并纳入门禁；统一 popup-layer/z-index、容器滚动锁、真实 Teleport Document、背景 pointer 序列、最上层 ESC、受控状态、KeepAlive 和过渡生命周期。 |
| dialog | dialog | 逻辑已同源 | 2026-09-21 完成逻辑同源。两端 Dialog 直接消费同源 modal-surface，不再嵌套 Popup 或维护端侧弹层状态机；use-dialog、use-dialog-drag、service 三份核心均为独立复制并纳入门禁，统一 beforeClose 竞态、拖拽、Promise/update/close、默认配置、宿主销毁及 app context。PC 与移动端保留各自 DOM、图标和样式。 |
| style-provider | style-provider | 已同源 | 主体、Props、函数注入、安装、默认值设置及配对测试已独立同源；仅前缀与本地导入不同，不共享运行时代码或状态。 |
| select | select | 已同源 | 主体、控制器、选项与搜索/虚拟列表算法、Menu 及语义样式已独立复制并纳入 check:selection-presentations；Cedar 仅 menu，Maple 通过静态扩展文件提供 list/picker 和移动触摸样式。公共 API 以 Cedar 为准；本地 Form/空状态接入独立，无跨库运行时、共享实例或 platform 配置。 第二十五批：公共源码保留严格主体比较，仅规范本地绑定导入的排序；Select/Checkbox BEM 同步原生同源控件，移动 presentation 扩展独立。 |
| cascader | cascader | 已同源 | 主体、控制器、树/路径/搜索/懒加载算法、CascaderPanel、Menu 与语义样式已独立复制；草稿会话由控制器统一持有。Cedar 仅 menu，Maple 的 list/picker 位于独立静态扩展文件；公共源码纳入 check:selection-presentations，保留本地系统接入与移动触摸样式差异，不共享运行时代码。 第二十五批：公共源码、路径算法与样式完成复制收口，移除旧 Checkbox/Radio hover 类名，使用 --状态与 __control；list/picker 仍为本地扩展。 |
| auto-complete | auto-complete | 已同源 | 2026-09-23 主体、Props、类型出口、Menu 样式和配对交互/SSR 测试完成独立同源复制；两端直接消费本地 Input、Trigger、Select 选项算法。统一 shouldOpen/过滤、分组、异步候选、虚拟列表、长度规则、Form 继承及焦点事件，补齐 hint/颜色/键盘提示；无跨库运行时或 platform 配置，AutoComplete 不提供滚轮 presentation。 第二十五批：主体、Props、配对44项交互测试及样式复制收口；绑定导入按本地路径排序，不忽略主体、模板或副作用导入顺序。 |
| date | date | 逻辑已同源 | 2026-09-30：日期族模型/严格解析、Date 禁用回调、包含边界、时分秒分级约束、范围提交、字段与纯面板主体和事件已独立复制；42 对源码/测试门禁覆盖；第十一批对齐 showCurrent、showNowButton 与 exchangeTime，当前动作复用统一校验/确认，删除旧按钮名和 Cedar 全局时间交换覆盖；第十批统一快捷项、视口控制/通知、预览与确认校验，保留独立复制源码。第九批拆清字段/纯面板 API，复制公共面板 Props/事件协议并补齐入口与展示 Options 类型；Cedar 纯面板移除字段/浮层 Prop 泄漏，Maple dayStartOfWeek 改为整数 0–6 并修复范围日历转发，旧 firstDayOfWeek 不保留。两端默认秒精度，format/valueFormat、defaultValue/defaultOpen、type、select/change/confirm/open-change/clear 对齐。桌面日历/Trigger 与移动滚轮/时钟/Popup 保留本地 presentation，Form 与全局多语言各自接入；Maple 多选和 Cedar 周/季度为明确展示能力差异，无共享运行时或 platform 配置。第十二批两端独立复制月份标签函数，补齐 abbreviation（仅日历月份网格），保留标题/星期/滚轮不变；第十三批删除 Cedar 日期级 locale 覆盖，Maple 范围内嵌日历仅接外观白名单，字段空默认不覆盖嵌套外观；修复范围日历误用滚轮默认展示。第十四批时间展示类型/白名单独立复制，Maple 单值/范围日期时间滚轮只接尺寸与外观，calendarClock 明确时钟；Cedar 内嵌时间精度服从日期根。第十五批删除 Cedar 字段无效 pickerProps/范围 datePickerProps，Maple 保留真实插件；旧 Demo 初始时间迁移到日期顶层。第十六批语言/周起始改为本库命名空间内的实例元数据，不覆盖宿主 Dayjs 默认或基础语言；模型字符串固定英文协议，展示/手输走全局界面语言，多实例更新/卸载和跨年周比较已回归。第十七批默认周文本按实例语言/周起始严格反解析并复用禁用/范围提交；季度由当前 Dayjs 原生支持，追加回归。第十八批两端公共所有者统一可编辑条件，单值/范围真实手输测试独立复制；Maple 原生输入与日历按钮/Popup 分离，Enter/blur、IME、拒绝回写、禁用和范围顺序已验证，multiple/函数格式保留面板选择。移动按钮 Token 登记为明确本地扩展；浏览器软键盘/触控验收未做。第十九批补齐 Maple 日期字段视口/快捷项事件转发，单值/范围完整所有者链路及真实日历导航回归；拒绝嵌套受控视口不改选择值，默认快捷项仍走确认。第二十批 Maple 字段嵌套 Options 删除无效 presentation，根字段/纯面板模式保留；两端复制过滤器阻止嵌套选择器，根模式动态切换不改模型，发布类型根正例/嵌套反例验证。 第二十一批补齐 Maple 周起始日动态更新的真实日期列回归（单值/范围及字段），本地格子改为响应式派生，与 Cedar 原有响应式行为一致；切换不提交模型。 第二十二批修复 Maple 日/月/年导航移除 min/max 后遗留禁用状态；十二个实际单值/范围及字段回归验证按端恢复，不改模型。导航禁用属于本地展示，日期候选约束仍使用两库独立同源规则。 |
| date-range | date-range | 逻辑已同源 | 2026-09-30：日期族模型/严格解析、Date 禁用回调、包含边界、时分秒分级约束、范围提交、字段与纯面板主体和事件已独立复制；42 对源码/测试门禁覆盖；第十一批对齐 showCurrent、showNowButton 与 exchangeTime，当前动作复用统一校验/确认，删除旧按钮名和 Cedar 全局时间交换覆盖；第十批统一快捷项、视口控制/通知、预览与确认校验，保留独立复制源码。第九批拆清字段/纯面板 API，复制公共面板 Props/事件协议并补齐入口与展示 Options 类型；Cedar 纯面板移除字段/浮层 Prop 泄漏，Maple dayStartOfWeek 改为整数 0–6 并修复范围日历转发，旧 firstDayOfWeek 不保留。两端默认秒精度，format/valueFormat、defaultValue/defaultOpen、type、select/change/confirm/open-change/clear 对齐。桌面日历/Trigger 与移动滚轮/时钟/Popup 保留本地 presentation，Form 与全局多语言各自接入；Maple 多选和 Cedar 周/季度为明确展示能力差异，无共享运行时或 platform 配置。第十二批两端独立复制月份标签函数，补齐 abbreviation（仅日历月份网格），保留标题/星期/滚轮不变；第十三批删除 Cedar 日期级 locale 覆盖，Maple 范围内嵌日历仅接外观白名单，字段空默认不覆盖嵌套外观；修复范围日历误用滚轮默认展示。第十四批时间展示类型/白名单独立复制，Maple 单值/范围日期时间滚轮只接尺寸与外观，calendarClock 明确时钟；Cedar 内嵌时间精度服从日期根。第十五批删除 Cedar 字段无效 pickerProps/范围 datePickerProps，Maple 保留真实插件；旧 Demo 初始时间迁移到日期顶层。第十六批语言/周起始改为本库命名空间内的实例元数据，不覆盖宿主 Dayjs 默认或基础语言；模型字符串固定英文协议，展示/手输走全局界面语言，多实例更新/卸载和跨年周比较已回归。第十七批默认周文本按实例语言/周起始严格反解析并复用禁用/范围提交；季度由当前 Dayjs 原生支持，追加回归。第十八批两端公共所有者统一可编辑条件，单值/范围真实手输测试独立复制；Maple 原生输入与日历按钮/Popup 分离，Enter/blur、IME、拒绝回写、禁用和范围顺序已验证，multiple/函数格式保留面板选择。移动按钮 Token 登记为明确本地扩展；浏览器软键盘/触控验收未做。第十九批补齐 Maple 日期字段视口/快捷项事件转发，单值/范围完整所有者链路及真实日历导航回归；拒绝嵌套受控视口不改选择值，默认快捷项仍走确认。第二十批 Maple 字段嵌套 Options 删除无效 presentation，根字段/纯面板模式保留；两端复制过滤器阻止嵌套选择器，根模式动态切换不改模型，发布类型根正例/嵌套反例验证。 第二十一批补齐 Maple 周起始日动态更新的真实日期列回归（单值/范围及字段），本地格子改为响应式派生，与 Cedar 原有响应式行为一致；切换不提交模型。 第二十二批修复 Maple 日/月/年导航移除 min/max 后遗留禁用状态；十二个实际单值/范围及字段回归验证按端恢复，不改模型。导航禁用属于本地展示，日期候选约束仍使用两库独立同源规则。 |
| time | time | 逻辑已同源 | 2026-09-23：Time/TimeRange 入口、TimeField 主体及字段状态协议已从 Cedar 独立复制到 Maple，值、草稿、确认/取消、清除、焦点和通知控制器同源。两库各自维护源码及实例，无共享运行时或 platform 配置；桌面 Trigger/列表与移动 Popup/滚轮/时钟，以及本地 Form、全局多语言接入和候选初始化保留在独立 presentation 文件。34 对时间源码/测试门禁覆盖；外观和纯时间面板仍单独验收。 2026-10-12：两端 inputEditable 已消费同源 PickerField/时间解析与提交链；Cedar 默认 true、Maple 默认 false。移动端可手输，时钟按钮/ArrowDown 打开原有面板，未增加共享运行时。 |
| time-range | time-range | 逻辑已同源 | 2026-09-23：Time/TimeRange 入口、TimeField 主体及字段状态协议已从 Cedar 独立复制到 Maple，值、草稿、确认/取消、清除、焦点和通知控制器同源。两库各自维护源码及实例，无共享运行时或 platform 配置；桌面 Trigger/列表与移动 Popup/滚轮/时钟，以及本地 Form、全局多语言接入和候选初始化保留在独立 presentation 文件。34 对时间源码/测试门禁覆盖；外观和纯时间面板仍单独验收。 2026-10-12：两端 inputEditable 已消费同源 PickerField/时间解析与提交链；Cedar 默认 true、Maple 默认 false。移动端可手输，时钟按钮/ArrowDown 打开原有面板，未增加共享运行时。 |
| date-picker | date-picker | 逻辑已同源 | 2026-09-30：日期族模型/严格解析、Date 禁用回调、包含边界、时分秒分级约束、范围提交、字段与纯面板主体和事件已独立复制；42 对源码/测试门禁覆盖；第十一批对齐 showCurrent、showNowButton 与 exchangeTime，当前动作复用统一校验/确认，删除旧按钮名和 Cedar 全局时间交换覆盖；第十批统一快捷项、视口控制/通知、预览与确认校验，保留独立复制源码。第九批拆清字段/纯面板 API，复制公共面板 Props/事件协议并补齐入口与展示 Options 类型；Cedar 纯面板移除字段/浮层 Prop 泄漏，Maple dayStartOfWeek 改为整数 0–6 并修复范围日历转发，旧 firstDayOfWeek 不保留。两端默认秒精度，format/valueFormat、defaultValue/defaultOpen、type、select/change/confirm/open-change/clear 对齐。桌面日历/Trigger 与移动滚轮/时钟/Popup 保留本地 presentation，Form 与全局多语言各自接入；Maple 多选和 Cedar 周/季度为明确展示能力差异，无共享运行时或 platform 配置。第十二批两端独立复制月份标签函数，补齐 abbreviation（仅日历月份网格），保留标题/星期/滚轮不变；第十三批删除 Cedar 日期级 locale 覆盖，Maple 范围内嵌日历仅接外观白名单，字段空默认不覆盖嵌套外观；修复范围日历误用滚轮默认展示。第十四批时间展示类型/白名单独立复制，Maple 单值/范围日期时间滚轮只接尺寸与外观，calendarClock 明确时钟；Cedar 内嵌时间精度服从日期根。第十五批删除 Cedar 字段无效 pickerProps/范围 datePickerProps，Maple 保留真实插件；旧 Demo 初始时间迁移到日期顶层。第十六批语言/周起始改为本库命名空间内的实例元数据，不覆盖宿主 Dayjs 默认或基础语言；模型字符串固定英文协议，展示/手输走全局界面语言，多实例更新/卸载和跨年周比较已回归。第十七批默认周文本按实例语言/周起始严格反解析并复用禁用/范围提交；季度由当前 Dayjs 原生支持，追加回归。第十八批两端公共所有者统一可编辑条件，单值/范围真实手输测试独立复制；Maple 原生输入与日历按钮/Popup 分离，Enter/blur、IME、拒绝回写、禁用和范围顺序已验证，multiple/函数格式保留面板选择。移动按钮 Token 登记为明确本地扩展；浏览器软键盘/触控验收未做。第十九批补齐 Maple 日期字段视口/快捷项事件转发，单值/范围完整所有者链路及真实日历导航回归；拒绝嵌套受控视口不改选择值，默认快捷项仍走确认。纯面板保留面板 API，不新增字段手输或浮层状态；外观仍按各端 presentation 单独验收。第二十批 Maple 字段嵌套 Options 删除无效 presentation，根字段/纯面板模式保留；两端复制过滤器阻止嵌套选择器，根模式动态切换不改模型，发布类型根正例/嵌套反例验证。 第二十一批补齐 Maple 周起始日动态更新的真实日期列回归（单值/范围及字段），本地格子改为响应式派生，与 Cedar 原有响应式行为一致；切换不提交模型。 第二十二批修复 Maple 日/月/年导航移除 min/max 后遗留禁用状态；十二个实际单值/范围及字段回归验证按端恢复，不改模型。导航禁用属于本地展示，日期候选约束仍使用两库独立同源规则。 |
| date-range-picker | date-range-picker | 逻辑已同源 | 2026-09-30：日期族模型/严格解析、Date 禁用回调、包含边界、时分秒分级约束、范围提交、字段与纯面板主体和事件已独立复制；42 对源码/测试门禁覆盖；第十一批对齐 showCurrent、showNowButton 与 exchangeTime，当前动作复用统一校验/确认，删除旧按钮名和 Cedar 全局时间交换覆盖；第十批统一快捷项、视口控制/通知、预览与确认校验，保留独立复制源码。第九批拆清字段/纯面板 API，复制公共面板 Props/事件协议并补齐入口与展示 Options 类型；Cedar 纯面板移除字段/浮层 Prop 泄漏，Maple dayStartOfWeek 改为整数 0–6 并修复范围日历转发，旧 firstDayOfWeek 不保留。两端默认秒精度，format/valueFormat、defaultValue/defaultOpen、type、select/change/confirm/open-change/clear 对齐。桌面日历/Trigger 与移动滚轮/时钟/Popup 保留本地 presentation，Form 与全局多语言各自接入；Maple 多选和 Cedar 周/季度为明确展示能力差异，无共享运行时或 platform 配置。第十二批两端独立复制月份标签函数，补齐 abbreviation（仅日历月份网格），保留标题/星期/滚轮不变；第十三批删除 Cedar 日期级 locale 覆盖，Maple 范围内嵌日历仅接外观白名单，字段空默认不覆盖嵌套外观；修复范围日历误用滚轮默认展示。第十四批时间展示类型/白名单独立复制，Maple 单值/范围日期时间滚轮只接尺寸与外观，calendarClock 明确时钟；Cedar 内嵌时间精度服从日期根。第十五批删除 Cedar 字段无效 pickerProps/范围 datePickerProps，Maple 保留真实插件；旧 Demo 初始时间迁移到日期顶层。第十六批语言/周起始改为本库命名空间内的实例元数据，不覆盖宿主 Dayjs 默认或基础语言；模型字符串固定英文协议，展示/手输走全局界面语言，多实例更新/卸载和跨年周比较已回归。第十七批默认周文本按实例语言/周起始严格反解析并复用禁用/范围提交；季度由当前 Dayjs 原生支持，追加回归。第十八批两端公共所有者统一可编辑条件，单值/范围真实手输测试独立复制；Maple 原生输入与日历按钮/Popup 分离，Enter/blur、IME、拒绝回写、禁用和范围顺序已验证，multiple/函数格式保留面板选择。移动按钮 Token 登记为明确本地扩展；浏览器软键盘/触控验收未做。第十九批补齐 Maple 日期字段视口/快捷项事件转发，单值/范围完整所有者链路及真实日历导航回归；拒绝嵌套受控视口不改选择值，默认快捷项仍走确认。纯面板保留面板 API，不新增字段手输或浮层状态；外观仍按各端 presentation 单独验收。第二十批 Maple 字段嵌套 Options 删除无效 presentation，根字段/纯面板模式保留；两端复制过滤器阻止嵌套选择器，根模式动态切换不改模型，发布类型根正例/嵌套反例验证。 第二十一批补齐 Maple 周起始日动态更新的真实日期列回归（单值/范围及字段），本地格子改为响应式派生，与 Cedar 原有响应式行为一致；切换不提交模型。 第二十二批修复 Maple 日/月/年导航移除 min/max 后遗留禁用状态；十二个实际单值/范围及字段回归验证按端恢复，不改模型。导航禁用属于本地展示，日期候选约束仍使用两库独立同源规则。 |
| time-picker | time-picker | 逻辑已同源 | 2026-09-30：纯时间面板的值、草稿、校验和选择/确认事务已独立复制；两端范围入口均直接持有范围状态，Cedar 不再经单值面板转调。类型化事件声明和范围事件编排同源，脚本入口收口为 script setup。列表与滚轮/时钟内容及手势留在独立 presentation 文件，两库各有源码及实例，无共享运行时。33 对源码/测试与 4 个面板展示边界门禁覆盖；端侧外观保持差异，浏览器视觉验收另行进行。 |
| time-range-picker | time-range-picker | 逻辑已同源 | 2026-09-30：纯时间面板的值、草稿、校验和选择/确认事务已独立复制；两端范围入口均直接持有范围状态，Cedar 不再经单值面板转调。类型化事件声明和范围事件编排同源，脚本入口收口为 script setup。列表与滚轮/时钟内容及手势留在独立 presentation 文件，两库各有源码及实例，无共享运行时。33 对源码/测试与 4 个面板展示边界门禁覆盖；端侧外观保持差异，浏览器视觉验收另行进行。 |
| menu | menu | 逻辑已同源 | 2026-10-09 复核：Props、selection/level/keyboard/options 与公共定位选项独立复制；strategy 响应式传递到所有子菜单，公开定位/子菜单类型补齐。两端保留 Scrollbar/原生列表、hover/click、动画、触控涟漪等视图差异，因此纠正旧“已同源”为“逻辑已同源”，不宣称整个主体一致。移除 platform 聚合层，差异留在 appearance.ts；无共享运行时或旧 API 别名。Menu 与 SplitButton 配对交互回归通过。 |
| popover | popover | 已同源 | 2026-09-20 完成独立同源复制：主体、Props、platform 外观映射、title/body DOM、结构样式及语义契约纳入门禁。双端统一 click、bottom、箭头、10px 间距和关闭缓存默认值，删除 defaultStyle、popoverClass、elevation；通过 Trigger referenceAttrs 关联 aria-controls/expanded。仅前缀、本地导入和主题 token 值不同。 |
| tooltip | tooltip | 已同源 | 2026-09-20 完成独立同源复制：主体、Props、platform 外观映射、结构样式与语义契约纳入门禁。双端统一 hover+focus、top、箭头、10px 间距、关闭卸载、xs/md、status、color/textColor，删除 backgroundColor 和布尔 xs；通过 Trigger referenceAttrs 关联 role=tooltip 与 aria-describedby。仅前缀、本地导入和主题 token 值不同。 |
| trigger | trigger | 已同源 | 2026-09-20 完成独立同源复制：Trigger 主体、最终 Props/types、无依赖定位器、结构样式、token 职责和定位契约测试已纳入 copied-components-check。两端统一十二方位、absolute/fixed、popupOffset、popupTranslate、cover、翻转避让、滚动与尺寸更新；Maple 删除 @popperjs/core、offsetX/offsetY 与 cascadeOptimization。仅 platform.ts 保留各库容器、层级、全局配置及 ResizeObserver 接线，不共享运行时核心或实例。 |
| split-button | split-button | 已同源 | 2026-09-08 完成独立同源复制：主体、21 项 Props、样式依赖入口和契约测试纳入一致性检查；统一异步点击、受控状态、禁用优先级、向下箭头及 open/close/resize。Cedar Menu 补齐浮层类名和屏幕轴偏移适配；两端 Menu 保留独立平台实现，无跨库运行时或实例共享。 |
| form | form | 逻辑已同源 | 2026-10-12：表单字段登记、校验调度、reset/clear 与异步竞态，以及标签/内容栅格 Props、布局继承、自然标签宽度登记/测量和生命周期逻辑均独立复制；12 对源码/行为测试门禁覆盖。Form/Item 支持响应式 Col、固定标签 flex、动态自动宽度和局部覆盖。Cedar 默认横向、Maple 默认纵向；本地规则引擎、表单注入、错误滚动与 FormDetails/标签外观保留独立展示，没有共享运行时、实例或 platform 配置。 补齐显式 Form.id 字段容器前缀与 Cedar formItemProps/严格 FormItemProps 入口导出。 Cedar 已移除无效 mergeProps 并补齐 Item.size；第八批补齐 Maple 六项普通装饰 API，FormItem Props 31/31 差集为零。装饰 Props、标签渲染、状态优先规则与配对测试独立复制；显式状态只覆盖展示，真实校验结果不变，自动状态 validating → success/error，清空恢复未校验。规则类型、默认布局与本地消息视图保留差异，不将 Props 名称相同算作全部主体一致。 |
| tabs | tabs | 已同源 | 2026-10-09：Tabs/TabPane/TabsNavs/TabNav/TabsItems/TabItem六件套主体、Props、事件、插槽及TabsNavs.resize已同源；13对源码和40项Token消费门禁、Cedar57/Maple56含InfiniteScroll专项通过。删除platform与无消费者绑定，仅本库配置/安装和四项已登记外观默认值独立，未扩建Maple全局Provider。 |
| carousel | carousel | 已同源 | 2026-10-09：Carousel / CarouselItem 主体、Props、布局、Pointer、受控状态、生命周期、样式与配对测试独立复制；12 对源码及 26 项 token 门禁，Cedar 25 / Maple 26 项测试通过。仅前缀、本地安装、图标及全局 Locale 接入不同。不复制子组件实例；无法连续覆盖的跨页跳转直接定位。 |
| message | message | 逻辑已同源 | 2026-09-21 完成逻辑同源：两端独立复制相同的可调用服务、按容器与位置隔离的队列、剩余时间计时、id 更新、幂等关闭和宿主销毁逻辑，并纳入轻量反馈一致性门禁。API 已统一为 default/info/success/warning/danger/loading、top/center/bottom、action、pauseOnHover、resetOnUpdate 与完整生命周期；删除 normal、模态阻断及端侧外观 Props。PC 紧凑提示与移动卡片样式各自维护。 第二十五批：默认 variant 两端统一 neutral，组件/函数/默认重置一致；补齐独立复制的计时器暂停/恢复/更新/卸载和默认变体回归，不保留旧默认兼容。 |
| upload | upload | 逻辑已同源 | 2026-10-09：Upload 主体、Props、读取/队列/请求/取消/URL 所有权/useUploader 与样式独立复制，20 对源码门禁、Cedar 41 / Maple 68 项测试通过；Form 与全局 Locale 本地接入，视频预览保留 Cedar Drawer / Maple Popup。中英 Demo 各 21 项，能力补齐；无共享运行时或兼容旧 API。 |
| table | table | 独立 | Cedar 42 个 Props（列、选择、树、分页、虚拟滚动等），Maple 仅 3 个容器 Props；语义层级不同，不建议对齐整个 Table。 |
| drawer | popup | 逻辑已同源 | 2026-09-21 完成逻辑同源改造。两端各自保存字节级一致的 modal-surface 控制器，并由同源门禁约束；已统一 open/defaultOpen、unmountOnClose、遮罩 pointer 序列、层级、焦点、容器锁滚动、ESC、显式路由关闭和生命周期。Cedar Drawer 保留标题/页脚/宽高及 beforeClose，Maple Popup 保留 center、安全区和移动转场。 |
| row | row | 已同源 | Grid/GridItem/Row/Col 主体、Props、响应式逻辑、样式和契约测试已按包内复制统一；Row/Col 有独立源码、安装和样式入口，两端 demo 配对。 入口职责已分离：Grid 仅包含 Grid.Item；Row/Col 独立入口、注册、文档与 Demo，不再通过 Grid 转导出。 |
| col | col | 已同源 | Grid/GridItem/Row/Col 主体、Props、响应式逻辑、样式和契约测试已按包内复制统一；Row/Col 有独立源码、安装和样式入口，两端 demo 配对。 入口职责已分离：Grid 仅包含 Grid.Item；Row/Col 独立入口、注册、文档与 Demo，不再通过 Grid 转导出。 |
| paper | paper | 已同源 | Cedar 新增 Paper；两端底层表面主体、Props、样式、token 和契约测试独立复制并验证。bordered 与 elevation 独立，无 variant、无默认 padding；保留尺寸、圆角与可选水波，不共享核心或实例。 |
| ripple | ripple | 已同源 | 第二十五批补录指令：主体、动画、键盘、禁用/卸载清理规则独立复制；两端真实样式入口编译与生命周期测试验证，Token 默认值和包/命名空间接线本地维护，无共享运行时。 |

## 后续维护与实施

1. 以已完成组件的包内独立复制和源码一致性检查为模板；差异按职责拆分到本库文件，不引入共享运行时或 platform 配置层。
2. 原待同源 11 组和 Link / Paper 已完成；后续按待适配、逻辑待同源分类逐项推进，不因本批完成而自动升级其他候选。
3. 每个组件先固定 Props 类型/默认值、事件载荷和顺序、Slots 参数、Expose，以及受控/非受控语义；子组件必须一并验收。
4. 配对测试各自保存在两库并分别运行，覆盖键盘与触控、禁用/只读、SSR、挂载清理和主题。弹层额外覆盖嵌套、焦点恢复及滚动锁。通过后再升级为已同源标记。

## 未配对范围

Cedar 的 Tree / Transfer / Descriptions / Timeline / FilterForm 等，以及 Maple 的 PullRefresh / SwipeCell / IndexBar / NumberKeyboard / Signature 等，本次没有确认可直接同源对齐的对应组件，保留原菜单。Drawer / Popup 是异名候选；Message 不直接等同 NoticeBar 或 Notification。Cedar 日期/时间 picker 在内部子目录，Maple 菜单通过字段文档组织，标记数量因此不同。

## 维护

唯一分类数据：design-ui/audits/component-reuse.json。修改后从工作区运行 node design-ui/bin/component-reuse-sync.mjs，同步两库的文档元数据；--check 检查漂移。复制的是文档元数据，不是组件源码。后续源码变化后应重新运行 Props 审计并复核分级，不能只更新日期。

## Props 差异快照


由 api-contract-inventory.mjs 从两库根入口追踪 TypeScript 符号生成（含子组件）。
仅比较实际公开运行时 Props 的键，不把工具目录当组件，也不据此声称事件、插槽、方法或行为完全相同。
已批准且实施的语义迁移见 api-alignment-plan.md；剩余集合差异是后续能力规划清单，不自动求并集。

Cedar：129 个 Props 导出；Maple：119 个；同名可比较：97 个。

| Props | Cedar / Maple 键数量 | 仅 Cedar | 仅 Maple |
| --- | --- | --- | --- |
| affixProps | 7 / 7 | — | — |
| alertProps | 10 / 10 | — | — |
| autoCompleteProps | 29 / 29 | — | — |
| avatarGroupProps | 9 / 9 | — | — |
| avatarProps | 15 / 15 | — | — |
| backTopProps | 9 / 9 | — | — |
| badgeProps | 16 / 16 | — | — |
| breadcrumbItemProps | 5 / 5 | — | — |
| breadcrumbProps | 3 / 3 | — | — |
| buttonGroupProps | 9 / 9 | — | — |
| buttonProps | 25 / 25 | — | — |
| cardProps | 19 / 19 | — | — |
| carouselItemProps | 0 / 0 | — | — |
| carouselProps | 27 / 27 | — | — |
| cascaderPanelProps | 0 / 0 | — | — |
| cascaderProps | 43 / 45 | — | `pickerProps`, `popupProps` |
| checkboxGroupProps | 11 / 11 | — | — |
| checkboxProps | 14 / 14 | — | — |
| colProps | 10 / 10 | — | — |
| collapseItemProps | 5 / 5 | — | — |
| collapseProps | 9 / 9 | — | — |
| countToProps | 6 / 6 | — | — |
| countdownProps | 3 / 3 | — | — |
| datePickerProps | 24 / 34 | — | `buttonElevation`, `color`, `elevation`, `hint`, `multiple`, `pickerProps`, `presentation`, `range`, `titleColor`, `touchable` |
| dateProps | 32 / 35 | — | `multiple`, `pickerProps`, `presentation` |
| dateRangePickerProps | 24 / 28 | — | `datePickerProps`, `elevation`, `pickerProps`, `presentation` |
| dateRangeProps | 32 / 35 | — | `datePickerProps`, `pickerProps`, `presentation` |
| dialogProps | 45 / 45 | — | — |
| dividerProps | 10 / 10 | — | — |
| menuProps | 26 / 26 | — | — |
| ellipsisProps | 5 / 5 | — | — |
| emptyProps | 6 / 6 | — | — |
| fieldDecoratorProps | 20 / 20 | — | — |
| formItemProps | 31 / 31 | — | — |
| formProps | 16 / 16 | — | — |
| gridItemProps | 3 / 3 | — | — |
| gridProps | 5 / 5 | — | — |
| hoverOverlayProps | 2 / 2 | — | — |
| iconProps | 7 / 7 | — | — |
| imagePreviewGroupProps | 24 / 24 | — | — |
| imagePreviewProps | 22 / 22 | — | — |
| imageProps | 26 / 26 | — | — |
| infiniteScrollProps | 5 / 5 | — | — |
| inputGroupProps | 5 / 5 | — | — |
| inputNumberProps | 19 / 19 | — | — |
| inputPasswordProps | 27 / 27 | — | — |
| inputProps | 24 / 24 | — | — |
| linkProps | 9 / 9 | — | — |
| listProps | 8 / 8 | — | — |
| loadingProps | 7 / 7 | — | — |
| menuOptionProps | 9 / 9 | — | — |
| messageProps | 14 / 14 | — | — |
| optgroupProps | 0 / 0 | — | — |
| optionProps | 0 / 0 | — | — |
| overlayProps | 8 / 8 | — | — |
| pageHeaderProps | 4 / 4 | — | — |
| paginationProps | 23 / 23 | — | — |
| paperProps | 8 / 8 | — | — |
| popoverProps | 45 / 45 | — | — |
| progressGroupProps | 11 / 11 | — | — |
| progressProps | 15 / 15 | — | — |
| radioGroupProps | 12 / 12 | — | — |
| radioProps | 15 / 15 | — | — |
| rateProps | 18 / 18 | — | — |
| resultProps | 5 / 5 | — | — |
| rowProps | 5 / 5 | — | — |
| searchProps | 39 / 39 | — | — |
| selectProps | 45 / 47 | — | `pickerProps`, `popupProps` |
| skeletonLineProps | 4 / 4 | — | — |
| skeletonProps | 12 / 12 | — | — |
| skeletonShapeProps | 2 / 2 | — | — |
| sliderProps | 23 / 23 | — | — |
| spaceProps | 6 / 6 | — | — |
| splitButtonProps | 21 / 21 | — | — |
| statisticProps | 16 / 16 | — | — |
| stepProps | 6 / 6 | — | — |
| stepsProps | 9 / 9 | — | — |
| styleProviderProps | 2 / 2 | — | — |
| switchProps | 17 / 17 | — | — |
| tabItemProps | 2 / 2 | — | — |
| tabNavProps | 4 / 4 | — | — |
| tabPaneProps | 6 / 6 | — | — |
| tableProps | 42 / 3 | `bordered`, `columnResizable`, `columns`, `components`, `data`, `defaultExpandAllRows`, `defaultExpandedKeys`, `defaultSelectedKeys`, `draggable`, `expandable`, `expandedKeys`, `extraColumn`, `filterIconAlignLeft`, `fit`, `height`, `hideExpandButtonOnEmpty`, `hoverable`, `indentSize`, `loadMore`, `loading`, `maxHeight`, `pagePosition`, `pagination`, `rowClass`, `rowKey`, `rowNumber`, `rowSelection`, `scrollbar`, `selectedKeys`, `showEmptyTree`, `showHeader`, `size`, `spanAll`, `spanMethod`, `stickyHeader`, `stickyPagination`, `stripe`, `summary`, `summarySpanMethod`, `summaryText`, `tableLayout`, `virtualListProps` | `elevation`, `fullWidth`, `scrollerHeight` |
| tabsItemsProps | 0 / 0 | — | — |
| tabsNavsProps | 0 / 0 | — | — |
| tabsProps | 25 / 25 | — | — |
| tagProps | 14 / 14 | — | — |
| textareaProps | 26 / 26 | — | — |
| timePickerProps | 16 / 20 | `showNextDay`, `type` | `color`, `elevation`, `hint`, `pickerProps`, `presentation`, `titleColor` |
| timeProps | 30 / 32 | — | `pickerProps`, `presentation` |
| timeRangePickerProps | 15 / 19 | — | `elevation`, `pickerProps`, `presentation`, `timePickerProps` |
| timeRangeProps | 32 / 35 | — | `pickerProps`, `presentation`, `timePickerProps` |
| tooltipProps | 48 / 48 | — | — |
| triggerProps | 43 / 43 | — | — |
| uploadProps | 40 / 40 | — | — |
| verificationCodeProps | 22 / 22 | — | — |
| watermarkProps | 15 / 15 | — | — |

## 仅 Cedar 根入口存在的 Props 导出

`anchorProps`, `calendarProps`, `colorPickerProps`, `colorProps`, `configProviderProps`, `descriptionsItemProps`, `descriptionsProps`, `drawerProps`, `filterFormProps`, `inputTagProps`, `layoutProps`, `mapProps`, `mentionProps`, `navMenuItemProps`, `navMenuProps`, `notificationProps`, `overflowListProps`, `peopleSelectProps`, `popconfirmProps`, `resizeBoxProps`, `schedulerProps`, `scrollbarProps`, `segmentedProps`, `splitProps`, `timelineProps`, `transferProps`, `treeProps`, `treeSelectProps`, `typographyParagraphProps`, `typographyProps`, `typographyTextProps`, `typographyTitleProps`

## 仅 Maple 根入口存在的 Props 导出

`actionSheetProps`, `cellProps`, `codeProps`, `counterProps`, `dragProps`, `fabProps`, `floatingPanelProps`, `formDetailsProps`, `highlighterProviderProps`, `indexAnchorProps`, `indexBarProps`, `loadingBarProps`, `localeProviderProps`, `noticeBarProps`, `numberKeyboardProps`, `pickerProps`, `popupProps`, `pullRefreshProps`, `signatureProps`, `swipeCellProps`, `tabBarItemProps`, `tabBarProps`

---

Document: llms/zh-CN/guide/controlled-uncontrolled.md

<!-- Source: docs/guide/controlled-uncontrolled.md; locale: zh-CN; page: /guide/controlled-uncontrolled/ -->

# 受控、非受控与清空值：从操作结果理解

本文面向第一次接触“受控”的使用者。先看 Input 的具体操作，再看 `v-model`，最后理解 `emptyValue`。示例描述当前工作区实现；尚未实施的统一方案单独放在末尾。

代码中的组件已按“快速开始”完成注册及样式引入。每个完整 Vue 示例可以独立使用。输入类示例显式设置 `edit-mode="direct"`，先排除弹层确认草稿的影响。

## 1. 先分清三个问题

| 问题                     | 决定它的东西                       | 例子                                                  |
| ------------------------ | ---------------------------------- | ----------------------------------------------------- |
| 当前值最终听谁的？       | `modelValue` 与组件的受控判定      | 父级传 A，拒绝 B，最终仍是 A                          |
| 只想提供初始值吗？       | `defaultValue`                     | 初始杭州，后续用户改成苏州                            |
| 点击清空时提出什么新值？ | `emptyValue`，模板写 `empty-value` | 清空提出 null、空字符串或其他配置值                   |
| 一个值是否显示成“空”？   | 组件的数据类型、选项和格式化规则   | Input 的 null 显示空文字；字符串 EMPTY 显示文字 EMPTY |

**受控的“控”是父组件控制最终值。** 不代表组件被禁用、不能聚焦、没有输入事件，也不代表值由服务器保存。父组件就是写下 `<c-input ... />` 的那个 Vue 组件；这里的 `ref` 或表单对象都属于父级。

`emptyValue` 解决第三个问题，不会自动解决第一个或第四个。它也不是“所有空值的列表”。

## 2. 非受控：只给初始值，之后组件自己保存

```vue
<script setup lang="ts">
import { ref } from "vue";

const seed = ref("杭州");
const instanceKey = ref(0);
const lastRequest = ref<string | null>();
function record(next: string | null) {
  lastRequest.value = next;
}
</script>

<template>
  <c-input
    :key="instanceKey"
    :default-value="seed"
    edit-mode="direct"
    @update:model-value="record"
  />
  <p>初始值变量：{{ seed }}</p>
  <p>最近一次更新请求：{{ JSON.stringify(lastRequest) }}</p>
  <button type="button" @click="seed = '北京'">只修改默认值</button>
  <button type="button" @click="instanceKey++">重新挂载</button>
</template>
```

按下面的顺序操作：

| 操作               | 输入框当前文字 | 父级 seed | 原因                                     |
| ------------------ | -------------- | --------- | ---------------------------------------- |
| 首次打开           | 杭州           | 杭州      | 组件读取默认值                           |
| 全选文字，改成苏州 | 苏州           | 杭州      | 组件保存新值；事件记录不会改 seed        |
| 点击“只修改默认值” | 仍为苏州       | 北京      | 默认值不是当前值，后续变化不覆盖用户输入 |
| 点击“重新挂载”     | 北京           | 北京      | 新实例重新读取默认值                     |

监听 `update:modelValue` 只是知道用户提出了什么。**只监听事件，并没有把记录值传回 modelValue，因此仍是非受控。** 初始化和重挂载不会为了同步父级而自动发出初始值更新。

默认值的变化不会被当前实例当成重置命令。需要程序主动控制当前值时，应使用下面的受控绑定。

## 3. 受控且接受更新：父级保存当前值

```vue
<script setup lang="ts">
import { ref } from "vue";
const text = ref<string | null>("A");
</script>

<template>
  <c-input v-model="text" edit-mode="direct" />
  <p>父级保存的值：{{ JSON.stringify(text) }}</p>
  <button type="button" @click="text = 'C'">父级主动设为 C</button>
</template>
```

全选 A 并输入 B 后，父级 `text` 变成 B，输入框随后以父级 B 为准。再点击按钮，父级把 `text` 改成 C，输入框也显示 C。

```text
父级 text=A → 传给输入框
用户输入 B → 输入框发出 update:modelValue(B)
父级接收并执行 text=B → 把 B 再传给输入框 → 最终显示 B
```

这里发生了一次“组件提出值 → 父级回写 → 组件读取父级值”的过程。“回写”指父级给自己的 ref/表单字段赋值，并让新值通过 prop 传回来，不是子组件直接改父级变量。

Vue 的 `v-model` 帮你自动写了这段回写逻辑。[Vue 官方说明](https://vuejs.org/guide/components/v-model.html)

## 4. 受控但拒绝更新：事件发生不等于值已被接受

```vue
<script setup lang="ts">
import { ref } from "vue";
const text = ref<string | null>("A");
const requested = ref<string | null>();
const count = ref(0);
function recordOnly(next: string | null) {
  requested.value = next;
  count.value++;
  // 有意不执行 text.value = next。
}
</script>

<template>
  <c-input
    :model-value="text"
    edit-mode="direct"
    @update:model-value="recordOnly"
  />
  <p>父级值：{{ JSON.stringify(text) }}</p>
  <p>候选值：{{ JSON.stringify(requested) }}；请求次数：{{ count }}</p>
</template>
```

全选 A 并尝试输入 B：候选值记录为 B，请求次数增加；父级 `text` 仍为 A，因此最终文字仍以 A 为准。输入时浏览器可能短暂显示编辑中的文字；判断最终状态，应看组件完成本轮更新后的结果。

| 项目            | 操作前 | 提出 B 后 |
| --------------- | ------ | --------- |
| 父级 text       | A      | A         |
| 组件提出的候选  | 尚无   | B         |
| 最终模型值/文字 | A      | A         |

这正是受控的用途：父级可以接受、拒绝或修正候选值。不是所有 `update:modelValue` 都会自动修改模型。

不要把这个示例当成只读的推荐写法。真正希望用户不能编辑时，用组件的 `readonly`/`disabled`；它们分别有聚焦、复制和事件行为的约定。拒绝更新演示的是状态所有权。

## 5. 根据条件决定是否接受

用布尔 Switch 可以更直观地观察“接受”与“拒绝”：

```vue
<script setup lang="ts">
import { ref } from "vue";
const enabled = ref(false);
const allowUpdate = ref(false);
const requested = ref<string | number | boolean | null>();
function decide(next: string | number | boolean | null) {
  requested.value = next;
  if (allowUpdate.value && typeof next === "boolean") {
    enabled.value = next;
  }
}
</script>

<template>
  <label><input v-model="allowUpdate" type="checkbox" />允许父级接受更新</label>
  <c-switch :model-value="enabled" @update:model-value="decide" />
  <p>父级值：{{ enabled }}；候选值：{{ JSON.stringify(requested) }}</p>
</template>
```

先保持复选框未选中，点击 Switch：收到 true 候选，但父级不赋值，Switch 仍关闭。勾选复选框后再点 Switch：父级保存 true，Switch 才开启。

这个例子使用 Switch 默认的布尔值；配置 `checkedValue`/`uncheckedValue` 后，父级类型和判断应一起调整。后台权限、外部表单状态等也可以参与父级决策；业务需要等待时，显式展示 pending，避免让用户误以为更新已经生效。

## 6. `v-model` 到底省略了什么？

```html
<c-input v-model="text" />
```

等价于下面的模板绑定：

```html
<c-input :model-value="text" @update:model-value="text = $event" />
```

在 `<script setup>` 的函数里写的是 `text.value = next`；模板会自动解包 ref，所以模板里写 `text = $event`。

| 写法                       | 是否把父级值传入 | 是否回写更新                     | 对严格受控组件的意义 |
| -------------------------- | ---------------- | -------------------------------- | -------------------- |
| 只传 default-value         | 否               | 否                               | 组件自己保存后续值   |
| 只监听 update:modelValue   | 否               | 由监听函数决定，但未传回就不控制 | 只观察               |
| 只传 model-value=A         | 是               | 否                               | 固定以 A 为准        |
| model-value 加只记录事件   | 是               | 否                               | 收到候选，保持 A     |
| model-value 加赋值处理函数 | 是               | 是                               | 父级可以筛选更新     |
| v-model=text               | 是               | 自动赋值                         | 通常直接接受每次更新 |

“v-model 总是受控”也有前提：对按 `modelValue !== undefined` 判定的组件，`ref(undefined)` 初始仍未受控。还有少数组件采用本地代理，见第 15 节。

给 `v-model` 再加 `@update:model-value` 监听器，不能靠 `return false` 阻止 v-model 自带的赋值。需要拒绝时，请使用第 4/5 节的显式绑定。`change` 是提交通知，也不能通过返回 false 当作守卫。不要把同一次提交同时在 update 和 change 里执行两次保存。

## 7. `emptyValue` 与受控有冲突吗？

**功能本身不冲突；`undefined` 在特定组合下会同时承担两个含义。**

对 Input、InputNumber、Switch、Slider、Select 等采用 undefined 判定的模型：

```ts
// 判定规则示意，不是使用者需要添加的代码。
const isControlled = modelValue !== undefined;
```

这表示 `''`、`0`、`false` 和合法 `null` 都是已定义的受控值。是否允许某个值仍取决于具体组件：例如页码不能因为 0 是已定义的就变成合法页码。

点击清空后，会先提出一个候选值。随后发生什么由父级决定：

| 清空候选     | 父级处理              | 回传的 modelValue | 结果                                     |
| ------------ | --------------------- | ----------------- | ---------------------------------------- |
| null         | 接受                  | null              | 仍受控，前提是组件支持 null              |
| 空字符串     | 接受                  | 空字符串          | 仍受控                                   |
| undefined    | 原样接受              | undefined         | 进入非受控模式                           |
| undefined    | 归一化为 null         | null              | 仍受控                                   |
| 任意清空候选 | 忽略更新，原值 A 不变 | A                 | 保持原来的受控值                         |
| undefined    | 组件本来就是非受控    | 未绑定            | 由组件处理内部空状态，不涉及交出父级控制 |

因此，**不能只看 emptyValue 配置，就断言一定失去控制。** 真正的控制模式变化发生在父级传回 undefined 时。单纯调用 emptyValue 工厂或收到事件，还没有改变外部 prop。

## 8. 四种 empty-value 写法并不等价

共享 `resolveEmptyValue` 的当前行为如下；未设置时的结果由各组件传入的 fallback 决定：

| 写法                             | 表示什么                                       |
| -------------------------------- | ---------------------------------------------- |
| 不写 empty-value                 | 使用组件现有的默认清空值                       |
| `:empty-value="undefined"`       | 同样使用组件默认清空值；不是强制输出 undefined |
| `:empty-value="() => undefined"` | 在该组件类型支持时，显式请求清空输出 undefined |
| `:empty-value="null"`            | 显式请求输出 null                              |
| `empty-value="EMPTY"`            | 请求输出字符串 EMPTY，不保证显示为空           |
| `:empty-value="0"`               | 请求输出数值 0；不是所有组件都接受这个值       |
| `:empty-value="() => []"`        | 请求新空数组，仍须符合组件模型与业务约束       |

工厂写法能区分“没有配置”和“明确返回 undefined”。Input 的空值类型是 string/null 及相应工厂，不应为了试验强行传入不支持的 undefined 工厂；下面使用支持该工厂的 InputNumber。

普通字符串要注意 Vue 绑定：`empty-value="null"` 是四个字符的字符串 null；`:empty-value="null"` 才是真正的 null。直接 `empty-value="0"` 也不是数值绑定。

目前核实的默认清空路径：

| 组件/路径                         | 未配置覆盖值时的当前候选                          |
| --------------------------------- | ------------------------------------------------- |
| Input 清空按钮                    | 空字符串                                          |
| InputNumber 清空按钮              | undefined                                         |
| Select 单选且没有空字符串选项     | 通常空字符串                                      |
| Select 单选且存在 value='' 的选项 | undefined，用来区分“选择空字符串选项”和“清空选择” |
| Select 多选                       | 通常空数组；受保护的禁用选中项可能保留            |

这张表不是全组件空值规范。日期/时间及不同面板另有路径，不要从组件名称推断。`emptyValue` 也不会绕过禁用、只读、待处理事务、受保护选项等业务限制。

## 9. 示例：Input 清空成 null，之后仍然受控

```vue
<script setup lang="ts">
import { ref } from "vue";
const text = ref<string | null>("A");
const updates = ref<string[]>([]);
function accept(next: string | null) {
  updates.value.push(JSON.stringify(next));
  text.value = next;
}
</script>

<template>
  <c-input
    :model-value="text"
    :empty-value="null"
    edit-mode="direct"
    clearable
    @update:model-value="accept"
  />
  <p>父级值：{{ JSON.stringify(text) }}</p>
  <p>请求记录：{{ updates.join(" → ") }}</p>
</template>
```

操作顺序与预期：

| 操作                    | 本次候选 | 父级 text | 输入框 |
| ----------------------- | -------- | --------- | ------ |
| 初始                    | 无       | A         | A      |
| 点击清空按钮            | null     | null      | 空白   |
| 再输入 B                | B        | B         | B      |
| 全选后按 Backspace 删光 | 空字符串 | 空字符串  | 空白   |

null 与空字符串都能显示空白，但模型里的值不同。**当前 emptyValue 控制清空动作的输出，不会把手动删光自动改成 null。** 如果业务要求所有空文字统一为 null，可在父级处理函数中使用 `text.value = next === '' ? null : next`。

同理，设置 `empty-value="EMPTY"` 的 Input，点击清空后会以字符串 EMPTY 为值；“清空按钮”并不保证最终得到无文字的状态。

## 10. 示例：undefined 清空后为什么改变模式？

这是观察当前行为的示例，不是持续受控表单的推荐配置。

```vue
<script setup lang="ts">
import { ref } from "vue";
const quantity = ref<number | null | undefined>(12);
const clearToUndefined = () => undefined;
const describe = (value: unknown) =>
  value === undefined ? "undefined" : JSON.stringify(value);
const lastRequest = ref("尚无更新");
function accept(next: number | null | undefined) {
  lastRequest.value = describe(next);
  quantity.value = next;
}
</script>

<template>
  <c-input-number
    :model-value="quantity"
    :empty-value="clearToUndefined"
    edit-mode="direct"
    clearable
    @update:model-value="accept"
  />
  <p>父级值：{{ describe(quantity) }}；候选值：{{ lastRequest }}</p>
  <p>按当前判定是否受控：{{ quantity !== undefined }}</p>
</template>
```

| 步骤                                 | 父级 quantity | quantity !== undefined | 谁保存最终值           |
| ------------------------------------ | ------------- | ---------------------- | ---------------------- |
| 初始为 12                            | 12            | true                   | 父级                   |
| 组件提出 undefined，父级尚未处理     | 仍为 12       | true                   | 仍为父级               |
| accept 原样回写                      | undefined     | false                  | 组件内部               |
| 后续用户操作，父级继续不提供已定义值 | undefined     | false                  | 组件可以保存后续内部值 |

这里的变化不是由“空白”造成的，而是由 modelValue 的实际值变成 undefined 造成的。之后如果父级又回写一个已定义数值，便重新进入受控。当前各组件切换时内部值的保留策略尚未统一，不应依赖切换模式完成 reset。

同样，不要期待 `v-model` 的类型声明替你做运行时转换。把 ref 写成 `number | null` 并不会自动把收到的 undefined 转成 null。

## 11. 推荐示例：父级归一化，兼容不同空输入路径

```vue
<script setup lang="ts">
import { ref } from "vue";
const quantity = ref<number | null>(12);
const lastRequest = ref("尚无更新");
function acceptNormalized(next: number | null | undefined) {
  lastRequest.value = next === undefined ? "undefined" : JSON.stringify(next);
  quantity.value = next ?? null;
}
</script>

<template>
  <c-input-number
    :model-value="quantity"
    :empty-value="null"
    edit-mode="direct"
    clearable
    @update:model-value="acceptNormalized"
  />
  <p>组件候选值：{{ lastRequest }}</p>
  <p>父级最终值：{{ JSON.stringify(quantity) }}</p>
  <p>按当前判定是否受控：{{ quantity !== undefined }}</p>
</template>
```

这个处理同时覆盖清空按钮和其他实际发出 undefined 的输入路径：null → null，undefined → null，0 → 0，其他数值保持不变。父级保存的 quantity 始终不为 undefined，所以最终模型保持受控。

为什么除了 empty-value=null，还需要处理函数？当前 InputNumber 的清空按钮经过 `resolveEmptyValue`，而手动删空并提交的分支可以直接产生 undefined；在 `modelEvent='input'` 时还可能更早提出空值。**emptyValue 不是输入解析器，也不是所有提交路径的归一化器。**

不要写 `next || null`：它会把有效数值 0 也变成 null。`next ?? null` 只合并 null/undefined。该例的字段允许空数值；不要直接把这套归一化套在页码等不允许 null 的模型上。

如果希望父级用 v-model 的形式调用，可以用带 setter 的 computed 做同样转换；只读 computed 没有可回写入口。异步保存也应与本地回写分开：例如先同步更新父级表单，再在提交按钮中保存；如果业务需要先审核再接受，保留旧值并显示 pending，不靠延迟回写掩盖状态。

## 12. 示例：空字符串是有效选项时，使用 null 区分未选择

```vue
<script setup lang="ts">
import { ref } from "vue";
const selected = ref<string | null>(null);
const options = [
  { label: "全部", value: "" },
  { label: "仅启用", value: "enabled" },
];
</script>

<template>
  <c-select
    v-model="selected"
    :options="options"
    :empty-value="null"
    edit-mode="direct"
    clearable
  />
  <p>父级值：{{ JSON.stringify(selected) }}</p>
</template>
```

| 操作         | 父级 selected | 含义                 |
| ------------ | ------------- | -------------------- |
| 初始         | null          | 尚未选择             |
| 选择“全部”   | 空字符串      | 已选择一个合法选项   |
| 选择“仅启用” | enabled       | 已选择另一个选项     |
| 点击清空     | null          | 恢复未选择，保持受控 |

不要把 `selected === ''` 同时当作“全部”和“未选择”。Element Plus 的文档用类似的空字符串选项说明这个问题，但它另有 `empty-values` 与 `value-on-clear` 两个 API；我们当前没有因此自动获得 `empty-values` 功能。

多选使用数组时，应按该组件的数组值域初始化并选择合适的 emptyValue，不能从“null 可用于某个单选”推出“所有多选都该改成 null”。选择器还会保留不能清除的禁用项；清空配置不覆盖这条业务规则。

## 13. 示例：值和弹层开合是两个独立模型

```vue
<script setup lang="ts">
import { ref } from "vue";
const selected = ref<string | null>(null);
const panelOpen = ref(false);
const allowClose = ref(true);
const options = [
  { label: "杭州", value: "hz" },
  { label: "北京", value: "bj" },
];
function acceptOpen(next: boolean) {
  if (next || allowClose.value) panelOpen.value = next;
}
</script>

<template>
  <label><input v-model="allowClose" type="checkbox" />允许接受关闭请求</label>
  <c-select
    v-model="selected"
    :open="panelOpen"
    :options="options"
    :empty-value="null"
    edit-mode="direct"
    clearable
    @update:open="acceptOpen"
  />
  <p>值：{{ JSON.stringify(selected) }}；展开：{{ panelOpen }}</p>
  <button type="button" @click="panelOpen = false">父级主动关闭</button>
</template>
```

选择值通过 v-model 直接接受，开合通过显式处理函数决定。取消“允许接受关闭请求”后，值仍可更新，但关闭请求会被父级拒绝；点击“父级主动关闭”则直接修改 panelOpen。

这不是一个“整个组件是否受控”的全局开关，而是两个状态分别有自己的所有者。`v-model:open="panelOpen"` 只是 `:open` 加 `@update:open="panelOpen = $event"` 的简写。

本例使用 Select 的直接编辑形态。弹层确认编辑还有 draft：面板中的候选可以与最终 modelValue 不同；确认才提交，取消应丢弃本轮草稿。看到候选文字变化，不足以判断最终模型是否被组件自行修改。

## 14. 表单初始化、重置与后端空值

```vue
<script setup lang="ts">
import { reactive, ref } from "vue";
const form = reactive<{ name: string | null; quantity: number | null }>({
  name: null,
  quantity: null,
});
const payloadText = ref("尚未提交");
function updateQuantity(next: number | null | undefined) {
  form.quantity = next ?? null;
}
function reset() {
  form.name = null;
  form.quantity = null;
}
function submit() {
  const payload = {
    name: form.name === null ? undefined : form.name,
    quantity: form.quantity === null ? undefined : form.quantity,
  };
  payloadText.value = JSON.stringify(payload);
}
</script>

<template>
  <c-input
    v-model="form.name"
    :empty-value="null"
    edit-mode="direct"
    clearable
  />
  <c-input-number
    :model-value="form.quantity"
    :empty-value="null"
    edit-mode="direct"
    clearable
    @update:model-value="updateQuantity"
  />
  <button type="button" @click="reset">重置父级数据</button>
  <button type="button" @click="submit">生成提交数据</button>
  <p>提交数据：{{ payloadText }}</p>
</template>
```

这个例子用普通 reactive 对象说明状态归属，不依赖 Form 的布局或校验 API：父级负责初始化和 reset。Input 的默认值不会把空的 form 字段自动填成有值；需要初始姓名时，应直接初始化 form.name。

生成提交数据时，把 UI 中的 null 转为对象属性的 undefined，JSON 序列化便省略该属性；这一步不改变 form 本身。业务若要求发送 JSON null，就不要做该转换。

**界面模型的空值与后端传输格式可以不同。** 无需为了后端“省略字段”的要求，让受控组件的 modelValue 也变成 undefined。这里的文本空字符串仍原样发送；如果业务也要求省略空字符串，需在序列化层明确处理，不把它与 null 混为一谈。

## 15. 当前还不能一概而论的组件

以下是现状说明，不是目标设计已落地的声明：

| 范围                                 | 当前差异                                                                      |
| ------------------------------------ | ----------------------------------------------------------------------------- |
| Maple ActionSheet.open               | 默认 useVModel 本地代理，内部可以先改变状态                                   |
| Maple NumberKeyboard.open/modelValue | 两个模型均使用默认本地代理                                                    |
| Maple FloatingPanel.modelValue       | 停靠高度使用代理；另有手势显示高度                                            |
| Maple Popup 设置 beforeClose         | 会使用内部 visible，并可能拦截父级 open=false，拒绝时反向发 update:open(true) |
| 两端 Collapse                        | 当前使用 nullish 回退；null 会回退内部状态，全部收起用 []                     |

前三项不能用“忽略 update 就一定不会变化”推断。父级传回同一个原值，也不一定触发同步代理的 watch。两端 useVModel 工具逻辑基本一致，但 Input/Switch/Slider 等自己实现状态管理；工具函数名称不代表全组件行为。

InputNumber 可能保留尚未提交的中间文本，Input 还涉及 IME；Popup 退场时可能保留 DOM。应区分最终模型、草稿/原生编辑状态和动画状态。

## 16. 其他文档有哪些写法值得借鉴？

以下是说明方式的参考，不表示这些库的 API、空值或模式切换规则可直接照搬到 Cedar/Maple。所有示例均针对我们的组件重写。

| 参考                                                                                                                          | 值得借鉴的说明方式                               |
| ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
| [Reka：Controlled State](https://www.reka-ui.com/docs/guides/controlled-state)                                                | 将显式回写、v-model 简写和 defaultValue 并排展示 |
| [React：Input](https://react.dev/reference/react-dom/components/input#controlling-an-input-with-a-state-variable)             | 通过“不回写便恢复原值”的操作结果解释所有权       |
| [Radix：Dialog 异步提交](https://www.radix-ui.com/primitives/docs/components/dialog#close-after-asynchronous-form-submission) | 用保存完成后由父级关闭的业务场景解释受控的价值   |
| [Element Plus：Select 空值](https://element-plus.org/en-US/component/select.html#empty-values)                                | 区分空值识别与清空输出，展示空字符串作为合法选项 |
| [Naive UI：受控说明](https://www.naiveui.com/zh-CN/docs/controlled-uncontrolled)                                              | 明确写出 undefined 如何影响控制模式              |

React 原生受控文本输入不应传 null/undefined；我们的 Input 接受 null 并显示为空。借鉴操作解释，不能把 React 的空值限制当成所有 Vue 组件库的规则。只有值 prop 的写法也不是一律写错：有意固定状态是合法用途；希望可编辑却忘记回写，才与预期不符。

## 17. 目标设计与现有 emptyValue 的关系

统一方案尚未实施。推荐保持这些边界：最终受控状态由父级决定；默认值只初始化；标准清空值尽量使用已定义的领域空值；草稿、手势、动画不能代替最终值。

**保留 emptyValue 的自定义输出能力，不把所有 () => undefined 一律视为非法。** 它与明确的父级归一化、已有接口和特定业务有配合价值；只是父级原样回传 undefined 时，必须接受当前判定下的非受控后果。

目标会继续单独设计各条空输入路径：清空按钮、键盘删空、面板清空和 Form reset，避免只改按钮而遗漏其他路径。更改已发布组件的默认空值、模式切换或代理行为，需要单独版本迁移，不能只更新文档就当作已经实现。

## 18. 排查时按这个顺序看

1. 确认当前讨论的是哪个状态：modelValue、open，还是 draft。
2. 看父级真正传下来的值；不要只看 ref 的静态类型或输入框是否空白。
3. 记录 update 事件候选，确认父级是否赋值，以及是否做了转换。
4. 若候选为空，区分清空按钮、手动删除、面板确认或 Form reset 路径。
5. 检查 emptyValue 是省略、显式 null、字符串，还是工厂返回 undefined。
6. 最后检查是否属于第 15 节的代理/守卫例外。

源码入口：两端 `packages/*-ui/src/input/use-input-value.ts`、`input-number/use-number-value.ts`、`select/use-select-controller.ts`、empty-value 工具；两端 `packages/*-use/src/useVModel.ts`；Maple 上述三个代理组件及 Popup。本文的预期值表用于说明已核实路径，不等于所有组件、平台与浏览器交互均已验收。

---

Document: llms/zh-CN/guide/design-token-reference.md

<!-- Source: docs/guide/design-token-reference.md; locale: zh-CN; page: /guide/design-token-reference/ -->

# Cedar 组件 CSS 变量参考

本页由组件 Token 声明编译生成，不手工维护表格。在 design-ui 运行 `node bin/token-catalog.mjs --patch` 后应用补丁；`--check` 检查源码与文档是否一致。

与《Design Token 与 CSS 变量分层》配合阅读：这里列出准确名称、声明值与消费证据，不代表所有组件均通过视觉验收。值是声明表达式，不是最终像素；多值保留各自选择器条件，主题对象和行内属性仍可覆盖。foundation/system 的角色见设计规范，不在这里冒充组件 API。

公开变量可在组件实际根节点或弹层真实挂载祖先覆盖；内部变量只用于实现，业务禁止依赖。size / variant / status / loading / disabled 决定何时消费，不能认为一个变量在所有状态都生效。消费属性列表来自编译后的传递引用，只证明可达性，不替代选择器可见性和优先级检查。

## _components/field-presentation

声明来源: `src/_components/field-presentation/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-field-presentation-border` | 内部 | `var(--c-color-border-2)` | 本组件 CSS<br>`border`, `border-bottom`, `border-top` |
| `--c-field-presentation-close-font-size` | 内部 | `24px` | 本组件 CSS<br>`font-size` |
| `--c-field-presentation-close-size` | 内部 | `32px` | 本组件 CSS<br>`height`, `width` |
| `--c-field-presentation-edit-hover-background` | 内部 | `var(--c-color-fill-2)` | 本组件 CSS<br>`background` |
| `--c-field-presentation-edit-size` | 内部 | `28px` | 本组件 CSS<br>`height`, `padding-inline-end`, `width` |
| `--c-field-presentation-editor-action-width` | 内部 | `88px` | 待审查，不应依赖 |
| `--c-field-presentation-editor-edge-gap` | 内部 | `8px` | 本组件 CSS<br>`max-height` |
| `--c-field-presentation-editor-max-height` | 内部 | `calc(100dvh - 2 * var(--c-field-presentation-editor-edge-gap))` | 本组件 CSS<br>`max-height` |
| `--c-field-presentation-editor-padding` | 内部 | `4px` | 本组件 CSS<br>`max-height`, `padding` |
| `--c-field-presentation-gap` | 内部 | `var(--c-sys-space-3)` | 本组件 CSS<br>`gap`, `margin-bottom`, `margin-top`, `padding-bottom`, `padding-top` |
| `--c-field-presentation-max-height` | 内部 | `60vh` | 本组件 CSS<br>`max-height` |
| `--c-field-presentation-min-width` | 内部 | `280px` | 本组件 CSS<br>`min-width` |
| `--c-field-presentation-padding` | 内部 | `var(--c-sys-space-4)` | 本组件 CSS<br>`inset-inline-end`, `max-width`, `padding`, `padding-block`, `padding-inline-end` |
| `--c-field-presentation-radius` | 内部 | `8px` | 本组件 CSS<br>`border-radius` |
| `--c-field-presentation-shadow` | 内部 | `0 8px 28px rgba(0, 0, 0, 0.12)` | 本组件 CSS<br>`box-shadow` |
| `--c-field-presentation-title-font-size` | 内部 | `16px` | 本组件 CSS<br>`font-size` |
| `--c-field-presentation-title-font-weight` | 内部 | `500` | 本组件 CSS<br>`font-weight` |

</div>

## _components/picker-field

声明来源: `src/_components/picker-field/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-picker-field-gap` | 公开 | `8px` | 本组件 CSS<br>`gap` |
| `--c-picker-field-input-min-width` | 公开 | `3em` | 本组件 CSS<br>`min-width` |

</div>

## _components/selected-options

声明来源: `src/_components/selected-options/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-selected-options-background` | 公开 | `var(--c-sys-color-surface-overlay)` | 本组件 CSS<br>`background` |
| `--c-selected-options-border` | 公开 | `var(--c-color-border-2)` | 本组件 CSS<br>`border-bottom` |
| `--c-selected-options-details-max-height` | 公开 | `50dvh` | 本组件 CSS<br>`max-height` |
| `--c-selected-options-disabled-opacity` | 公开 | `0.5` | 本组件 CSS<br>`opacity` |
| `--c-selected-options-gap` | 公开 | `8px` | 本组件 CSS<br>`gap` |
| `--c-selected-options-padding` | 公开 | `8px 12px` | 本组件 CSS<br>`padding` |
| `--c-selected-options-radius` | 公开 | `4px` | 本组件 CSS<br>`border-radius` |
| `--c-selected-options-remove-size` | 公开 | `24px` | 本组件 CSS<br>`height`, `width` |
| `--c-selected-options-tag-padding` | 公开 | `2px 6px` | 本组件 CSS<br>`padding` |
| `--c-selected-options-tags-max-height` | 公开 | `112px` | 本组件 CSS<br>`max-height` |
| `--c-selection-editor-accent` | 公开 | `var(--c-color-primary)` | 本组件 CSS<br>`color` |
| `--c-selection-editor-background` | 公开 | `var(--c-sys-color-surface-overlay)` | 本组件 CSS<br>`background` |
| `--c-selection-editor-border` | 公开 | `var(--c-color-border-2)` | 本组件 CSS<br>`border-bottom`, `border-right` |
| `--c-selection-editor-check-size` | 公开 | `20px` | 本组件 CSS<br>`height`, `width` |
| `--c-selection-editor-color` | 公开 | `var(--c-color-text-1)` | 本组件 CSS<br>`color` |
| `--c-selection-editor-dialog-height` | 公开 | `min(30dvh, 260px)` | 本组件 CSS<br>`height`, `min-height` |
| `--c-selection-editor-font-size` | 公开 | `14px` | 本组件 CSS<br>`font-size` |
| `--c-selection-editor-gap` | 公开 | `8px` | 本组件 CSS<br>`gap`, `margin-inline-start`, `padding` |
| `--c-selection-editor-height` | 公开 | `min(40dvh, 320px)` | 本组件 CSS<br>`height`, `min-height` |
| `--c-selection-editor-muted-background` | 公开 | `var(--c-color-fill-1)` | 本组件 CSS<br>`background` |
| `--c-selection-editor-muted-color` | 公开 | `var(--c-color-text-3)` | 本组件 CSS<br>`color` |
| `--c-selection-editor-padding` | 公开 | `12px` | 本组件 CSS<br>`margin-block`, `padding` |
| `--c-selection-editor-path-height` | 公开 | `44px` | 本组件 CSS<br>`min-height` |
| `--c-selection-editor-radius` | 公开 | `8px` | 本组件 CSS<br>`border-radius` |
| `--c-selection-editor-row-height` | 公开 | `42px` | 本组件 CSS<br>`min-height` |
| `--c-selection-editor-selected-background` | 公开 | `var(--c-color-primary-light-1)` | 本组件 CSS<br>`background` |
| `--c-selection-editor-touch-font-size` | 公开 | `16px` | 本组件 CSS<br>`font-size` |
| `--c-selection-editor-touch-height` | 公开 | `52px` | 本组件 CSS<br>`min-height` |
| `--c-selection-editor-width` | 公开 | `640px` | 本组件 CSS<br>`width` |

</div>

## _components/selection-field

声明来源: `src/_components/selection-field/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-selection-field-gap` | 公开 | `4px` | 本组件 CSS<br>`gap` |
| `--c-selection-field-icon-transition-duration` | 公开 | `0.2s` | 本组件 CSS<br>`transition` |
| `--c-selection-field-input-min-width` | 公开 | `2px` | 本组件 CSS<br>`flex-basis`, `min-width` |
| `--c-selection-field-loading-duration` | 公开 | `1s` | 本组件 CSS<br>`animation` |
| `--c-selection-field-search-min-width` | 公开 | `3em` | 本组件 CSS<br>`flex`, `min-width` |

</div>

## alert

声明来源: `src/alert/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-alert-action-margin-left` | 公开 | `var(--c-sys-space-5)` | 本组件 CSS<br>`margin-left` |
| `--c-alert-border-radius` | 公开 | `var(--c-sys-radius-md)` | 本组件 CSS<br>`border-radius` |
| `--c-alert-border-width` | 公开 | `1px` | 本组件 CSS<br>`border` |
| `--c-alert-close-duration` | 公开 | `var(--c-sys-motion-duration-slow)` | 本组件 CSS<br>`transition` |
| `--c-alert-close-margin-left` | 公开 | `var(--c-sys-space-4)` | 本组件 CSS<br>`margin-left` |
| `--c-alert-font-size-content` | 公开 | `var(--c-sys-font-size-md)` | 本组件 CSS<br>`font-size` |
| `--c-alert-font-size-title` | 公开 | `var(--c-sys-font-size-lg)` | 本组件 CSS<br>`font-size` |
| `--c-alert-font-weight-title` | 公开 | `var(--c-sys-font-weight-medium)` | 本组件 CSS<br>`font-weight` |
| `--c-alert-icon-margin-right` | 公开 | `var(--c-sys-space-4)` | 本组件 CSS<br>`margin-right` |
| `--c-alert-icon-size` | 公开 | `16px` | 本组件 CSS<br>`font-size` |
| `--c-alert-line-height` | 公开 | `1.5715` | 本组件 CSS<br>`line-height` |
| `--c-alert-line-height-title` | 公开 | `1.5` | 本组件 CSS<br>`line-height` |
| `--c-alert-outline-danger-border` | 公开 | `var(--c-sys-color-content-danger)` | 本组件 CSS<br>`border-color` |
| `--c-alert-outline-danger-content` | 公开 | `var(--c-sys-color-content-danger)` | 本组件 CSS<br>`color` |
| `--c-alert-outline-danger-icon` | 公开 | `var(--c-sys-color-content-danger)` | 本组件 CSS<br>`color` |
| `--c-alert-outline-danger-title` | 公开 | `var(--c-sys-color-content-danger)` | 本组件 CSS<br>`color` |
| `--c-alert-outline-default-border` | 公开 | `var(--c-sys-color-border-default)` | 本组件 CSS<br>`border-color` |
| `--c-alert-outline-default-content` | 公开 | `var(--c-sys-color-content-secondary)` | 本组件 CSS<br>`color` |
| `--c-alert-outline-default-icon` | 公开 | `var(--c-sys-color-content-secondary)` | 本组件 CSS<br>`color` |
| `--c-alert-outline-default-title` | 公开 | `var(--c-sys-color-content-primary)` | 本组件 CSS<br>`color` |
| `--c-alert-outline-info-border` | 公开 | `var(--c-sys-color-content-info)` | 本组件 CSS<br>`border-color` |
| `--c-alert-outline-info-content` | 公开 | `var(--c-sys-color-content-info)` | 本组件 CSS<br>`color` |
| `--c-alert-outline-info-icon` | 公开 | `var(--c-sys-color-content-info)` | 本组件 CSS<br>`color` |
| `--c-alert-outline-info-title` | 公开 | `var(--c-sys-color-content-info)` | 本组件 CSS<br>`color` |
| `--c-alert-outline-success-border` | 公开 | `var(--c-sys-color-content-success)` | 本组件 CSS<br>`border-color` |
| `--c-alert-outline-success-content` | 公开 | `var(--c-sys-color-content-success)` | 本组件 CSS<br>`color` |
| `--c-alert-outline-success-icon` | 公开 | `var(--c-sys-color-content-success)` | 本组件 CSS<br>`color` |
| `--c-alert-outline-success-title` | 公开 | `var(--c-sys-color-content-success)` | 本组件 CSS<br>`color` |
| `--c-alert-outline-warning-border` | 公开 | `var(--c-sys-color-content-warning)` | 本组件 CSS<br>`border-color` |
| `--c-alert-outline-warning-content` | 公开 | `var(--c-sys-color-content-warning)` | 本组件 CSS<br>`color` |
| `--c-alert-outline-warning-icon` | 公开 | `var(--c-sys-color-content-warning)` | 本组件 CSS<br>`color` |
| `--c-alert-outline-warning-title` | 公开 | `var(--c-sys-color-content-warning)` | 本组件 CSS<br>`color` |
| `--c-alert-padding-horizontal` | 公开 | `var(--c-sys-space-6)` | 本组件 CSS<br>`padding` |
| `--c-alert-padding-horizontal-with-title` | 公开 | `var(--c-sys-space-6)` | 本组件 CSS<br>`padding` |
| `--c-alert-padding-vertical` | 公开 | `var(--c-sys-space-4)` | 本组件 CSS<br>`padding` |
| `--c-alert-padding-vertical-with-title` | 公开 | `var(--c-sys-space-6)` | 本组件 CSS<br>`padding` |
| `--c-alert-standard-danger-bg` | 公开 | `rgb(var(--c-danger-1))` | 本组件 CSS<br>`background-color` |
| `--c-alert-standard-danger-border` | 公开 | `rgb(var(--c-danger-3))` | 本组件 CSS<br>`border-color` |
| `--c-alert-standard-danger-content` | 公开 | `var(--c-sys-color-content-danger)` | 本组件 CSS<br>`color` |
| `--c-alert-standard-danger-icon` | 公开 | `var(--c-sys-color-content-danger)` | 本组件 CSS<br>`color` |
| `--c-alert-standard-danger-title` | 公开 | `var(--c-sys-color-content-danger)` | 本组件 CSS<br>`color` |
| `--c-alert-standard-default-bg` | 公开 | `var(--c-color-fill-2)` | 本组件 CSS<br>`background-color` |
| `--c-alert-standard-default-border` | 公开 | `var(--c-sys-color-border-default)` | 本组件 CSS<br>`border-color` |
| `--c-alert-standard-default-content` | 公开 | `var(--c-sys-color-content-secondary)` | 本组件 CSS<br>`color` |
| `--c-alert-standard-default-icon` | 公开 | `var(--c-sys-color-content-secondary)` | 本组件 CSS<br>`color` |
| `--c-alert-standard-default-title` | 公开 | `var(--c-sys-color-content-primary)` | 本组件 CSS<br>`color` |
| `--c-alert-standard-info-bg` | 公开 | `rgb(var(--c-blue-1))` | 本组件 CSS<br>`background-color` |
| `--c-alert-standard-info-border` | 公开 | `rgb(var(--c-blue-3))` | 本组件 CSS<br>`border-color` |
| `--c-alert-standard-info-content` | 公开 | `var(--c-sys-color-content-info)` | 本组件 CSS<br>`color` |
| `--c-alert-standard-info-icon` | 公开 | `var(--c-sys-color-content-info)` | 本组件 CSS<br>`color` |
| `--c-alert-standard-info-title` | 公开 | `var(--c-sys-color-content-info)` | 本组件 CSS<br>`color` |
| `--c-alert-standard-success-bg` | 公开 | `rgb(var(--c-success-1))` | 本组件 CSS<br>`background-color` |
| `--c-alert-standard-success-border` | 公开 | `rgb(var(--c-success-3))` | 本组件 CSS<br>`border-color` |
| `--c-alert-standard-success-content` | 公开 | `var(--c-sys-color-content-success)` | 本组件 CSS<br>`color` |
| `--c-alert-standard-success-icon` | 公开 | `var(--c-sys-color-content-success)` | 本组件 CSS<br>`color` |
| `--c-alert-standard-success-title` | 公开 | `var(--c-sys-color-content-success)` | 本组件 CSS<br>`color` |
| `--c-alert-standard-warning-bg` | 公开 | `rgb(var(--c-warning-1))` | 本组件 CSS<br>`background-color` |
| `--c-alert-standard-warning-border` | 公开 | `rgb(var(--c-warning-3))` | 本组件 CSS<br>`border-color` |
| `--c-alert-standard-warning-content` | 公开 | `var(--c-sys-color-content-warning)` | 本组件 CSS<br>`color` |
| `--c-alert-standard-warning-icon` | 公开 | `var(--c-sys-color-content-warning)` | 本组件 CSS<br>`color` |
| `--c-alert-standard-warning-title` | 公开 | `var(--c-sys-color-content-warning)` | 本组件 CSS<br>`color` |
| `--c-alert-title-margin-bottom` | 公开 | `var(--c-sys-space-2)` | 本组件 CSS<br>`margin-bottom` |
| `--c-alert-tonal-danger-bg` | 公开 | `rgb(var(--c-danger-1))` | 本组件 CSS<br>`background-color` |
| `--c-alert-tonal-danger-content` | 公开 | `var(--c-sys-color-content-danger)` | 本组件 CSS<br>`color` |
| `--c-alert-tonal-danger-icon` | 公开 | `var(--c-sys-color-content-danger)` | 本组件 CSS<br>`color` |
| `--c-alert-tonal-danger-title` | 公开 | `var(--c-sys-color-content-danger)` | 本组件 CSS<br>`color` |
| `--c-alert-tonal-default-bg` | 公开 | `var(--c-color-fill-2)` | 本组件 CSS<br>`background-color` |
| `--c-alert-tonal-default-content` | 公开 | `var(--c-sys-color-content-secondary)` | 本组件 CSS<br>`color` |
| `--c-alert-tonal-default-icon` | 公开 | `var(--c-sys-color-content-secondary)` | 本组件 CSS<br>`color` |
| `--c-alert-tonal-default-title` | 公开 | `var(--c-sys-color-content-primary)` | 本组件 CSS<br>`color` |
| `--c-alert-tonal-info-bg` | 公开 | `rgb(var(--c-blue-1))` | 本组件 CSS<br>`background-color` |
| `--c-alert-tonal-info-content` | 公开 | `var(--c-sys-color-content-info)` | 本组件 CSS<br>`color` |
| `--c-alert-tonal-info-icon` | 公开 | `var(--c-sys-color-content-info)` | 本组件 CSS<br>`color` |
| `--c-alert-tonal-info-title` | 公开 | `var(--c-sys-color-content-info)` | 本组件 CSS<br>`color` |
| `--c-alert-tonal-success-bg` | 公开 | `rgb(var(--c-success-1))` | 本组件 CSS<br>`background-color` |
| `--c-alert-tonal-success-content` | 公开 | `var(--c-sys-color-content-success)` | 本组件 CSS<br>`color` |
| `--c-alert-tonal-success-icon` | 公开 | `var(--c-sys-color-content-success)` | 本组件 CSS<br>`color` |
| `--c-alert-tonal-success-title` | 公开 | `var(--c-sys-color-content-success)` | 本组件 CSS<br>`color` |
| `--c-alert-tonal-warning-bg` | 公开 | `rgb(var(--c-warning-1))` | 本组件 CSS<br>`background-color` |
| `--c-alert-tonal-warning-content` | 公开 | `var(--c-sys-color-content-warning)` | 本组件 CSS<br>`color` |
| `--c-alert-tonal-warning-icon` | 公开 | `var(--c-sys-color-content-warning)` | 本组件 CSS<br>`color` |
| `--c-alert-tonal-warning-title` | 公开 | `var(--c-sys-color-content-warning)` | 本组件 CSS<br>`color` |

</div>

## anchor

声明来源: `src/anchor/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-anchor-border-radius-title-hover` | 公开 | `var(--c-border-radius-sm)` | 本组件 CSS<br>`border-radius` |
| `--c-anchor-color-bg-line` | 公开 | `var(--c-color-fill-3)` | 本组件 CSS<br>`background-color` |
| `--c-anchor-color-bg-line-active` | 公开 | `rgb(var(--c-primary-6))` | 本组件 CSS<br>`background-color` |
| `--c-anchor-color-bg-title-hover` | 公开 | `var(--c-color-fill-2)` | 本组件 CSS<br>`background-color` |
| `--c-anchor-color-title` | 公开 | `var(--c-color-text-2)` | 本组件 CSS<br>`color` |
| `--c-anchor-color-title-active` | 公开 | `var(--c-sys-color-content-brand)` | 本组件 CSS<br>`color` |
| `--c-anchor-color-title-hover` | 公开 | `rgb(var(--c-primary-5))` | 本组件 CSS<br>`color` |
| `--c-anchor-font-size-title` | 公开 | `14px` | 本组件 CSS<br>`font-size` |
| `--c-anchor-font-weight-title-active` | 公开 | `var(--c-font-weight-500)` | 本组件 CSS<br>`font-weight` |
| `--c-anchor-font-weight-title-hover` | 公开 | `var(--c-font-weight-500)` | 本组件 CSS<br>`font-weight` |
| `--c-anchor-line-slider-height` | 公开 | `12px` | 本组件 CSS<br>`height` |
| `--c-anchor-line-width` | 公开 | `2px` | 本组件 CSS<br>`left`, `width` |
| `--c-anchor-sub-item--inset` | 公开 | `-6px` | 本组件 CSS<br>`margin-left` |
| `--c-anchor-title-margin-bottom` | 公开 | `var(--c-spacing-1)` | 本组件 CSS<br>`margin-bottom` |
| `--c-anchor-title-padding-x` | 公开 | `16px` | 本组件 CSS<br>`padding-left` |
| `--c-anchor-title-padding-y` | 公开 | `4px` | 本组件 CSS<br>`padding` |

</div>

## auto-complete

声明来源: `src/auto-complete/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-auto-complete-option-bg-default` | 公开 | `var(--c-select-popup-option-bg)` | 本组件 CSS<br>`background-color` |
| `--c-auto-complete-option-bg-disabled` | 公开 | `var(--c-select-popup-option-bg-disabled)` | 本组件 CSS<br>`background-color` |
| `--c-auto-complete-option-bg-hover` | 公开 | `var(--c-select-popup-option-bg-hover)` | 本组件 CSS<br>`background-color` |
| `--c-auto-complete-option-bg-selected` | 公开 | `var(--c-select-popup-option-bg-selected)` | 本组件 CSS<br>`background-color` |
| `--c-auto-complete-option-font-weight-selected` | 公开 | `var(--c-select-popup-option-font-weight-selected)` | 本组件 CSS<br>`font-weight` |
| `--c-auto-complete-option-height` | 公开 | `var(--c-select-popup-option-height)` | 本组件 CSS<br>`line-height` |
| `--c-auto-complete-option-padding-horizontal` | 公开 | `var(--c-select-popup-option-padding-horizontal)` | 本组件 CSS<br>`padding-inline` |
| `--c-auto-complete-option-text-color-default` | 公开 | `var(--c-select-popup-option-text-color)` | 本组件 CSS<br>`color` |
| `--c-auto-complete-option-text-color-disabled` | 公开 | `var(--c-select-popup-option-text-color-disabled)` | 本组件 CSS<br>`color` |
| `--c-auto-complete-option-text-color-hover` | 公开 | `var(--c-select-popup-option-text-color-hover)` | 本组件 CSS<br>`color` |
| `--c-auto-complete-option-text-color-selected` | 公开 | `var(--c-select-popup-option-text-color-selected)` | 本组件 CSS<br>`color` |
| `--c-auto-complete-popup-bg` | 公开 | `var(--c-select-popup-bg)` | 本组件 CSS<br>`background-color` |
| `--c-auto-complete-popup-border-color` | 公开 | `var(--c-select-popup-border-color)` | 本组件 CSS<br>`border-color` |
| `--c-auto-complete-popup-border-radius` | 公开 | `var(--c-select-popup-border-radius)` | 本组件 CSS<br>`border-radius` |
| `--c-auto-complete-popup-box-shadow` | 公开 | `var(--c-select-popup-box-shadow)` | 本组件 CSS<br>`box-shadow` |
| `--c-auto-complete-popup-font-size` | 公开 | `var(--c-select-popup-font-size)` | 本组件 CSS<br>`font-size` |
| `--c-auto-complete-popup-max-height` | 公开 | `var(--c-select-popup-max-height)` | 本组件 CSS<br>`max-height` |
| `--c-auto-complete-popup-padding-vertical` | 公开 | `var(--c-select-popup-padding-vertical)` | 本组件 CSS<br>`padding-block` |

</div>

## avatar

声明来源: `src/avatar/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-avatar-bg` | 公开 | `var(--c-color-fill-4)` | 本组件 CSS<br>`background-color` |
| `--c-avatar-border-color` | 公开 | `var(--c-sys-color-surface-default)` | 本组件 CSS<br>`border` |
| `--c-avatar-border-width` | 公开 | `2px` | 本组件 CSS<br>`border` |
| `--c-avatar-circle-border-radius` | 公开 | `50%` | 本组件 CSS<br>`border-radius` |
| `--c-avatar-font-size-max-count` | 公开 | `20px` | 本组件 CSS<br>`font-size` |
| `--c-avatar-font-size-text` | 公开 | `20px` | 本组件 CSS<br>`font-size` |
| `--c-avatar-font-weight-text` | 公开 | `500` | 本组件 CSS<br>`font-weight` |
| `--c-avatar-group-item-border` | 公开 | `var(--c-sys-color-surface-default)` | 本组件 CSS<br>`border` |
| `--c-avatar-group-item-border-width` | 公开 | `2px` | 本组件 CSS<br>`border` |
| `--c-avatar-group-offset` | 公开 | `-10px` | 本组件 CSS<br>`margin-block-start`, `margin-inline-start` |
| `--c-avatar-group-popover-item-spacing` | 公开 | `8px` | 本组件 CSS<br>`gap` |
| `--c-avatar-hover-transform` | 公开 | `scale(1.1)` | 本组件 CSS<br>`transform` |
| `--c-avatar-max-count-text-color` | 公开 | `var(--c-sys-color-content-primary)` | 本组件 CSS<br>`color` |
| `--c-avatar-motion-duration` | 公开 | `0.2s` | 本组件 CSS<br>`transition` |
| `--c-avatar-size-default` | 公开 | `40px` | 本组件 CSS<br>`height`, `width` |
| `--c-avatar-size-trigger-button` | 公开 | `20px` | 本组件 CSS<br>`height`, `width` |
| `--c-avatar-size-trigger-icon` | 公开 | `12px` | 本组件 CSS<br>`font-size` |
| `--c-avatar-spacing-trigger-button-bottom` | 公开 | `4px` | 本组件 CSS<br>`bottom` |
| `--c-avatar-spacing-trigger-button-right` | 公开 | `4px` | 本组件 CSS<br>`inset-inline-end` |
| `--c-avatar-square-border-radius` | 公开 | `4px` | 本组件 CSS<br>`border-radius` |
| `--c-avatar-text-color` | 公开 | `var(--c-sys-color-content-primary)` | 本组件 CSS<br>`color` |
| `--c-avatar-text-padding-inline` | 公开 | `4px` | 本组件 CSS<br>`padding-inline` |
| `--c-avatar-trigger-button-bg` | 公开 | `var(--c-color-fill-2)` | 本组件 CSS<br>`background-color` |
| `--c-avatar-trigger-button-bg-hover` | 公开 | `var(--c-color-fill-3)` | 本组件 CSS<br>`background-color` |
| `--c-avatar-trigger-button-border-radius` | 公开 | `50%` | 本组件 CSS<br>`border-radius` |
| `--c-avatar-trigger-icon-button` | 公开 | `var(--c-sys-color-content-primary)` | 本组件 CSS<br>`color` |
| `--c-avatar-trigger-overlay-bg` | 公开 | `color-mix(in srgb, var(--c-color-black) 60%, transparent)` | 本组件 CSS<br>`background-color` |
| `--c-avatar-trigger-overlay-font-size` | 公开 | `16px` | 本组件 CSS<br>`font-size` |
| `--c-avatar-trigger-overlay-icon` | 公开 | `var(--c-sys-color-content-on-dark)` | 本组件 CSS<br>`color` |
| `--c-avatar-z-index-overlay` | 公开 | `0` | 本组件 CSS<br>`z-index` |
| `--c-avatar-z-index-overlay-hover` | 公开 | `2` | 本组件 CSS<br>`z-index` |
| `--c-avatar-z-index-trigger` | 公开 | `1` | 本组件 CSS<br>`z-index` |

</div>

## back-top

声明来源: `src/back-top/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-back-top-background` | 公开 | `var(--c-sys-color-surface-raised)` | 本组件 CSS<br>`background` |
| `--c-back-top-bottom` | 公开 | `40px` | 本组件 CSS<br>`bottom` |
| `--c-back-top-button-border-radius` | 公开 | `50%` | 本组件 CSS<br>`border-radius` |
| `--c-back-top-button-size` | 公开 | `var(--c-sys-control-touch-target)` | 本组件 CSS<br>`height`, `width` |
| `--c-back-top-focus-color` | 公开 | `var(--c-sys-color-content-brand)` | 本组件 CSS<br>`outline` |
| `--c-back-top-focus-offset` | 公开 | `2px` | 本组件 CSS<br>`outline-offset` |
| `--c-back-top-focus-width` | 公开 | `2px` | 本组件 CSS<br>`outline` |
| `--c-back-top-font-size` | 公开 | `var(--c-sys-font-size-md)` | 本组件 CSS<br>`font-size` |
| `--c-back-top-hover-background` | 公开 | `var(--c-sys-color-state-hover)` | 本组件 CSS<br>`background` |
| `--c-back-top-icon-size` | 公开 | `20px` | 本组件 CSS<br>`height`, `width` |
| `--c-back-top-right` | 公开 | `40px` | 本组件 CSS<br>`right` |
| `--c-back-top-text-color` | 公开 | `var(--c-sys-color-content-brand)` | 本组件 CSS<br>`color` |
| `--c-back-top-z-index` | 公开 | `var(--c-z-index-local-sticky)` | 本组件 CSS<br>`z-index` |

</div>

## badge

声明来源: `src/badge/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-badge-bg-color` | 公开 | `rgb(var(--c-danger-7))`<br>`rgb(var(--c-danger-4))` (`:root[cedar-theme="dark"]`) | 本组件 CSS<br>`background-color` |
| `--c-badge-border-color` | 公开 | `var(--c-sys-color-surface-default)` | 本组件 CSS<br>`background-color`, `box-shadow` |
| `--c-badge-description-size-lg-font-size` | 公开 | `var(--c-sys-font-size-lg)` | 本组件 CSS<br>`font-size` |
| `--c-badge-description-size-md-font-size` | 公开 | `var(--c-sys-font-size-md)` | 本组件 CSS<br>`font-size` |
| `--c-badge-description-size-sm-font-size` | 公开 | `var(--c-sys-font-size-xs)` | 本组件 CSS<br>`font-size` |
| `--c-badge-description-size-xl-font-size` | 公开 | `var(--c-sys-font-size-xl)` | 本组件 CSS<br>`font-size` |
| `--c-badge-description-size-xs-font-size` | 公开 | `var(--c-sys-font-size-xs)` | 本组件 CSS<br>`font-size` |
| `--c-badge-description-text-color` | 公开 | `var(--c-sys-color-content-primary)` | 本组件 CSS<br>`color` |
| `--c-badge-font-weight` | 公开 | `var(--c-sys-font-weight-medium)` | 本组件 CSS<br>`font-weight` |
| `--c-badge-offset` | 公开 | `2px` | 本组件 CSS<br>`bottom`, `left`, `right`, `top` |
| `--c-badge-ring-width` | 公开 | `2px` | 本组件 CSS<br>`box-shadow`, `line-height` |
| `--c-badge-size-lg-border-radius` | 公开 | `28px` | 本组件 CSS<br>`border-radius` |
| `--c-badge-size-lg-dot-height` | 公开 | `7px` | 本组件 CSS<br>`height` |
| `--c-badge-size-lg-dot-width` | 公开 | `7px` | 本组件 CSS<br>`width` |
| `--c-badge-size-lg-font-size` | 公开 | `var(--c-sys-font-size-md)` | 本组件 CSS<br>`font-size` |
| `--c-badge-size-lg-height` | 公开 | `28px` | 本组件 CSS<br>`line-height`, `min-width` |
| `--c-badge-size-lg-padding` | 公开 | `0 var(--c-sys-space-4)` | 本组件 CSS<br>`padding` |
| `--c-badge-size-lg-scale` | 公开 | `1` | 本组件 CSS<br>`transform` |
| `--c-badge-size-lg-space` | 公开 | `var(--c-sys-space-3)` | 本组件 CSS<br>`margin-inline` |
| `--c-badge-size-md-border-radius` | 公开 | `24px` | 本组件 CSS<br>`border-radius` |
| `--c-badge-size-md-dot-height` | 公开 | `6px` | 本组件 CSS<br>`height` |
| `--c-badge-size-md-dot-width` | 公开 | `6px` | 本组件 CSS<br>`width` |
| `--c-badge-size-md-font-size` | 公开 | `var(--c-sys-font-size-xs)` | 本组件 CSS<br>`font-size` |
| `--c-badge-size-md-height` | 公开 | `24px` | 本组件 CSS<br>`line-height`, `min-width` |
| `--c-badge-size-md-padding` | 公开 | `0 var(--c-sys-space-4)` | 本组件 CSS<br>`padding` |
| `--c-badge-size-md-scale` | 公开 | `1` | 本组件 CSS<br>`transform` |
| `--c-badge-size-md-space` | 公开 | `var(--c-sys-space-3)` | 本组件 CSS<br>`margin-inline` |
| `--c-badge-size-sm-border-radius` | 公开 | `20px` | 本组件 CSS<br>`border-radius` |
| `--c-badge-size-sm-dot-height` | 公开 | `5px` | 本组件 CSS<br>`height` |
| `--c-badge-size-sm-dot-width` | 公开 | `5px` | 本组件 CSS<br>`width` |
| `--c-badge-size-sm-font-size` | 公开 | `var(--c-sys-font-size-xs)` | 本组件 CSS<br>`font-size` |
| `--c-badge-size-sm-height` | 公开 | `20px` | 本组件 CSS<br>`line-height`, `min-width` |
| `--c-badge-size-sm-padding` | 公开 | `0 var(--c-sys-space-3)` | 本组件 CSS<br>`padding` |
| `--c-badge-size-sm-scale` | 公开 | `0.8333` | 本组件 CSS<br>`transform` |
| `--c-badge-size-sm-space` | 公开 | `var(--c-sys-space-1)` | 本组件 CSS<br>`margin-inline` |
| `--c-badge-size-xl-border-radius` | 公开 | `32px` | 本组件 CSS<br>`border-radius` |
| `--c-badge-size-xl-dot-height` | 公开 | `8px` | 本组件 CSS<br>`height` |
| `--c-badge-size-xl-dot-width` | 公开 | `8px` | 本组件 CSS<br>`width` |
| `--c-badge-size-xl-font-size` | 公开 | `var(--c-sys-font-size-lg)` | 本组件 CSS<br>`font-size` |
| `--c-badge-size-xl-height` | 公开 | `32px` | 本组件 CSS<br>`line-height`, `min-width` |
| `--c-badge-size-xl-padding` | 公开 | `0 10px` | 本组件 CSS<br>`padding` |
| `--c-badge-size-xl-scale` | 公开 | `1` | 本组件 CSS<br>`transform` |
| `--c-badge-size-xl-space` | 公开 | `var(--c-sys-space-4)` | 本组件 CSS<br>`margin-inline` |
| `--c-badge-size-xs-border-radius` | 公开 | `20px` | 本组件 CSS<br>`border-radius` |
| `--c-badge-size-xs-dot-height` | 公开 | `4px` | 本组件 CSS<br>`height` |
| `--c-badge-size-xs-dot-width` | 公开 | `4px` | 本组件 CSS<br>`width` |
| `--c-badge-size-xs-font-size` | 公开 | `var(--c-sys-font-size-xs)` | 本组件 CSS<br>`font-size` |
| `--c-badge-size-xs-height` | 公开 | `20px` | 本组件 CSS<br>`line-height`, `min-width` |
| `--c-badge-size-xs-padding` | 公开 | `0 var(--c-sys-space-3)` | 本组件 CSS<br>`padding` |
| `--c-badge-size-xs-scale` | 公开 | `0.6667` | 本组件 CSS<br>`transform` |
| `--c-badge-size-xs-space` | 公开 | `0px` | 本组件 CSS<br>`margin-inline` |
| `--c-badge-status-danger-bg-color` | 公开 | `rgb(var(--c-danger-7))`<br>`rgb(var(--c-danger-4))` (`:root[cedar-theme="dark"]`) | 本组件 CSS<br>`background-color` |
| `--c-badge-status-danger-text-color` | 公开 | `var(--c-sys-color-content-on-dark)` | 本组件 CSS<br>`color` |
| `--c-badge-status-default-bg-color` | 公开 | `#e0e0e0` | 本组件 CSS<br>`background-color` |
| `--c-badge-status-default-text-color` | 公开 | `var(--c-sys-color-content-on-bright)` | 本组件 CSS<br>`color` |
| `--c-badge-status-info-bg-color` | 公开 | `var(--c-sys-color-status-info)` | 本组件 CSS<br>`background-color` |
| `--c-badge-status-info-text-color` | 公开 | `var(--c-sys-color-content-on-dark)` | 本组件 CSS<br>`color` |
| `--c-badge-status-primary-bg-color` | 公开 | `var(--c-sys-color-action-primary)` | 本组件 CSS<br>`background-color` |
| `--c-badge-status-primary-text-color` | 公开 | `var(--c-sys-color-content-on-dark)` | 本组件 CSS<br>`color` |
| `--c-badge-status-secondary-bg-color` | 公开 | `rgb(var(--c-gray-6))` | 本组件 CSS<br>`background-color` |
| `--c-badge-status-secondary-text-color` | 公开 | `var(--c-sys-color-content-on-dark)` | 本组件 CSS<br>`color` |
| `--c-badge-status-success-bg-color` | 公开 | `var(--c-sys-color-status-success)` | 本组件 CSS<br>`background-color` |
| `--c-badge-status-success-text-color` | 公开 | `var(--c-sys-color-content-on-dark)` | 本组件 CSS<br>`color` |
| `--c-badge-status-tertiary-bg-color` | 公开 | `rgb(var(--c-gray-7))` | 本组件 CSS<br>`background-color` |
| `--c-badge-status-tertiary-text-color` | 公开 | `var(--c-sys-color-content-on-dark)`<br>`var(--c-sys-color-content-on-bright)` (`:root[cedar-theme="dark"]`) | 本组件 CSS<br>`color` |
| `--c-badge-status-warning-bg-color` | 公开 | `var(--c-sys-color-status-warning)` | 本组件 CSS<br>`background-color` |
| `--c-badge-status-warning-text-color` | 公开 | `var(--c-sys-color-content-on-dark)` | 本组件 CSS<br>`color` |
| `--c-badge-text-color` | 公开 | `var(--c-sys-color-content-on-dark)` | 本组件 CSS<br>`color` |
| `--c-badge-variant-outline-bg-color` | 公开 | `transparent` | 本组件 CSS<br>`background-color` |
| `--c-badge-variant-outline-status-danger-text-color` | 公开 | `var(--c-sys-color-content-danger)` | 本组件 CSS<br>`border`, `color` |
| `--c-badge-variant-outline-status-default-text-color` | 公开 | `var(--c-sys-color-content-primary)` | 本组件 CSS<br>`border`, `color` |
| `--c-badge-variant-outline-status-info-text-color` | 公开 | `var(--c-sys-color-content-info)` | 本组件 CSS<br>`border`, `color` |
| `--c-badge-variant-outline-status-primary-text-color` | 公开 | `var(--c-sys-color-content-brand)` | 本组件 CSS<br>`border`, `color` |
| `--c-badge-variant-outline-status-secondary-text-color` | 公开 | `var(--c-sys-color-content-secondary)` | 本组件 CSS<br>`border`, `color` |
| `--c-badge-variant-outline-status-success-text-color` | 公开 | `var(--c-sys-color-content-success)` | 本组件 CSS<br>`border`, `color` |
| `--c-badge-variant-outline-status-tertiary-text-color` | 公开 | `var(--c-sys-color-content-secondary)` | 本组件 CSS<br>`border`, `color` |
| `--c-badge-variant-outline-status-warning-text-color` | 公开 | `var(--c-sys-color-content-warning)` | 本组件 CSS<br>`border`, `color` |
| `--c-badge-variant-outline-text-color` | 公开 | `var(--c-sys-color-content-danger)` | 本组件 CSS<br>`border`, `color` |

</div>

## breadcrumb

声明来源: `src/breadcrumb/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-breadcrumb-bg` | 公开 | `transparent` | 本组件 CSS<br>`background-color` |
| `--c-breadcrumb-bg-hover` | 公开 | `var(--c-color-fill-2)` | 本组件 CSS<br>`background-color` |
| `--c-breadcrumb-dropdown-icon` | 公开 | `var(--c-color-text-2)` | 本组件 CSS<br>`color` |
| `--c-breadcrumb-font-weight-active` | 公开 | `var(--c-font-weight-400)` | 本组件 CSS<br>`font-weight` |
| `--c-breadcrumb-icon-color` | 公开 | `var(--c-color-text-3)` | 本组件 CSS<br>`color` |
| `--c-breadcrumb-link-text-color` | 公开 | `rgb(var(--c-primary-8))` | 本组件 CSS<br>`color` |
| `--c-breadcrumb-link-text-color-hover` | 公开 | `rgb(var(--c-primary-9))` | 本组件 CSS<br>`color` |
| `--c-breadcrumb-margin-dropdown-icon-left` | 公开 | `var(--c-spacing-2)` | 本组件 CSS<br>`margin-left` |
| `--c-breadcrumb-margin-separator-horizontal` | 公开 | `var(--c-spacing-2)` | 本组件 CSS<br>`margin` |
| `--c-breadcrumb-padding-text-horizontal` | 公开 | `var(--c-spacing-2)` | 本组件 CSS<br>`margin`, `padding` |
| `--c-breadcrumb-separator-color` | 公开 | `var(--c-color-text-4)` | 本组件 CSS<br>`color` |
| `--c-breadcrumb-separator-font-size` | 公开 | `inherit` | 本组件 CSS<br>`font-size` |
| `--c-breadcrumb-separator-margin` | 公开 | `0 var(--c-breadcrumb-margin-separator-horizontal)` | 本组件 CSS<br>`margin` |
| `--c-breadcrumb-size-dropdown-icon` | 公开 | `var(--c-size-3)` | 本组件 CSS<br>`font-size` |
| `--c-breadcrumb-size-font-size` | 公开 | `var(--c-font-size-body-3)` | 本组件 CSS<br>`font-size` |
| `--c-breadcrumb-size-text-height` | 公开 | `var(--c-size-6)` | 本组件 CSS<br>`line-height` |
| `--c-breadcrumb-text-border-radius-hover` | 公开 | `var(--c-border-radius-sm)` | 本组件 CSS<br>`border-radius` |
| `--c-breadcrumb-text-color` | 公开 | `var(--c-color-text-2)` | 本组件 CSS<br>`color` |
| `--c-breadcrumb-text-color-active` | 公开 | `var(--c-color-text-1)` | 本组件 CSS<br>`color` |
| `--c-breadcrumb-touch-target-size` | 公开 | `44px` | 本组件 CSS<br>`min-height`, `min-width` |

</div>

## button

声明来源: `src/button/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-button-border-radius` | 公开 | `var(--c-sys-radius-md)` | 本组件 CSS<br>`border-radius` |
| `--c-button-content-gap` | 公开 | `var(--c-sys-space-3)` | 本组件 CSS<br>`gap` |
| `--c-button-danger-color` | 公开 | `var(--c-sys-color-status-danger)` | 本组件 CSS<br>`background-color` |
| `--c-button-danger-disabled-color` | 公开 | `rgb(var(--c-danger-3))`<br>`rgba(var(--c-danger-6), 0.5)` (`:root[cedar-theme="dark"]`) | 本组件 CSS<br>`background-color`, `color` |
| `--c-button-danger-foreground-color` | 公开 | `var(--c-sys-color-content-danger)` | 本组件 CSS<br>`color` |
| `--c-button-danger-tonal-color` | 公开 | `rgb(var(--c-danger-1))` | 本组件 CSS<br>`background-color` |
| `--c-button-default-color` | 公开 | `var(--c-sys-color-surface-default)` | 本组件 CSS<br>`background-color` |
| `--c-button-default-foreground-color` | 公开 | `var(--c-sys-color-content-primary)` | 本组件 CSS<br>`background-color`, `color` |
| `--c-button-default-tonal-color` | 公开 | `var(--c-sys-color-surface-muted)` | 本组件 CSS<br>`background-color` |
| `--c-button-disabled-color` | 公开 | `var(--c-color-fill-2)` | 本组件 CSS<br>`background-color` |
| `--c-button-disabled-solid-text-color` | 公开 | `var(--c-sys-color-content-on-dark)`<br>`rgba(255, 255, 255, 0.3)` (`:root[cedar-theme="dark"]`) | 本组件 CSS<br>`color` |
| `--c-button-disabled-text-color` | 公开 | `var(--c-sys-color-content-disabled)` | 本组件 CSS<br>`color` |
| `--c-button-focus-color` | 公开 | `var(--c-sys-color-content-brand)` | 本组件 CSS<br>`outline` |
| `--c-button-info-color` | 公开 | `var(--c-sys-color-status-info)` | 本组件 CSS<br>`background-color` |
| `--c-button-info-disabled-color` | 公开 | `rgb(var(--c-blue-3))`<br>`rgba(var(--c-blue-6), 0.5)` (`:root[cedar-theme="dark"]`) | 本组件 CSS<br>`background-color`, `color` |
| `--c-button-info-foreground-color` | 公开 | `var(--c-sys-color-content-info)` | 本组件 CSS<br>`color` |
| `--c-button-info-tonal-color` | 公开 | `rgb(var(--c-blue-1))` | 本组件 CSS<br>`background-color` |
| `--c-button-lg-height` | 公开 | `36px` | 本组件 CSS<br>`height`, `min-width`, `width` |
| `--c-button-lg-padding` | 公开 | `0 var(--c-sys-space-7)` | 本组件 CSS<br>`padding` |
| `--c-button-loading-duration` | 公开 | `1s` | 本组件 CSS<br>`animation` |
| `--c-button-loading-line-height` | 公开 | `3px` | 本组件 CSS<br>`height` |
| `--c-button-md-height` | 公开 | `32px` | 本组件 CSS<br>`height`, `min-width`, `width` |
| `--c-button-md-padding` | 公开 | `0 var(--c-sys-space-6)` | 本组件 CSS<br>`padding` |
| `--c-button-plain-state-opacity-active` | 公开 | `1` | 本组件 CSS<br>`opacity` |
| `--c-button-plain-state-opacity-hover` | 公开 | `0.5` | 本组件 CSS<br>`opacity` |
| `--c-button-primary-color` | 公开 | `var(--c-sys-color-action-primary)` | 本组件 CSS<br>`background-color` |
| `--c-button-primary-disabled-color` | 公开 | `rgb(var(--c-primary-3))`<br>`rgba(var(--c-primary-6), 0.5)` (`:root[cedar-theme="dark"]`) | 本组件 CSS<br>`background-color`, `color` |
| `--c-button-primary-foreground-color` | 公开 | `var(--c-sys-color-content-brand)` | 本组件 CSS<br>`color` |
| `--c-button-primary-state-layer-color` | 公开 | `var(--c-button-solid-state-layer-color)` | 本组件 CSS<br>`background-color` |
| `--c-button-primary-tonal-color` | 公开 | `rgb(var(--c-primary-1))` | 本组件 CSS<br>`background-color` |
| `--c-button-secondary-color` | 公开 | `rgb(var(--c-gray-6))` | 本组件 CSS<br>`background-color` |
| `--c-button-secondary-foreground-color` | 公开 | `var(--c-sys-color-content-secondary)` | 本组件 CSS<br>`color` |
| `--c-button-secondary-tonal-color` | 公开 | `rgb(var(--c-gray-2))` | 本组件 CSS<br>`background-color` |
| `--c-button-sm-height` | 公开 | `28px` | 本组件 CSS<br>`height`, `min-width`, `width` |
| `--c-button-sm-padding` | 公开 | `0 var(--c-sys-space-5)` | 本组件 CSS<br>`padding` |
| `--c-button-solid-state-layer-color` | 公开 | `var(--c-sys-color-content-on-dark)` | 本组件 CSS<br>`background-color` |
| `--c-button-solid-text-color` | 公开 | `var(--c-sys-color-content-on-dark)` | 本组件 CSS<br>`color` |
| `--c-button-stacked-gap` | 公开 | `var(--c-sys-space-2)` | 本组件 CSS<br>`gap`, `min-height`, `min-width` |
| `--c-button-state-layer-color` | 公开 | `var(--c-sys-color-surface-page)` | 本组件 CSS<br>`background-color` |
| `--c-button-state-opacity-active` | 公开 | `0.12` | 本组件 CSS<br>`opacity` |
| `--c-button-state-opacity-hover` | 公开 | `0.08` | 本组件 CSS<br>`opacity` |
| `--c-button-success-color` | 公开 | `var(--c-sys-color-status-success)` | 本组件 CSS<br>`background-color` |
| `--c-button-success-disabled-color` | 公开 | `rgb(var(--c-success-3))`<br>`rgba(var(--c-success-6), 0.5)` (`:root[cedar-theme="dark"]`) | 本组件 CSS<br>`background-color`, `color` |
| `--c-button-success-foreground-color` | 公开 | `var(--c-sys-color-content-success)` | 本组件 CSS<br>`color` |
| `--c-button-success-tonal-color` | 公开 | `rgb(var(--c-success-1))` | 本组件 CSS<br>`background-color` |
| `--c-button-tertiary-color` | 公开 | `rgb(var(--c-gray-7))` | 本组件 CSS<br>`background-color` |
| `--c-button-tertiary-foreground-color` | 公开 | `var(--c-sys-color-content-secondary)` | 本组件 CSS<br>`color` |
| `--c-button-tertiary-state-layer-color` | 公开 | `var(--c-sys-color-content-on-bright)`<br>`var(--c-sys-color-content-on-dark)` (`:root[cedar-theme="dark"]`) | 本组件 CSS<br>`background-color` |
| `--c-button-tertiary-text-color` | 公开 | `var(--c-sys-color-content-on-dark)`<br>`var(--c-sys-color-content-on-bright)` (`:root[cedar-theme="dark"]`) | 本组件 CSS<br>`color` |
| `--c-button-tertiary-tonal-color` | 公开 | `rgb(var(--c-gray-1))` | 本组件 CSS<br>`background-color` |
| `--c-button-warning-color` | 公开 | `var(--c-sys-color-status-warning)` | 本组件 CSS<br>`background-color` |
| `--c-button-warning-disabled-color` | 公开 | `rgb(var(--c-warning-3))`<br>`rgba(var(--c-warning-6), 0.5)` (`:root[cedar-theme="dark"]`) | 本组件 CSS<br>`background-color`, `color` |
| `--c-button-warning-foreground-color` | 公开 | `var(--c-sys-color-content-warning)` | 本组件 CSS<br>`color` |
| `--c-button-warning-tonal-color` | 公开 | `rgb(var(--c-warning-1))` | 本组件 CSS<br>`background-color` |
| `--c-button-xl-height` | 公开 | `44px` | 本组件 CSS<br>`height`, `min-width`, `width` |
| `--c-button-xl-padding` | 公开 | `0 var(--c-sys-space-8)` | 本组件 CSS<br>`padding` |
| `--c-button-xs-height` | 公开 | `24px` | 本组件 CSS<br>`height`, `min-width`, `width` |
| `--c-button-xs-padding` | 公开 | `0 var(--c-sys-space-4)` | 本组件 CSS<br>`padding` |

</div>

## calendar

声明来源: `src/calendar/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-calendar-bg-cell-disabled` | 公开 | `var(--c-color-fill-1)` | 本组件 CSS<br>`background-color` |
| `--c-calendar-bg-cell-hover-in-range` | 公开 | `var(--c-color-primary-light-1)` | 本组件 CSS<br>`background-color` |
| `--c-calendar-bg-cell-hover-range-boundary` | 公开 | `var(--c-color-primary-light-2)` | 本组件 CSS<br>`background-color` |
| `--c-calendar-bg-cell-in-range` | 公开 | `var(--c-color-primary-light-1)` | 本组件 CSS<br>`background-color` |
| `--c-calendar-bg-cell-range-boundary` | 公开 | `rgb(var(--c-primary-6))` | 本组件 CSS<br>`background-color` |
| `--c-calendar-bg-circle-selected` | 公开 | `rgb(var(--c-primary-6))` | 本组件 CSS<br>`background-color`, `border` |
| `--c-calendar-bg-switch-icon` | 公开 | `var(--c-color-bg-5)` | 本组件 CSS<br>`background-color` |
| `--c-calendar-bg-switch-icon-hover` | 公开 | `var(--c-color-fill-3)` | 本组件 CSS<br>`background-color` |
| `--c-calendar-border-color` | 公开 | `var(--c-color-neutral-3)` | 本组件 CSS<br>`border`, `border-bottom`, `border-left`, `border-right`, `border-top` |
| `--c-calendar-box-shadow` | 公开 | `var(--c-color-primary-light-3)` | 本组件 CSS<br>`box-shadow` |
| `--c-calendar-cell-text-in-view` | 公开 | `var(--c-color-text-1)` | 本组件 CSS<br>`color` |
| `--c-calendar-cell-text-not-in-view` | 公开 | `var(--c-color-text-4)` | 本组件 CSS<br>`color` |
| `--c-calendar-cell-text-selected` | 公开 | `var(--c-color-white)` | 本组件 CSS<br>`color` |
| `--c-calendar-cell-today-border-color` | 公开 | `var(--c-sys-color-content-brand)` | 本组件 CSS<br>`border` |
| `--c-calendar-date-circle-border-radius` | 公开 | `var(--c-border-radius-circle)` | 本组件 CSS<br>`border-radius` |
| `--c-calendar-date-circle-size` | 公开 | `var(--c-size-7)` | 本组件 CSS<br>`height`, `width` |
| `--c-calendar-date-content-height` | 公开 | `70px` | 本组件 CSS<br>`height` |
| `--c-calendar-date-padding` | 公开 | `var(--c-spacing-5)` | 本组件 CSS<br>`padding` |
| `--c-calendar-date-value-font-size` | 公开 | `var(--c-font-size-title-1)` | 本组件 CSS<br>`font-size` |
| `--c-calendar-date-value-font-weight` | 公开 | `var(--c-font-weight-500)` | 本组件 CSS<br>`font-weight` |
| `--c-calendar-header-height` | 公开 | `var(--c-size-7)` | 本组件 CSS<br>`height`, `line-height` |
| `--c-calendar-header-icon-border-radius` | 公开 | `var(--c-border-radius-circle)` | 本组件 CSS<br>`border-radius` |
| `--c-calendar-header-icon-box-shadow` | 公开 | `0 0 0 var(--c-spacing-1) var(--c-calendar-box-shadow)` | 本组件 CSS<br>`box-shadow` |
| `--c-calendar-header-icon-font-size` | 公开 | `var(--c-font-size-body-1)` | 本组件 CSS<br>`font-size` |
| `--c-calendar-header-icon-margin` | 公开 | `var(--c-spacing-6)` | 本组件 CSS<br>`margin`, `margin-left`, `margin-right` |
| `--c-calendar-header-icon-size` | 公开 | `var(--c-size-7)` | 本组件 CSS<br>`height`, `line-height`, `width` |
| `--c-calendar-header-padding-horizontal` | 公开 | `var(--c-spacing-9)` | 本组件 CSS<br>`padding` |
| `--c-calendar-header-padding-vertical` | 公开 | `var(--c-spacing-9)` | 本组件 CSS<br>`padding` |
| `--c-calendar-header-value-font-size` | 公开 | `var(--c-font-size-title-2)` | 本组件 CSS<br>`font-size` |
| `--c-calendar-header-value-font-weight` | 公开 | `var(--c-font-weight-500)` | 本组件 CSS<br>`font-weight` |
| `--c-calendar-header-value-month-margin` | 公开 | `var(--c-spacing-10)` | 本组件 CSS<br>`margin-left`, `margin-right` |
| `--c-calendar-header-value-month-width` | 公开 | `var(--c-size-19)` | 本组件 CSS<br>`width` |
| `--c-calendar-header-value-year-margin` | 公开 | `var(--c-spacing-4)` | 本组件 CSS<br>`margin-left`, `margin-right` |
| `--c-calendar-header-value-year-width` | 公开 | `var(--c-size-25)` | 本组件 CSS<br>`width` |
| `--c-calendar-mode-year-body-padding` | 公开 | `var(--c-spacing-6)` | 本组件 CSS<br>`padding` |
| `--c-calendar-mode-year-min-width` | 公开 | `820px` | 本组件 CSS<br>`min-width` |
| `--c-calendar-month-cell-date-circle-size` | 公开 | `22px` | 本组件 CSS<br>`height`, `width` |
| `--c-calendar-month-cell-date-padding` | 公开 | `var(--c-spacing-1)` | 本组件 CSS<br>`padding` |
| `--c-calendar-month-cell-date-value-font-size` | 公开 | `var(--c-font-size-body-3)` | 本组件 CSS<br>`font-size` |
| `--c-calendar-month-cell-font-size` | 公开 | `var(--c-font-size-body-1)` | 本组件 CSS<br>`font-size` |
| `--c-calendar-month-cell-week-list-item-padding` | 公开 | `var(--c-spacing-3)` | 本组件 CSS<br>`padding` |
| `--c-calendar-month-row-height` | 公开 | `var(--c-size-25)` | 本组件 CSS<br>`height` |
| `--c-calendar-month-title-font-size` | 公开 | `var(--c-font-size-title-1)` | 本组件 CSS<br>`font-size` |
| `--c-calendar-month-title-font-weight` | 公开 | `var(--c-font-weight-500)` | 本组件 CSS<br>`font-weight` |
| `--c-calendar-month-title-padding-horizontal` | 公开 | `var(--c-spacing-3)` | 本组件 CSS<br>`padding` |
| `--c-calendar-month-title-padding-vertical` | 公开 | `var(--c-spacing-5)` | 本组件 CSS<br>`padding` |
| `--c-calendar-month-with-days-row-height` | 公开 | `26px` | 本组件 CSS<br>`height` |
| `--c-calendar-panel-bg-cell-hover` | 公开 | `var(--c-color-primary-light-1)` | 本组件 CSS<br>`background-color` |
| `--c-calendar-panel-bg-cell-selected` | 公开 | `rgb(var(--c-primary-6))` | 本组件 CSS<br>`background-color` |
| `--c-calendar-panel-body-padding-horizontal` | 公开 | `var(--c-spacing-7)` | 本组件 CSS<br>`padding` |
| `--c-calendar-panel-body-padding-vertical` | 公开 | `14px` | 本组件 CSS<br>`padding` |
| `--c-calendar-panel-cell-boundary-border-radius` | 公开 | `(   (var(~'--c-calendar-panel-date-cell-circle-height') + var(~'--c-calendar-panel-date-cell-padding-vertical') * 2) / 2 )` | 本组件 CSS<br>`border-radius` |
| `--c-calendar-panel-cell-padding-vertical` | 公开 | `var(--c-spacing-1)` | 本组件 CSS<br>`padding` |
| `--c-calendar-panel-cell-selected-border-radius` | 公开 | `var(--c-border-radius-circle)` | 本组件 CSS<br>`border-radius` |
| `--c-calendar-panel-color-current-time-dot` | 公开 | `rgb(var(--c-primary-6))` | 本组件 CSS<br>`background-color` |
| `--c-calendar-panel-date-cell-circle-height` | 公开 | `var(--c-size-6)` | 本组件 CSS<br>`height`, `line-height`, `min-width` |
| `--c-calendar-panel-date-cell-padding-vertical` | 公开 | `var(--c-spacing-2)` | 本组件 CSS<br>`padding` |
| `--c-calendar-panel-date-value-font-size` | 公开 | `var(--c-font-size-body-3)` | 本组件 CSS<br>`font-size` |
| `--c-calendar-panel-footer-height` | 公开 | `38px` | 本组件 CSS<br>`height`, `line-height` |
| `--c-calendar-panel-header-icon-margin` | 公开 | `var(--c-spacing-1)` | 本组件 CSS<br>`margin-left`, `margin-right` |
| `--c-calendar-panel-header-icon-size` | 公开 | `var(--c-size-6)` | 本组件 CSS<br>`height`, `line-height`, `width` |
| `--c-calendar-panel-header-padding-horizontal` | 公开 | `var(--c-spacing-7)` | 本组件 CSS<br>`padding` |
| `--c-calendar-panel-header-padding-vertical` | 公开 | `var(--c-spacing-4)` | 本组件 CSS<br>`padding` |
| `--c-calendar-panel-header-value-font-size` | 公开 | `var(--c-font-size-body-3)` | 本组件 CSS<br>`font-size` |
| `--c-calendar-panel-header-value-line-height` | 公开 | `var(--c-size-6)` | 本组件 CSS<br>`line-height` |
| `--c-calendar-panel-text-color-cell-hover` | 公开 | `var(--c-sys-color-content-brand)` | 本组件 CSS<br>`color` |
| `--c-calendar-panel-text-color-cell-selected` | 公开 | `var(--c-color-white)` | 本组件 CSS<br>`color` |
| `--c-calendar-panel-today-dot-offset` | 公开 | `var(--c-spacing-1)` | 本组件 CSS<br>`margin-left` |
| `--c-calendar-panel-today-dot-size` | 公开 | `var(--c-spacing-2)` | 本组件 CSS<br>`height`, `width` |
| `--c-calendar-panel-week-list-item-font-weight` | 公开 | `var(--c-font-weight-400)` | 本组件 CSS<br>`font-weight` |
| `--c-calendar-panel-week-list-item-height` | 公开 | `var(--c-size-8)` | 本组件 CSS<br>`height`, `line-height` |
| `--c-calendar-panel-year-cell-circle-height` | 公开 | `var(--c-size-6)` | 本组件 CSS<br>`border-radius` |
| `--c-calendar-panel-year-cell-padding-vertical` | 公开 | `var(--c-spacing-2)` | 本组件 CSS<br>`padding` |
| `--c-calendar-panel-year-date-value-border-radius` | 公开 | `var(--c-spacing-6)` | 本组件 CSS<br>`border-radius` |
| `--c-calendar-panel-year-mode-cell-padding-vertical` | 公开 | `var(--c-spacing-2)` | 本组件 CSS<br>`padding` |
| `--c-calendar-switch-icon` | 公开 | `var(--c-color-text-2)` | 本组件 CSS<br>`color` |
| `--c-calendar-text-color-cell-hover-range-boundary` | 公开 | `var(--c-color-text-1)` | 本组件 CSS<br>`color` |
| `--c-calendar-text-color-cell-range-boundary` | 公开 | `var(--c-color-white)` | 本组件 CSS<br>`color` |
| `--c-calendar-text-title-color` | 公开 | `var(--c-color-text-1)` | 本组件 CSS<br>`color` |
| `--c-calendar-week-list-item-padding-horizontal` | 公开 | `var(--c-spacing-7)` | 本组件 CSS<br>`padding` |
| `--c-calendar-week-list-item-padding-vertical` | 公开 | `var(--c-spacing-8)` | 本组件 CSS<br>`padding` |
| `--c-calendar-week-list-text-color` | 公开 | `#7d7d7f` | 本组件 CSS<br>`color` |
| `--c-calendar-year-cell-padding-horizontal` | 公开 | `var(--c-spacing-4)` | 本组件 CSS<br>`padding` |
| `--c-calendar-year-cell-padding-vertical` | 公开 | `var(--c-spacing-8)` | 本组件 CSS<br>`padding` |

</div>

## card

声明来源: `src/card/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-card-animation-duration` | 公开 | `var(--c-sys-motion-duration-slow)` | 本组件 CSS<br>`transition` |
| `--c-card-animation-easing` | 公开 | `var(--c-sys-motion-easing-standard)` | 本组件 CSS<br>`transition-timing-function` |
| `--c-card-background` | 公开 | `var(--c-sys-color-surface-default)` | 本组件 CSS<br>`background` |
| `--c-card-border-radius` | 公开 | `4px` | 本组件 CSS<br>`border-radius` |
| `--c-card-close-button-background` | 公开 | `#212121` | 本组件 CSS<br>`background-color` |
| `--c-card-close-button-border-radius` | 公开 | `50%` | 本组件 CSS<br>`border-radius` |
| `--c-card-close-button-icon-size` | 公开 | `24px` | 本组件 CSS<br>`font-size` |
| `--c-card-close-button-size` | 公开 | `56px` | 本组件 CSS<br>`height`, `width` |
| `--c-card-close-button-text-color` | 公开 | `var(--c-sys-color-content-on-dark)` | 本组件 CSS<br>`color` |
| `--c-card-content-color` | 公开 | `var(--c-sys-color-content-tertiary)` | 本组件 CSS<br>`color` |
| `--c-card-content-font-size` | 公开 | `14px` | 本组件 CSS<br>`font-size` |
| `--c-card-content-margin` | 公开 | `16px 0 0 0` | 本组件 CSS<br>`margin` |
| `--c-card-content-padding` | 公开 | `0 16px` | 本组件 CSS<br>`padding` |
| `--c-card-content-row-margin` | 公开 | `16px 0 0 0` | 本组件 CSS<br>`margin` |
| `--c-card-description-color` | 公开 | `var(--c-sys-color-content-secondary)` | 本组件 CSS<br>`color` |
| `--c-card-description-font-size` | 公开 | `14px` | 本组件 CSS<br>`font-size` |
| `--c-card-description-margin` | 公开 | `20px 0 0 0` | 本组件 CSS<br>`margin` |
| `--c-card-description-padding` | 公开 | `0 13px` | 本组件 CSS<br>`padding` |
| `--c-card-filled-background` | 公开 | `var(--c-sys-color-surface-muted)` | 本组件 CSS<br>`background-color` |
| `--c-card-floating-buttons-bottom` | 公开 | `16px` | 本组件 CSS<br>`bottom` |
| `--c-card-floating-buttons-color` | 公开 | `var(--c-sys-color-content-primary)` | 本组件 CSS<br>`color` |
| `--c-card-floating-buttons-right` | 公开 | `16px` | 本组件 CSS<br>`right` |
| `--c-card-footer-bottom` | 公开 | `9px` | 本组件 CSS<br>`bottom` |
| `--c-card-footer-margin` | 公开 | `30px 0 0 0` | 本组件 CSS<br>`margin` |
| `--c-card-footer-padding` | 公开 | `0 12px` | 本组件 CSS<br>`padding` |
| `--c-card-footer-right` | 公开 | `13px` | 本组件 CSS<br>`right` |
| `--c-card-hover-shadow` | 公开 | `0 4px 12px rgba(0, 0, 0, 0.12)` | 本组件 CSS<br>`box-shadow` |
| `--c-card-image-height` | 公开 | `200px` | 本组件 CSS<br>`height` |
| `--c-card-image-width` | 公开 | `100%` | 本组件 CSS<br>`width` |
| `--c-card-line-height` | 公开 | `22px` | 本组件 CSS<br>`line-height` |
| `--c-card-outline-color` | 公开 | `var(--c-sys-color-border-default)` | 本组件 CSS<br>`border` |
| `--c-card-padding` | 公开 | `0 0 15px 0` | 本组件 CSS<br>`padding` |
| `--c-card-row-height` | 公开 | `140px` | 本组件 CSS<br>`min-height` |
| `--c-card-row-image-width` | 公开 | `140px` | 本组件 CSS<br>`width` |
| `--c-card-row-line-height` | 公开 | `1.5` | 本组件 CSS<br>`line-height` |
| `--c-card-size-sm-section-margin` | 公开 | `8px 0 0` | 本组件 CSS<br>`margin` |
| `--c-card-size-sm-section-padding` | 公开 | `0 12px` | 本组件 CSS<br>`padding` |
| `--c-card-size-sm-title-font-size` | 公开 | `16px` | 本组件 CSS<br>`font-size` |
| `--c-card-subtitle-color` | 公开 | `var(--c-sys-color-content-secondary)` | 本组件 CSS<br>`color` |
| `--c-card-subtitle-font-size` | 公开 | `14px` | 本组件 CSS<br>`font-size` |
| `--c-card-subtitle-margin` | 公开 | `10px 0 0 0` | 本组件 CSS<br>`margin` |
| `--c-card-subtitle-padding` | 公开 | `0 12px` | 本组件 CSS<br>`padding` |
| `--c-card-subtitle-row-margin` | 公开 | `-8px 0 0 0` | 本组件 CSS<br>`margin` |
| `--c-card-title-color` | 公开 | `var(--c-sys-color-content-primary)` | 本组件 CSS<br>`color` |
| `--c-card-title-font-size` | 公开 | `20px` | 本组件 CSS<br>`font-size` |
| `--c-card-title-margin` | 公开 | `15px 0 0 0` | 本组件 CSS<br>`margin` |
| `--c-card-title-padding` | 公开 | `0 12px` | 本组件 CSS<br>`padding` |
| `--c-card-title-row-margin` | 公开 | `12px 0` | 本组件 CSS<br>`margin` |

</div>

## carousel

声明来源: `src/carousel/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-carousel-arrow-background` | 公开 | `rgb(0 0 0 / 35%)` | 本组件 CSS<br>`background` |
| `--c-carousel-arrow-background-hover` | 公开 | `rgb(0 0 0 / 55%)` | 本组件 CSS<br>`background` |
| `--c-carousel-arrow-color` | 公开 | `var(--c-sys-color-content-on-dark)` | 本组件 CSS<br>`color` |
| `--c-carousel-arrow-disabled-opacity` | 公开 | `0.4` | 本组件 CSS<br>`opacity` |
| `--c-carousel-arrow-font-size` | 公开 | `var(--c-sys-font-size-xl)` | 本组件 CSS<br>`font-size` |
| `--c-carousel-arrow-margin` | 公开 | `var(--c-sys-space-4)` | 本组件 CSS<br>`bottom`, `left`, `right`, `top` |
| `--c-carousel-arrow-size` | 公开 | `var(--c-sys-control-height-md)` | 本组件 CSS<br>`height`, `width` |
| `--c-carousel-card-duration` | 公开 | `var(--c-sys-motion-duration-standard)` | 本组件 CSS<br>`transition` |
| `--c-carousel-card-opacity` | 公开 | `0.6` | 本组件 CSS<br>`opacity` |
| `--c-carousel-card-scale` | 公开 | `0.85` | 本组件 CSS<br>`transform` |
| `--c-carousel-fade-duration` | 公开 | `var(--c-sys-motion-duration-standard)` | 本组件 CSS<br>`transition` |
| `--c-carousel-focus-color` | 公开 | `var(--c-sys-color-content-brand)` | 本组件 CSS<br>`outline` |
| `--c-carousel-focus-offset` | 公开 | `2px` | 本组件 CSS<br>`outline-offset` |
| `--c-carousel-focus-width` | 公开 | `2px` | 本组件 CSS<br>`outline` |
| `--c-carousel-indicator-color-active` | 公开 | `var(--c-sys-color-content-on-dark)` | 本组件 CSS<br>`background` |
| `--c-carousel-indicator-color-default` | 公开 | `rgb(255 255 255 / 35%)` | 本组件 CSS<br>`background` |
| `--c-carousel-indicator-dot-size` | 公开 | `8px` | 本组件 CSS<br>`height`, `width` |
| `--c-carousel-indicator-gap` | 公开 | `var(--c-sys-space-3)` | 本组件 CSS<br>`gap` |
| `--c-carousel-indicator-line-border-radius` | 公开 | `var(--c-sys-radius-sm)` | 本组件 CSS<br>`border-radius` |
| `--c-carousel-indicator-line-height` | 公开 | `3px` | 本组件 CSS<br>`height` |
| `--c-carousel-indicator-line-width` | 公开 | `20px` | 本组件 CSS<br>`width` |
| `--c-carousel-indicator-outer-margin-bottom` | 公开 | `var(--c-sys-space-8)` | 本组件 CSS<br>`padding-bottom` |
| `--c-carousel-indicator-position` | 公开 | `var(--c-sys-space-4)` | 本组件 CSS<br>`bottom`, `left`, `right`, `top` |
| `--c-carousel-navigation-z-index` | 公开 | `10` | 本组件 CSS<br>`z-index` |
| `--c-carousel-transition-duration` | 公开 | `var(--c-sys-motion-duration-standard)` | 本组件 CSS<br>`transition` |
| `--c-carousel-transition-timing-function` | 公开 | `ease` | 本组件 CSS<br>`transition` |

</div>

## cascader

声明来源: `src/cascader/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-cascader-checkbox-bg-hover` | 公开 | `var(--c-color-fill-3)` | 本组件 CSS<br>`background-color` |
| `--c-cascader-font-item-size` | 公开 | `var(--c-sys-font-size-md)` | 本组件 CSS<br>`font-size` |
| `--c-cascader-item-bg-active` | 公开 | `var(--c-color-fill-2)` | 本组件 CSS<br>`background-color` |
| `--c-cascader-item-bg-disabled` | 公开 | `transparent` | 本组件 CSS<br>`background-color` |
| `--c-cascader-item-bg-disabled-active` | 公开 | `var(--c-color-fill-2)` | 本组件 CSS<br>`background-color` |
| `--c-cascader-item-bg-hover` | 公开 | `var(--c-cascader-item-bg-active)` | 本组件 CSS<br>`background-color` |
| `--c-cascader-item-check-color` | 公开 | `var(--c-sys-color-action-primary)` | 本组件 CSS<br>`color` |
| `--c-cascader-item-check-size` | 公开 | `var(--c-sys-font-size-md)` | 本组件 CSS<br>`height`, `width` |
| `--c-cascader-item-icon-color` | 公开 | `var(--c-sys-color-content-secondary)` | 本组件 CSS<br>`color` |
| `--c-cascader-item-text-color` | 公开 | `var(--c-sys-color-content-primary)` | 本组件 CSS<br>`color` |
| `--c-cascader-item-text-color-active` | 公开 | `var(--c-cascader-item-text-color)` | 本组件 CSS<br>`color` |
| `--c-cascader-item-text-color-disabled` | 公开 | `var(--c-sys-color-content-disabled)` | 本组件 CSS<br>`color` |
| `--c-cascader-item-text-color-disabled-active` | 公开 | `var(--c-sys-color-content-disabled)` | 本组件 CSS<br>`color` |
| `--c-cascader-item-text-color-hover` | 公开 | `var(--c-cascader-item-text-color)` | 本组件 CSS<br>`color` |
| `--c-cascader-margin-checkbox-right` | 公开 | `var(--c-sys-space-4)` | 本组件 CSS<br>`margin-right` |
| `--c-cascader-margin-item-icon-left` | 公开 | `var(--c-sys-space-5)` | 本组件 CSS<br>`margin-inline-start` |
| `--c-cascader-option-min-width` | 公开 | `100px` | 本组件 CSS<br>`min-width` |
| `--c-cascader-padding-item-left` | 公开 | `var(--c-sys-space-5)` | 本组件 CSS<br>`padding-left`, `padding-right` |
| `--c-cascader-padding-item-right` | 公开 | `var(--c-sys-space-5)` | 本组件 CSS<br>`margin-inline-end`, `padding-right` |
| `--c-cascader-panel-column-max-height` | 公开 | `200px` | 本组件 CSS<br>`max-height` |
| `--c-cascader-panel-column-min-width` | 公开 | `120px` | 本组件 CSS<br>`min-width` |
| `--c-cascader-popup-border-radius` | 公开 | `var(--c-sys-radius-md)` | 本组件 CSS<br>`border-radius` |
| `--c-cascader-popup-box-shadow` | 公开 | `0 4px 10px rgba(0, 0, 0, 0.1)` | 本组件 CSS<br>`box-shadow` |
| `--c-cascader-popup-color-border` | 公开 | `var(--c-color-fill-3)` | 本组件 CSS<br>`border`, `border-right`, `border-top` |
| `--c-cascader-popup-max-height` | 公开 | `200px` | 本组件 CSS<br>`height` |
| `--c-cascader-popup-padding-vertical` | 公开 | `var(--c-sys-space-2)` | 本组件 CSS<br>`padding` |
| `--c-cascader-size-item-height` | 公开 | `36px` | 本组件 CSS<br>`height`, `line-height` |
| `--c-cascader-size-item-icon` | 公开 | `12px` | 本组件 CSS<br>`height`, `width` |
| `--c-cascader-slide-margin` | 公开 | `120px` | 本组件 CSS<br>`margin-left` |

</div>

## checkbox

声明来源: `src/checkbox/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-checkbox-action-padding` | 公开 | `5px` | 本组件 CSS<br>`padding` |
| `--c-checkbox-animation-duration` | 公开 | `var(--c-transition-duration-3)` | 本组件 CSS<br>`transition` |
| `--c-checkbox-control-border-radius` | 公开 | `2px` | 本组件 CSS<br>`border-radius` |
| `--c-checkbox-control-color` | 公开 | `var(--c-sys-color-content-secondary)` | 本组件 CSS<br>`color` |
| `--c-checkbox-control-color-checked` | 公开 | `var(--c-sys-color-content-brand)` | 本组件 CSS<br>`color`, `outline` |
| `--c-checkbox-control-color-disabled` | 公开 | `var(--c-sys-color-content-disabled)` | 本组件 CSS<br>`color` |
| `--c-checkbox-control-color-error` | 公开 | `var(--c-sys-color-content-danger)` | 本组件 CSS<br>`color` |
| `--c-checkbox-control-size` | 公开 | `14px` | 本组件 CSS<br>`height`, `width` |
| `--c-checkbox-group-gap` | 公开 | `var(--c-spacing-7)` | 本组件 CSS<br>`gap` |
| `--c-checkbox-label-font-size` | 公开 | `var(--c-font-size-body-3)` | 本组件 CSS<br>`font-size` |
| `--c-checkbox-label-gap` | 公开 | `var(--c-spacing-4)` | 本组件 CSS<br>`margin-inline-start` |
| `--c-checkbox-label-text-color` | 公开 | `var(--c-sys-color-content-primary)` | 本组件 CSS<br>`color` |
| `--c-checkbox-label-text-color-disabled` | 公开 | `var(--c-sys-color-content-disabled)` | 本组件 CSS<br>`color` |
| `--c-checkbox-mark-color` | 公开 | `var(--c-sys-color-surface-default)` | 本组件 CSS<br>`background-color`, `color` |
| `--c-internal-checkbox-action-radius` | 内部 | `50%` | 本组件 CSS<br>`border-radius` |
| `--c-internal-checkbox-background` | 内部 | `var(--c-sys-color-surface-default)` | 本组件 CSS<br>`background-color` |
| `--c-internal-checkbox-background-disabled` | 内部 | `var(--c-sys-color-surface-muted)` | 本组件 CSS<br>`background-color` |
| `--c-internal-checkbox-border-radius` | 内部 | `var(--c-checkbox-control-border-radius)` | 本组件 CSS<br>`border-radius` |
| `--c-internal-checkbox-border-width` | 内部 | `1px` | 本组件 CSS<br>`border` |
| `--c-internal-checkbox-focus-offset` | 内部 | `2px` | 本组件 CSS<br>`outline-offset` |
| `--c-internal-checkbox-focus-width` | 内部 | `2px` | 本组件 CSS<br>`outline` |
| `--c-internal-checkbox-hover-background` | 内部 | `var(--c-sys-color-state-hover)` | 本组件 CSS<br>`background-color` |
| `--c-internal-checkbox-mark-color` | 内部 | `var(--c-checkbox-mark-color)` | 本组件 CSS<br>`background-color`, `color` |
| `--c-internal-checkbox-mark-height` | 内部 | `2px` | 本组件 CSS<br>`height` |
| `--c-internal-checkbox-mark-radius` | 内部 | `1px` | 本组件 CSS<br>`border-radius` |
| `--c-internal-checkbox-mark-size` | 内部 | `75%` | 本组件 CSS<br>`height`, `width` |

</div>

## collapse

声明来源: `src/collapse/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-collapse-border-color` | 公开 | `var(--c-sys-color-border-default)` | 本组件 CSS<br>`border` |
| `--c-collapse-border-radius` | 公开 | `var(--c-border-radius-md)` | 本组件 CSS<br>`border-radius` |
| `--c-collapse-border-width` | 公开 | `var(--c-border-width-1)` | 本组件 CSS<br>`border` |
| `--c-collapse-content-bg` | 公开 | `var(--c-sys-color-surface-muted)` | 本组件 CSS<br>`background-color` |
| `--c-collapse-content-font-size` | 公开 | `var(--c-font-size-body-3)` | 本组件 CSS<br>`font-size` |
| `--c-collapse-content-padding-vertical` | 公开 | `var(--c-spacing-4)` | 本组件 CSS<br>`padding` |
| `--c-collapse-content-text-color` | 公开 | `var(--c-sys-color-content-primary)` | 本组件 CSS<br>`color` |
| `--c-collapse-content-text-color-disabled` | 公开 | `var(--c-sys-color-content-disabled)` | 本组件 CSS<br>`color` |
| `--c-collapse-expand-icon` | 公开 | `var(--c-sys-color-content-secondary)` | 本组件 CSS<br>`color` |
| `--c-collapse-expand-icon-active-transform` | 公开 | `rotate(90deg)` | 本组件 CSS<br>`transform` |
| `--c-collapse-expand-icon-right-active-transform` | 公开 | `rotate(-90deg)` | 本组件 CSS<br>`transform` |
| `--c-collapse-expand-icon-right-transform` | 公开 | `rotate(0deg)` | 本组件 CSS<br>`transform` |
| `--c-collapse-expand-icon-size` | 公开 | `14px` | 本组件 CSS<br>`font-size` |
| `--c-collapse-expand-icon-spacing-text` | 公开 | `5px` | 本组件 CSS<br>`gap` |
| `--c-collapse-expand-icon-transform` | 公开 | `rotate(0deg)` | 本组件 CSS<br>`transform` |
| `--c-collapse-item-border-color` | 公开 | `var(--c-sys-color-border-default)` | 本组件 CSS<br>`border-bottom` |
| `--c-collapse-item-border-width` | 公开 | `var(--c-border-width-1)` | 本组件 CSS<br>`border-bottom` |
| `--c-collapse-item-margin-top` | 公开 | `var(--c-spacing-4)` | 本组件 CSS<br>`margin-top` |
| `--c-collapse-line-height` | 公开 | `1.5715` | 本组件 CSS<br>`line-height` |
| `--c-collapse-motion-duration` | 公开 | `var(--c-transition-duration-2)` | 本组件 CSS<br>`transition` |
| `--c-collapse-motion-easing` | 公开 | `var(--c-transition-timing-function-standard)` | 本组件 CSS<br>`transition` |
| `--c-collapse-title-bg` | 公开 | `var(--c-sys-color-surface-default)` | 本组件 CSS<br>`background`, `background-color` |
| `--c-collapse-title-bg-active` | 公开 | `var(--c-sys-color-surface-default)` | 本组件 CSS<br>`background-color` |
| `--c-collapse-title-bg-disabled` | 公开 | `var(--c-sys-color-surface-default)` | 本组件 CSS<br>`background-color` |
| `--c-collapse-title-font-size` | 公开 | `var(--c-font-size-body-3)` | 本组件 CSS<br>`font-size` |
| `--c-collapse-title-font-weight-active` | 公开 | `var(--c-font-weight-500)` | 本组件 CSS<br>`font-weight` |
| `--c-collapse-title-line-height` | 公开 | `24px` | 本组件 CSS<br>`line-height` |
| `--c-collapse-title-padding-horizontal` | 公开 | `13px` | 本组件 CSS<br>`padding` |
| `--c-collapse-title-padding-vertical` | 公开 | `var(--c-spacing-4)` | 本组件 CSS<br>`padding` |
| `--c-collapse-title-text-color` | 公开 | `var(--c-sys-color-content-primary)` | 本组件 CSS<br>`color` |
| `--c-collapse-title-text-color-disabled` | 公开 | `var(--c-sys-color-content-disabled)` | 本组件 CSS<br>`color` |

</div>

## color-picker

声明来源: `src/color-picker/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-color-picker-control-bar-alpha-margin-top` | 公开 | `var(--c-spacing-9)` | 本组件 CSS<br>`margin-top` |
| `--c-color-picker-control-bar-border-radius` | 公开 | `10px` | 本组件 CSS<br>`border-radius` |
| `--c-color-picker-control-bar-handle-inner-offset` | 公开 | `var(--c-spacing-4)` | 本组件 CSS<br>`height`, `width` |
| `--c-color-picker-control-bar-handle-size` | 公开 | `var(--c-size-4)` | 本组件 CSS<br>`height`, `width` |
| `--c-color-picker-control-bar-height` | 公开 | `14px` | 本组件 CSS<br>`height` |
| `--c-color-picker-control-bar-width` | 公开 | `182px` | 本组件 CSS<br>`width` |
| `--c-color-picker-input-bg-color` | 公开 | `var(--c-color-fill-2)` | 本组件 CSS<br>`background-color` |
| `--c-color-picker-input-border-radius` | 公开 | `var(--c-border-radius-sm)` | 本组件 CSS<br>`border-radius` |
| `--c-color-picker-input-size-lg-padding` | 公开 | `calc((var(--c-field-size-lg-height) - var(--c-color-picker-preview-size-lg)) / 2) var(--c-spacing-3)` | 本组件 CSS<br>`padding` |
| `--c-color-picker-input-size-md-padding` | 公开 | `calc((var(--c-field-size-md-height) - var(--c-color-picker-preview-size-md)) / 2) var(--c-spacing-2)` | 本组件 CSS<br>`padding` |
| `--c-color-picker-input-size-sm-padding` | 公开 | `calc((var(--c-field-size-sm-height) - var(--c-color-picker-preview-size-sm)) / 2) var(--c-spacing-2)` | 本组件 CSS<br>`padding` |
| `--c-color-picker-input-size-xs-padding` | 公开 | `calc((var(--c-field-size-xs-height) - var(--c-color-picker-preview-size-xs)) / 2) var(--c-spacing-2)` | 本组件 CSS<br>`padding` |
| `--c-color-picker-palette-handle-border-size` | 公开 | `var(--c-border-width-2)` | 本组件 CSS<br>`border` |
| `--c-color-picker-palette-handle-size` | 公开 | `var(--c-size-4)` | 本组件 CSS<br>`height`, `width` |
| `--c-color-picker-palette-height` | 公开 | `178px` | 本组件 CSS<br>`height` |
| `--c-color-picker-panel-affix-font-size` | 公开 | `var(--c-font-size-body-1)` | 本组件 CSS<br>`font-size` |
| `--c-color-picker-panel-alpha-input-width` | 公开 | `52px` | 本组件 CSS<br>`width` |
| `--c-color-picker-panel-bg-color` | 公开 | `var(--c-color-bg-1)` | 本组件 CSS<br>`background-color` |
| `--c-color-picker-panel-block-border-radius` | 公开 | `var(--c-border-radius-sm)` | 本组件 CSS<br>`border-radius` |
| `--c-color-picker-panel-block-margin` | 公开 | `var(--c-spacing-6)` | 本组件 CSS<br>`margin` |
| `--c-color-picker-panel-block-size` | 公开 | `var(--c-size-4)` | 本组件 CSS<br>`height`, `width` |
| `--c-color-picker-panel-border-color` | 公开 | `var(--c-color-border-2)` | 本组件 CSS<br>`border`, `border-left`, `border-right`, `border-top` |
| `--c-color-picker-panel-border-radius` | 公开 | `var(--c-border-radius-sm)` | 本组件 CSS<br>`border-radius` |
| `--c-color-picker-panel-box-shadow` | 公开 | `var(--c-shadow2-down)` | 本组件 CSS<br>`box-shadow` |
| `--c-color-picker-panel-checker-size` | 公开 | `var(--c-spacing-4)` | 本组件 CSS<br>`background-size` |
| `--c-color-picker-panel-colors-empty-margin-y` | 公开 | `var(--c-spacing-9)` | 本组件 CSS<br>`margin` |
| `--c-color-picker-panel-colors-list-margin` | 公开 | `calc(-1 * var(--c-spacing-4)) calc(-1 * var(--c-spacing-2)) 0` | 本组件 CSS<br>`margin` |
| `--c-color-picker-panel-colors-section-margin-top` | 公开 | `var(--c-spacing-9)` | 本组件 CSS<br>`margin-top` |
| `--c-color-picker-panel-colors-wrapper-margin-top` | 公开 | `var(--c-spacing-7)` | 本组件 CSS<br>`margin-top` |
| `--c-color-picker-panel-empty-font-size` | 公开 | `var(--c-font-size-body-3)` | 本组件 CSS<br>`font-size` |
| `--c-color-picker-panel-format-padding-left` | 公开 | `var(--c-spacing-4)` | 本组件 CSS<br>`padding-left` |
| `--c-color-picker-panel-format-select-width` | 公开 | `58px` | 本组件 CSS<br>`width` |
| `--c-color-picker-panel-input-group-margin-left` | 公开 | `var(--c-spacing-9)` | 本组件 CSS<br>`margin-left` |
| `--c-color-picker-panel-input-margin-top` | 公开 | `var(--c-spacing-9)` | 本组件 CSS<br>`margin-top` |
| `--c-color-picker-panel-input-padding-x` | 公开 | `var(--c-spacing-6)` | 本组件 CSS<br>`padding` |
| `--c-color-picker-panel-padding` | 公开 | `var(--c-spacing-9)` | 本组件 CSS<br>`padding` |
| `--c-color-picker-panel-preview-size` | 公开 | `var(--c-size-10)` | 本组件 CSS<br>`font-size`, `height`, `width` |
| `--c-color-picker-panel-section-title-font-size` | 公开 | `var(--c-font-size-body-1)` | 本组件 CSS<br>`font-size` |
| `--c-color-picker-panel-section-title-font-weight` | 公开 | `var(--c-font-weight-400)` | 本组件 CSS<br>`font-weight` |
| `--c-color-picker-panel-width` | 公开 | `260px` | 本组件 CSS<br>`width` |
| `--c-color-picker-preview-border-color` | 公开 | `var(--c-color-border-2)` | 本组件 CSS<br>`border` |
| `--c-color-picker-preview-border-size` | 公开 | `var(--c-border-width-1)` | 本组件 CSS<br>`border` |
| `--c-color-picker-preview-size-lg` | 公开 | `26px` | 本组件 CSS<br>`height`, `padding`, `width` |
| `--c-color-picker-preview-size-md` | 公开 | `var(--c-size-6)` | 本组件 CSS<br>`height`, `padding`, `width` |
| `--c-color-picker-preview-size-sm` | 公开 | `22px` | 本组件 CSS<br>`height`, `padding`, `width` |
| `--c-color-picker-preview-size-xs` | 公开 | `var(--c-size-4)` | 本组件 CSS<br>`height`, `padding`, `width` |
| `--c-color-picker-value-font-color` | 公开 | `var(--c-color-text-1)` | 本组件 CSS<br>`color` |
| `--c-color-picker-value-font-color-disabled` | 公开 | `var(--c-color-text-4)` | 本组件 CSS<br>`color` |
| `--c-color-picker-value-font-size` | 公开 | `var(--c-field-size-md-font-size)` | 本组件 CSS<br>`font-size` |
| `--c-color-picker-value-margin-left` | 公开 | `var(--c-spacing-2)` | 本组件 CSS<br>`margin-left` |

</div>

## count-to

声明来源: `src/count-to/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-count-to-text-color` | 公开 | `var(--c-sys-color-content-primary)` | 本组件 CSS<br>`color` |
| `--c-count-to-text-font-size` | 公开 | `var(--c-font-size-lg)` | 本组件 CSS<br>`font-size` |

</div>

## countdown

声明来源: `src/countdown/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-countdown-text-color` | 公开 | `var(--c-sys-color-content-primary)` | 本组件 CSS<br>`color` |
| `--c-countdown-text-font-size` | 公开 | `var(--c-font-size-lg)` | 本组件 CSS<br>`font-size` |

</div>

## date/picker

声明来源: `src/date/picker/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-date-picker-actions-padding` | 公开 | `8px 12px` | 本组件 CSS<br>`padding` |
| `--c-date-picker-body-padding-horizontal` | 公开 | `var(--c-spacing-7)` | 本组件 CSS<br>`padding` |
| `--c-date-picker-body-padding-vertical` | 公开 | `14px` | 本组件 CSS<br>`padding` |
| `--c-date-picker-box-shadow` | 公开 | `var(--c-shadow1-down)` | 本组件 CSS<br>`box-shadow` |
| `--c-date-picker-btn-confirm-margin-vertical` | 公开 | `5px` | 本组件 CSS<br>`margin` |
| `--c-date-picker-cell-bg-disabled` | 公开 | `var(--c-color-fill-1)` | 本组件 CSS<br>`background-color` |
| `--c-date-picker-cell-bg-hover-in-range` | 公开 | `var(--c-color-fill-2)` | 本组件 CSS<br>`background-color` |
| `--c-date-picker-cell-bg-in-range` | 公开 | `var(--c-color-primary-light-1)` | 本组件 CSS<br>`background-color` |
| `--c-date-picker-cell-font-size` | 公开 | `var(--c-font-size-body-3)` | 本组件 CSS<br>`font-size` |
| `--c-date-picker-cell-font-weight-in-view` | 公开 | `var(--c-font-weight-500)` | 本组件 CSS<br>`font-weight` |
| `--c-date-picker-cell-hover-range-boundary-bg` | 公开 | `var(--c-color-fill-2)` | 本组件 CSS<br>`background-color` |
| `--c-date-picker-cell-hover-range-boundary-text-color` | 公开 | `var(--c-color-text-1)` | 本组件 CSS<br>`color` |
| `--c-date-picker-cell-range-boundary-bg` | 公开 | `rgb(var(--c-primary-6))` | 本组件 CSS<br>`background-color` |
| `--c-date-picker-cell-range-boundary-text-color` | 公开 | `var(--c-color-white)` | 本组件 CSS<br>`color` |
| `--c-date-picker-cell-text-color-in-view` | 公开 | `var(--c-color-text-1)` | 本组件 CSS<br>`color` |
| `--c-date-picker-cell-text-color-not-in-view` | 公开 | `var(--c-color-text-4)` | 本组件 CSS<br>`color` |
| `--c-date-picker-container-border-radius` | 公开 | `var(--c-border-radius-md)` | 本组件 CSS<br>`border-radius` |
| `--c-date-picker-container-min-height` | 公开 | `var(--c-size-15)` | 本组件 CSS<br>`min-height` |
| `--c-date-picker-datetime-popover-width` | 公开 | `calc(var(--c-date-picker-panel-date-width) + var(--c-date-picker-time-panel-min-width) + 2px)` | 本组件 CSS<br>`flex`, `width` |
| `--c-date-picker-footer-btn-wrapper-padding-horizontal` | 公开 | `var(--c-spacing-4)` | 本组件 CSS<br>`padding` |
| `--c-date-picker-footer-btn-wrapper-padding-vertical` | 公开 | `3px` | 本组件 CSS<br>`padding` |
| `--c-date-picker-footer-extra-font-size` | 公开 | `var(--c-font-size-body-1)` | 本组件 CSS<br>`font-size` |
| `--c-date-picker-footer-extra-padding-horizontal` | 公开 | `var(--c-spacing-9)` | 本组件 CSS<br>`padding` |
| `--c-date-picker-footer-extra-padding-vertical` | 公开 | `var(--c-spacing-4)` | 本组件 CSS<br>`padding` |
| `--c-date-picker-footer-now-height` | 公开 | `var(--c-size-9)` | 本组件 CSS<br>`height`, `line-height` |
| `--c-date-picker-header-label-border-radius` | 公开 | `var(--c-border-radius-sm)` | 本组件 CSS<br>`border-radius` |
| `--c-date-picker-header-label-padding` | 公开 | `var(--c-spacing-1)` | 本组件 CSS<br>`padding` |
| `--c-date-picker-header-padding-horizontal` | 公开 | `var(--c-spacing-7)` | 本组件 CSS<br>`padding` |
| `--c-date-picker-header-padding-vertical` | 公开 | `var(--c-spacing-4)` | 本组件 CSS<br>`padding` |
| `--c-date-picker-header-title-font-size` | 公开 | `var(--c-font-size-body-3)` | 本组件 CSS<br>`font-size` |
| `--c-date-picker-header-title-line-height` | 公开 | `var(--c-size-6)` | 本组件 CSS<br>`line-height` |
| `--c-date-picker-panel-background` | 公开 | `var(--c-sys-color-surface-overlay)` | 本组件 CSS<br>`background` |
| `--c-date-picker-panel-border` | 公开 | `var(--c-color-border-2)` | 本组件 CSS<br>`border` |
| `--c-date-picker-panel-border-color` | 公开 | `var(--c-color-neutral-3)` | 本组件 CSS<br>`border`, `border-bottom`, `border-left`, `border-right`, `border-top` |
| `--c-date-picker-panel-cell-bg-hover` | 公开 | `var(--c-color-fill-3)` | 本组件 CSS<br>`background-color` |
| `--c-date-picker-panel-cell-bg-selected` | 公开 | `rgb(var(--c-primary-6))` | 本组件 CSS<br>`background-color` |
| `--c-date-picker-panel-cell-border-radius` | 公开 | `var(--c-date-picker-panel-cell-circle-height)` | 本组件 CSS<br>`border-bottom-left-radius`, `border-bottom-right-radius`, `border-top-left-radius`, `border-top-right-radius` |
| `--c-date-picker-panel-cell-boundary-border-radius` | 公开 | `var(--c-date-picker-panel-cell-circle-height)` | 本组件 CSS<br>`border-bottom-left-radius`, `border-bottom-right-radius`, `border-radius`, `border-top-left-radius`, `border-top-right-radius` |
| `--c-date-picker-panel-cell-circle-height` | 公开 | `var(--c-size-6)` | 本组件 CSS<br>`border-bottom-left-radius`, `border-bottom-right-radius`, `border-radius`, `border-top-left-radius`, `border-top-right-radius`, `height`, `line-height`, `min-width`, `width` |
| `--c-date-picker-panel-cell-padding-vertical` | 公开 | `var(--c-spacing-2)` | 本组件 CSS<br>`padding`, `padding-left`, `padding-right` |
| `--c-date-picker-panel-cell-selected-border-radius` | 公开 | `var(--c-border-radius-circle)` | 本组件 CSS<br>`border-radius` |
| `--c-date-picker-panel-cell-text-color-hover` | 公开 | `var(--c-color-text-1)` | 本组件 CSS<br>`color` |
| `--c-date-picker-panel-cell-text-color-selected` | 公开 | `var(--c-color-white)` | 本组件 CSS<br>`color` |
| `--c-date-picker-panel-current-time-dot-color` | 公开 | `rgb(var(--c-primary-6))` | 本组件 CSS<br>`background-color` |
| `--c-date-picker-panel-date-width` | 公开 | `265px` | 本组件 CSS<br>`flex`, `min-width`, `width` |
| `--c-date-picker-panel-label-bg-hover` | 公开 | `var(--c-color-fill-3)` | 本组件 CSS<br>`background-color` |
| `--c-date-picker-panel-month-width` | 公开 | `265px` | 本组件 CSS<br>`width` |
| `--c-date-picker-panel-preferred-width` | 公开 | `var(--c-date-picker-popover-width)` | 本组件 CSS<br>`flex`, `width` |
| `--c-date-picker-panel-quarter-width` | 公开 | `265px` | 本组件 CSS<br>`width` |
| `--c-date-picker-panel-radius` | 公开 | `8px` | 本组件 CSS<br>`border-radius` |
| `--c-date-picker-panel-time-cell-spacing-horizontal` | 公开 | `var(--c-spacing-2)` | 本组件 CSS<br>`padding` |
| `--c-date-picker-panel-time-cell-width` | 公开 | `var(--c-size-9)` | 本组件 CSS<br>`width` |
| `--c-date-picker-panel-time-padding` | 公开 | `var(--c-spacing-3)` | 本组件 CSS<br>`padding` |
| `--c-date-picker-panel-time-padding-horizontal` | 公开 | `var(--c-spacing-5)` | 本组件 CSS<br>`padding-left` |
| `--c-date-picker-panel-week-width` | 公开 | `298px` | 本组件 CSS<br>`flex`, `width` |
| `--c-date-picker-panel-year-width` | 公开 | `265px` | 本组件 CSS<br>`width` |
| `--c-date-picker-popover-gap` | 公开 | `32px` | 本组件 CSS<br>`max-height`, `max-width` |
| `--c-date-picker-popover-max-height` | 公开 | `calc(50dvh - var(--c-date-picker-popover-gap))` | 本组件 CSS<br>`max-height` |
| `--c-date-picker-popover-width` | 公开 | `calc(var(--c-date-picker-panel-date-width) + 2px)` | 本组件 CSS<br>`flex`, `width` |
| `--c-date-picker-preview-outline` | 公开 | `1px dashed var(--c-color-primary)` | 本组件 CSS<br>`outline` |
| `--c-date-picker-range-panel-min-width` | 公开 | `224px` | 本组件 CSS<br>`min-width` |
| `--c-date-picker-range-popover-width` | 公开 | `calc(var(--c-date-picker-panel-date-width) * 2 + 2px)` | 本组件 CSS<br>`flex`, `width` |
| `--c-date-picker-row-padding-vertical` | 公开 | `var(--c-spacing-1)` | 本组件 CSS<br>`padding` |
| `--c-date-picker-shortcuts-active-text-color` | 公开 | `var(--c-sys-color-content-brand)` | 本组件 CSS<br>`color` |
| `--c-date-picker-shortcuts-column-width` | 公开 | `128px` | 本组件 CSS<br>`flex`, `width` |
| `--c-date-picker-shortcuts-inline-item-margin-right` | 公开 | `var(--c-spacing-5)` | 本组件 CSS<br>`margin` |
| `--c-date-picker-shortcuts-inline-item-margin-vertical` | 公开 | `5px` | 本组件 CSS<br>`margin` |
| `--c-date-picker-shortcuts-item-padding-horizontal` | 公开 | `var(--c-spacing-7)` | 本组件 CSS<br>`padding` |
| `--c-date-picker-shortcuts-item-padding-vertical` | 公开 | `var(--c-spacing-3)` | 本组件 CSS<br>`padding` |
| `--c-date-picker-shortcuts-margin-top` | 公开 | `var(--c-spacing-5)` | 本组件 CSS<br>`margin` |
| `--c-date-picker-shortcuts-max-height` | 公开 | `300px` | 本组件 CSS<br>`max-height` |
| `--c-date-picker-shortcuts-placement-item-margin-vertical` | 公开 | `5px` | 本组件 CSS<br>`margin` |
| `--c-date-picker-shortcuts-placement-padding-horizontal` | 公开 | `var(--c-spacing-4)` | 本组件 CSS<br>`padding` |
| `--c-date-picker-shortcuts-placement-padding-vertical` | 公开 | `5px` | 本组件 CSS<br>`padding` |
| `--c-date-picker-shortcuts-width` | 公开 | `106px` | 本组件 CSS<br>`width` |
| `--c-date-picker-switch-icon-bg` | 公开 | `var(--c-color-bg-popup)` | 本组件 CSS<br>`background-color` |
| `--c-date-picker-switch-icon-bg-hover` | 公开 | `var(--c-color-fill-3)` | 本组件 CSS<br>`background-color` |
| `--c-date-picker-switch-icon-border-radius` | 公开 | `var(--c-border-radius-circle)` | 本组件 CSS<br>`border-radius` |
| `--c-date-picker-switch-icon-color` | 公开 | `var(--c-color-text-2)` | 本组件 CSS<br>`color` |
| `--c-date-picker-switch-icon-font-size` | 公开 | `var(--c-font-size-body-1)` | 本组件 CSS<br>`font-size` |
| `--c-date-picker-switch-icon-margin` | 公开 | `var(--c-spacing-1)` | 本组件 CSS<br>`margin-left`, `margin-right` |
| `--c-date-picker-switch-icon-size` | 公开 | `var(--c-size-6)` | 本组件 CSS<br>`height`, `width` |
| `--c-date-picker-time-panel-min-width` | 公开 | `160px` | 本组件 CSS<br>`flex`, `min-width`, `width` |
| `--c-date-picker-timepicker-height` | 公开 | `276px` | 本组件 CSS<br>`height` |
| `--c-date-picker-timepicker-title-font-size` | 公开 | `var(--c-font-size-body-3)` | 本组件 CSS<br>`font-size` |
| `--c-date-picker-timepicker-title-height` | 公开 | `var(--c-size-10)` | 本组件 CSS<br>`height`, `line-height` |
| `--c-date-picker-today-dot-offset` | 公开 | `var(--c-spacing-1)` | 本组件 CSS<br>`bottom`, `margin-left` |
| `--c-date-picker-today-dot-size` | 公开 | `var(--c-spacing-2)` | 本组件 CSS<br>`height`, `width` |
| `--c-date-picker-transition-duration-1` | 公开 | `var(--c-transition-duration-1)` | 本组件 CSS<br>`transition` |
| `--c-date-picker-transition-timing-function-linear` | 公开 | `var(--c-transition-timing-function-linear)` | 本组件 CSS<br>`transition` |
| `--c-date-picker-view-tab-pane-font-size` | 公开 | `var(--c-font-size-body-3)` | 本组件 CSS<br>`font-size` |
| `--c-date-picker-view-tab-pane-text-color-active` | 公开 | `var(--c-color-text-1)` | 本组件 CSS<br>`color` |
| `--c-date-picker-view-tab-pane-text-color-inactive` | 公开 | `var(--c-color-text-4)` | 本组件 CSS<br>`color` |
| `--c-date-picker-view-tab-pane-text-icon-spacing` | 公开 | `var(--c-spacing-4)` | 本组件 CSS<br>`margin-left` |
| `--c-date-picker-view-tabs-height` | 公开 | `50px` | 本组件 CSS<br>`height`, `line-height` |
| `--c-date-picker-week-list-item-color` | 公开 | `var(--c-color-text-3)` | 本组件 CSS<br>`color` |
| `--c-date-picker-week-list-item-height` | 公开 | `var(--c-size-8)` | 本组件 CSS<br>`height`, `line-height` |
| `--c-date-picker-week-popover-width` | 公开 | `calc(var(--c-date-picker-panel-week-width) + 2px)` | 本组件 CSS<br>`flex`, `width` |
| `--c-date-picker-week-range-popover-width` | 公开 | `calc(var(--c-date-picker-panel-week-width) * 2 + 2px)` | 本组件 CSS<br>`flex`, `width` |

</div>

## descriptions

声明来源: `src/descriptions/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-descriptions-border-bg-label` | 公开 | `var(--c-color-fill-1)` | 本组件 CSS<br>`background-color` |
| `--c-descriptions-border-color` | 公开 | `var(--c-color-neutral-3)` | 本组件 CSS<br>`border`, `border-bottom`, `border-right` |
| `--c-descriptions-border-item-size-lg-padding-horizontal` | 公开 | `var(--c-spacing-8)` | 本组件 CSS<br>`padding`, `padding-right` |
| `--c-descriptions-border-item-size-lg-padding-vertical` | 公开 | `9px` | 本组件 CSS<br>`padding` |
| `--c-descriptions-border-item-size-md-padding-horizontal` | 公开 | `var(--c-spacing-8)` | 本组件 CSS<br>`padding`, `padding-right` |
| `--c-descriptions-border-item-size-md-padding-vertical` | 公开 | `5px` | 本组件 CSS<br>`padding` |
| `--c-descriptions-border-item-size-sm-padding-horizontal` | 公开 | `var(--c-spacing-8)` | 本组件 CSS<br>`padding`, `padding-right` |
| `--c-descriptions-border-item-size-sm-padding-vertical` | 公开 | `3px` | 本组件 CSS<br>`padding` |
| `--c-descriptions-border-item-size-xl-padding-horizontal` | 公开 | `var(--c-spacing-8)` | 本组件 CSS<br>`padding`, `padding-right` |
| `--c-descriptions-border-item-size-xl-padding-vertical` | 公开 | `var(--c-spacing-6)` | 本组件 CSS<br>`padding` |
| `--c-descriptions-border-item-size-xs-padding-horizontal` | 公开 | `var(--c-spacing-8)` | 本组件 CSS<br>`padding`, `padding-right` |
| `--c-descriptions-border-item-size-xs-padding-vertical` | 公开 | `3px` | 本组件 CSS<br>`padding` |
| `--c-descriptions-border-radius` | 公开 | `var(--c-border-radius-md)` | 本组件 CSS<br>`border-radius` |
| `--c-descriptions-border-style` | 公开 | `solid` | 本组件 CSS<br>`border`, `border-bottom`, `border-right` |
| `--c-descriptions-border-width` | 公开 | `1px` | 本组件 CSS<br>`border`, `border-bottom`, `border-right` |
| `--c-descriptions-font-size-title` | 公开 | `var(--c-font-size-title-1)` | 本组件 CSS<br>`font-size` |
| `--c-descriptions-font-weight-text-label` | 公开 | `var(--c-font-weight-500)` | 本组件 CSS<br>`font-weight` |
| `--c-descriptions-font-weight-text-value` | 公开 | `var(--c-font-weight-400)` | 本组件 CSS<br>`font-weight` |
| `--c-descriptions-font-weight-title` | 公开 | `var(--c-font-weight-500)` | 本组件 CSS<br>`font-weight` |
| `--c-descriptions-inline-vertical-padding-extra` | 公开 | `5px` | 本组件 CSS<br>`padding` |
| `--c-descriptions-item-label-inline-margin-bottom` | 公开 | `var(--c-spacing-1)` | 本组件 CSS<br>`margin-bottom` |
| `--c-descriptions-item-label-inline-margin-right` | 公开 | `var(--c-spacing-2)` | 本组件 CSS<br>`margin-right` |
| `--c-descriptions-item-label-padding-x` | 公开 | `var(--c-spacing-2)` | 本组件 CSS<br>`padding` |
| `--c-descriptions-item-size-lg-spacing-bottom` | 公开 | `var(--c-spacing-6)` | 本组件 CSS<br>`padding-bottom` |
| `--c-descriptions-item-size-md-spacing-bottom` | 公开 | `var(--c-spacing-4)` | 本组件 CSS<br>`padding`, `padding-bottom` |
| `--c-descriptions-item-size-sm-spacing-bottom` | 公开 | `var(--c-spacing-2)` | 本组件 CSS<br>`padding-bottom` |
| `--c-descriptions-item-size-xl-spacing-bottom` | 公开 | `var(--c-spacing-7)` | 本组件 CSS<br>`padding-bottom` |
| `--c-descriptions-item-size-xs-spacing-bottom` | 公开 | `var(--c-spacing-1)` | 本组件 CSS<br>`padding-bottom` |
| `--c-descriptions-size-lg-font-size-text` | 公开 | `var(--c-font-size-body-3)` | 本组件 CSS<br>`font-size` |
| `--c-descriptions-size-lg-title-margin-bottom` | 公开 | `var(--c-spacing-8)` | 本组件 CSS<br>`margin-bottom` |
| `--c-descriptions-size-md-font-size-text` | 公开 | `var(--c-font-size-body-3)` | 本组件 CSS<br>`font-size` |
| `--c-descriptions-size-md-title-margin-bottom` | 公开 | `var(--c-spacing-7)` | 本组件 CSS<br>`margin-bottom` |
| `--c-descriptions-size-sm-font-size-text` | 公开 | `var(--c-font-size-body-3)` | 本组件 CSS<br>`font-size` |
| `--c-descriptions-size-sm-title-margin-bottom` | 公开 | `var(--c-spacing-4)` | 本组件 CSS<br>`margin-bottom` |
| `--c-descriptions-size-xl-font-size-text` | 公开 | `var(--c-font-size-body-3)` | 本组件 CSS<br>`font-size` |
| `--c-descriptions-size-xl-title-margin-bottom` | 公开 | `var(--c-spacing-8)` | 本组件 CSS<br>`margin-bottom` |
| `--c-descriptions-size-xs-font-size-text` | 公开 | `var(--c-font-size-body-1)` | 本组件 CSS<br>`font-size` |
| `--c-descriptions-size-xs-title-margin-bottom` | 公开 | `var(--c-spacing-3)` | 本组件 CSS<br>`margin-bottom` |
| `--c-descriptions-text-color-label` | 公开 | `var(--c-color-text-3)` | 本组件 CSS<br>`color` |
| `--c-descriptions-text-color-value` | 公开 | `var(--c-color-text-1)` | 本组件 CSS<br>`color` |
| `--c-descriptions-title-color` | 公开 | `var(--c-color-text-1)` | 本组件 CSS<br>`color` |

</div>

## dialog

声明来源: `src/dialog/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-dialog-actions-button-gap` | 公开 | `var(--c-sys-space-6)` | 本组件 CSS<br>`margin-left` |
| `--c-dialog-actions-padding` | 公开 | `var(--c-sys-space-7) var(--c-sys-space-8)` | 本组件 CSS<br>`padding` |
| `--c-dialog-animation-duration` | 公开 | `var(--c-sys-motion-duration-slow)` | 本组件 CSS<br>`transition` |
| `--c-dialog-animation-easing` | 公开 | `var(--c-sys-motion-easing-standard)` | 本组件 CSS<br>`transition` |
| `--c-dialog-background` | 公开 | `var(--c-sys-color-surface-raised)` | 本组件 CSS<br>`background-color` |
| `--c-dialog-border-color` | 公开 | `var(--c-sys-color-border-default)` | 本组件 CSS<br>`border-bottom`, `border-top` |
| `--c-dialog-border-radius` | 公开 | `var(--c-sys-radius-md)` | 本组件 CSS<br>`border-radius` |
| `--c-dialog-border-width` | 公开 | `1px` | 本组件 CSS<br>`border-bottom`, `border-top` |
| `--c-dialog-close-button-color` | 公开 | `var(--c-sys-color-content-secondary)` | 本组件 CSS<br>`color` |
| `--c-dialog-close-button-font-size` | 公开 | `var(--c-sys-font-size-lg)` | 本组件 CSS<br>`font-size` |
| `--c-dialog-close-button-inset-inline-end` | 公开 | `var(--c-sys-space-7)` | 本组件 CSS<br>`right` |
| `--c-dialog-close-button-size` | 公开 | `32px` | 本组件 CSS<br>`height`, `width` |
| `--c-dialog-content-font-size` | 公开 | `var(--c-sys-font-size-md)` | 本组件 CSS<br>`font-size` |
| `--c-dialog-content-line-height` | 公开 | `var(--c-line-height)` | 本组件 CSS<br>`line-height` |
| `--c-dialog-content-padding` | 公开 | `28px var(--c-sys-space-8)` | 本组件 CSS<br>`padding` |
| `--c-dialog-content-text-color` | 公开 | `var(--c-sys-color-content-primary)` | 本组件 CSS<br>`color` |
| `--c-dialog-fullscreen-height` | 公开 | `100vh` | 本组件 CSS<br>`height` |
| `--c-dialog-fullscreen-width` | 公开 | `100vw` | 本组件 CSS<br>`width` |
| `--c-dialog-margin-top` | 公开 | `100px` | 本组件 CSS<br>`top` |
| `--c-dialog-overlay-background` | 公开 | `var(--c-sys-color-scrim)` | 本组件 CSS<br>`background-color` |
| `--c-dialog-simple-actions-gap` | 公开 | `32px` | 本组件 CSS<br>`margin-top` |
| `--c-dialog-simple-border-radius` | 公开 | `var(--c-sys-radius-md)` | 本组件 CSS<br>`border-radius` |
| `--c-dialog-simple-content-gap` | 公开 | `28px` | 本组件 CSS<br>`margin-bottom` |
| `--c-dialog-simple-padding` | 公开 | `28px 32px 32px` | 本组件 CSS<br>`padding` |
| `--c-dialog-simple-width` | 公开 | `400px` | 本组件 CSS<br>`width` |
| `--c-dialog-status-danger-color` | 公开 | `var(--c-sys-color-content-danger)` | 本组件 CSS<br>`color` |
| `--c-dialog-status-icon-gap` | 公开 | `var(--c-sys-space-5)` | 本组件 CSS<br>`margin-right` |
| `--c-dialog-status-icon-size` | 公开 | `18px` | 本组件 CSS<br>`font-size` |
| `--c-dialog-status-info-color` | 公开 | `var(--c-sys-color-content-info)` | 本组件 CSS<br>`color` |
| `--c-dialog-status-success-color` | 公开 | `var(--c-sys-color-content-success)` | 本组件 CSS<br>`color` |
| `--c-dialog-status-warning-color` | 公开 | `var(--c-sys-color-content-warning)` | 本组件 CSS<br>`color` |
| `--c-dialog-title-font-size` | 公开 | `var(--c-sys-font-size-lg)` | 本组件 CSS<br>`font-size` |
| `--c-dialog-title-font-weight` | 公开 | `var(--c-sys-font-weight-medium)` | 本组件 CSS<br>`font-weight` |
| `--c-dialog-title-justify` | 公开 | `center` | 本组件 CSS<br>`justify-content` |
| `--c-dialog-title-min-height` | 公开 | `48px` | 本组件 CSS<br>`min-height` |
| `--c-dialog-title-padding` | 公开 | `0 var(--c-sys-space-8)` | 本组件 CSS<br>`padding` |
| `--c-dialog-title-text-color` | 公开 | `var(--c-sys-color-content-primary)` | 本组件 CSS<br>`color` |
| `--c-dialog-width` | 公开 | `520px` | 本组件 CSS<br>`width` |

</div>

## divider

声明来源: `src/divider/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-divider-border-width` | 公开 | `1px` | 本组件 CSS<br>`border-left-width`, `border-top-width` |
| `--c-divider-color` | 公开 | `var(--c-sys-color-border-default)` | 本组件 CSS<br>`border-left-color`, `border-top-color` |
| `--c-divider-orientation-horizontal-inset-lg` | 公开 | `32px` | 本组件 CSS<br>`margin-inline-end`, `margin-inline-start`, `max-width` |
| `--c-divider-orientation-horizontal-inset-md` | 公开 | `24px` | 本组件 CSS<br>`margin-inline-end`, `margin-inline-start`, `max-width` |
| `--c-divider-orientation-horizontal-inset-sm` | 公开 | `16px` | 本组件 CSS<br>`margin-inline-end`, `margin-inline-start`, `max-width` |
| `--c-divider-orientation-horizontal-inset-xl` | 公开 | `40px` | 本组件 CSS<br>`margin-inline-end`, `margin-inline-start`, `max-width` |
| `--c-divider-orientation-horizontal-inset-xs` | 公开 | `12px` | 本组件 CSS<br>`margin-inline-end`, `margin-inline-start`, `max-width` |
| `--c-divider-orientation-horizontal-spacing-lg` | 公开 | `24px` | 本组件 CSS<br>`margin-block-end`, `margin-block-start` |
| `--c-divider-orientation-horizontal-spacing-md` | 公开 | `16px` | 本组件 CSS<br>`margin-block-end`, `margin-block-start` |
| `--c-divider-orientation-horizontal-spacing-sm` | 公开 | `12px` | 本组件 CSS<br>`margin-block-end`, `margin-block-start` |
| `--c-divider-orientation-horizontal-spacing-xl` | 公开 | `32px` | 本组件 CSS<br>`margin-block-end`, `margin-block-start` |
| `--c-divider-orientation-horizontal-spacing-xs` | 公开 | `8px` | 本组件 CSS<br>`margin-block-end`, `margin-block-start` |
| `--c-divider-orientation-vertical-inset-lg` | 公开 | `8px` | 本组件 CSS<br>`margin-block-end`, `margin-block-start`, `max-height` |
| `--c-divider-orientation-vertical-inset-md` | 公开 | `6px` | 本组件 CSS<br>`margin-block-end`, `margin-block-start`, `max-height` |
| `--c-divider-orientation-vertical-inset-sm` | 公开 | `4px` | 本组件 CSS<br>`margin-block-end`, `margin-block-start`, `max-height` |
| `--c-divider-orientation-vertical-inset-xl` | 公开 | `12px` | 本组件 CSS<br>`margin-block-end`, `margin-block-start`, `max-height` |
| `--c-divider-orientation-vertical-inset-xs` | 公开 | `2px` | 本组件 CSS<br>`margin-block-end`, `margin-block-start`, `max-height` |
| `--c-divider-orientation-vertical-spacing-lg` | 公开 | `16px` | 本组件 CSS<br>`margin-inline-end`, `margin-inline-start` |
| `--c-divider-orientation-vertical-spacing-md` | 公开 | `12px` | 本组件 CSS<br>`margin-inline-end`, `margin-inline-start` |
| `--c-divider-orientation-vertical-spacing-sm` | 公开 | `8px` | 本组件 CSS<br>`margin-inline-end`, `margin-inline-start` |
| `--c-divider-orientation-vertical-spacing-xl` | 公开 | `24px` | 本组件 CSS<br>`margin-inline-end`, `margin-inline-start` |
| `--c-divider-orientation-vertical-spacing-xs` | 公开 | `4px` | 本组件 CSS<br>`margin-inline-end`, `margin-inline-start` |
| `--c-divider-text-align-inset` | 公开 | `24px` | 本组件 CSS<br>`height`, `width` |
| `--c-divider-text-color` | 公开 | `var(--c-sys-color-content-secondary)` | 本组件 CSS<br>`color` |
| `--c-divider-text-padding` | 公开 | `16px` | 本组件 CSS<br>`padding` |

</div>

## drawer

声明来源: `src/drawer/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-drawer-bg` | 公开 | `var(--c-sys-color-surface-raised)` | 本组件 CSS<br>`background-color` |
| `--c-drawer-border-color` | 公开 | `var(--c-sys-color-border-default)` | 本组件 CSS<br>`border-bottom`, `border-top` |
| `--c-drawer-border-width` | 公开 | `var(--c-border-width-1)` | 本组件 CSS<br>`border-bottom`, `border-top` |
| `--c-drawer-close-btn-margin-left` | 公开 | `var(--c-spacing-4)` | 本组件 CSS<br>`margin-left` |
| `--c-drawer-close-icon-font-size` | 公开 | `var(--c-size-3)` | 本组件 CSS<br>`font-size` |
| `--c-drawer-content-padding-vertical` | 公开 | `var(--c-spacing-6)` | 本组件 CSS<br>`padding` |
| `--c-drawer-content-text-color` | 公开 | `var(--c-sys-color-content-primary)` | 本组件 CSS<br>`color` |
| `--c-drawer-footer-button-margin-left` | 公开 | `var(--c-spacing-6)` | 本组件 CSS<br>`margin-left` |
| `--c-drawer-footer-padding-vertical` | 公开 | `var(--c-spacing-7)` | 本组件 CSS<br>`padding` |
| `--c-drawer-header-font-size` | 公开 | `var(--c-font-size-title-1)` | 本组件 CSS<br>`font-size` |
| `--c-drawer-header-font-weight` | 公开 | `var(--c-font-weight-500)` | 本组件 CSS<br>`font-weight` |
| `--c-drawer-header-height` | 公开 | `var(--c-size-12)` | 本组件 CSS<br>`height` |
| `--c-drawer-header-text-color` | 公开 | `var(--c-sys-color-content-primary)` | 本组件 CSS<br>`color` |
| `--c-drawer-line-height` | 公开 | `var(--c-line-height)` | 本组件 CSS<br>`line-height` |
| `--c-drawer-overlay-bg` | 公开 | `var(--c-sys-color-scrim)` | 本组件 CSS<br>`background-color` |
| `--c-drawer-padding-horizontal` | 公开 | `var(--c-spacing-7)` | 本组件 CSS<br>`padding` |
| `--c-drawer-transition-duration` | 公开 | `var(--c-transition-duration-3)` | 本组件 CSS<br>`transition` |
| `--c-drawer-transition-timing-function` | 公开 | `var(--c-transition-timing-function-standard)` | 本组件 CSS<br>`transition` |
| `--c-drawer-z-index` | 公开 | `var(--c-z-index-drawer)` | 本组件 CSS<br>`z-index` |

</div>

## ellipsis

声明来源: `src/ellipsis/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-ellipsis-focus-color` | 公开 | `var(--c-sys-color-content-brand)` | 本组件 CSS<br>`outline` |
| `--c-ellipsis-focus-offset` | 公开 | `2px` | 本组件 CSS<br>`outline-offset` |
| `--c-ellipsis-focus-width` | 公开 | `2px` | 本组件 CSS<br>`outline` |

</div>

## empty

声明来源: `src/empty/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-empty-description-color` | 公开 | `var(--c-sys-color-content-tertiary)` | 本组件 CSS<br>`color` |
| `--c-empty-description-font-size` | 公开 | `var(--c-font-size-body-3)` | 本组件 CSS<br>`font-size` |
| `--c-empty-description-line-height` | 公开 | `var(--c-line-height)` | 本组件 CSS<br>`line-height` |
| `--c-empty-extra-margin-top` | 公开 | `var(--c-spacing-5)` | 本组件 CSS<br>`margin-top` |
| `--c-empty-icon-color` | 公开 | `var(--c-sys-color-content-decorative)` | 本组件 CSS<br>`color` |
| `--c-empty-image-margin-bottom` | 公开 | `var(--c-spacing-2)` | 本组件 CSS<br>`margin-bottom` |
| `--c-empty-padding` | 公开 | `var(--c-spacing-5) 0` | 本组件 CSS<br>`padding` |
| `--c-empty-size-lg` | 公开 | `var(--c-size-35)` | 本组件 CSS<br>`font-size`, `height`, `width` |
| `--c-empty-size-md` | 公开 | `var(--c-size-25)` | 本组件 CSS<br>`font-size`, `height`, `width` |
| `--c-empty-size-sm` | 公开 | `var(--c-size-20)` | 本组件 CSS<br>`font-size`, `height`, `width` |
| `--c-empty-size-xl` | 公开 | `var(--c-size-45)` | 本组件 CSS<br>`font-size`, `height`, `width` |
| `--c-empty-size-xs` | 公开 | `var(--c-size-15)` | 本组件 CSS<br>`font-size`, `height`, `width` |

</div>

## field-decorator

声明来源: `src/field-decorator/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-field-blur-color` | 公开 | `var(--c-sys-color-content-tertiary)` | 本组件 CSS<br>`border-bottom`, `color` |
| `--c-field-border-radius` | 公开 | `var(--c-border-radius-md)` | 本组件 CSS<br>`border-end-end-radius`, `border-end-start-radius`, `border-radius`, `border-start-end-radius`, `border-start-start-radius` |
| `--c-field-border-width` | 公开 | `1px` | 本组件 CSS<br>`border`, `border-bottom`, `margin-inline-start`, `min-height`, `outline`, `outline-offset`, `padding-inline-start` |
| `--c-field-caret-color` | 公开 | `currentColor` | 跨组件 CSS<br>`caret-color` |
| `--c-field-clear-icon-color` | 公开 | `var(--c-sys-color-content-secondary)` | 本组件 CSS<br>`color` |
| `--c-field-clear-icon-size` | 公开 | `12px` | 本组件 CSS<br>`font-size` |
| `--c-field-clear-padding` | 公开 | `2px` | 本组件 CSS<br>`padding` |
| `--c-field-clear-radius` | 公开 | `50%` | 本组件 CSS<br>`border-radius` |
| `--c-field-clear-visibility` | 公开 | `hidden` | 本组件 CSS<br>`visibility` |
| `--c-field-content-gap` | 公开 | `8px` | 本组件 CSS<br>`gap`, `padding-inline-end`, `padding-inline-start` |
| `--c-field-content-padding-vertical` | 公开 | `5px` | 本组件 CSS<br>`top` |
| `--c-field-control-text-color` | 公开 | `var(--c-sys-color-content-primary)` | 本组件 CSS<br>`color` |
| `--c-field-control-text-color-disabled` | 公开 | `var(--c-sys-color-content-disabled)` | 本组件 CSS<br>`-webkit-text-fill-color`, `color` |
| `--c-field-error-color` | 公开 | `var(--c-sys-color-status-danger)` | 本组件 CSS<br>`border-bottom-color`, `border-color`, `color` |
| `--c-field-focus-color` | 公开 | `var(--c-sys-color-action-primary)` | 本组件 CSS<br>`border-bottom-color`, `color`, `outline` |
| `--c-field-hint-duration` | 公开 | `0.2s` | 本组件 CSS<br>`transition` |
| `--c-field-hint-scale` | 公开 | `0.75` | 本组件 CSS<br>`font-size`, `top`, `transform` |
| `--c-field-hint-space` | 公开 | `4px` | 本组件 CSS<br>`padding`, `padding-inline-start` |
| `--c-field-icon-size` | 公开 | `14px` | 本组件 CSS<br>`font-size` |
| `--c-field-line-height` | 公开 | `1.5` | 本组件 CSS<br>`line-height`, `top` |
| `--c-field-padding-horizontal` | 公开 | `12px` | 本组件 CSS<br>`left`, `margin-inline-end`, `margin-inline-start`, `max-width`, `padding`, `padding-inline-start`, `padding-left`, `padding-right` |
| `--c-field-placeholder-text-color` | 公开 | `var(--c-sys-color-content-tertiary)` | 本组件 CSS<br>`color` |
| `--c-field-prefix-text-color` | 公开 | `var(--c-sys-color-content-secondary)` | 本组件 CSS<br>`color` |
| `--c-field-size-lg-font-size` | 公开 | `14px` | 本组件 CSS<br>`font-size` |
| `--c-field-size-lg-height` | 公开 | `36px` | 本组件 CSS<br>`flex`, `height`, `min-height`, `padding` |
| `--c-field-size-md-font-size` | 公开 | `14px` | 本组件 CSS<br>`font-size` |
| `--c-field-size-md-height` | 公开 | `32px` | 本组件 CSS<br>`flex`, `height`, `min-height`, `padding` |
| `--c-field-size-sm-font-size` | 公开 | `14px` | 本组件 CSS<br>`font-size` |
| `--c-field-size-sm-height` | 公开 | `28px` | 本组件 CSS<br>`flex`, `height`, `min-height`, `padding` |
| `--c-field-size-xl-font-size` | 公开 | `16px` | 本组件 CSS<br>`font-size` |
| `--c-field-size-xl-height` | 公开 | `44px` | 本组件 CSS<br>`flex`, `height`, `min-height` |
| `--c-field-size-xs-font-size` | 公开 | `12px` | 本组件 CSS<br>`font-size` |
| `--c-field-size-xs-height` | 公开 | `24px` | 本组件 CSS<br>`flex`, `height`, `min-height`, `padding` |
| `--c-field-suffix-text-color` | 公开 | `var(--c-sys-color-content-secondary)` | 本组件 CSS<br>`color` |
| `--c-field-variant-filled-background` | 公开 | `var(--c-sys-color-surface-muted)` | 本组件 CSS<br>`background` |
| `--c-field-variant-filled-background-disabled` | 公开 | `var(--c-color-fill-2)` | 本组件 CSS<br>`background` |
| `--c-field-variant-filled-background-error` | 公开 | `var(--c-color-danger-light-1)` | 本组件 CSS<br>`background` |
| `--c-field-variant-filled-background-focus` | 公开 | `var(--c-color-fill-3)` | 本组件 CSS<br>`background` |
| `--c-field-variant-filled-background-hover` | 公开 | `var(--c-sys-color-state-hover)` | 本组件 CSS<br>`background` |
| `--c-field-variant-outline-background` | 公开 | `transparent` | 本组件 CSS<br>`background` |
| `--c-field-variant-outline-border-color` | 公开 | `var(--c-sys-color-border-default)` | 本组件 CSS<br>`border`, `border-color` |
| `--c-field-variant-outline-border-color-disabled` | 公开 | `var(--c-sys-color-border-subtle)` | 本组件 CSS<br>`border-color` |
| `--c-field-variant-outline-border-color-error` | 公开 | `var(--c-sys-color-status-danger)` | 本组件 CSS<br>`border-color` |
| `--c-field-variant-outline-border-color-focus` | 公开 | `var(--c-sys-color-action-primary)` | 本组件 CSS<br>`border-color` |
| `--c-field-variant-outline-border-color-hover` | 公开 | `var(--c-sys-color-border-strong)` | 本组件 CSS<br>`border-color` |
| `--c-field-variant-standard-line-color` | 公开 | `var(--c-field-blur-color)` | 本组件 CSS<br>`border-bottom` |
| `--c-field-variant-standard-line-color-disabled` | 公开 | `var(--c-sys-color-border-subtle)` | 本组件 CSS<br>`border-bottom-color` |
| `--c-field-variant-standard-line-color-error` | 公开 | `var(--c-field-error-color)` | 本组件 CSS<br>`border-bottom-color` |
| `--c-field-variant-standard-line-color-focus` | 公开 | `var(--c-field-focus-color)` | 本组件 CSS<br>`border-bottom-color` |
| `--c-field-variant-standard-line-size` | 公开 | `1px` | 本组件 CSS<br>`border-bottom` |
| `--c-field-variant-standard-line-size-focus` | 公开 | `2px` | 本组件 CSS<br>`border-bottom-width` |
| `--c-search-color-icon` | 公开 | `var(--c-color-text-2)` | 跨组件 CSS<br>`color` |
| `--c-search-size-icon` | 公开 | `14px` | 跨组件 CSS<br>`font-size` |

</div>

## filter-form

声明来源: `src/filter-form/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-filter-form-action-offset` | 公开 | `calc(1em * var(--c-form-line-height) + var(--c-form-vertical-label-margin-bottom))` | 本组件 CSS<br>`padding-top` |
| `--c-filter-form-actions-gap` | 公开 | `var(--c-sys-space-5)` | 本组件 CSS<br>`gap` |
| `--c-filter-form-background-color` | 公开 | `var(--c-sys-color-surface-default)` | 本组件 CSS<br>`background-color` |
| `--c-filter-form-border-color` | 公开 | `var(--c-sys-color-border-subtle)` | 本组件 CSS<br>`border` |
| `--c-filter-form-border-radius` | 公开 | `var(--c-border-radius-md)` | 本组件 CSS<br>`border-radius` |
| `--c-filter-form-border-width` | 公开 | `1px` | 本组件 CSS<br>`border` |
| `--c-filter-form-collapse-color` | 公开 | `var(--c-color-text-2)` | 本组件 CSS<br>`color` |
| `--c-filter-form-collapse-gap` | 公开 | `4px` | 本组件 CSS<br>`gap` |
| `--c-filter-form-collapse-hover-color` | 公开 | `var(--c-sys-color-content-brand)` | 本组件 CSS<br>`color`, `outline` |
| `--c-filter-form-focus-offset` | 公开 | `3px` | 本组件 CSS<br>`outline-offset` |
| `--c-filter-form-focus-width` | 公开 | `2px` | 本组件 CSS<br>`outline` |
| `--c-filter-form-item-margin-bottom` | 公开 | `0px` | 本组件 CSS<br>`margin-bottom` |
| `--c-filter-form-padding` | 公开 | `var(--c-sys-space-7)` | 本组件 CSS<br>`padding` |

</div>

## form

声明来源: `src/form/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-form-error-text-font-size` | 公开 | `var(--c-font-size-body-1)` | 本组件 CSS<br>`font-size` |
| `--c-form-extra-margin-bottom` | 公开 | `var(--c-spacing-2)` | 本组件 CSS<br>`margin-bottom` |
| `--c-form-extra-margin-top` | 公开 | `var(--c-spacing-2)` | 本组件 CSS<br>`margin-top` |
| `--c-form-extra-text-color` | 公开 | `var(--c-sys-color-content-secondary)` | 本组件 CSS<br>`color` |
| `--c-form-extra-text-font-size` | 公开 | `var(--c-font-size-body-1)` | 本组件 CSS<br>`font-size` |
| `--c-form-feedback-icon-font-size` | 公开 | `14px` | 本组件 CSS<br>`font-size` |
| `--c-form-feedback-icon-right` | 公开 | `9px` | 本组件 CSS<br>`right` |
| `--c-form-feedback-loading-font-size` | 公开 | `12px` | 本组件 CSS<br>`font-size` |
| `--c-form-has-feedback-control-padding-right` | 公开 | `28px` | 本组件 CSS<br>`padding-right` |
| `--c-form-inline-item-margin-bottom` | 公开 | `var(--c-spacing-4)` | 本组件 CSS<br>`margin-bottom` |
| `--c-form-inline-item-margin-right` | 公开 | `var(--c-spacing-9)` | 本组件 CSS<br>`margin-right` |
| `--c-form-label-margin-right` | 公开 | `var(--c-spacing-7)` | 本组件 CSS<br>`padding-right` |
| `--c-form-label-text-color` | 公开 | `var(--c-sys-color-content-primary)` | 本组件 CSS<br>`color` |
| `--c-form-line-height` | 公开 | `var(--c-line-height)` | 本组件 CSS<br>`line-height`, `padding-top` |
| `--c-form-required-symbol-color` | 公开 | `var(--c-sys-color-content-danger)` | 本组件 CSS<br>`color` |
| `--c-form-required-symbol-font-size` | 公开 | `var(--c-font-size-body-1)` | 本组件 CSS<br>`font-size` |
| `--c-form-size-lg-height` | 公开 | `var(--c-size-lg)` | 本组件 CSS<br>`line-height`, `min-height` |
| `--c-form-size-lg-item-margin-bottom` | 公开 | `var(--c-spacing-8)` | 本组件 CSS<br>`line-height`, `margin-bottom`, `min-height` |
| `--c-form-size-lg-label-font-size` | 公开 | `var(--c-font-size-body-3)` | 本组件 CSS<br>`font-size` |
| `--c-form-size-md-height` | 公开 | `var(--c-size-md)` | 本组件 CSS<br>`line-height`, `min-height` |
| `--c-form-size-md-item-margin-bottom` | 公开 | `var(--c-spacing-8)` | 本组件 CSS<br>`line-height`, `margin-bottom`, `min-height` |
| `--c-form-size-md-label-font-size` | 公开 | `var(--c-font-size-body-3)` | 本组件 CSS<br>`font-size` |
| `--c-form-size-sm-height` | 公开 | `var(--c-size-sm)` | 本组件 CSS<br>`line-height`, `min-height` |
| `--c-form-size-sm-item-margin-bottom` | 公开 | `var(--c-spacing-8)` | 本组件 CSS<br>`line-height`, `margin-bottom`, `min-height` |
| `--c-form-size-sm-label-font-size` | 公开 | `var(--c-font-size-body-3)` | 本组件 CSS<br>`font-size` |
| `--c-form-size-xl-height` | 公开 | `var(--c-size-xl)` | 本组件 CSS<br>`line-height`, `min-height` |
| `--c-form-size-xl-item-margin-bottom` | 公开 | `var(--c-spacing-8)` | 本组件 CSS<br>`line-height`, `margin-bottom`, `min-height` |
| `--c-form-size-xl-label-font-size` | 公开 | `var(--c-sys-font-size-lg)` | 本组件 CSS<br>`font-size` |
| `--c-form-size-xs-height` | 公开 | `var(--c-size-xs)` | 本组件 CSS<br>`line-height`, `min-height` |
| `--c-form-size-xs-item-margin-bottom` | 公开 | `var(--c-spacing-7)` | 本组件 CSS<br>`line-height`, `margin-bottom`, `min-height` |
| `--c-form-size-xs-label-font-size` | 公开 | `var(--c-font-size-body-1)` | 本组件 CSS<br>`font-size` |
| `--c-form-status-error-bg` | 公开 | `var(--c-color-danger-light-1)` | 本组件 CSS<br>`background-color` |
| `--c-form-status-error-border-color` | 公开 | `transparent` | 本组件 CSS<br>`border-color` |
| `--c-form-status-error-focus-bg` | 公开 | `var(--c-color-bg-2)` | 本组件 CSS<br>`background-color` |
| `--c-form-status-error-focus-border-color` | 公开 | `var(--c-sys-color-content-danger)` | 本组件 CSS<br>`border-color` |
| `--c-form-status-error-focus-shadow-color` | 公开 | `var(--c-color-danger-light-2)` | 本组件 CSS<br>`box-shadow` |
| `--c-form-status-error-focus-shadow-size` | 公开 | `var(--c-shadow-distance-none)` | 本组件 CSS<br>`box-shadow` |
| `--c-form-status-error-hover-bg` | 公开 | `var(--c-color-danger-light-2)` | 本组件 CSS<br>`background-color` |
| `--c-form-status-error-hover-border-color` | 公开 | `transparent` | 本组件 CSS<br>`border-color` |
| `--c-form-status-error-tip-icon-color` | 公开 | `var(--c-sys-color-content-danger)` | 本组件 CSS<br>`color` |
| `--c-form-status-error-tip-text-color` | 公开 | `var(--c-sys-color-content-danger)` | 本组件 CSS<br>`color` |
| `--c-form-status-success-bg` | 公开 | `var(--c-color-fill-2)` | 本组件 CSS<br>`background-color` |
| `--c-form-status-success-border-color` | 公开 | `transparent` | 本组件 CSS<br>`border-color` |
| `--c-form-status-success-focus-bg` | 公开 | `var(--c-color-bg-2)` | 本组件 CSS<br>`background-color` |
| `--c-form-status-success-focus-border-color` | 公开 | `var(--c-sys-color-content-success)` | 本组件 CSS<br>`border-color` |
| `--c-form-status-success-focus-shadow-color` | 公开 | `var(--c-color-success-light-2)` | 本组件 CSS<br>`box-shadow` |
| `--c-form-status-success-focus-shadow-size` | 公开 | `var(--c-shadow-distance-none)` | 本组件 CSS<br>`box-shadow` |
| `--c-form-status-success-hover-bg` | 公开 | `var(--c-color-fill-3)` | 本组件 CSS<br>`background-color` |
| `--c-form-status-success-hover-border-color` | 公开 | `transparent` | 本组件 CSS<br>`border-color` |
| `--c-form-status-success-tip-icon-color` | 公开 | `var(--c-sys-color-content-success)` | 本组件 CSS<br>`color` |
| `--c-form-status-success-tip-text-color` | 公开 | `var(--c-sys-color-content-success)` | 本组件 CSS<br>`color` |
| `--c-form-status-validating-bg` | 公开 | `var(--c-color-fill-2)` | 本组件 CSS<br>`background-color` |
| `--c-form-status-validating-border-color` | 公开 | `transparent` | 本组件 CSS<br>`border-color` |
| `--c-form-status-validating-focus-bg` | 公开 | `var(--c-color-bg-2)` | 本组件 CSS<br>`background-color` |
| `--c-form-status-validating-focus-border-color` | 公开 | `var(--c-sys-color-content-brand)` | 本组件 CSS<br>`border-color` |
| `--c-form-status-validating-focus-shadow-color` | 公开 | `var(--c-color-primary-light-2)` | 本组件 CSS<br>`box-shadow` |
| `--c-form-status-validating-focus-shadow-size` | 公开 | `var(--c-shadow-distance-none)` | 本组件 CSS<br>`box-shadow` |
| `--c-form-status-validating-hover-bg` | 公开 | `var(--c-color-fill-3)` | 本组件 CSS<br>`background-color` |
| `--c-form-status-validating-hover-border-color` | 公开 | `transparent` | 本组件 CSS<br>`border-color` |
| `--c-form-status-validating-tip-icon-color` | 公开 | `var(--c-sys-color-content-brand)` | 本组件 CSS<br>`color` |
| `--c-form-status-validating-tip-text-color` | 公开 | `var(--c-sys-color-content-brand)` | 本组件 CSS<br>`color` |
| `--c-form-status-warning-bg` | 公开 | `var(--c-color-warning-light-1)` | 本组件 CSS<br>`background-color` |
| `--c-form-status-warning-border-color` | 公开 | `transparent` | 本组件 CSS<br>`border-color` |
| `--c-form-status-warning-focus-bg` | 公开 | `var(--c-color-bg-2)` | 本组件 CSS<br>`background-color` |
| `--c-form-status-warning-focus-border-color` | 公开 | `var(--c-sys-color-content-warning)` | 本组件 CSS<br>`border-color` |
| `--c-form-status-warning-focus-shadow-color` | 公开 | `var(--c-color-warning-light-2)` | 本组件 CSS<br>`box-shadow` |
| `--c-form-status-warning-focus-shadow-size` | 公开 | `var(--c-shadow-distance-none)` | 本组件 CSS<br>`box-shadow` |
| `--c-form-status-warning-hover-bg` | 公开 | `var(--c-color-warning-light-2)` | 本组件 CSS<br>`background-color` |
| `--c-form-status-warning-hover-border-color` | 公开 | `transparent` | 本组件 CSS<br>`border-color` |
| `--c-form-status-warning-tip-icon-color` | 公开 | `var(--c-sys-color-content-warning)` | 本组件 CSS<br>`color` |
| `--c-form-status-warning-tip-text-color` | 公开 | `var(--c-sys-color-content-warning)` | 本组件 CSS<br>`color` |
| `--c-form-tooltip-margin-left` | 公开 | `var(--c-sys-space-2)` | 本组件 CSS<br>`margin-inline-start` |
| `--c-form-tooltip-text-color` | 公开 | `var(--c-sys-color-content-secondary)` | 本组件 CSS<br>`color` |
| `--c-form-transition-duration-3` | 公开 | `var(--c-transition-duration-3)` | 本组件 CSS<br>`transition` |
| `--c-form-transition-duration-5` | 公开 | `var(--c-transition-duration-5)` | 本组件 CSS<br>`animation` |
| `--c-form-transition-timing-function-linear` | 公开 | `var(--c-transition-timing-function-linear)` | 本组件 CSS<br>`animation`, `transition` |
| `--c-form-vertical-label-margin-bottom` | 公开 | `var(--c-spacing-4)` | 本组件 CSS<br>`margin-bottom`, `padding-top` |

</div>

## hover

声明来源: `src/hover/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-hover-overlay-focusing-opacity` | 公开 | `0.12` | 本组件 CSS<br>`opacity` |
| `--c-hover-overlay-opacity` | 公开 | `0.04` | 本组件 CSS<br>`opacity` |
| `--c-hover-transition-duration` | 公开 | `var(--c-sys-motion-duration-fast)` | 本组件 CSS<br>`transition` |

</div>

## icon

声明来源: `src/icon/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-icon-size` | 公开 | `inherit` | 本组件 CSS<br>`font-size` |
| `--c-icon-spin-duration` | 公开 | `1s` | 本组件 CSS<br>`animation` |

</div>

## image

声明来源: `src/image/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-image-border-radius` | 公开 | `var(--c-border-radius-sm)` | 本组件 CSS<br>`border-radius` |
| `--c-image-description-footer-inner-text-color` | 公开 | `var(--c-color-white)` | 本组件 CSS<br>`color` |
| `--c-image-description-footer-outer-text-color` | 公开 | `var(--c-color-neutral-6)` | 本组件 CSS<br>`color` |
| `--c-image-error-bg` | 公开 | `var(--c-color-neutral-1)` | 本组件 CSS<br>`background-color` |
| `--c-image-error-text-color` | 公开 | `var(--c-color-neutral-4)` | 本组件 CSS<br>`color` |
| `--c-image-font-size-description` | 公开 | `var(--c-font-size-body-3)` | 本组件 CSS<br>`font-size` |
| `--c-image-font-size-error-icon` | 公开 | `60px` | 本组件 CSS<br>`height`, `width` |
| `--c-image-font-size-error-text` | 公开 | `var(--c-font-size-body-1)` | 本组件 CSS<br>`font-size` |
| `--c-image-font-size-loader-spin` | 公开 | `32px` | 本组件 CSS<br>`font-size` |
| `--c-image-font-size-loader-spin-text` | 公开 | `var(--c-font-size-title-1)` | 本组件 CSS<br>`font-size` |
| `--c-image-font-size-title` | 公开 | `var(--c-font-size-title-1)` | 本组件 CSS<br>`font-size` |
| `--c-image-font-weight-title` | 公开 | `var(--c-font-weight-500)` | 本组件 CSS<br>`font-weight` |
| `--c-image-footer-inner-bg` | 公开 | `linear-gradient(360deg, rgba(0, 0, 0, 0.3) 0%, rgba(0, 0, 0, 0) 100%)` | 本组件 CSS<br>`background` |
| `--c-image-footer-inner-text-color` | 公开 | `var(--c-color-white)` | 本组件 CSS<br>`color` |
| `--c-image-footer-outer-text-color` | 公开 | `var(--c-color-neutral-8)` | 本组件 CSS<br>`color` |
| `--c-image-line-height-error-text` | 公开 | `1.6667` | 本组件 CSS<br>`line-height` |
| `--c-image-loader-bg` | 公开 | `var(--c-color-neutral-1)` | 本组件 CSS<br>`background-color` |
| `--c-image-loader-spin-text-color` | 公开 | `var(--c-sys-color-content-brand)` | 本组件 CSS<br>`color` |
| `--c-image-loader-spin-text-text-color` | 公开 | `var(--c-color-neutral-6)` | 本组件 CSS<br>`color` |
| `--c-image-padding-footer-inner-horizontal` | 公开 | `16px` | 本组件 CSS<br>`padding` |
| `--c-image-padding-footer-inner-vertical` | 公开 | `9px` | 本组件 CSS<br>`padding` |
| `--c-image-preview-arrow-bg` | 公开 | `rgba(255, 255, 255, 0.3)` | 本组件 CSS<br>`background-color` |
| `--c-image-preview-arrow-bg-disabled` | 公开 | `rgba(255, 255, 255, 0.2)` | 本组件 CSS<br>`background-color` |
| `--c-image-preview-arrow-bg-hover` | 公开 | `rgba(255, 255, 255, 0.5)` | 本组件 CSS<br>`background-color` |
| `--c-image-preview-arrow-font-size` | 公开 | `var(--c-size-4)` | 本组件 CSS<br>`font-size` |
| `--c-image-preview-arrow-icon-color` | 公开 | `var(--c-color-white)` | 本组件 CSS<br>`color` |
| `--c-image-preview-arrow-icon-color-disabled` | 公开 | `rgba(255, 255, 255, 0.3)` | 本组件 CSS<br>`color` |
| `--c-image-preview-arrow-position` | 公开 | `var(--c-spacing-8)` | 本组件 CSS<br>`left`, `right` |
| `--c-image-preview-arrow-size` | 公开 | `var(--c-size-8)` | 本组件 CSS<br>`height`, `width` |
| `--c-image-preview-border-radius-action` | 公开 | `var(--c-border-radius-sm)` | 本组件 CSS<br>`border-radius` |
| `--c-image-preview-border-radius-loading` | 公开 | `var(--c-border-radius-md)` | 本组件 CSS<br>`border-radius` |
| `--c-image-preview-border-radius-toolbar` | 公开 | `var(--c-border-radius-md)` | 本组件 CSS<br>`border-radius` |
| `--c-image-preview-color-action-bg` | 公开 | `transparent` | 本组件 CSS<br>`background-color` |
| `--c-image-preview-color-action-disabled-bg` | 公开 | `transparent` | 本组件 CSS<br>`background-color` |
| `--c-image-preview-color-action-disabled-text` | 公开 | `var(--c-color-text-4)` | 本组件 CSS<br>`color` |
| `--c-image-preview-color-action-hover-bg` | 公开 | `var(--c-color-neutral-2)` | 本组件 CSS<br>`background-color` |
| `--c-image-preview-color-action-hover-text` | 公开 | `var(--c-sys-color-content-brand)` | 本组件 CSS<br>`color` |
| `--c-image-preview-color-action-text` | 公开 | `var(--c-color-neutral-8)` | 本组件 CSS<br>`color` |
| `--c-image-preview-color-close-btn-bg` | 公开 | `rgba(0, 0, 0, 0.5)` | 本组件 CSS<br>`background` |
| `--c-image-preview-color-close-btn-text` | 公开 | `var(--c-color-white)` | 本组件 CSS<br>`color` |
| `--c-image-preview-color-loading-bg` | 公开 | `#232324` | 本组件 CSS<br>`background-color` |
| `--c-image-preview-color-loading-text` | 公开 | `var(--c-sys-color-content-brand)` | 本组件 CSS<br>`color` |
| `--c-image-preview-color-scale-value-text` | 公开 | `var(--c-color-white)` | 本组件 CSS<br>`color` |
| `--c-image-preview-color-toolbar-bg` | 公开 | `var(--c-color-bg-2)` | 本组件 CSS<br>`background-color` |
| `--c-image-preview-font-size-action` | 公开 | `14px` | 本组件 CSS<br>`font-size` |
| `--c-image-preview-font-size-loading` | 公开 | `18px` | 本组件 CSS<br>`font-size` |
| `--c-image-preview-margin-action-right` | 公开 | `var(--c-spacing-none)` | 本组件 CSS<br>`margin-right` |
| `--c-image-preview-overlay-bg` | 公开 | `var(--c-color-overlay-bg)` | 跨组件 CSS<br>`background-color` |
| `--c-image-preview-padding-action-content` | 公开 | `13px` | 本组件 CSS<br>`padding` |
| `--c-image-preview-position-close-btn-right` | 公开 | `36px` | 本组件 CSS<br>`right` |
| `--c-image-preview-position-close-btn-top` | 公开 | `36px` | 本组件 CSS<br>`top` |
| `--c-image-preview-position-toolbar-bottom` | 公开 | `46px` | 本组件 CSS<br>`bottom` |
| `--c-image-preview-size-close-btn-width` | 公开 | `32px` | 本组件 CSS<br>`height`, `line-height`, `width` |
| `--c-image-preview-size-close-icon` | 公开 | `14px` | 本组件 CSS<br>`font-size` |
| `--c-image-preview-size-loading-height` | 公开 | `48px` | 本组件 CSS<br>`height` |
| `--c-image-preview-size-loading-width` | 公开 | `48px` | 本组件 CSS<br>`width` |
| `--c-image-preview-spacing-loading-padding` | 公开 | `var(--c-spacing-5)` | 本组件 CSS<br>`padding` |
| `--c-image-preview-spacing-toolbar-horizontal` | 公开 | `var(--c-spacing-7)` | 本组件 CSS<br>`padding` |
| `--c-image-preview-spacing-toolbar-vertical` | 公开 | `var(--c-spacing-2)` | 本组件 CSS<br>`padding` |
| `--c-image-spacing-actions-left` | 公开 | `var(--c-spacing-6)` | 本组件 CSS<br>`padding-left` |
| `--c-image-spacing-error-padding` | 公开 | `var(--c-spacing-7)` | 本组件 CSS<br>`padding` |
| `--c-image-spacing-footer-top` | 公开 | `var(--c-spacing-2)` | 本组件 CSS<br>`margin-top` |
| `--c-image-title-text-color-footer-inner` | 公开 | `var(--c-color-white)` | 本组件 CSS<br>`color` |
| `--c-image-title-text-color-footer-outer` | 公开 | `var(--c-color-text-1)` | 本组件 CSS<br>`color` |

</div>

## infinite-scroll

声明来源: `src/infinite-scroll/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-infinite-scroll-error-color` | 公开 | `var(--c-sys-color-content-danger)` | 本组件 CSS<br>`color` |
| `--c-infinite-scroll-loading-gap` | 公开 | `8px` | 本组件 CSS<br>`gap` |
| `--c-infinite-scroll-status-color` | 公开 | `var(--c-color-text-3)` | 本组件 CSS<br>`color` |
| `--c-infinite-scroll-status-font-size` | 公开 | `var(--c-font-size-md)` | 本组件 CSS<br>`font-size` |
| `--c-infinite-scroll-status-min-height` | 公开 | `50px` | 本组件 CSS<br>`min-height` |
| `--c-infinite-scroll-status-padding` | 公开 | `12px 0` | 本组件 CSS<br>`padding` |

</div>

## input

声明来源: `src/input/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-input-caret-color` | 公开 | `var(--c-field-caret-color)` | 本组件 CSS<br>`caret-color` |
| `--c-input-control-font-size` | 公开 | `inherit` | 本组件 CSS<br>`font-size` |
| `--c-input-control-height` | 公开 | `auto` | 本组件 CSS<br>`height` |
| `--c-input-control-line-height` | 公开 | `inherit` | 本组件 CSS<br>`line-height` |
| `--c-input-control-padding-horizontal` | 公开 | `0` | 本组件 CSS<br>`padding` |
| `--c-input-counter-color` | 公开 | `var(--c-field-suffix-text-color)` | 本组件 CSS<br>`color` |
| `--c-input-counter-font-size` | 公开 | `12px` | 本组件 CSS<br>`font-size` |
| `--c-input-feedback-duration` | 公开 | `1s` | 本组件 CSS<br>`animation` |
| `--c-input-feedback-error-color` | 公开 | `var(--c-sys-color-content-danger)` | 本组件 CSS<br>`color` |
| `--c-input-feedback-success-color` | 公开 | `var(--c-sys-color-content-success)` | 本组件 CSS<br>`color` |
| `--c-input-feedback-validating-color` | 公开 | `var(--c-sys-color-content-brand)` | 本组件 CSS<br>`color` |
| `--c-input-feedback-warning-color` | 公开 | `var(--c-sys-color-content-warning)` | 本组件 CSS<br>`color` |

</div>

## input-number

声明来源: `src/input-number/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-input-number-addon-background` | 公开 | `var(--c-sys-color-surface-muted)` | 本组件 CSS<br>`background` |
| `--c-input-number-addon-border-color` | 公开 | `var(--c-sys-color-border-default)` | 本组件 CSS<br>`border` |
| `--c-input-number-addon-color` | 公开 | `var(--c-sys-color-content-primary)` | 本组件 CSS<br>`color` |
| `--c-input-number-border-radius` | 公开 | `var(--c-field-border-radius)` | 本组件 CSS<br>`border-end-end-radius`, `border-end-start-radius`, `border-start-end-radius`, `border-start-start-radius` |
| `--c-input-number-border-width` | 公开 | `1px` | 本组件 CSS<br>`border`, `border-inline-end`, `border-inline-start`, `border-top`, `outline`, `outline-offset` |
| `--c-input-number-caret-color` | 公开 | `var(--c-field-caret-color)` | 本组件 CSS<br>`caret-color` |
| `--c-input-number-size-lg-step-button-width` | 公开 | `var(--c-sys-control-height-lg)` | 本组件 CSS<br>`width` |
| `--c-input-number-size-md-step-button-width` | 公开 | `var(--c-sys-control-height-md)` | 本组件 CSS<br>`width` |
| `--c-input-number-size-sm-step-button-width` | 公开 | `var(--c-sys-control-height-sm)` | 本组件 CSS<br>`width` |
| `--c-input-number-size-xl-step-button-width` | 公开 | `var(--c-sys-control-height-xl)` | 本组件 CSS<br>`width` |
| `--c-input-number-size-xs-step-button-width` | 公开 | `var(--c-sys-control-height-xs)` | 本组件 CSS<br>`width` |
| `--c-input-number-step-button-active-background` | 公开 | `var(--c-sys-color-state-selected)` | 本组件 CSS<br>`background` |
| `--c-input-number-step-button-background` | 公开 | `var(--c-sys-color-surface-muted)` | 本组件 CSS<br>`background` |
| `--c-input-number-step-button-border-color` | 公开 | `var(--c-sys-color-border-subtle)` | 本组件 CSS<br>`border-inline-end`, `border-inline-start`, `border-top` |
| `--c-input-number-step-button-color` | 公开 | `var(--c-sys-color-content-secondary)` | 本组件 CSS<br>`color` |
| `--c-input-number-step-button-disabled-color` | 公开 | `var(--c-sys-color-content-disabled)` | 本组件 CSS<br>`color` |
| `--c-input-number-step-button-hover-background` | 公开 | `var(--c-sys-color-state-hover)` | 本组件 CSS<br>`background` |
| `--c-input-number-step-button-icon-size` | 公开 | `14px` | 本组件 CSS<br>`font-size` |
| `--c-input-number-step-button-transition-duration` | 公开 | `0.2s` | 本组件 CSS<br>`transition` |
| `--c-input-number-step-button-width` | 公开 | `var(--c-sys-control-height-md)` | 本组件 CSS<br>`width` |

</div>

## input-tag

声明来源: `src/input-tag/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-input-tag-color-text-default` | 公开 | `var(--c-sys-color-content-primary)` | 本组件 CSS<br>`color` |
| `--c-input-tag-color-text-disabled` | 公开 | `var(--c-sys-color-content-disabled)` | 本组件 CSS<br>`color` |
| `--c-input-tag-padding-x` | 公开 | `4px` | 本组件 CSS<br>`padding-left`, `padding-right` |
| `--c-input-tag-size-lg-font-size` | 公开 | `14px` | 本组件 CSS<br>`font-size` |
| `--c-input-tag-size-lg-padding-y` | 公开 | `2px` | 本组件 CSS<br>`padding-bottom`, `padding-top` |
| `--c-input-tag-size-lg-tag-height` | 公开 | `28px` | 本组件 CSS<br>`line-height`, `min-height` |
| `--c-input-tag-size-md-font-size` | 公开 | `14px` | 本组件 CSS<br>`font-size` |
| `--c-input-tag-size-md-padding-y` | 公开 | `2px` | 本组件 CSS<br>`padding-bottom`, `padding-top` |
| `--c-input-tag-size-md-tag-height` | 公开 | `24px` | 本组件 CSS<br>`line-height`, `min-height` |
| `--c-input-tag-size-sm-font-size` | 公开 | `14px` | 本组件 CSS<br>`font-size` |
| `--c-input-tag-size-sm-padding-y` | 公开 | `2px` | 本组件 CSS<br>`padding-bottom`, `padding-top` |
| `--c-input-tag-size-sm-tag-height` | 公开 | `20px` | 本组件 CSS<br>`line-height`, `min-height` |
| `--c-input-tag-size-xl-font-size` | 公开 | `16px` | 本组件 CSS<br>`font-size` |
| `--c-input-tag-size-xl-padding-y` | 公开 | `4px` | 本组件 CSS<br>`padding-bottom`, `padding-top` |
| `--c-input-tag-size-xl-tag-height` | 公开 | `32px` | 本组件 CSS<br>`line-height`, `min-height` |
| `--c-input-tag-size-xs-font-size` | 公开 | `12px` | 本组件 CSS<br>`font-size` |
| `--c-input-tag-size-xs-padding-y` | 公开 | `0px` | 本组件 CSS<br>`padding-bottom`, `padding-top` |
| `--c-input-tag-size-xs-tag-height` | 公开 | `20px` | 本组件 CSS<br>`line-height`, `min-height` |
| `--c-input-tag-tag-color-bg` | 公开 | `var(--c-sys-color-surface-default)` | 本组件 CSS<br>`background-color` |
| `--c-input-tag-tag-color-bg-disabled` | 公开 | `var(--c-sys-color-state-hover)` | 本组件 CSS<br>`background-color` |
| `--c-input-tag-tag-color-bg-focus` | 公开 | `var(--c-sys-color-state-hover)` | 本组件 CSS<br>`background-color` |
| `--c-input-tag-tag-color-border` | 公开 | `var(--c-color-fill-3)` | 本组件 CSS<br>`border-color` |
| `--c-input-tag-tag-color-border-disabled` | 公开 | `var(--c-color-fill-3)` | 本组件 CSS<br>`border-color` |
| `--c-input-tag-tag-color-border-focus` | 公开 | `var(--c-sys-color-state-hover)` | 本组件 CSS<br>`border-color` |
| `--c-input-tag-tag-font-size` | 公开 | `12px` | 本组件 CSS<br>`font-size` |
| `--c-input-tag-tag-margin-right` | 公开 | `4px` | 本组件 CSS<br>`margin-right` |
| `--c-input-tag-tag-margin-y` | 公开 | `2px` | 本组件 CSS<br>`margin-bottom`, `margin-top` |

</div>

## layout

声明来源: `src/layout/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-layout-border-color` | 公开 | `var(--c-color-border-2)` | 本组件 CSS<br>`border-bottom`, `border-left`, `border-right`, `border-top` |
| `--c-layout-focus-color` | 公开 | `var(--c-sys-color-content-brand)` | 本组件 CSS<br>`outline` |
| `--c-layout-font-color` | 公开 | `var(--c-color-text-1)` | 本组件 CSS<br>`color` |
| `--c-layout-font-color-dark` | 公开 | `var(--c-color-white)` | 本组件 CSS<br>`color` |
| `--c-layout-sider-background` | 公开 | `var(--c-color-menu-dark-bg)` | 本组件 CSS<br>`background` |
| `--c-layout-sider-background-light` | 公开 | `var(--c-color-bg-2)` | 本组件 CSS<br>`background` |
| `--c-layout-sider-light-box-shadow` | 公开 | `0 2px 5px 0 rgba(0, 0, 0, 0.08)` | 本组件 CSS<br>`box-shadow` |
| `--c-layout-trigger-dark-color` | 公开 | `rgba(255, 255, 255, 0.2)` | 本组件 CSS<br>`background` |
| `--c-layout-trigger-height` | 公开 | `var(--c-size-12)` | 本组件 CSS<br>`height`, `padding-bottom`, `width` |
| `--c-layout-trigger-light-border-color` | 公开 | `var(--c-color-bg-5)` | 本组件 CSS<br>`border-top` |

</div>

## link

声明来源: `src/link/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-link-bg-active` | 公开 | `var(--c-color-fill-3)` | 本组件 CSS<br>`background-color` |
| `--c-link-bg-hover` | 公开 | `var(--c-color-fill-2)` | 本组件 CSS<br>`background-color` |
| `--c-link-border-radius` | 公开 | `var(--c-sys-radius-sm)` | 本组件 CSS<br>`border-radius` |
| `--c-link-focus-color` | 公开 | `currentColor` | 本组件 CSS<br>`outline` |
| `--c-link-focus-offset` | 公开 | `2px` | 本组件 CSS<br>`outline-offset` |
| `--c-link-focus-opacity` | 公开 | `0.8` | 本组件 CSS<br>`opacity` |
| `--c-link-focus-width` | 公开 | `2px` | 本组件 CSS<br>`outline` |
| `--c-link-font-size` | 公开 | `var(--c-sys-font-size-md)` | 本组件 CSS<br>`font-size` |
| `--c-link-line-height` | 公开 | `var(--c-line-height)` | 本组件 CSS<br>`line-height` |
| `--c-link-margin-icon-right` | 公开 | `var(--c-spacing-3)` | 本组件 CSS<br>`margin-right` |
| `--c-link-padding-horizontal` | 公开 | `var(--c-spacing-2)` | 本组件 CSS<br>`padding` |
| `--c-link-padding-vertical` | 公开 | `1px` | 本组件 CSS<br>`padding` |
| `--c-link-size-icon` | 公开 | `1em` | 本组件 CSS<br>`font-size` |
| `--c-link-size-lg-font-size` | 公开 | `var(--c-sys-font-size-lg)` | 本组件 CSS<br>`font-size` |
| `--c-link-size-md-font-size` | 公开 | `var(--c-link-font-size)` | 本组件 CSS<br>`font-size` |
| `--c-link-size-sm-font-size` | 公开 | `var(--c-sys-font-size-sm)` | 本组件 CSS<br>`font-size` |
| `--c-link-size-xl-font-size` | 公开 | `var(--c-sys-font-size-xl)` | 本组件 CSS<br>`font-size` |
| `--c-link-size-xs-font-size` | 公开 | `var(--c-sys-font-size-xs)` | 本组件 CSS<br>`font-size` |
| `--c-link-spin-duration` | 公开 | `1s` | 本组件 CSS<br>`animation` |
| `--c-link-text-color` | 公开 | `var(--c-sys-color-content-brand)` | 本组件 CSS<br>`color` |
| `--c-link-text-color-active` | 公开 | `var(--c-link-text-color)` | 本组件 CSS<br>`color` |
| `--c-link-text-color-default` | 公开 | `var(--c-sys-color-content-primary)` | 本组件 CSS<br>`color` |
| `--c-link-text-color-disabled` | 公开 | `var(--c-sys-color-content-disabled)` | 本组件 CSS<br>`color` |
| `--c-link-text-color-error` | 公开 | `var(--c-sys-color-content-danger)` | 本组件 CSS<br>`color` |
| `--c-link-text-color-error-active` | 公开 | `var(--c-link-text-color-error)` | 本组件 CSS<br>`color` |
| `--c-link-text-color-error-disabled` | 公开 | `var(--c-sys-color-content-disabled)` | 本组件 CSS<br>`color` |
| `--c-link-text-color-error-hover` | 公开 | `var(--c-link-text-color-error)` | 本组件 CSS<br>`color` |
| `--c-link-text-color-error-loading` | 公开 | `var(--c-sys-color-content-disabled)` | 本组件 CSS<br>`color` |
| `--c-link-text-color-hover` | 公开 | `var(--c-link-text-color)` | 本组件 CSS<br>`color` |
| `--c-link-text-color-info` | 公开 | `var(--c-sys-color-content-info)` | 本组件 CSS<br>`color` |
| `--c-link-text-color-loading` | 公开 | `var(--c-sys-color-content-disabled)` | 本组件 CSS<br>`color` |
| `--c-link-text-color-primary` | 公开 | `var(--c-sys-color-content-brand)` | 本组件 CSS<br>`color` |
| `--c-link-text-color-secondary` | 公开 | `var(--c-sys-color-content-secondary)` | 本组件 CSS<br>`color` |
| `--c-link-text-color-success` | 公开 | `var(--c-sys-color-content-success)` | 本组件 CSS<br>`color` |
| `--c-link-text-color-success-active` | 公开 | `var(--c-link-text-color-success)` | 本组件 CSS<br>`color` |
| `--c-link-text-color-success-disabled` | 公开 | `var(--c-sys-color-content-disabled)` | 本组件 CSS<br>`color` |
| `--c-link-text-color-success-hover` | 公开 | `var(--c-link-text-color-success)` | 本组件 CSS<br>`color` |
| `--c-link-text-color-success-loading` | 公开 | `var(--c-sys-color-content-disabled)` | 本组件 CSS<br>`color` |
| `--c-link-text-color-tertiary` | 公开 | `var(--c-sys-color-content-secondary)` | 本组件 CSS<br>`color` |
| `--c-link-text-color-warning` | 公开 | `var(--c-sys-color-content-warning)` | 本组件 CSS<br>`color` |
| `--c-link-text-color-warning-active` | 公开 | `var(--c-link-text-color-warning)` | 本组件 CSS<br>`color` |
| `--c-link-text-color-warning-disabled` | 公开 | `var(--c-sys-color-content-disabled)` | 本组件 CSS<br>`color` |
| `--c-link-text-color-warning-hover` | 公开 | `var(--c-link-text-color-warning)` | 本组件 CSS<br>`color` |
| `--c-link-text-color-warning-loading` | 公开 | `var(--c-sys-color-content-disabled)` | 本组件 CSS<br>`color` |
| `--c-link-transition-duration` | 公开 | `0.15s` | 本组件 CSS<br>`transition` |

</div>

## list

声明来源: `src/list/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-list-background` | 公开 | `transparent` | 本组件 CSS<br>`background` |
| `--c-list-border-color` | 公开 | `var(--c-color-neutral-3)` | 本组件 CSS<br>`border`, `border-bottom`, `border-top` |
| `--c-list-border-radius` | 公开 | `var(--c-border-radius-md)` | 本组件 CSS<br>`border-radius` |
| `--c-list-border-width` | 公开 | `1px` | 本组件 CSS<br>`border`, `border-bottom`, `border-top` |
| `--c-list-empty-color` | 公开 | `var(--c-list-text-color)` | 本组件 CSS<br>`color` |
| `--c-list-empty-padding` | 公开 | `16px` | 本组件 CSS<br>`padding` |
| `--c-list-font-size` | 公开 | `var(--c-font-size-body-3)` | 本组件 CSS<br>`font-size` |
| `--c-list-font-size-header` | 公开 | `var(--c-font-size-title-1)` | 本组件 CSS<br>`font-size` |
| `--c-list-font-weight-header` | 公开 | `var(--c-font-weight-500)` | 本组件 CSS<br>`font-weight` |
| `--c-list-item-prefix-margin-right` | 公开 | `var(--c-spacing-8)` | 本组件 CSS<br>`margin-right` |
| `--c-list-item-suffix-margin-left` | 公开 | `var(--c-spacing-8)` | 本组件 CSS<br>`margin-left` |
| `--c-list-line-height` | 公开 | `var(--c-line-height)` | 本组件 CSS<br>`line-height` |
| `--c-list-line-height-header` | 公开 | `1.5` | 本组件 CSS<br>`line-height` |
| `--c-list-loading-padding` | 公开 | `0px` | 本组件 CSS<br>`padding` |
| `--c-list-size-lg-padding-horizontal-footer` | 公开 | `var(--c-list-size-lg-padding-horizontal-item)` | 本组件 CSS<br>`padding` |
| `--c-list-size-lg-padding-horizontal-header` | 公开 | `var(--c-spacing-8)` | 本组件 CSS<br>`padding` |
| `--c-list-size-lg-padding-horizontal-item` | 公开 | `var(--c-spacing-8)` | 本组件 CSS<br>`padding` |
| `--c-list-size-lg-padding-vertical-footer` | 公开 | `var(--c-list-size-lg-padding-vertical-item)` | 本组件 CSS<br>`padding` |
| `--c-list-size-lg-padding-vertical-header` | 公开 | `var(--c-spacing-7)` | 本组件 CSS<br>`padding` |
| `--c-list-size-lg-padding-vertical-item` | 公开 | `17px` | 本组件 CSS<br>`padding` |
| `--c-list-size-md-padding-horizontal-footer` | 公开 | `var(--c-list-size-md-padding-horizontal-item)` | 本组件 CSS<br>`padding` |
| `--c-list-size-md-padding-horizontal-header` | 公开 | `var(--c-spacing-8)` | 本组件 CSS<br>`padding` |
| `--c-list-size-md-padding-horizontal-item` | 公开 | `var(--c-spacing-8)` | 本组件 CSS<br>`padding` |
| `--c-list-size-md-padding-vertical-footer` | 公开 | `var(--c-list-size-md-padding-vertical-item)` | 本组件 CSS<br>`padding` |
| `--c-list-size-md-padding-vertical-header` | 公开 | `var(--c-spacing-6)` | 本组件 CSS<br>`padding` |
| `--c-list-size-md-padding-vertical-item` | 公开 | `13px` | 本组件 CSS<br>`padding` |
| `--c-list-size-sm-padding-horizontal-footer` | 公开 | `var(--c-list-size-sm-padding-horizontal-item)` | 本组件 CSS<br>`padding` |
| `--c-list-size-sm-padding-horizontal-header` | 公开 | `var(--c-spacing-8)` | 本组件 CSS<br>`padding` |
| `--c-list-size-sm-padding-horizontal-item` | 公开 | `var(--c-spacing-8)` | 本组件 CSS<br>`padding` |
| `--c-list-size-sm-padding-vertical-footer` | 公开 | `var(--c-list-size-sm-padding-vertical-item)` | 本组件 CSS<br>`padding` |
| `--c-list-size-sm-padding-vertical-header` | 公开 | `var(--c-spacing-4)` | 本组件 CSS<br>`padding` |
| `--c-list-size-sm-padding-vertical-item` | 公开 | `9px` | 本组件 CSS<br>`padding` |
| `--c-list-text-color` | 公开 | `var(--c-color-text-1)` | 本组件 CSS<br>`color` |
| `--c-list-text-color-header` | 公开 | `var(--c-color-text-1)` | 本组件 CSS<br>`color` |

</div>

## loading

声明来源: `src/loading/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-loading-color` | 公开 | `rgb(var(--c-primary-6))` | 本组件 CSS<br>`background-color`, `color` |
| `--c-loading-directive-z-index` | 公开 | `2000` | 本组件 CSS<br>`z-index` |
| `--c-loading-indicator-size` | 公开 | `20px` | 本组件 CSS<br>`font-size` |
| `--c-loading-opacity` | 公开 | `0.38` | 本组件 CSS<br>`opacity` |
| `--c-loading-overlay-background` | 公开 | `color-mix(in srgb, var(--c-color-bg-white) 62%, transparent)` | 本组件 CSS<br>`background` |
| `--c-loading-tip-color` | 公开 | `var(--c-sys-color-content-brand)` | 本组件 CSS<br>`color` |
| `--c-loading-tip-font-weight` | 公开 | `var(--c-font-weight-500)` | 本组件 CSS<br>`font-weight` |
| `--c-loading-tip-margin` | 公开 | `var(--c-spacing-3) 0 0` | 本组件 CSS<br>`margin` |

</div>

## map

声明来源: `src/map/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-map-locate-me-bg` | 公开 | `var(--c-color-bg-white)` | 本组件 CSS<br>`background` |
| `--c-map-locate-me-bottom` | 公开 | `var(--c-spacing-10)` | 本组件 CSS<br>`bottom` |
| `--c-map-locate-me-icon-size` | 公开 | `18px` | 本组件 CSS<br>`height`, `width` |
| `--c-map-locate-me-left` | 公开 | `var(--c-spacing-6)` | 本组件 CSS<br>`left` |
| `--c-map-locate-me-shadow-blur` | 公开 | `var(--c-spacing-2)` | 本组件 CSS<br>`box-shadow` |
| `--c-map-locate-me-shadow-color` | 公开 | `rgb(var(--c-gray-10))` | 本组件 CSS<br>`box-shadow` |
| `--c-map-locate-me-size` | 公开 | `var(--c-size-6)` | 本组件 CSS<br>`height`, `width` |
| `--c-map-poi-address-color` | 公开 | `var(--c-color-text-3)` | 本组件 CSS<br>`color`, `stroke` |
| `--c-map-poi-address-font-size` | 公开 | `var(--c-font-size-body-1)` | 本组件 CSS<br>`font-size` |
| `--c-map-poi-bg` | 公开 | `rgb(var(--c-gray-10))` | 本组件 CSS<br>`background-color` |
| `--c-map-poi-border-radius` | 公开 | `var(--c-size-25)` | 本组件 CSS<br>`border-radius` |
| `--c-map-poi-edit-margin-left` | 公开 | `var(--c-spacing-2)` | 本组件 CSS<br>`margin-left` |
| `--c-map-poi-name-color` | 公开 | `var(--c-color-white)` | 本组件 CSS<br>`color` |
| `--c-map-poi-name-font-size` | 公开 | `var(--c-font-size-body-3)` | 本组件 CSS<br>`font-size` |
| `--c-map-poi-padding-x` | 公开 | `var(--c-spacing-9)` | 本组件 CSS<br>`padding` |
| `--c-map-poi-padding-y` | 公开 | `var(--c-spacing-5)` | 本组件 CSS<br>`padding` |
| `--c-map-poi-translate-y` | 公开 | `-7px` | 本组件 CSS<br>`transform` |
| `--c-map-position-current-right` | 公开 | `var(--c-size-10)` | 本组件 CSS<br>`right` |
| `--c-map-position-current-size` | 公开 | `var(--c-size-6)` | 本组件 CSS<br>`height`, `width` |
| `--c-map-position-current-top` | 公开 | `var(--c-size-25)` | 本组件 CSS<br>`top` |
| `--c-map-position-dot-margin-left` | 公开 | `calc(-1 * var(--c-spacing-6))` | 本组件 CSS<br>`margin-left` |
| `--c-map-position-dot-margin-top` | 公开 | `calc(-1 * var(--c-size-6))` | 本组件 CSS<br>`margin-top` |
| `--c-map-position-dot-size` | 公开 | `var(--c-size-6)` | 本组件 CSS<br>`height`, `width` |
| `--c-map-search-box-padding-x` | 公开 | `var(--c-spacing-6)` | 本组件 CSS<br>`padding` |
| `--c-map-search-box-padding-y` | 公开 | `7px` | 本组件 CSS<br>`padding` |
| `--c-map-search-empty-padding` | 公开 | `var(--c-spacing-8)` | 本组件 CSS<br>`padding` |
| `--c-map-search-item-address-color` | 公开 | `var(--c-color-text-3)` | 本组件 CSS<br>`color` |
| `--c-map-search-item-name-color` | 公开 | `var(--c-color-text-1)` | 本组件 CSS<br>`color` |
| `--c-map-search-item-padding-x` | 公开 | `var(--c-spacing-6)` | 本组件 CSS<br>`padding` |
| `--c-map-search-item-padding-y` | 公开 | `var(--c-spacing-4)` | 本组件 CSS<br>`padding` |
| `--c-map-search-item-selected-bg` | 公开 | `var(--c-color-fill-1)` | 本组件 CSS<br>`background-color` |
| `--c-map-search-margin` | 公开 | `var(--c-spacing-9)` | 本组件 CSS<br>`margin` |
| `--c-map-search-width` | 公开 | `230px` | 本组件 CSS<br>`width` |
| `--c-map-tips-color` | 公开 | `var(--c-color-text-3)` | 本组件 CSS<br>`color` |
| `--c-map-tips-padding-y` | 公开 | `var(--c-spacing-5)` | 本组件 CSS<br>`padding` |

</div>

## mention

声明来源: `src/mention/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |

</div>

## menu

声明来源: `src/menu/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-menu-bg` | 公开 | `var(--c-color-bg-popup)` | 本组件 CSS<br>`background-color` |
| `--c-menu-border-color` | 公开 | `var(--c-color-fill-3)` | 本组件 CSS<br>`background-color`, `border`, `border-top` |
| `--c-menu-border-radius` | 公开 | `var(--c-border-radius-md)` | 本组件 CSS<br>`border-radius` |
| `--c-menu-box-shadow` | 公开 | `var(--c-shadow2-down)` | 本组件 CSS<br>`box-shadow` |
| `--c-menu-font-size` | 公开 | `var(--c-font-size-body-3)` | 本组件 CSS<br>`font-size` |
| `--c-menu-group-title-font-size` | 公开 | `var(--c-font-size-body-1)` | 本组件 CSS<br>`font-size` |
| `--c-menu-group-title-height` | 公开 | `var(--c-size-5)` | 本组件 CSS<br>`line-height` |
| `--c-menu-group-title-margin-top` | 公开 | `var(--c-spacing-4)` | 本组件 CSS<br>`margin-top` |
| `--c-menu-group-title-padding-horizontal` | 公开 | `var(--c-spacing-6)` | 本组件 CSS<br>`padding` |
| `--c-menu-group-title-text-color` | 公开 | `var(--c-color-text-3)` | 本组件 CSS<br>`color` |
| `--c-menu-max-height` | 公开 | `var(--c-size-50)` | 本组件 CSS<br>`max-height` |
| `--c-menu-option-bg` | 公开 | `transparent` | 本组件 CSS<br>`background-color` |
| `--c-menu-option-bg-disabled` | 公开 | `transparent` | 本组件 CSS<br>`background-color` |
| `--c-menu-option-bg-hover` | 公开 | `var(--c-color-fill-2)` | 本组件 CSS<br>`background-color` |
| `--c-menu-option-bg-selected` | 公开 | `var(--c-color-fill-2)` | 本组件 CSS<br>`background-color` |
| `--c-menu-option-bg-selected-hover` | 公开 | `var(--c-menu-option-bg-selected)` | 本组件 CSS<br>`background-color` |
| `--c-menu-option-font-weight-selected` | 公开 | `var(--c-font-weight-500)` | 本组件 CSS<br>`font-weight` |
| `--c-menu-option-height` | 公开 | `var(--c-size-9)` | 本组件 CSS<br>`line-height` |
| `--c-menu-option-icon-margin-right` | 公开 | `var(--c-spacing-4)` | 本组件 CSS<br>`margin-right` |
| `--c-menu-option-padding-horizontal` | 公开 | `var(--c-spacing-6)` | 本组件 CSS<br>`padding` |
| `--c-menu-option-suffix-icon-margin-left` | 公开 | `var(--c-spacing-6)` | 本组件 CSS<br>`margin-left` |
| `--c-menu-option-text-color` | 公开 | `var(--c-color-text-2)` | 本组件 CSS<br>`color` |
| `--c-menu-option-text-color-disabled` | 公开 | `var(--c-color-text-4)` | 本组件 CSS<br>`color` |
| `--c-menu-option-text-color-hover` | 公开 | `var(--c-color-text-1)` | 本组件 CSS<br>`color` |
| `--c-menu-option-text-color-selected` | 公开 | `var(--c-color-text-1)` | 本组件 CSS<br>`color` |
| `--c-menu-padding-vertical` | 公开 | `var(--c-spacing-2)` | 本组件 CSS<br>`margin`, `margin-top`, `padding` |

</div>

## message

声明来源: `src/message/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-message-border-radius` | 公开 | `var(--c-border-radius-sm)` | 本组件 CSS<br>`border-radius` |
| `--c-message-border-style` | 公开 | `solid` | 本组件 CSS<br>`border` |
| `--c-message-border-width` | 公开 | `1px` | 本组件 CSS<br>`border` |
| `--c-message-box-shadow` | 公开 | `var(--c-shadow2-down)` | 本组件 CSS<br>`box-shadow` |
| `--c-message-close-btn-margin-left` | 公开 | `var(--c-spacing-4)` | 本组件 CSS<br>`margin-left` |
| `--c-message-close-icon-font-size` | 公开 | `12px` | 本组件 CSS<br>`font-size` |
| `--c-message-close-icon-hover-opacity` | 公开 | `0.08` | 本组件 CSS<br>`opacity` |
| `--c-message-close-icon-hover-size` | 公开 | `20px` | 本组件 CSS<br>`height`, `width` |
| `--c-message-content-font-size` | 公开 | `var(--c-font-size-body-3)` | 本组件 CSS<br>`font-size` |
| `--c-message-icon-font-size` | 公开 | `20px` | 本组件 CSS<br>`font-size` |
| `--c-message-icon-margin-right` | 公开 | `var(--c-spacing-4)` | 本组件 CSS<br>`margin-left`, `margin-right` |
| `--c-message-margin-bottom` | 公开 | `var(--c-spacing-7)` | 本组件 CSS<br>`margin-bottom` |
| `--c-message-neutral-danger-bg` | 公开 | `var(--c-sys-color-surface-overlay)` | 本组件 CSS<br>`background-color` |
| `--c-message-neutral-danger-border-color` | 公开 | `var(--c-sys-color-border-default)` | 本组件 CSS<br>`border-color` |
| `--c-message-neutral-danger-close-color` | 公开 | `var(--c-sys-color-content-secondary)` | 本组件 CSS<br>`color` |
| `--c-message-neutral-danger-content-color` | 公开 | `var(--c-sys-color-content-primary)` | 本组件 CSS<br>`color` |
| `--c-message-neutral-danger-icon-color` | 公开 | `var(--c-sys-color-content-danger)` | 本组件 CSS<br>`color` |
| `--c-message-neutral-default-bg` | 公开 | `var(--c-sys-color-surface-overlay)` | 本组件 CSS<br>`background-color` |
| `--c-message-neutral-default-border-color` | 公开 | `var(--c-sys-color-border-default)` | 本组件 CSS<br>`border-color` |
| `--c-message-neutral-default-close-color` | 公开 | `var(--c-sys-color-content-secondary)` | 本组件 CSS<br>`color` |
| `--c-message-neutral-default-content-color` | 公开 | `var(--c-sys-color-content-primary)` | 本组件 CSS<br>`color` |
| `--c-message-neutral-default-icon-color` | 公开 | `var(--c-sys-color-content-primary)` | 本组件 CSS<br>`color` |
| `--c-message-neutral-info-bg` | 公开 | `var(--c-sys-color-surface-overlay)` | 本组件 CSS<br>`background-color` |
| `--c-message-neutral-info-border-color` | 公开 | `var(--c-sys-color-border-default)` | 本组件 CSS<br>`border-color` |
| `--c-message-neutral-info-close-color` | 公开 | `var(--c-sys-color-content-secondary)` | 本组件 CSS<br>`color` |
| `--c-message-neutral-info-content-color` | 公开 | `var(--c-sys-color-content-primary)` | 本组件 CSS<br>`color` |
| `--c-message-neutral-info-icon-color` | 公开 | `var(--c-sys-color-content-info)` | 本组件 CSS<br>`color` |
| `--c-message-neutral-loading-bg` | 公开 | `var(--c-sys-color-surface-overlay)` | 本组件 CSS<br>`background-color` |
| `--c-message-neutral-loading-border-color` | 公开 | `var(--c-sys-color-border-default)` | 本组件 CSS<br>`border-color` |
| `--c-message-neutral-loading-close-color` | 公开 | `var(--c-sys-color-content-secondary)` | 本组件 CSS<br>`color` |
| `--c-message-neutral-loading-content-color` | 公开 | `var(--c-sys-color-content-primary)` | 本组件 CSS<br>`color` |
| `--c-message-neutral-loading-icon-color` | 公开 | `var(--c-sys-color-content-brand)` | 本组件 CSS<br>`color` |
| `--c-message-neutral-success-bg` | 公开 | `var(--c-sys-color-surface-overlay)` | 本组件 CSS<br>`background-color` |
| `--c-message-neutral-success-border-color` | 公开 | `var(--c-sys-color-border-default)` | 本组件 CSS<br>`border-color` |
| `--c-message-neutral-success-close-color` | 公开 | `var(--c-sys-color-content-secondary)` | 本组件 CSS<br>`color` |
| `--c-message-neutral-success-content-color` | 公开 | `var(--c-sys-color-content-primary)` | 本组件 CSS<br>`color` |
| `--c-message-neutral-success-icon-color` | 公开 | `var(--c-sys-color-content-success)` | 本组件 CSS<br>`color` |
| `--c-message-neutral-warning-bg` | 公开 | `var(--c-sys-color-surface-overlay)` | 本组件 CSS<br>`background-color` |
| `--c-message-neutral-warning-border-color` | 公开 | `var(--c-sys-color-border-default)` | 本组件 CSS<br>`border-color` |
| `--c-message-neutral-warning-close-color` | 公开 | `var(--c-sys-color-content-secondary)` | 本组件 CSS<br>`color` |
| `--c-message-neutral-warning-content-color` | 公开 | `var(--c-sys-color-content-primary)` | 本组件 CSS<br>`color` |
| `--c-message-neutral-warning-icon-color` | 公开 | `var(--c-sys-color-content-warning)` | 本组件 CSS<br>`color` |
| `--c-message-padding-bottom` | 公开 | `var(--c-spacing-5)` | 本组件 CSS<br>`padding` |
| `--c-message-padding-left` | 公开 | `var(--c-spacing-7)` | 本组件 CSS<br>`padding` |
| `--c-message-padding-right` | 公开 | `var(--c-spacing-7)` | 本组件 CSS<br>`padding` |
| `--c-message-padding-top` | 公开 | `var(--c-spacing-5)` | 本组件 CSS<br>`padding` |
| `--c-message-solid-danger-bg` | 公开 | `var(--c-sys-color-status-danger)` | 本组件 CSS<br>`background-color` |
| `--c-message-solid-danger-border-color` | 公开 | `transparent` | 本组件 CSS<br>`border-color` |
| `--c-message-solid-danger-close-color` | 公开 | `var(--c-sys-color-content-on-bright)` | 本组件 CSS<br>`color` |
| `--c-message-solid-danger-content-color` | 公开 | `var(--c-sys-color-content-on-bright)` | 本组件 CSS<br>`color` |
| `--c-message-solid-danger-icon-color` | 公开 | `var(--c-sys-color-content-on-bright)` | 本组件 CSS<br>`color` |
| `--c-message-solid-default-bg` | 公开 | `#333` | 本组件 CSS<br>`background-color` |
| `--c-message-solid-default-border-color` | 公开 | `transparent` | 本组件 CSS<br>`border-color` |
| `--c-message-solid-default-close-color` | 公开 | `var(--c-sys-color-content-on-dark)` | 本组件 CSS<br>`color` |
| `--c-message-solid-default-content-color` | 公开 | `var(--c-sys-color-content-on-dark)` | 本组件 CSS<br>`color` |
| `--c-message-solid-default-icon-color` | 公开 | `var(--c-sys-color-content-on-dark)` | 本组件 CSS<br>`color` |
| `--c-message-solid-info-bg` | 公开 | `var(--c-sys-color-status-info)` | 本组件 CSS<br>`background-color` |
| `--c-message-solid-info-border-color` | 公开 | `transparent` | 本组件 CSS<br>`border-color` |
| `--c-message-solid-info-close-color` | 公开 | `var(--c-sys-color-content-on-bright)` | 本组件 CSS<br>`color` |
| `--c-message-solid-info-content-color` | 公开 | `var(--c-sys-color-content-on-bright)` | 本组件 CSS<br>`color` |
| `--c-message-solid-info-icon-color` | 公开 | `var(--c-sys-color-content-on-bright)` | 本组件 CSS<br>`color` |
| `--c-message-solid-loading-bg` | 公开 | `#333` | 本组件 CSS<br>`background-color` |
| `--c-message-solid-loading-border-color` | 公开 | `transparent` | 本组件 CSS<br>`border-color` |
| `--c-message-solid-loading-close-color` | 公开 | `var(--c-sys-color-content-on-dark)` | 本组件 CSS<br>`color` |
| `--c-message-solid-loading-content-color` | 公开 | `var(--c-sys-color-content-on-dark)` | 本组件 CSS<br>`color` |
| `--c-message-solid-loading-icon-color` | 公开 | `var(--c-sys-color-content-on-dark)` | 本组件 CSS<br>`color` |
| `--c-message-solid-success-bg` | 公开 | `var(--c-sys-color-status-success)` | 本组件 CSS<br>`background-color` |
| `--c-message-solid-success-border-color` | 公开 | `transparent` | 本组件 CSS<br>`border-color` |
| `--c-message-solid-success-close-color` | 公开 | `var(--c-sys-color-content-on-bright)` | 本组件 CSS<br>`color` |
| `--c-message-solid-success-content-color` | 公开 | `var(--c-sys-color-content-on-bright)` | 本组件 CSS<br>`color` |
| `--c-message-solid-success-icon-color` | 公开 | `var(--c-sys-color-content-on-bright)` | 本组件 CSS<br>`color` |
| `--c-message-solid-warning-bg` | 公开 | `var(--c-sys-color-status-warning)` | 本组件 CSS<br>`background-color` |
| `--c-message-solid-warning-border-color` | 公开 | `transparent` | 本组件 CSS<br>`border-color` |
| `--c-message-solid-warning-close-color` | 公开 | `var(--c-sys-color-content-on-bright)` | 本组件 CSS<br>`color` |
| `--c-message-solid-warning-content-color` | 公开 | `var(--c-sys-color-content-on-bright)` | 本组件 CSS<br>`color` |
| `--c-message-solid-warning-icon-color` | 公开 | `var(--c-sys-color-content-on-bright)` | 本组件 CSS<br>`color` |
| `--c-message-tonal-danger-bg` | 公开 | `var(--c-color-danger-light-1)` | 本组件 CSS<br>`background-color` |
| `--c-message-tonal-danger-border-color` | 公开 | `transparent` | 本组件 CSS<br>`border-color` |
| `--c-message-tonal-danger-close-color` | 公开 | `var(--c-sys-color-content-primary)` | 本组件 CSS<br>`color` |
| `--c-message-tonal-danger-content-color` | 公开 | `var(--c-sys-color-content-primary)` | 本组件 CSS<br>`color` |
| `--c-message-tonal-danger-icon-color` | 公开 | `var(--c-sys-color-content-danger)` | 本组件 CSS<br>`color` |
| `--c-message-tonal-default-bg` | 公开 | `var(--c-sys-color-surface-muted)` | 本组件 CSS<br>`background-color` |
| `--c-message-tonal-default-border-color` | 公开 | `transparent` | 本组件 CSS<br>`border-color` |
| `--c-message-tonal-default-close-color` | 公开 | `var(--c-sys-color-content-primary)` | 本组件 CSS<br>`color` |
| `--c-message-tonal-default-content-color` | 公开 | `var(--c-sys-color-content-primary)` | 本组件 CSS<br>`color` |
| `--c-message-tonal-default-icon-color` | 公开 | `var(--c-sys-color-content-primary)` | 本组件 CSS<br>`color` |
| `--c-message-tonal-info-bg` | 公开 | `rgba(var(--c-blue-6), 0.12)` | 本组件 CSS<br>`background-color` |
| `--c-message-tonal-info-border-color` | 公开 | `transparent` | 本组件 CSS<br>`border-color` |
| `--c-message-tonal-info-close-color` | 公开 | `var(--c-sys-color-content-primary)` | 本组件 CSS<br>`color` |
| `--c-message-tonal-info-content-color` | 公开 | `var(--c-sys-color-content-primary)` | 本组件 CSS<br>`color` |
| `--c-message-tonal-info-icon-color` | 公开 | `var(--c-sys-color-content-info)` | 本组件 CSS<br>`color` |
| `--c-message-tonal-loading-bg` | 公开 | `var(--c-color-primary-light-1)` | 本组件 CSS<br>`background-color` |
| `--c-message-tonal-loading-border-color` | 公开 | `transparent` | 本组件 CSS<br>`border-color` |
| `--c-message-tonal-loading-close-color` | 公开 | `var(--c-sys-color-content-primary)` | 本组件 CSS<br>`color` |
| `--c-message-tonal-loading-content-color` | 公开 | `var(--c-sys-color-content-primary)` | 本组件 CSS<br>`color` |
| `--c-message-tonal-loading-icon-color` | 公开 | `var(--c-sys-color-content-brand)` | 本组件 CSS<br>`color` |
| `--c-message-tonal-success-bg` | 公开 | `var(--c-color-success-light-1)` | 本组件 CSS<br>`background-color` |
| `--c-message-tonal-success-border-color` | 公开 | `transparent` | 本组件 CSS<br>`border-color` |
| `--c-message-tonal-success-close-color` | 公开 | `var(--c-sys-color-content-primary)` | 本组件 CSS<br>`color` |
| `--c-message-tonal-success-content-color` | 公开 | `var(--c-sys-color-content-primary)` | 本组件 CSS<br>`color` |
| `--c-message-tonal-success-icon-color` | 公开 | `var(--c-sys-color-content-success)` | 本组件 CSS<br>`color` |
| `--c-message-tonal-warning-bg` | 公开 | `var(--c-color-warning-light-1)` | 本组件 CSS<br>`background-color` |
| `--c-message-tonal-warning-border-color` | 公开 | `transparent` | 本组件 CSS<br>`border-color` |
| `--c-message-tonal-warning-close-color` | 公开 | `var(--c-sys-color-content-primary)` | 本组件 CSS<br>`color` |
| `--c-message-tonal-warning-content-color` | 公开 | `var(--c-sys-color-content-primary)` | 本组件 CSS<br>`color` |
| `--c-message-tonal-warning-icon-color` | 公开 | `var(--c-sys-color-content-warning)` | 本组件 CSS<br>`color` |
| `--c-message-transition-duration` | 公开 | `var(--c-transition-duration-1)` | 本组件 CSS<br>`animation`, `transition` |
| `--c-message-transition-duration-icon` | 公开 | `var(--c-transition-duration-4)` | 本组件 CSS<br>`animation` |
| `--c-message-transition-timing-function` | 公开 | `var(--c-transition-timing-function-linear)` | 本组件 CSS<br>`animation`, `transition` |
| `--c-message-transition-timing-function-icon` | 公开 | `var(--c-transition-timing-function-overshoot)` | 本组件 CSS<br>`animation` |
| `--c-message-wrapper-margin-bottom` | 公开 | `var(--c-spacing-12)` | 本组件 CSS<br>`bottom` |
| `--c-message-wrapper-margin-top` | 公开 | `var(--c-spacing-12)` | 本组件 CSS<br>`top` |
| `--c-message-wrapper-padding-horizontal` | 公开 | `var(--c-spacing-5)` | 本组件 CSS<br>`padding` |
| `--c-message-z-index` | 公开 | `var(--c-z-index-message)` | 本组件 CSS<br>`z-index` |

</div>

## nav-menu

声明来源: `src/nav-menu/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-nav-menu-arrow-size` | 公开 | `12px` | 本组件 CSS<br>`width` |
| `--c-nav-menu-border-radius` | 公开 | `var(--c-border-radius-sm)` | 本组件 CSS<br>`border-radius` |
| `--c-nav-menu-content-gap` | 公开 | `8px` | 本组件 CSS<br>`gap`, `margin`, `padding` |
| `--c-nav-menu-content-padding` | 公开 | `12px` | 本组件 CSS<br>`padding` |
| `--c-nav-menu-dark-bg` | 公开 | `var(--c-color-menu-dark-bg)` | 本组件 CSS<br>`background` |
| `--c-nav-menu-dark-item-bg-hover` | 公开 | `var(--c-color-menu-dark-hover)` | 本组件 CSS<br>`background` |
| `--c-nav-menu-dark-item-bg-selected` | 公开 | `var(--c-color-menu-dark-hover)` | 本组件 CSS<br>`background` |
| `--c-nav-menu-dark-item-text-color` | 公开 | `var(--c-color-text-4)` | 本组件 CSS<br>`color` |
| `--c-nav-menu-dark-item-text-color-disabled` | 公开 | `var(--c-color-text-2)` | 本组件 CSS<br>`color` |
| `--c-nav-menu-dark-item-text-color-selected` | 公开 | `var(--c-color-white)` | 本组件 CSS<br>`color`, `outline` |
| `--c-nav-menu-divider-color` | 公开 | `var(--c-color-border-2)` | 本组件 CSS<br>`background`, `border` |
| `--c-nav-menu-divider-width` | 公开 | `1px` | 本组件 CSS<br>`border`, `height`, `width` |
| `--c-nav-menu-focus-offset` | 公开 | `-2px` | 本组件 CSS<br>`outline-offset` |
| `--c-nav-menu-focus-width` | 公开 | `2px` | 本组件 CSS<br>`outline` |
| `--c-nav-menu-font-size` | 公开 | `var(--c-font-size-body-3)` | 本组件 CSS<br>`font-size` |
| `--c-nav-menu-icon-size` | 公开 | `20px` | 本组件 CSS<br>`font-size` |
| `--c-nav-menu-light-bg` | 公开 | `var(--c-color-bg-2)` | 本组件 CSS<br>`background` |
| `--c-nav-menu-light-item-bg-hover` | 公开 | `var(--c-color-fill-2)` | 本组件 CSS<br>`background` |
| `--c-nav-menu-light-item-bg-selected` | 公开 | `var(--c-color-fill-2)` | 本组件 CSS<br>`background` |
| `--c-nav-menu-light-item-text-color` | 公开 | `var(--c-color-text-2)` | 本组件 CSS<br>`color` |
| `--c-nav-menu-light-item-text-color-disabled` | 公开 | `var(--c-color-text-4)` | 本组件 CSS<br>`color` |
| `--c-nav-menu-light-item-text-color-selected` | 公开 | `var(--c-sys-color-content-brand)` | 本组件 CSS<br>`color`, `outline` |
| `--c-nav-menu-motion-duration` | 公开 | `150ms` | 本组件 CSS<br>`transition` |
| `--c-nav-menu-panel-width` | 公开 | `min(400px, 100vw)` | 运行时引用（不代表可见性证明）<br>`nav-menu/item.tsx` |
| `--c-nav-menu-popup-max-height` | 公开 | `320px` | 本组件 CSS<br>`max-height` |
| `--c-nav-menu-popup-min-width` | 公开 | `180px` | 本组件 CSS<br>`min-width` |
| `--c-nav-menu-popup-shadow` | 公开 | `0 6px 24px rgba(0, 0, 0, 0.12)` | 本组件 CSS<br>`box-shadow` |
| `--c-nav-menu-row-height` | 公开 | `40px` | 本组件 CSS<br>`min-height` |
| `--c-nav-menu-row-height-lg` | 公开 | `48px` | 本组件 CSS<br>`min-height` |
| `--c-nav-menu-row-height-sm` | 公开 | `32px` | 本组件 CSS<br>`min-height` |
| `--c-nav-menu-row-height-xl` | 公开 | `56px` | 本组件 CSS<br>`min-height` |
| `--c-nav-menu-row-height-xs` | 公开 | `28px` | 本组件 CSS<br>`min-height` |

</div>

## notification

声明来源: `src/notification/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-notification-border-radius` | 公开 | `var(--c-border-radius-md)` | 本组件 CSS<br>`border-radius` |
| `--c-notification-border-style` | 公开 | `solid` | 本组件 CSS<br>`border` |
| `--c-notification-border-width` | 公开 | `1px` | 本组件 CSS<br>`border` |
| `--c-notification-box-shadow` | 公开 | `0 4px 12px rgba(0, 0, 0, 0.15)` | 本组件 CSS<br>`box-shadow` |
| `--c-notification-close-icon-color` | 公开 | `var(--c-sys-color-content-secondary)` | 本组件 CSS<br>`color` |
| `--c-notification-close-icon-font-size` | 公开 | `12px` | 本组件 CSS<br>`font-size` |
| `--c-notification-close-icon-hover-size` | 公开 | `20px` | 本组件 CSS<br>`height`, `width` |
| `--c-notification-close-icon-right` | 公开 | `var(--c-spacing-6)` | 本组件 CSS<br>`right` |
| `--c-notification-close-icon-top` | 公开 | `var(--c-spacing-6)` | 本组件 CSS<br>`top` |
| `--c-notification-content-font-size` | 公开 | `var(--c-font-size-body-3)` | 本组件 CSS<br>`font-size` |
| `--c-notification-error-bg` | 公开 | `var(--c-sys-color-surface-overlay)` | 本组件 CSS<br>`background-color` |
| `--c-notification-error-border-color` | 公开 | `var(--c-sys-color-border-default)` | 本组件 CSS<br>`border-color` |
| `--c-notification-error-content-color` | 公开 | `var(--c-sys-color-content-primary)` | 本组件 CSS<br>`color` |
| `--c-notification-error-icon-color` | 公开 | `var(--c-sys-color-content-danger)` | 本组件 CSS<br>`color` |
| `--c-notification-error-title-color` | 公开 | `var(--c-sys-color-content-primary)` | 本组件 CSS<br>`color` |
| `--c-notification-footer-margin-top` | 公开 | `var(--c-spacing-7)` | 本组件 CSS<br>`margin-top` |
| `--c-notification-icon-font-size` | 公开 | `24px` | 本组件 CSS<br>`font-size` |
| `--c-notification-icon-margin-right` | 公开 | `var(--c-spacing-7)` | 本组件 CSS<br>`padding-right` |
| `--c-notification-info-bg` | 公开 | `var(--c-sys-color-surface-overlay)` | 本组件 CSS<br>`background-color` |
| `--c-notification-info-border-color` | 公开 | `var(--c-sys-color-border-default)` | 本组件 CSS<br>`border-color` |
| `--c-notification-info-content-color` | 公开 | `var(--c-sys-color-content-primary)` | 本组件 CSS<br>`color` |
| `--c-notification-info-icon-color` | 公开 | `var(--c-sys-color-content-info)` | 本组件 CSS<br>`color` |
| `--c-notification-info-title-color` | 公开 | `var(--c-sys-color-content-primary)` | 本组件 CSS<br>`color` |
| `--c-notification-margin-bottom` | 公开 | `var(--c-spacing-8)` | 本组件 CSS<br>`margin-bottom` |
| `--c-notification-normal-bg` | 公开 | `var(--c-sys-color-surface-overlay)` | 本组件 CSS<br>`background-color` |
| `--c-notification-normal-border-color` | 公开 | `var(--c-sys-color-border-default)` | 本组件 CSS<br>`border` |
| `--c-notification-normal-content-color` | 公开 | `var(--c-sys-color-content-primary)` | 本组件 CSS<br>`color` |
| `--c-notification-normal-icon-color` | 公开 | `var(--c-sys-color-content-primary)` | 本组件 CSS<br>`color` |
| `--c-notification-normal-title-color` | 公开 | `var(--c-sys-color-content-primary)` | 本组件 CSS<br>`color` |
| `--c-notification-padding-bottom` | 公开 | `var(--c-spacing-8)` | 本组件 CSS<br>`padding` |
| `--c-notification-padding-left` | 公开 | `var(--c-spacing-8)` | 本组件 CSS<br>`padding`, `width` |
| `--c-notification-padding-right` | 公开 | `var(--c-spacing-8)` | 本组件 CSS<br>`padding`, `width` |
| `--c-notification-padding-top` | 公开 | `var(--c-spacing-8)` | 本组件 CSS<br>`padding` |
| `--c-notification-success-bg` | 公开 | `var(--c-sys-color-surface-overlay)` | 本组件 CSS<br>`background-color` |
| `--c-notification-success-border-color` | 公开 | `var(--c-sys-color-border-default)` | 本组件 CSS<br>`border-color` |
| `--c-notification-success-content-color` | 公开 | `var(--c-sys-color-content-primary)` | 本组件 CSS<br>`color` |
| `--c-notification-success-icon-color` | 公开 | `var(--c-sys-color-content-success)` | 本组件 CSS<br>`color` |
| `--c-notification-success-title-color` | 公开 | `var(--c-sys-color-content-primary)` | 本组件 CSS<br>`color` |
| `--c-notification-title-font-size` | 公开 | `var(--c-font-size-title-1)` | 本组件 CSS<br>`font-size` |
| `--c-notification-title-font-weight` | 公开 | `var(--c-font-weight-500)` | 本组件 CSS<br>`font-weight` |
| `--c-notification-title-margin-bottom` | 公开 | `var(--c-spacing-2)` | 本组件 CSS<br>`margin-top` |
| `--c-notification-transition-duration` | 公开 | `var(--c-transition-duration-2)` | 本组件 CSS<br>`transition` |
| `--c-notification-transition-duration-enter` | 公开 | `var(--c-transition-duration-4)` | 本组件 CSS<br>`transition` |
| `--c-notification-transition-duration-leave` | 公开 | `var(--c-transition-duration-3)` | 本组件 CSS<br>`transition` |
| `--c-notification-transition-timing-function` | 公开 | `var(--c-transition-timing-function-linear)` | 本组件 CSS<br>`transition` |
| `--c-notification-transition-timing-function-enter` | 公开 | `var(--c-transition-timing-function-overshoot)` | 本组件 CSS<br>`transition` |
| `--c-notification-transition-timing-function-leave` | 公开 | `var(--c-transition-timing-function-standard)` | 本组件 CSS<br>`transition` |
| `--c-notification-warning-bg` | 公开 | `var(--c-sys-color-surface-overlay)` | 本组件 CSS<br>`background-color` |
| `--c-notification-warning-border-color` | 公开 | `var(--c-sys-color-border-default)` | 本组件 CSS<br>`border-color` |
| `--c-notification-warning-content-color` | 公开 | `var(--c-sys-color-content-primary)` | 本组件 CSS<br>`color` |
| `--c-notification-warning-icon-color` | 公开 | `var(--c-sys-color-content-warning)` | 本组件 CSS<br>`color` |
| `--c-notification-warning-title-color` | 公开 | `var(--c-sys-color-content-primary)` | 本组件 CSS<br>`color` |
| `--c-notification-width` | 公开 | `300px` | 本组件 CSS<br>`width` |
| `--c-notification-wrapper-margin-bottom` | 公开 | `var(--c-spacing-8)` | 本组件 CSS<br>`bottom` |
| `--c-notification-wrapper-margin-left` | 公开 | `var(--c-spacing-8)` | 本组件 CSS<br>`left` |
| `--c-notification-wrapper-margin-right` | 公开 | `var(--c-spacing-8)` | 本组件 CSS<br>`right` |
| `--c-notification-wrapper-margin-top` | 公开 | `var(--c-spacing-8)` | 本组件 CSS<br>`top` |
| `--c-notification-z-index` | 公开 | `var(--c-z-index-notification)` | 本组件 CSS<br>`z-index` |

</div>

## overlay

声明来源: `src/overlay/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-overlay-animation-duration` | 公开 | `var(--c-sys-motion-duration-slow)` | 本组件 CSS<br>`transition` |
| `--c-overlay-background-color` | 公开 | `var(--c-sys-color-scrim)` | 本组件 CSS<br>`background-color` |
| `--c-overlay-content-z-index` | 公开 | `var(--c-sys-layer-raised)` | 本组件 CSS<br>`z-index` |

</div>

## page-header

声明来源: `src/page-header/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-page-header-back-color` | 公开 | `var(--c-color-text-2)` | 本组件 CSS<br>`color` |
| `--c-page-header-back-hover-bg` | 公开 | `var(--c-sys-color-state-hover)` | 本组件 CSS<br>`background` |
| `--c-page-header-back-hover-size` | 公开 | `30px` | 本组件 CSS<br>`height`, `width` |
| `--c-page-header-back-size` | 公开 | `var(--c-font-size-body-3)` | 本组件 CSS<br>`font-size` |
| `--c-page-header-content-margin-top` | 公开 | `var(--c-spacing-8)` | 本组件 CSS<br>`margin-top` |
| `--c-page-header-font-size` | 公开 | `var(--c-font-size-body-3)` | 本组件 CSS<br>`font-size` |
| `--c-page-header-footer-margin-top` | 公开 | `var(--c-spacing-8)` | 本组件 CSS<br>`margin-top` |
| `--c-page-header-item-gap` | 公开 | `var(--c-spacing-6)` | 本组件 CSS<br>`margin-left` |
| `--c-page-header-row-gap` | 公开 | `var(--c-spacing-6)` | 本组件 CSS<br>`margin-bottom` |
| `--c-page-header-subtitle-color` | 公开 | `var(--c-color-text-3)` | 本组件 CSS<br>`color` |
| `--c-page-header-title-color` | 公开 | `var(--c-color-text-1)` | 本组件 CSS<br>`color` |
| `--c-page-header-title-font-size` | 公开 | `var(--c-font-size-title-2)` | 本组件 CSS<br>`font-size` |
| `--c-page-header-title-font-weight` | 公开 | `600` | 本组件 CSS<br>`font-weight` |

</div>

## pagination

声明来源: `src/pagination/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-pagination-active-background` | 公开 | `var(--c-color-primary-light-1)` | 本组件 CSS<br>`background` |
| `--c-pagination-active-color` | 公开 | `var(--c-sys-color-content-brand)` | 本组件 CSS<br>`color` |
| `--c-pagination-disabled-background` | 公开 | `var(--c-color-fill-1)` | 本组件 CSS<br>`background` |
| `--c-pagination-disabled-color` | 公开 | `var(--c-color-text-4)` | 本组件 CSS<br>`color` |
| `--c-pagination-focus-color` | 公开 | `var(--c-sys-color-content-brand)` | 本组件 CSS<br>`outline` |
| `--c-pagination-focus-offset` | 公开 | `1px` | 本组件 CSS<br>`outline-offset` |
| `--c-pagination-focus-space` | 公开 | `3px` | 本组件 CSS<br>`padding` |
| `--c-pagination-focus-width` | 公开 | `2px` | 本组件 CSS<br>`outline` |
| `--c-pagination-font-size` | 公开 | `var(--c-sys-font-size-md)` | 本组件 CSS<br>`font-size` |
| `--c-pagination-gap` | 公开 | `var(--c-sys-space-5)` | 本组件 CSS<br>`gap` |
| `--c-pagination-hover-background` | 公开 | `var(--c-color-fill-1)` | 本组件 CSS<br>`background` |
| `--c-pagination-icon-size` | 公开 | `16px` | 本组件 CSS<br>`height`, `width` |
| `--c-pagination-input-width` | 公开 | `32px` | 本组件 CSS<br>`width` |
| `--c-pagination-item-background` | 公开 | `transparent` | 本组件 CSS<br>`background` |
| `--c-pagination-item-border-radius` | 公开 | `var(--c-sys-radius-md)` | 本组件 CSS<br>`border-radius` |
| `--c-pagination-item-gap` | 公开 | `var(--c-sys-space-2)` | 本组件 CSS<br>`gap`, `padding-inline-start` |
| `--c-pagination-item-padding` | 公开 | `var(--c-sys-space-4)` | 本组件 CSS<br>`padding` |
| `--c-pagination-select-width` | 公开 | `max-content` | 本组件 CSS<br>`width` |
| `--c-pagination-size-lg` | 公开 | `44px` | 本组件 CSS<br>`height`, `min-height`, `min-width` |
| `--c-pagination-size-md` | 公开 | `36px` | 本组件 CSS<br>`height`, `min-height`, `min-width` |
| `--c-pagination-size-sm` | 公开 | `28px` | 本组件 CSS<br>`height`, `min-height`, `min-width` |
| `--c-pagination-size-xl` | 公开 | `52px` | 本组件 CSS<br>`height`, `min-height`, `min-width` |
| `--c-pagination-size-xs` | 公开 | `24px` | 本组件 CSS<br>`height`, `min-height`, `min-width` |
| `--c-pagination-text-color` | 公开 | `var(--c-color-text-1)` | 本组件 CSS<br>`color` |
| `--c-pagination-touch-size` | 公开 | `44px` | 本组件 CSS<br>`height`, `min-height` |

</div>

## paper

声明来源: `src/paper/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-paper-background` | 公开 | `var(--c-sys-color-surface-default)` | 本组件 CSS<br>`background` |
| `--c-paper-border-color` | 公开 | `var(--c-sys-color-border-default)` | 本组件 CSS<br>`border` |
| `--c-paper-border-radius` | 公开 | `var(--c-sys-radius-md)` | 本组件 CSS<br>`border-radius` |
| `--c-paper-border-width` | 公开 | `1px` | 本组件 CSS<br>`border` |
| `--c-paper-transition-duration` | 公开 | `var(--c-sys-motion-duration-slow)` | 本组件 CSS<br>`transition` |

</div>

## people-select

声明来源: `src/people-select/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-people-select-avatar-radius` | 公开 | `50%` | 本组件 CSS<br>`border-radius` |
| `--c-people-select-avatar-size` | 公开 | `24px` | 本组件 CSS<br>`height`, `width` |
| `--c-people-select-content-gap` | 公开 | `8px` | 本组件 CSS<br>`gap` |

</div>

## popconfirm

声明来源: `src/popconfirm/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-popconfirm-border-color` | 公开 | `var(--c-color-neutral-3)` | 本组件 CSS<br>`border` |
| `--c-popconfirm-border-radius` | 公开 | `var(--c-border-radius-md)` | 本组件 CSS<br>`border-radius` |
| `--c-popconfirm-border-width` | 公开 | `var(--c-border-width-1)` | 本组件 CSS<br>`border` |
| `--c-popconfirm-box-shadow` | 公开 | `var(--c-shadow2-down)` | 本组件 CSS<br>`box-shadow` |
| `--c-popconfirm-button-margin-left` | 公开 | `var(--c-spacing-4)` | 本组件 CSS<br>`margin-left` |
| `--c-popconfirm-content-bg` | 公开 | `var(--c-color-bg-popup)` | 本组件 CSS<br>`background-color` |
| `--c-popconfirm-content-text-color` | 公开 | `var(--c-color-text-2)` | 本组件 CSS<br>`color` |
| `--c-popconfirm-font-size` | 公开 | `var(--c-font-size-body-3)` | 本组件 CSS<br>`font-size` |
| `--c-popconfirm-icon-margin-right` | 公开 | `var(--c-spacing-4)` | 本组件 CSS<br>`margin-right` |
| `--c-popconfirm-line-height` | 公开 | `var(--c-line-height)` | 本组件 CSS<br>`height`, `line-height` |
| `--c-popconfirm-padding-horizontal` | 公开 | `var(--c-spacing-7)` | 本组件 CSS<br>`padding` |
| `--c-popconfirm-padding-vertical` | 公开 | `var(--c-spacing-7)` | 本组件 CSS<br>`padding` |
| `--c-popconfirm-status-danger-title-icon-color` | 公开 | `var(--c-sys-color-content-danger)` | 本组件 CSS<br>`color` |
| `--c-popconfirm-status-info-title-icon-color` | 公开 | `var(--c-sys-color-content-brand)` | 本组件 CSS<br>`color` |
| `--c-popconfirm-status-success-title-icon-color` | 公开 | `var(--c-sys-color-content-success)` | 本组件 CSS<br>`color` |
| `--c-popconfirm-title-font-size` | 公开 | `var(--c-font-size-body-3)` | 本组件 CSS<br>`font-size`, `height` |
| `--c-popconfirm-title-icon-color` | 公开 | `var(--c-sys-color-content-warning)` | 本组件 CSS<br>`color` |
| `--c-popconfirm-title-icon-size` | 公开 | `18px` | 本组件 CSS<br>`font-size` |
| `--c-popconfirm-title-margin-bottom` | 公开 | `var(--c-spacing-7)` | 本组件 CSS<br>`margin-bottom` |
| `--c-popconfirm-title-text-color` | 公开 | `var(--c-color-text-1)` | 本组件 CSS<br>`color` |

</div>

## popover

声明来源: `src/popover/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-popover-animation-duration` | 公开 | `var(--c-sys-motion-duration-standard)` | 本组件 CSS<br>`transition` |
| `--c-popover-arrow-z-index` | 公开 | `1` | 本组件 CSS<br>`z-index` |
| `--c-popover-background` | 公开 | `var(--c-sys-color-surface-overlay)` | 本组件 CSS<br>`background-color` |
| `--c-popover-border-color` | 公开 | `var(--c-sys-color-border-default)` | 本组件 CSS<br>`border` |
| `--c-popover-border-radius` | 公开 | `var(--c-sys-radius-md)` | 本组件 CSS<br>`border-radius` |
| `--c-popover-border-width` | 公开 | `1px` | 本组件 CSS<br>`border` |
| `--c-popover-box-shadow` | 公开 | `var(--c-shadow2-down)` | 本组件 CSS<br>`box-shadow` |
| `--c-popover-font-size` | 公开 | `var(--c-sys-font-size-md)` | 本组件 CSS<br>`font-size` |
| `--c-popover-line-height` | 公开 | `var(--c-line-height)` | 本组件 CSS<br>`line-height` |
| `--c-popover-padding-horizontal` | 公开 | `var(--c-sys-space-7)` | 本组件 CSS<br>`padding` |
| `--c-popover-padding-vertical` | 公开 | `var(--c-sys-space-6)` | 本组件 CSS<br>`padding` |
| `--c-popover-text-color` | 公开 | `var(--c-sys-color-content-secondary)` | 本组件 CSS<br>`color` |
| `--c-popover-title-content-gap` | 公开 | `var(--c-sys-space-2)` | 本组件 CSS<br>`margin-top` |
| `--c-popover-title-font-size` | 公开 | `var(--c-sys-font-size-lg)` | 本组件 CSS<br>`font-size` |
| `--c-popover-title-font-weight` | 公开 | `var(--c-sys-font-weight-medium)` | 本组件 CSS<br>`font-weight` |
| `--c-popover-title-text-color` | 公开 | `var(--c-sys-color-content-primary)` | 本组件 CSS<br>`color` |

</div>

## progress

声明来源: `src/progress/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-internal-progress-highlight` | 内部 | `rgba(255, 255, 255, 0.5)` | 本组件 CSS<br>`background` |
| `--c-progress-animation-duration` | 公开 | `1.5s` | 本组件 CSS<br>`animation`, `animation-delay` |
| `--c-progress-danger-color` | 公开 | `var(--c-sys-color-content-danger)` | 本组件 CSS<br>`color` |
| `--c-progress-default-color` | 公开 | `var(--c-sys-color-content-brand)` | 本组件 CSS<br>`color` |
| `--c-progress-font-size` | 公开 | `var(--c-sys-font-size-sm)` | 本组件 CSS<br>`font-size` |
| `--c-progress-info-color` | 公开 | `var(--c-sys-color-content-info)` | 本组件 CSS<br>`color` |
| `--c-progress-line-border-radius` | 公开 | `9999px` | 本组件 CSS<br>`border-radius` |
| `--c-progress-primary-color` | 公开 | `var(--c-sys-color-content-brand)` | 本组件 CSS<br>`color` |
| `--c-progress-secondary-color` | 公开 | `var(--c-sys-color-content-secondary)` | 本组件 CSS<br>`color` |
| `--c-progress-steps-gap` | 公开 | `var(--c-sys-space-2)` | 本组件 CSS<br>`gap` |
| `--c-progress-success-color` | 公开 | `var(--c-sys-color-content-success)` | 本组件 CSS<br>`color` |
| `--c-progress-tertiary-color` | 公开 | `var(--c-sys-color-content-tertiary)` | 本组件 CSS<br>`color` |
| `--c-progress-text-color` | 公开 | `var(--c-sys-color-content-secondary)` | 本组件 CSS<br>`color` |
| `--c-progress-text-gap` | 公开 | `var(--c-sys-space-4)` | 本组件 CSS<br>`gap` |
| `--c-progress-track-color` | 公开 | `var(--c-sys-color-state-hover)` | 本组件 CSS<br>`background`, `stroke` |
| `--c-progress-transition-duration` | 公开 | `var(--c-sys-motion-duration-standard)` | 本组件 CSS<br>`transition` |
| `--c-progress-warning-color` | 公开 | `var(--c-sys-color-content-warning)` | 本组件 CSS<br>`color` |

</div>

## progress-group

声明来源: `src/progress-group/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-progress-group-dot-size` | 公开 | `var(--c-sys-space-4)` | 本组件 CSS<br>`height`, `width` |
| `--c-progress-group-font-size` | 公开 | `var(--c-sys-font-size-sm)` | 本组件 CSS<br>`font-size` |
| `--c-progress-group-gap` | 公开 | `var(--c-sys-space-3)` | 本组件 CSS<br>`gap` |
| `--c-progress-group-item-gap` | 公开 | `var(--c-sys-space-2)` | 本组件 CSS<br>`gap` |
| `--c-progress-group-muted-color` | 公开 | `var(--c-sys-color-content-secondary)` | 本组件 CSS<br>`color` |
| `--c-progress-group-radius` | 公开 | `9999px` | 本组件 CSS<br>`border-radius`, `clip-path` |
| `--c-progress-group-size-lg-thickness` | 公开 | `12px` | 本组件 CSS<br>`height`, `width` |
| `--c-progress-group-size-md-thickness` | 公开 | `8px` | 本组件 CSS<br>`height`, `width` |
| `--c-progress-group-size-sm-thickness` | 公开 | `4px` | 本组件 CSS<br>`height`, `width` |
| `--c-progress-group-size-xl-thickness` | 公开 | `16px` | 本组件 CSS<br>`height`, `width` |
| `--c-progress-group-size-xs-thickness` | 公开 | `2px` | 本组件 CSS<br>`height`, `width` |
| `--c-progress-group-text-color` | 公开 | `var(--c-sys-color-content-primary)` | 本组件 CSS<br>`color` |
| `--c-progress-group-text-font-weight` | 公开 | `var(--c-sys-font-weight-medium)` | 本组件 CSS<br>`font-weight` |
| `--c-progress-group-tooltip-bg` | 公开 | `var(--c-sys-color-surface-tooltip)` | 本组件 CSS<br>`background` |
| `--c-progress-group-tooltip-color` | 公开 | `var(--c-sys-color-content-on-dark)` | 本组件 CSS<br>`color` |
| `--c-progress-group-tooltip-duration` | 公开 | `var(--c-sys-motion-duration-fast)` | 本组件 CSS<br>`animation` |
| `--c-progress-group-tooltip-font-size` | 公开 | `var(--c-sys-font-size-xs)` | 本组件 CSS<br>`font-size` |
| `--c-progress-group-tooltip-line-height` | 公开 | `1.4` | 本组件 CSS<br>`line-height` |
| `--c-progress-group-tooltip-max-width` | 公开 | `240px` | 本组件 CSS<br>`max-width` |
| `--c-progress-group-tooltip-offset` | 公开 | `var(--c-sys-space-4)` | 本组件 CSS<br>`bottom`, `left` |
| `--c-progress-group-tooltip-padding` | 公开 | `5px var(--c-sys-space-4)` | 本组件 CSS<br>`padding` |
| `--c-progress-group-tooltip-radius` | 公开 | `var(--c-sys-radius-md)` | 本组件 CSS<br>`border-radius` |
| `--c-progress-group-track-color` | 公开 | `var(--c-sys-color-state-hover)` | 本组件 CSS<br>`background`, `stroke` |
| `--c-progress-group-transition-duration` | 公开 | `var(--c-sys-motion-duration-standard)` | 本组件 CSS<br>`animation`, `transition` |

</div>

## radio

声明来源: `src/radio/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-internal-radio-focus-offset` | 内部 | `2px` | 本组件 CSS<br>`outline-offset` |
| `--c-internal-radio-focus-width` | 内部 | `2px` | 本组件 CSS<br>`outline` |
| `--c-internal-radio-mask-height` | 内部 | `var(--c-size-6)` | 本组件 CSS<br>`padding` |
| `--c-internal-radio-segment-bg` | 内部 | `var(--c-sys-color-surface-default)` | 本组件 CSS<br>`background` |
| `--c-internal-radio-segment-gap` | 内部 | `3px` | 本组件 CSS<br>`gap`, `padding` |
| `--c-internal-radio-segment-group-bg` | 内部 | `var(--c-sys-color-surface-muted)` | 本组件 CSS<br>`background` |
| `--c-internal-radio-segment-height` | 内部 | `var(--c-sys-control-height-md)` | 本组件 CSS<br>`line-height`, `min-height` |
| `--c-internal-radio-segment-hover` | 内部 | `var(--c-sys-color-state-hover)` | 本组件 CSS<br>`background` |
| `--c-internal-radio-segment-padding` | 内部 | `12px` | 本组件 CSS<br>`padding-inline` |
| `--c-internal-radio-segment-radius` | 内部 | `var(--c-sys-radius-md)` | 本组件 CSS<br>`border-radius` |
| `--c-radio-action-padding` | 公开 | `calc((var(--c-internal-radio-mask-height) / 2) - (var(--c-radio-control-size) / 2))` | 本组件 CSS<br>`padding` |
| `--c-radio-animation-duration` | 公开 | `var(--c-transition-duration-3)` | 本组件 CSS<br>`transition` |
| `--c-radio-control-color` | 公开 | `var(--c-sys-color-content-secondary)` | 本组件 CSS<br>`color` |
| `--c-radio-control-color-checked` | 公开 | `var(--c-sys-color-content-brand)` | 本组件 CSS<br>`color`, `outline` |
| `--c-radio-control-color-disabled` | 公开 | `var(--c-sys-color-content-disabled)` | 本组件 CSS<br>`color` |
| `--c-radio-control-color-error` | 公开 | `var(--c-sys-color-content-danger)` | 本组件 CSS<br>`color` |
| `--c-radio-control-size` | 公开 | `14px` | 本组件 CSS<br>`font-size`, `height`, `padding`, `width` |
| `--c-radio-group-gap` | 公开 | `var(--c-spacing-8)` | 本组件 CSS<br>`gap` |
| `--c-radio-label-font-size` | 公开 | `var(--c-font-size-body-3)` | 本组件 CSS<br>`font-size` |
| `--c-radio-label-gap` | 公开 | `var(--c-spacing-4)` | 本组件 CSS<br>`margin-inline-start` |
| `--c-radio-label-text-color` | 公开 | `var(--c-sys-color-content-primary)` | 本组件 CSS<br>`color` |
| `--c-radio-label-text-color-disabled` | 公开 | `var(--c-sys-color-content-disabled)` | 本组件 CSS<br>`color` |

</div>

## rate

声明来源: `src/rate/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-rate-action-padding` | 公开 | `0px` | 本组件 CSS<br>`padding` |
| `--c-rate-active-color` | 公开 | `rgb(var(--c-gold-6))` | 本组件 CSS<br>`color` |
| `--c-rate-active-scale` | 公开 | `1.2` | 本组件 CSS<br>`transform` |
| `--c-rate-disabled-color` | 公开 | `var(--c-sys-color-content-disabled)` | 本组件 CSS<br>`color` |
| `--c-rate-empty-color` | 公开 | `var(--c-color-fill-3)` | 本组件 CSS<br>`color` |
| `--c-rate-error-color` | 公开 | `var(--c-sys-color-content-danger)` | 本组件 CSS<br>`color` |
| `--c-rate-focus-color` | 公开 | `var(--c-sys-color-content-brand)` | 本组件 CSS<br>`outline` |
| `--c-rate-focus-offset` | 公开 | `2px` | 本组件 CSS<br>`outline-offset` |
| `--c-rate-focus-width` | 公开 | `2px` | 本组件 CSS<br>`outline` |
| `--c-rate-gap` | 公开 | `var(--c-spacing-4)` | 本组件 CSS<br>`margin-right` |
| `--c-rate-min-height` | 公开 | `var(--c-size-md)` | 本组件 CSS<br>`min-height` |
| `--c-rate-scale-duration` | 公开 | `var(--c-transition-duration-4)` | 本组件 CSS<br>`animation` |
| `--c-rate-size` | 公开 | `var(--c-font-size-title-3)` | 本组件 CSS<br>`font-size` |
| `--c-rate-transition-duration` | 公开 | `var(--c-transition-duration-2)` | 本组件 CSS<br>`transition` |
| `--c-rate-transition-timing-function` | 公开 | `var(--c-transition-timing-function-standard)` | 本组件 CSS<br>`animation`, `transition` |

</div>

## resize-box

声明来源: `src/resize-box/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-resize-box-trigger-bg` | 公开 | `var(--c-color-neutral-3)` | 本组件 CSS<br>`background-color` |
| `--c-resize-box-trigger-font-size-icon` | 公开 | `12px` | 本组件 CSS<br>`font-size`, `margin` |
| `--c-resize-box-trigger-icon-color` | 公开 | `var(--c-color-text-1)` | 本组件 CSS<br>`color` |

</div>

## result

声明来源: `src/result/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-result-background` | 公开 | `var(--c-color-bg-white)` | 本组件 CSS<br>`background-color` |
| `--c-result-border-radius` | 公开 | `var(--c-border-radius-md)` | 本组件 CSS<br>`border-radius` |
| `--c-result-content-margin` | 公开 | `var(--c-spacing-8) 0 0` | 本组件 CSS<br>`margin` |
| `--c-result-danger-border-color` | 公开 | `var(--c-color-danger-light-3)` | 本组件 CSS<br>`border-color` |
| `--c-result-danger-color` | 公开 | `var(--c-sys-color-content-danger)` | 本组件 CSS<br>`fill` |
| `--c-result-empty-border-color` | 公开 | `rgb(var(--c-gray-2))` | 本组件 CSS<br>`border-color` |
| `--c-result-empty-color` | 公开 | `rgb(var(--c-gray-5))` | 本组件 CSS<br>`fill` |
| `--c-result-extra-margin` | 公开 | `var(--c-spacing-8) 0 0` | 本组件 CSS<br>`margin` |
| `--c-result-image-size` | 公开 | `80px` | 本组件 CSS<br>`border`, `height`, `width` |
| `--c-result-info-border-color` | 公开 | `var(--c-color-primary-light-3)` | 本组件 CSS<br>`border-color` |
| `--c-result-info-color` | 公开 | `var(--c-color-info)` | 本组件 CSS<br>`fill` |
| `--c-result-padding` | 公开 | `var(--c-spacing-10)` | 本组件 CSS<br>`padding` |
| `--c-result-question-border-color` | 公开 | `rgb(var(--c-gray-2))` | 本组件 CSS<br>`border-color` |
| `--c-result-question-color` | 公开 | `rgb(var(--c-gray-6))` | 本组件 CSS<br>`fill` |
| `--c-result-subtitle-color` | 公开 | `var(--c-color-text-2)` | 本组件 CSS<br>`color` |
| `--c-result-subtitle-font-size` | 公开 | `var(--c-font-size-body-3)` | 本组件 CSS<br>`font-size` |
| `--c-result-subtitle-line-height` | 公开 | `1.5715` | 本组件 CSS<br>`line-height` |
| `--c-result-subtitle-margin` | 公开 | `var(--c-spacing-4) 0 0` | 本组件 CSS<br>`margin` |
| `--c-result-success-border-color` | 公开 | `var(--c-color-success-light-3)` | 本组件 CSS<br>`border-color` |
| `--c-result-success-color` | 公开 | `var(--c-sys-color-content-success)` | 本组件 CSS<br>`fill` |
| `--c-result-title-color` | 公开 | `var(--c-color-text-1)` | 本组件 CSS<br>`color` |
| `--c-result-title-font-size` | 公开 | `var(--c-font-size-title-1)` | 本组件 CSS<br>`font-size` |
| `--c-result-title-font-weight` | 公开 | `var(--c-font-weight-500)` | 本组件 CSS<br>`font-weight` |
| `--c-result-title-margin` | 公开 | `var(--c-spacing-7) 0 0` | 本组件 CSS<br>`margin` |
| `--c-result-warning-border-color` | 公开 | `var(--c-color-warning-light-3)` | 本组件 CSS<br>`border-color` |
| `--c-result-warning-color` | 公开 | `var(--c-sys-color-content-warning)` | 本组件 CSS<br>`fill` |

</div>

## ripple

声明来源: `src/ripple/style/token.less`

expand-duration／fade-duration 消费到 transform／opacity 过渡；运行时再读取实际波纹计算后的 duration/delay，避免提前淡出或删除。两个 250ms 生命周期下限不是 CSS Token。采样边界与清理归属见设计指南；此间接时序消费不冒充运行时字面 var() 引用。

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-ripple-color` | 公开 | `currentColor` | 本组件 CSS<br>`background-color` |
| `--c-ripple-cubic-bezier` | 公开 | `cubic-bezier(0.68, 0.01, 0.62, 0.6)` | 本组件 CSS<br>`transition` |
| `--c-ripple-expand-duration` | 公开 | `200ms` | 本组件 CSS<br>`transition` |
| `--c-ripple-fade-duration` | 公开 | `140ms` | 本组件 CSS<br>`transition` |

</div>

## scheduler

声明来源: `src/scheduler/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-scheduler-axis-cell-width` | 公开 | `96px` | 本组件 CSS<br>`min-width` |
| `--c-scheduler-background` | 公开 | `var(--c-color-bg-2)` | 本组件 CSS<br>`background` |
| `--c-scheduler-border-color` | 公开 | `var(--c-color-border)` | 本组件 CSS<br>`border`, `border-bottom`, `border-left`, `border-right`, `border-top` |
| `--c-scheduler-border-width` | 公开 | `1px` | 本组件 CSS<br>`border`, `border-bottom`, `border-left`, `border-right`, `border-top`, `height`, `width` |
| `--c-scheduler-color` | 公开 | `var(--c-color-text-1)` | 本组件 CSS<br>`color` |
| `--c-scheduler-column-min-width` | 公开 | `120px` | 本组件 CSS<br>`grid-template-columns`, `min-width` |
| `--c-scheduler-dependency-width` | 公开 | `2px` | 本组件 CSS<br>`stroke-width` |
| `--c-scheduler-dragging-opacity` | 公开 | `0.3` | 本组件 CSS<br>`opacity` |
| `--c-scheduler-editor-width` | 公开 | `440px` | 运行时引用（不代表可见性证明）<br>`scheduler/components/SchedulerEditor.vue` |
| `--c-scheduler-event-accent-color` | 公开 | `var(--c-scheduler-event-color)` | 本组件 CSS<br>`border-left` |
| `--c-scheduler-event-accent-width` | 公开 | `3px` | 本组件 CSS<br>`border-left` |
| `--c-scheduler-event-background` | 公开 | `var(--c-color-primary-light-1)` | 本组件 CSS<br>`background`, `background-color`, `background-image` |
| `--c-scheduler-event-background-image` | 公开 | `linear-gradient(var(--c-scheduler-event-background), var(--c-scheduler-event-background))` | 本组件 CSS<br>`background-image` |
| `--c-scheduler-event-color` | 公开 | `rgb(var(--c-primary-6))` | 本组件 CSS<br>`background-image`, `border-left`, `color` |
| `--c-scheduler-event-font-size` | 公开 | `12px` | 本组件 CSS<br>`font-size` |
| `--c-scheduler-event-gap` | 公开 | `2px` | 本组件 CSS<br>`gap`, `height`, `margin-bottom`, `padding`, `top` |
| `--c-scheduler-event-min-height` | 公开 | `20px` | 本组件 CSS<br>`min-height`, `min-width` |
| `--c-scheduler-event-padding` | 公开 | `4px` | 本组件 CSS<br>`padding` |
| `--c-scheduler-event-radius` | 公开 | `4px` | 本组件 CSS<br>`border-radius` |
| `--c-scheduler-focus-color` | 公开 | `var(--c-sys-color-content-brand)` | 本组件 CSS<br>`outline` |
| `--c-scheduler-focus-width` | 公开 | `2px` | 本组件 CSS<br>`outline`, `outline-offset` |
| `--c-scheduler-font-size` | 公开 | `14px` | 本组件 CSS<br>`font-size` |
| `--c-scheduler-gap` | 公开 | `12px` | 本组件 CSS<br>`gap`, `margin-bottom`, `padding` |
| `--c-scheduler-ghost-opacity` | 公开 | `0.96` | 本组件 CSS<br>`opacity` |
| `--c-scheduler-ghost-padding` | 公开 | `8px 12px` | 本组件 CSS<br>`padding` |
| `--c-scheduler-ghost-z-index` | 公开 | `2000` | 本组件 CSS<br>`z-index` |
| `--c-scheduler-gutter-width` | 公开 | `64px` | 本组件 CSS<br>`grid-template-columns`, `min-width` |
| `--c-scheduler-header-z-index` | 公开 | `4` | 本组件 CSS<br>`z-index` |
| `--c-scheduler-heading-height` | 公开 | `44px` | 本组件 CSS<br>`min-height` |
| `--c-scheduler-lane-height` | 公开 | `38px` | 本组件 CSS<br>`height`, `top` |
| `--c-scheduler-line-height` | 公开 | `1.5` | 本组件 CSS<br>`line-height` |
| `--c-scheduler-max-height` | 公开 | `720px` | 本组件 CSS<br>`max-height` |
| `--c-scheduler-min-height` | 公开 | `560px` | 本组件 CSS<br>`min-height` |
| `--c-scheduler-mode-width` | 公开 | `150px` | 本组件 CSS<br>`width` |
| `--c-scheduler-month-cell-height` | 公开 | `124px` | 本组件 CSS<br>`height`, `min-height` |
| `--c-scheduler-muted-color` | 公开 | `var(--c-color-text-3)` | 本组件 CSS<br>`color` |
| `--c-scheduler-now-color` | 公开 | `var(--c-sys-color-content-danger)` | 本组件 CSS<br>`border-top`, `color` |
| `--c-scheduler-now-width` | 公开 | `2px` | 本组件 CSS<br>`border-top` |
| `--c-scheduler-now-z-index` | 公开 | `3` | 本组件 CSS<br>`z-index` |
| `--c-scheduler-padding` | 公开 | `16px` | 本组件 CSS<br>`margin-bottom`, `padding` |
| `--c-scheduler-preview-duration` | 公开 | `0ms` | 本组件 CSS<br>`transition` |
| `--c-scheduler-preview-opacity` | 公开 | `0.65` | 本组件 CSS<br>`opacity` |
| `--c-scheduler-preview-shadow` | 公开 | `0 4px 16px rgba(0, 0, 0, 0.15)` | 本组件 CSS<br>`box-shadow` |
| `--c-scheduler-preview-z-index` | 公开 | `3` | 本组件 CSS<br>`z-index` |
| `--c-scheduler-radius` | 公开 | `8px` | 本组件 CSS<br>`border-radius` |
| `--c-scheduler-resize-height` | 公开 | `6px` | 本组件 CSS<br>`height` |
| `--c-scheduler-resource-width` | 公开 | `150px` | 本组件 CSS<br>`grid-template-columns`, `min-width`, `width` |
| `--c-scheduler-resource-z-index` | 公开 | `2` | 本组件 CSS<br>`z-index` |
| `--c-scheduler-selected-background` | 公开 | `var(--c-color-primary-light-1)` | 本组件 CSS<br>`background` |
| `--c-scheduler-sidebar-width` | 公开 | `220px` | 本组件 CSS<br>`width` |
| `--c-scheduler-slot-height` | 公开 | `36px` | 本组件 CSS<br>`height` |
| `--c-scheduler-stack-focus-step` | 公开 | `1` | 本组件 CSS<br>`z-index` |
| `--c-scheduler-subtle-background` | 公开 | `var(--c-color-fill-1)` | 本组件 CSS<br>`background` |
| `--c-scheduler-timeline-min-width` | 公开 | `1000px` | 本组件 CSS<br>`min-width` |
| `--c-scheduler-today-background` | 公开 | `var(--c-color-primary-light-1)` | 本组件 CSS<br>`background` |
| `--c-scheduler-today-color` | 公开 | `var(--c-sys-color-content-brand)` | 本组件 CSS<br>`color` |
| `--c-scheduler-unavailable-background` | 公开 | `var(--c-color-fill-2)` | 本组件 CSS<br>`background` |
| `--c-scheduler-virtual-height` | 公开 | `480px` | 运行时引用（不代表可见性证明）<br>`scheduler/components/SchedulerTimelineRows.vue` |
| `--c-scheduler-weekday-count` | 公开 | `7` | 本组件 CSS<br>`grid-template-columns` |

</div>

## scrollbar

声明来源: `src/scrollbar/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-scrollbar-thumb-bar-bg-color` | 公开 | `var(--c-sys-color-border-default)` | 本组件 CSS<br>`background-color` |
| `--c-scrollbar-thumb-bar-bg-color-hover` | 公开 | `var(--c-sys-color-border-strong)` | 本组件 CSS<br>`background-color` |
| `--c-scrollbar-thumb-bar-border-radius` | 公开 | `6px` | 本组件 CSS<br>`border-radius` |
| `--c-scrollbar-thumb-bar-size` | 公开 | `9px` | 本组件 CSS<br>`height`, `margin`, `width` |
| `--c-scrollbar-track-bg-color` | 公开 | `var(--c-sys-color-surface-muted)` | 本组件 CSS<br>`background-color` |
| `--c-scrollbar-track-border-color` | 公开 | `var(--c-sys-color-border-subtle)` | 本组件 CSS<br>`border-bottom`, `border-left`, `border-right`, `border-top` |
| `--c-scrollbar-track-border-size` | 公开 | `1px` | 本组件 CSS<br>`border-bottom`, `border-left`, `border-right`, `border-top`, `margin`, `right` |
| `--c-scrollbar-track-size` | 公开 | `15px` | 本组件 CSS<br>`height`, `margin`, `width` |

</div>

## search

声明来源: `src/search/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-search-action-color-text` | 公开 | `var(--c-sys-color-content-primary)` | 本组件 CSS<br>`color` |
| `--c-search-action-font-size` | 公开 | `16px` | 本组件 CSS<br>`font-size` |
| `--c-search-action-spacing-inline-start` | 公开 | `16px` | 本组件 CSS<br>`margin-inline-start` |
| `--c-search-color-bg` | 公开 | `var(--c-sys-color-surface-default)` | 本组件 CSS<br>`background` |
| `--c-search-color-icon` | 公开 | `var(--c-sys-color-content-secondary)` | 本组件 CSS<br>`color` |
| `--c-search-field-color-bg` | 公开 | `var(--c-sys-color-surface-muted)` | 本组件 CSS<br>`background` |
| `--c-search-field-radius` | 公开 | `4px` | 本组件 CSS<br>`border-radius` |
| `--c-search-field-size-min-height` | 公开 | `32px` | 本组件 CSS<br>`border-radius`, `min-height` |
| `--c-search-field-spacing-padding` | 公开 | `0` | 本组件 CSS<br>`padding` |
| `--c-search-history-item-color-border` | 公开 | `var(--c-sys-color-border-default)` | 本组件 CSS<br>`border-bottom` |
| `--c-search-history-item-color-text` | 公开 | `var(--c-sys-color-content-primary)` | 本组件 CSS<br>`color` |
| `--c-search-history-item-size-min-height` | 公开 | `44px` | 本组件 CSS<br>`min-height` |
| `--c-search-history-spacing-padding` | 公开 | `8px 16px 24px` | 本组件 CSS<br>`padding` |
| `--c-search-icon-spacing` | 公开 | `8px` | 本组件 CSS<br>`margin-inline-end` |
| `--c-search-label-color-text` | 公开 | `var(--c-sys-color-content-primary)` | 本组件 CSS<br>`color` |
| `--c-search-label-font-size` | 公开 | `16px` | 本组件 CSS<br>`font-size` |
| `--c-search-label-spacing-inline-end` | 公开 | `10px` | 本组件 CSS<br>`margin-inline-end` |
| `--c-search-opacity-disabled` | 公开 | `0.6` | 本组件 CSS<br>`opacity` |
| `--c-search-select-icon-size` | 公开 | `18px` | 本组件 CSS<br>`font-size` |
| `--c-search-select-icon-spacing` | 公开 | `2px` | 本组件 CSS<br>`margin-inline-start` |
| `--c-search-select-size-max-width` | 公开 | `120px` | 本组件 CSS<br>`max-width` |
| `--c-search-select-size-min-width` | 公开 | `96px` | 本组件 CSS<br>`min-width` |
| `--c-search-size-icon` | 公开 | `16px` | 本组件 CSS<br>`font-size` |
| `--c-search-size-min-height` | 公开 | `32px` | 本组件 CSS<br>`min-height` |
| `--c-search-spacing-padding` | 公开 | `0` | 本组件 CSS<br>`padding` |

</div>

## segmented

声明来源: `src/segmented/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-segmented-bg` | 公开 | `var(--c-sys-color-surface-muted)` | 本组件 CSS<br>`background` |
| `--c-segmented-border-radius` | 公开 | `var(--c-border-radius-md)` | 本组件 CSS<br>`border-radius` |
| `--c-segmented-font-size-lg` | 公开 | `var(--c-font-size-body-3)` | 本组件 CSS<br>`font-size` |
| `--c-segmented-font-size-md` | 公开 | `var(--c-font-size-body-3)` | 本组件 CSS<br>`font-size` |
| `--c-segmented-font-size-sm` | 公开 | `var(--c-font-size-body-1)` | 本组件 CSS<br>`font-size` |
| `--c-segmented-font-size-xl` | 公开 | `var(--c-font-size-title-1)` | 本组件 CSS<br>`font-size` |
| `--c-segmented-font-size-xs` | 公开 | `var(--c-font-size-body-1)` | 本组件 CSS<br>`font-size` |
| `--c-segmented-height-lg` | 公开 | `var(--c-size-9)` | 本组件 CSS<br>`min-height` |
| `--c-segmented-height-md` | 公开 | `var(--c-size-8)` | 本组件 CSS<br>`min-height` |
| `--c-segmented-height-sm` | 公开 | `var(--c-size-7)` | 本组件 CSS<br>`min-height` |
| `--c-segmented-height-xl` | 公开 | `var(--c-size-10)` | 本组件 CSS<br>`min-height` |
| `--c-segmented-height-xs` | 公开 | `var(--c-size-6)` | 本组件 CSS<br>`min-height` |
| `--c-segmented-item-bg-hover` | 公开 | `var(--c-sys-color-state-hover)` | 本组件 CSS<br>`background` |
| `--c-segmented-item-bg-selected` | 公开 | `var(--c-sys-color-surface-default)` | 本组件 CSS<br>`background` |
| `--c-segmented-item-border-radius` | 公开 | `calc(var(--c-segmented-border-radius) - 1px)` | 本组件 CSS<br>`border-radius` |
| `--c-segmented-item-color` | 公开 | `var(--c-sys-color-content-secondary)` | 本组件 CSS<br>`color` |
| `--c-segmented-item-color-hover` | 公开 | `var(--c-sys-color-content-primary)` | 本组件 CSS<br>`color` |
| `--c-segmented-item-color-selected` | 公开 | `var(--c-sys-color-content-primary)` | 本组件 CSS<br>`color` |
| `--c-segmented-item-disabled-color` | 公开 | `var(--c-sys-color-content-disabled)` | 本组件 CSS<br>`color` |
| `--c-segmented-item-font-weight-selected` | 公开 | `500` | 本组件 CSS<br>`font-weight` |
| `--c-segmented-item-padding-lg` | 公开 | `0 14px` | 本组件 CSS<br>`padding` |
| `--c-segmented-item-padding-md` | 公开 | `0 var(--c-spacing-6)` | 本组件 CSS<br>`padding` |
| `--c-segmented-item-padding-sm` | 公开 | `0 var(--c-spacing-5)` | 本组件 CSS<br>`padding` |
| `--c-segmented-item-padding-xl` | 公开 | `0 var(--c-spacing-7)` | 本组件 CSS<br>`padding` |
| `--c-segmented-item-padding-xs` | 公开 | `0 var(--c-spacing-4)` | 本组件 CSS<br>`padding` |
| `--c-segmented-label-gap` | 公开 | `var(--c-spacing-2)` | 本组件 CSS<br>`gap` |
| `--c-segmented-padding` | 公开 | `var(--c-border-width-3)` | 本组件 CSS<br>`padding` |
| `--c-segmented-shadow-selected` | 公开 | `0 1px 2px rgba(0, 0, 0, 0.06)` | 本组件 CSS<br>`box-shadow` |

</div>

## select

声明来源: `src/select/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-select-popup-bg` | 公开 | `var(--c-sys-color-surface-overlay)` | 本组件 CSS<br>`background-color` |
| `--c-select-popup-border-color` | 公开 | `var(--c-sys-color-border-default)` | 本组件 CSS<br>`border`, `border-bottom`, `border-color`, `border-top` |
| `--c-select-popup-border-radius` | 公开 | `var(--c-sys-radius-md)` | 本组件 CSS<br>`border-radius` |
| `--c-select-popup-box-shadow` | 公开 | `0 4px 10px rgba(0, 0, 0, 0.1)` | 本组件 CSS<br>`box-shadow` |
| `--c-select-popup-font-size` | 公开 | `var(--c-sys-font-size-md)` | 本组件 CSS<br>`font-size` |
| `--c-select-popup-group-title-font-size` | 公开 | `var(--c-sys-font-size-xs)` | 本组件 CSS<br>`font-size` |
| `--c-select-popup-group-title-height` | 公开 | `20px` | 本组件 CSS<br>`line-height` |
| `--c-select-popup-group-title-padding-horizontal` | 公开 | `var(--c-select-popup-option-padding-horizontal)` | 本组件 CSS<br>`padding` |
| `--c-select-popup-group-title-padding-top` | 公开 | `var(--c-sys-space-4)` | 本组件 CSS<br>`margin-top` |
| `--c-select-popup-group-title-text-color` | 公开 | `var(--c-sys-color-content-secondary)` | 本组件 CSS<br>`color` |
| `--c-select-popup-loading-min-height` | 公开 | `50px` | 本组件 CSS<br>`min-height` |
| `--c-select-popup-max-height` | 公开 | `200px` | 本组件 CSS<br>`max-height` |
| `--c-select-popup-option-bg` | 公开 | `var(--c-sys-color-surface-overlay)` | 本组件 CSS<br>`background-color` |
| `--c-select-popup-option-bg-disabled` | 公开 | `var(--c-sys-color-surface-overlay)` | 本组件 CSS<br>`background-color` |
| `--c-select-popup-option-bg-hover` | 公开 | `var(--c-sys-color-state-hover)` | 本组件 CSS<br>`background-color` |
| `--c-select-popup-option-bg-selected` | 公开 | `var(--c-sys-color-surface-overlay)` | 本组件 CSS<br>`background-color` |
| `--c-select-popup-option-check-color` | 公开 | `var(--c-sys-color-action-primary)` | 本组件 CSS<br>`color` |
| `--c-select-popup-option-check-gap` | 公开 | `var(--c-sys-space-4)` | 本组件 CSS<br>`margin-inline-start` |
| `--c-select-popup-option-check-size` | 公开 | `var(--c-sys-font-size-md)` | 本组件 CSS<br>`height`, `width` |
| `--c-select-popup-option-font-weight-selected` | 公开 | `var(--c-sys-font-weight-medium)` | 本组件 CSS<br>`font-weight` |
| `--c-select-popup-option-height` | 公开 | `36px` | 本组件 CSS<br>`line-height` |
| `--c-select-popup-option-icon-margin-right` | 公开 | `var(--c-sys-space-4)` | 本组件 CSS<br>`margin-right` |
| `--c-select-popup-option-padding-horizontal` | 公开 | `var(--c-sys-space-5)` | 本组件 CSS<br>`padding`, `padding-inline` |
| `--c-select-popup-option-suffix-icon-margin-left` | 公开 | `var(--c-sys-space-5)` | 本组件 CSS<br>`margin-left` |
| `--c-select-popup-option-text-color` | 公开 | `var(--c-sys-color-content-primary)` | 本组件 CSS<br>`color` |
| `--c-select-popup-option-text-color-disabled` | 公开 | `var(--c-sys-color-content-disabled)` | 本组件 CSS<br>`color` |
| `--c-select-popup-option-text-color-hover` | 公开 | `var(--c-sys-color-content-primary)` | 本组件 CSS<br>`color` |
| `--c-select-popup-option-text-color-selected` | 公开 | `var(--c-sys-color-content-primary)` | 本组件 CSS<br>`color` |
| `--c-select-popup-padding-vertical` | 公开 | `var(--c-sys-space-2)` | 本组件 CSS<br>`padding`, `padding-block` |

</div>

## skeleton

声明来源: `src/skeleton/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-skeleton-animation-background` | 公开 | `linear-gradient(90deg, transparent, var(--c-sys-color-surface-default), transparent)` | 本组件 CSS<br>`background` |
| `--c-skeleton-animation-duration` | 公开 | `1s` | 本组件 CSS<br>`animation` |
| `--c-skeleton-avatar-background-color` | 公开 | `var(--c-sys-color-state-hover)` | 本组件 CSS<br>`background-color` |
| `--c-skeleton-avatar-border-radius` | 公开 | `50%` | 本组件 CSS<br>`border-radius` |
| `--c-skeleton-avatar-margin-right` | 公开 | `var(--c-sys-space-6)` | 本组件 CSS<br>`margin-right` |
| `--c-skeleton-avatar-size` | 公开 | `34px` | 本组件 CSS<br>`height`, `width` |
| `--c-skeleton-card-background-color` | 公开 | `var(--c-sys-color-state-hover)` | 本组件 CSS<br>`background-color` |
| `--c-skeleton-card-border-radius` | 公开 | `var(--c-sys-radius-md)` | 本组件 CSS<br>`border-radius` |
| `--c-skeleton-card-height` | 公开 | `160px` | 本组件 CSS<br>`height` |
| `--c-skeleton-card-margin-bottom` | 公开 | `var(--c-sys-space-6)` | 本组件 CSS<br>`margin-bottom` |
| `--c-skeleton-content-padding` | 公开 | `var(--c-sys-space-6)` | 本组件 CSS<br>`padding` |
| `--c-skeleton-row-border-radius` | 公开 | `10px` | 本组件 CSS<br>`border-radius` |
| `--c-skeleton-row-height` | 公开 | `12px` | 本组件 CSS<br>`height` |
| `--c-skeleton-row-margin-top` | 公开 | `10px` | 本组件 CSS<br>`margin-top` |
| `--c-skeleton-shape-border-radius` | 公开 | `var(--c-sys-radius-md)` | 本组件 CSS<br>`border-radius` |
| `--c-skeleton-shape-size-lg` | 公开 | `60px` | 本组件 CSS<br>`height`, `width` |
| `--c-skeleton-shape-size-md` | 公开 | `48px` | 本组件 CSS<br>`height`, `width` |
| `--c-skeleton-shape-size-sm` | 公开 | `36px` | 本组件 CSS<br>`height`, `width` |
| `--c-skeleton-title-background-color` | 公开 | `var(--c-sys-color-state-hover)` | 本组件 CSS<br>`background-color` |
| `--c-skeleton-title-border-radius` | 公开 | `10px` | 本组件 CSS<br>`border-radius` |
| `--c-skeleton-title-width` | 公开 | `50%` | 本组件 CSS<br>`width` |
| `--c-skeleton-transition-duration` | 公开 | `var(--c-sys-motion-duration-slow)` | 本组件 CSS<br>`transition` |

</div>

## slider

声明来源: `src/slider/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-internal-slider-border-width` | 内部 | `2px` | 本组件 CSS<br>`border`, `outline` |
| `--c-internal-slider-focus-offset` | 内部 | `3px` | 本组件 CSS<br>`outline-offset` |
| `--c-internal-slider-mark-offset` | 内部 | `8px` | 本组件 CSS<br>`left`, `top` |
| `--c-slider-active-color` | 公开 | `var(--c-sys-color-content-brand)` | 本组件 CSS<br>`background`, `outline` |
| `--c-slider-control-height` | 公开 | `var(--c-sys-control-height-md)` | 本组件 CSS<br>`height`, `min-height`, `padding-bottom`, `padding-inline-end`, `width` |
| `--c-slider-disabled-color` | 公开 | `var(--c-sys-color-content-disabled)` | 本组件 CSS<br>`background`, `border-color` |
| `--c-slider-error-color` | 公开 | `var(--c-sys-color-content-danger)` | 本组件 CSS<br>`background`, `border-color` |
| `--c-slider-font-size` | 公开 | `var(--c-sys-font-size-sm)` | 本组件 CSS<br>`font-size` |
| `--c-slider-gap` | 公开 | `var(--c-sys-space-4)` | 本组件 CSS<br>`bottom`, `gap`, `left`, `padding` |
| `--c-slider-input-width` | 公开 | `80px` | 本组件 CSS<br>`width` |
| `--c-slider-radius` | 公开 | `var(--c-sys-radius-md)` | 本组件 CSS<br>`border-radius` |
| `--c-slider-text-color` | 公开 | `var(--c-sys-color-content-secondary)` | 本组件 CSS<br>`color` |
| `--c-slider-thumb-border-color` | 公开 | `var(--c-sys-color-content-brand)` | 本组件 CSS<br>`border` |
| `--c-slider-thumb-color` | 公开 | `var(--c-sys-color-surface-default)` | 本组件 CSS<br>`background` |
| `--c-slider-thumb-size` | 公开 | `16px` | 本组件 CSS<br>`height`, `width` |
| `--c-slider-tooltip-background` | 公开 | `var(--c-sys-color-surface-tooltip)` | 本组件 CSS<br>`background` |
| `--c-slider-tooltip-color` | 公开 | `var(--c-sys-color-content-on-dark)` | 本组件 CSS<br>`color` |
| `--c-slider-track-color` | 公开 | `var(--c-sys-color-state-hover)` | 本组件 CSS<br>`background` |
| `--c-slider-track-height` | 公开 | `4px` | 本组件 CSS<br>`height`, `width` |
| `--c-slider-transition-duration` | 公开 | `var(--c-sys-motion-duration-fast)` | 本组件 CSS<br>`transition` |

</div>

## space

声明来源: `src/space/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-space-size-lg-column-gap` | 公开 | `var(--c-sys-space-5)` | 已审动态运行时<br>`space/space.tsx: getSize -> gapStyle -> style.gap` |
| `--c-space-size-lg-row-gap` | 公开 | `var(--c-sys-space-6)` | 已审动态运行时<br>`space/space.tsx: getSize -> gapStyle -> style.gap` |
| `--c-space-size-md-column-gap` | 公开 | `var(--c-sys-space-4)` | 已审动态运行时<br>`space/space.tsx: getSize -> gapStyle -> style.gap` |
| `--c-space-size-md-row-gap` | 公开 | `var(--c-sys-space-5)` | 已审动态运行时<br>`space/space.tsx: getSize -> gapStyle -> style.gap` |
| `--c-space-size-sm-column-gap` | 公开 | `var(--c-sys-space-3)` | 已审动态运行时<br>`space/space.tsx: getSize -> gapStyle -> style.gap` |
| `--c-space-size-sm-row-gap` | 公开 | `var(--c-sys-space-4)` | 已审动态运行时<br>`space/space.tsx: getSize -> gapStyle -> style.gap` |
| `--c-space-size-xl-column-gap` | 公开 | `var(--c-sys-space-6)` | 已审动态运行时<br>`space/space.tsx: getSize -> gapStyle -> style.gap` |
| `--c-space-size-xl-row-gap` | 公开 | `var(--c-sys-space-8)` | 已审动态运行时<br>`space/space.tsx: getSize -> gapStyle -> style.gap` |
| `--c-space-size-xs-column-gap` | 公开 | `var(--c-sys-space-2)` | 已审动态运行时<br>`space/space.tsx: getSize -> gapStyle -> style.gap` |
| `--c-space-size-xs-row-gap` | 公开 | `var(--c-sys-space-2)` | 已审动态运行时<br>`space/space.tsx: getSize -> gapStyle -> style.gap` |

</div>

## split

声明来源: `src/split/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-split-trigger-bg` | 公开 | `var(--c-color-neutral-3)` | 本组件 CSS<br>`background-color` |
| `--c-split-trigger-font-size-icon` | 公开 | `12px` | 本组件 CSS<br>`font-size`, `margin` |
| `--c-split-trigger-icon-color` | 公开 | `var(--c-color-text-1)` | 本组件 CSS<br>`color` |
| `--c-split-trigger-size-icon-wrapper` | 公开 | `6px` | 本组件 CSS<br>`height`, `width` |

</div>

## statistic

声明来源: `src/statistic/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-statistic-decimal-font-size` | 公开 | `inherit` | 本组件 CSS<br>`font-size` |
| `--c-statistic-extra-color` | 公开 | `var(--c-sys-color-content-secondary)` | 本组件 CSS<br>`color` |
| `--c-statistic-extra-font-size` | 公开 | `var(--c-font-size-body-3)` | 本组件 CSS<br>`font-size` |
| `--c-statistic-extra-margin-top` | 公开 | `var(--c-spacing-4)` | 本组件 CSS<br>`margin-top` |
| `--c-statistic-prefix-color` | 公开 | `var(--c-sys-color-content-secondary)` | 本组件 CSS<br>`color` |
| `--c-statistic-prefix-font-size` | 公开 | `14px` | 本组件 CSS<br>`font-size` |
| `--c-statistic-prefix-spacing` | 公开 | `var(--c-spacing-1)` | 本组件 CSS<br>`margin-right` |
| `--c-statistic-suffix-color` | 公开 | `var(--c-sys-color-content-secondary)` | 本组件 CSS<br>`color` |
| `--c-statistic-suffix-font-size` | 公开 | `14px` | 本组件 CSS<br>`font-size` |
| `--c-statistic-suffix-spacing` | 公开 | `var(--c-spacing-1)` | 本组件 CSS<br>`margin-left` |
| `--c-statistic-title-color` | 公开 | `var(--c-sys-color-content-secondary)` | 本组件 CSS<br>`color` |
| `--c-statistic-title-font-size` | 公开 | `var(--c-font-size-body-3)` | 本组件 CSS<br>`font-size` |
| `--c-statistic-title-margin-bottom` | 公开 | `var(--c-spacing-4)` | 本组件 CSS<br>`margin-bottom` |
| `--c-statistic-value-color` | 公开 | `var(--c-sys-color-content-primary)` | 本组件 CSS<br>`color` |
| `--c-statistic-value-font-size` | 公开 | `26px` | 本组件 CSS<br>`font-size` |
| `--c-statistic-value-font-weight` | 公开 | `var(--c-font-weight-500)` | 本组件 CSS<br>`font-weight` |

</div>

## steps

声明来源: `src/steps/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-steps-arrow-item-bg-error` | 公开 | `var(--c-sys-color-content-danger)` | 本组件 CSS<br>`background-color`, `border-inline-start` |
| `--c-steps-arrow-item-bg-finish` | 公开 | `var(--c-sys-color-state-selected)` | 本组件 CSS<br>`background-color`, `border-inline-start` |
| `--c-steps-arrow-item-bg-process` | 公开 | `var(--c-sys-color-content-brand)` | 本组件 CSS<br>`background-color`, `border-inline-start` |
| `--c-steps-arrow-item-bg-wait` | 公开 | `var(--c-sys-color-surface-muted)` | 本组件 CSS<br>`background-color`, `border-inline-start` |
| `--c-steps-arrow-item-description-color-error` | 公开 | `var(--c-sys-color-surface-default)` | 本组件 CSS<br>`color` |
| `--c-steps-arrow-item-description-color-finish` | 公开 | `var(--c-sys-color-content-secondary)` | 本组件 CSS<br>`color` |
| `--c-steps-arrow-item-description-color-process` | 公开 | `var(--c-sys-color-surface-default)` | 本组件 CSS<br>`color` |
| `--c-steps-arrow-item-description-color-wait` | 公开 | `var(--c-sys-color-content-secondary)` | 本组件 CSS<br>`color` |
| `--c-steps-arrow-item-description-margin-top` | 公开 | `0` | 本组件 CSS<br>`margin-top` |
| `--c-steps-arrow-item-gap` | 公开 | `var(--c-spacing-2)` | 本组件 CSS<br>`margin-inline-end` |
| `--c-steps-arrow-item-title-color-error` | 公开 | `var(--c-sys-color-surface-default)` | 本组件 CSS<br>`color` |
| `--c-steps-arrow-item-title-color-finish` | 公开 | `var(--c-sys-color-content-primary)` | 本组件 CSS<br>`color` |
| `--c-steps-arrow-item-title-color-process` | 公开 | `var(--c-sys-color-surface-default)` | 本组件 CSS<br>`color` |
| `--c-steps-arrow-item-title-color-wait` | 公开 | `var(--c-sys-color-content-secondary)` | 本组件 CSS<br>`color` |
| `--c-steps-arrow-item-title-font-weight-active` | 公开 | `var(--c-font-weight-500)` | 本组件 CSS<br>`font-weight` |
| `--c-steps-arrow-size-md-title-padding-left` | 公开 | `var(--c-spacing-7)` | 本组件 CSS<br>`padding-inline-start` |
| `--c-steps-arrow-size-sm-title-padding-left` | 公开 | `var(--c-spacing-8)` | 本组件 CSS<br>`padding-inline-start` |
| `--c-steps-changeable-hover-text-color` | 公开 | `var(--c-sys-color-content-brand)` | 本组件 CSS<br>`color` |
| `--c-steps-circle-horizontal-item-description-margin-top` | 公开 | `var(--c-spacing-1)` | 本组件 CSS<br>`margin-top` |
| `--c-steps-circle-item-bg-error` | 公开 | `var(--c-sys-color-content-danger)` | 本组件 CSS<br>`background-color` |
| `--c-steps-circle-item-bg-finish` | 公开 | `var(--c-sys-color-state-selected)` | 本组件 CSS<br>`background-color` |
| `--c-steps-circle-item-bg-process` | 公开 | `var(--c-sys-color-content-brand)` | 本组件 CSS<br>`background-color` |
| `--c-steps-circle-item-bg-wait` | 公开 | `var(--c-sys-color-surface-muted)` | 本组件 CSS<br>`background-color` |
| `--c-steps-circle-item-border-color-error` | 公开 | `transparent` | 本组件 CSS<br>`border` |
| `--c-steps-circle-item-border-color-finish` | 公开 | `transparent` | 本组件 CSS<br>`border` |
| `--c-steps-circle-item-border-color-process` | 公开 | `transparent` | 本组件 CSS<br>`border` |
| `--c-steps-circle-item-border-color-wait` | 公开 | `transparent` | 本组件 CSS<br>`border` |
| `--c-steps-circle-item-description-color-error` | 公开 | `var(--c-sys-color-content-secondary)` | 本组件 CSS<br>`color` |
| `--c-steps-circle-item-description-color-finish` | 公开 | `var(--c-sys-color-content-secondary)` | 本组件 CSS<br>`color` |
| `--c-steps-circle-item-description-color-process` | 公开 | `var(--c-sys-color-content-secondary)` | 本组件 CSS<br>`color` |
| `--c-steps-circle-item-description-color-wait` | 公开 | `var(--c-sys-color-content-secondary)` | 本组件 CSS<br>`color` |
| `--c-steps-circle-item-icon-border-radius` | 公开 | `var(--c-border-radius-circle)` | 本组件 CSS<br>`border-radius` |
| `--c-steps-circle-item-icon-gap` | 公开 | `var(--c-spacing-6)` | 本组件 CSS<br>`inset-inline-start`, `margin-inline-end`, `padding-inline-end` |
| `--c-steps-circle-item-icon-text-color-error` | 公开 | `var(--c-sys-color-surface-default)` | 本组件 CSS<br>`color` |
| `--c-steps-circle-item-icon-text-color-finish` | 公开 | `var(--c-sys-color-content-brand)` | 本组件 CSS<br>`color` |
| `--c-steps-circle-item-icon-text-color-process` | 公开 | `var(--c-sys-color-surface-default)` | 本组件 CSS<br>`color` |
| `--c-steps-circle-item-icon-text-color-wait` | 公开 | `var(--c-sys-color-content-secondary)` | 本组件 CSS<br>`color` |
| `--c-steps-circle-item-tail-color-error` | 公开 | `var(--c-sys-color-content-danger)` | 本组件 CSS<br>`background-color` |
| `--c-steps-circle-item-tail-color-process` | 公开 | `var(--c-sys-color-content-brand)` | 本组件 CSS<br>`background-color` |
| `--c-steps-circle-item-tail-color-wait` | 公开 | `var(--c-sys-color-border-default)` | 本组件 CSS<br>`background-color` |
| `--c-steps-circle-item-tail-size` | 公开 | `var(--c-border-width-1)` | 本组件 CSS<br>`height`, `inset-inline-start`, `top`, `width` |
| `--c-steps-circle-item-title-color-error` | 公开 | `var(--c-sys-color-content-primary)` | 本组件 CSS<br>`color` |
| `--c-steps-circle-item-title-color-finish` | 公开 | `var(--c-sys-color-content-primary)` | 本组件 CSS<br>`color` |
| `--c-steps-circle-item-title-color-process` | 公开 | `var(--c-sys-color-content-primary)` | 本组件 CSS<br>`color` |
| `--c-steps-circle-item-title-color-wait` | 公开 | `var(--c-sys-color-content-secondary)` | 本组件 CSS<br>`color` |
| `--c-steps-circle-item-title-font-weight-active` | 公开 | `var(--c-font-weight-500)` | 本组件 CSS<br>`font-weight` |
| `--c-steps-circle-tail-hack-width` | 公开 | `5000px` | 本组件 CSS<br>`width` |
| `--c-steps-circle-vertical-item-description-margin-top` | 公开 | `var(--c-spacing-1)` | 本组件 CSS<br>`margin-top` |
| `--c-steps-circle-vertical-tail-padding-extra` | 公开 | `var(--c-spacing-3)` | 本组件 CSS<br>`padding` |
| `--c-steps-direction-horizontal-description-width` | 公开 | `var(--c-size-35)` | 本组件 CSS<br>`max-width` |
| `--c-steps-dot-horizontal-item-description-margin-top` | 公开 | `var(--c-spacing-2)` | 本组件 CSS<br>`margin-top` |
| `--c-steps-dot-horizontal-item-title-margin-top` | 公开 | `var(--c-spacing-2)` | 本组件 CSS<br>`margin-top` |
| `--c-steps-dot-item-bg-error` | 公开 | `var(--c-sys-color-content-danger)` | 本组件 CSS<br>`background-color` |
| `--c-steps-dot-item-bg-finish` | 公开 | `var(--c-sys-color-content-brand)` | 本组件 CSS<br>`background-color` |
| `--c-steps-dot-item-bg-process` | 公开 | `var(--c-sys-color-content-brand)` | 本组件 CSS<br>`background-color` |
| `--c-steps-dot-item-bg-wait` | 公开 | `var(--c-sys-color-content-secondary)` | 本组件 CSS<br>`background-color` |
| `--c-steps-dot-item-border-color-error` | 公开 | `var(--c-sys-color-content-danger)` | 本组件 CSS<br>`border-color` |
| `--c-steps-dot-item-border-color-finish` | 公开 | `var(--c-sys-color-content-brand)` | 本组件 CSS<br>`border-color` |
| `--c-steps-dot-item-border-color-process` | 公开 | `var(--c-sys-color-content-brand)` | 本组件 CSS<br>`border-color` |
| `--c-steps-dot-item-border-color-wait` | 公开 | `var(--c-sys-color-content-secondary)` | 本组件 CSS<br>`border-color` |
| `--c-steps-dot-item-description-color-error` | 公开 | `var(--c-sys-color-content-secondary)` | 本组件 CSS<br>`color` |
| `--c-steps-dot-item-description-color-finish` | 公开 | `var(--c-sys-color-content-secondary)` | 本组件 CSS<br>`color` |
| `--c-steps-dot-item-description-color-process` | 公开 | `var(--c-sys-color-content-secondary)` | 本组件 CSS<br>`color` |
| `--c-steps-dot-item-description-color-wait` | 公开 | `var(--c-sys-color-content-secondary)` | 本组件 CSS<br>`color` |
| `--c-steps-dot-item-icon-border-radius` | 公开 | `var(--c-border-radius-circle)` | 本组件 CSS<br>`border-radius` |
| `--c-steps-dot-item-icon-gap` | 公开 | `var(--c-spacing-2)` | 本组件 CSS<br>`inset-inline-start`, `margin-inline-end`, `padding-top` |
| `--c-steps-dot-item-icon-margin-left` | 公开 | `calc((var(--c-steps-label-vertical-content-width) - var(--c-steps-dot-item-icon-size)) / 2)` | 本组件 CSS<br>`inset-inline-start`, `margin-inline-start` |
| `--c-steps-dot-item-icon-size` | 公开 | `var(--c-size-2)` | 本组件 CSS<br>`height`, `inset-inline-start`, `margin-inline-end`, `margin-inline-start`, `margin-top`, `padding-top`, `top`, `width` |
| `--c-steps-dot-item-icon-size-active` | 公开 | `var(--c-spacing-5)` | 本组件 CSS<br>`height`, `margin-inline-start`, `margin-top`, `width` |
| `--c-steps-dot-item-tail-color-error` | 公开 | `var(--c-sys-color-content-danger)` | 本组件 CSS<br>`background-color` |
| `--c-steps-dot-item-tail-color-process` | 公开 | `var(--c-sys-color-content-brand)` | 本组件 CSS<br>`background-color` |
| `--c-steps-dot-item-tail-color-wait` | 公开 | `var(--c-sys-color-border-default)` | 本组件 CSS<br>`background-color` |
| `--c-steps-dot-item-tail-size` | 公开 | `var(--c-border-width-1)` | 本组件 CSS<br>`height`, `top` |
| `--c-steps-dot-item-title-color-error` | 公开 | `var(--c-sys-color-content-primary)` | 本组件 CSS<br>`color` |
| `--c-steps-dot-item-title-color-finish` | 公开 | `var(--c-sys-color-content-primary)` | 本组件 CSS<br>`color` |
| `--c-steps-dot-item-title-color-process` | 公开 | `var(--c-sys-color-content-primary)` | 本组件 CSS<br>`color` |
| `--c-steps-dot-item-title-color-wait` | 公开 | `var(--c-sys-color-content-secondary)` | 本组件 CSS<br>`color` |
| `--c-steps-dot-item-title-font-weight-active` | 公开 | `var(--c-font-weight-500)` | 本组件 CSS<br>`font-weight` |
| `--c-steps-dot-vertical-item-description-margin-top` | 公开 | `var(--c-spacing-2)` | 本组件 CSS<br>`margin-top` |
| `--c-steps-dot-vertical-item-dot-margin-top` | 公开 | `var(--c-spacing-4)` | 本组件 CSS<br>`margin-top` |
| `--c-steps-dot-vertical-item-dot-margin-top-active` | 公开 | `calc(var(--c-steps-dot-vertical-item-dot-margin-top) - (var(--c-steps-dot-item-icon-size-active) - var(--c-steps-dot-item-icon-size)))` | 本组件 CSS<br>`margin-top` |
| `--c-steps-dot-vertical-item-icon-margin-right` | 公开 | `var(--c-spacing-7)` | 本组件 CSS<br>`margin-inline-end` |
| `--c-steps-dot-vertical-tail-padding-bottom` | 公开 | `var(--c-spacing-1)` | 本组件 CSS<br>`padding-bottom` |
| `--c-steps-dot-vertical-tail-padding-top-extra` | 公开 | `var(--c-spacing-2)` | 本组件 CSS<br>`padding-top` |
| `--c-steps-label-vertical-content-width` | 公开 | `100%` | 本组件 CSS<br>`inset-inline-start`, `margin-inline-start` |
| `--c-steps-navigation-arrow-color` | 公开 | `var(--c-sys-color-content-secondary)` | 本组件 CSS<br>`border` |
| `--c-steps-navigation-arrow-line-width` | 公开 | `var(--c-border-width-2)` | 本组件 CSS<br>`border` |
| `--c-steps-navigation-arrow-right` | 公开 | `30px` | 本组件 CSS<br>`inset-inline-end` |
| `--c-steps-navigation-arrow-size` | 公开 | `var(--c-spacing-3)` | 本组件 CSS<br>`height`, `width` |
| `--c-steps-navigation-arrow-spacing-right` | 公开 | `var(--c-spacing-5)` | 本组件 CSS<br>`padding-inline-end` |
| `--c-steps-navigation-arrow-top` | 公开 | `var(--c-spacing-5)` | 本组件 CSS<br>`top` |
| `--c-steps-navigation-content-margin-bottom` | 公开 | `var(--c-spacing-8)` | 本组件 CSS<br>`margin-bottom` |
| `--c-steps-navigation-description-padding-right` | 公开 | `var(--c-spacing-8)` | 本组件 CSS<br>`padding-inline-end` |
| `--c-steps-navigation-ink-bg` | 公开 | `var(--c-sys-color-content-brand)` | 本组件 CSS<br>`background-color` |
| `--c-steps-navigation-ink-height` | 公开 | `var(--c-border-width-2)` | 本组件 CSS<br>`height` |
| `--c-steps-navigation-ink-spacing-left` | 公开 | `var(--c-spacing-none)` | 本组件 CSS<br>`inset-inline-start` |
| `--c-steps-navigation-ink-spacing-right` | 公开 | `30px` | 本组件 CSS<br>`inset-inline-end` |
| `--c-steps-navigation-margin-right` | 公开 | `var(--c-spacing-10)` | 本组件 CSS<br>`margin-inline-end` |
| `--c-steps-navigation-padding-left` | 公开 | `var(--c-spacing-8)` | 本组件 CSS<br>`padding-inline-start` |
| `--c-steps-node-font-weight` | 公开 | `var(--c-font-weight-500)` | 本组件 CSS<br>`font-weight` |
| `--c-steps-size-md` | 公开 | `var(--c-size-7)` | 本组件 CSS<br>`height`, `inset-inline-start`, `line-height`, `margin-inline-start`, `margin-top`, `padding`, `padding-inline-end`, `top`, `width` |
| `--c-steps-size-md-arrow` | 公开 | `var(--c-size-18)` | 本组件 CSS<br>`border-bottom`, `border-inline-start`, `border-top`, `height`, `inset-inline-end`, `padding-inline-start` |
| `--c-steps-size-md-description-font-size` | 公开 | `var(--c-font-size-body-1)` | 本组件 CSS<br>`font-size` |
| `--c-steps-size-md-icon-font-size` | 公开 | `var(--c-size-4)` | 本组件 CSS<br>`font-size` |
| `--c-steps-size-md-item-icon-margin-left` | 公开 | `calc((var(--c-steps-label-vertical-content-width) - var(--c-steps-size-md)) / 2)` | 本组件 CSS<br>`inset-inline-start`, `margin-inline-start` |
| `--c-steps-size-md-title-font-size` | 公开 | `var(--c-font-size-title-1)` | 本组件 CSS<br>`font-size` |
| `--c-steps-size-sm` | 公开 | `var(--c-size-6)` | 本组件 CSS<br>`height`, `inset-inline-start`, `line-height`, `margin-inline-start`, `padding`, `padding-inline-end`, `top`, `width` |
| `--c-steps-size-sm-arrow` | 公开 | `var(--c-size-10)` | 本组件 CSS<br>`border-bottom`, `border-inline-start`, `border-top`, `height`, `inset-inline-end`, `padding-inline-start` |
| `--c-steps-size-sm-description-font-size` | 公开 | `var(--c-font-size-body-1)` | 本组件 CSS<br>`font-size` |
| `--c-steps-size-sm-icon-font-size` | 公开 | `var(--c-font-size-body-3)` | 本组件 CSS<br>`font-size` |
| `--c-steps-size-sm-item-icon-margin-left` | 公开 | `calc((var(--c-steps-label-vertical-content-width) - var(--c-steps-size-sm)) / 2)` | 本组件 CSS<br>`inset-inline-start`, `margin-inline-start` |
| `--c-steps-size-sm-title-font-size` | 公开 | `var(--c-font-size-body-3)` | 本组件 CSS<br>`font-size` |
| `--c-steps-transition-duration-1` | 公开 | `var(--c-transition-duration-1)` | 本组件 CSS<br>`transition` |
| `--c-steps-transition-timing-function-linear` | 公开 | `var(--c-transition-timing-function-linear)` | 本组件 CSS<br>`transition` |
| `--c-steps-vertical-item-min-height` | 公开 | `90px` | 本组件 CSS<br>`min-height` |

</div>

## switch

声明来源: `src/switch/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-switch-disabled-opacity` | 公开 | `0.5` | 本组件 CSS<br>`opacity` |
| `--c-switch-duration` | 公开 | `var(--c-sys-motion-duration-standard)` | 本组件 CSS<br>`transition` |
| `--c-switch-focus-width` | 公开 | `2px` | 本组件 CSS<br>`outline`, `outline-offset` |
| `--c-switch-font-size` | 公开 | `var(--c-sys-font-size-xs)` | 本组件 CSS<br>`font-size` |
| `--c-switch-gap` | 公开 | `var(--c-sys-space-2)` | 本组件 CSS<br>`inset-inline-start`, `padding-inline` |
| `--c-switch-handle-background` | 公开 | `var(--c-sys-color-surface-default)` | 本组件 CSS<br>`background` |
| `--c-switch-handle-color` | 公开 | `var(--c-sys-color-content-brand)` | 本组件 CSS<br>`color` |
| `--c-switch-handle-size` | 公开 | `16px` | 本组件 CSS<br>`height`, `inset-inline-start`, `padding-inline`, `width` |
| `--c-switch-height` | 公开 | `24px` | 本组件 CSS<br>`height` |
| `--c-switch-hit-area` | 公开 | `0px` | 本组件 CSS<br>`inset` |
| `--c-switch-line-handle-size` | 公开 | `20px` | 本组件 CSS<br>`height`, `inset-inline-start`, `padding-inline`, `width` |
| `--c-switch-line-height` | 公开 | `12px` | 本组件 CSS<br>`height` |
| `--c-switch-loading-duration` | 公开 | `1s` | 本组件 CSS<br>`animation` |
| `--c-switch-radius` | 公开 | `var(--c-sys-radius-pill)` | 本组件 CSS<br>`border-radius` |
| `--c-switch-ripple-duration` | 公开 | `400ms` | 本组件 CSS<br>`animation` |
| `--c-switch-ripple-scale` | 公开 | `2.4` | 本组件 CSS<br>`transform` |
| `--c-switch-round-radius` | 公开 | `var(--c-sys-radius-md)` | 本组件 CSS<br>`border-radius` |
| `--c-switch-shadow-color` | 公开 | `#0003` | 运行时引用（不代表可见性证明）<br>`switch/Switch.vue` |
| `--c-switch-size-lg-scale` | 公开 | `1.2` | 本组件 CSS<br>`font-size`, `height`, `inset-inline-start`, `min-width`, `padding-inline`, `width` |
| `--c-switch-size-sm-scale` | 公开 | `0.8` | 本组件 CSS<br>`font-size`, `height`, `inset-inline-start`, `min-width`, `padding-inline`, `width` |
| `--c-switch-text-color` | 公开 | `var(--c-sys-color-surface-default)` | 本组件 CSS<br>`color` |
| `--c-switch-tonal-border-color` | 公开 | `var(--c-sys-color-content-secondary)` | 本组件 CSS<br>`background`, `border` |
| `--c-switch-tonal-border-width` | 公开 | `2px` | 本组件 CSS<br>`border` |
| `--c-switch-tonal-handle-color` | 公开 | `var(--c-sys-color-surface-default)` | 本组件 CSS<br>`color` |
| `--c-switch-tonal-handle-size` | 公开 | `24px` | 本组件 CSS<br>`height`, `inset-inline-start`, `padding-inline`, `width` |
| `--c-switch-tonal-height` | 公开 | `32px` | 本组件 CSS<br>`height` |
| `--c-switch-tonal-text-color` | 公开 | `var(--c-sys-color-content-secondary)` | 本组件 CSS<br>`color` |
| `--c-switch-tonal-track-background` | 公开 | `var(--c-sys-color-surface-muted)` | 本组件 CSS<br>`background` |
| `--c-switch-tonal-width` | 公开 | `52px` | 本组件 CSS<br>`min-width` |
| `--c-switch-track-active-background` | 公开 | `var(--c-sys-color-content-brand)` | 本组件 CSS<br>`background`, `outline` |
| `--c-switch-track-background` | 公开 | `var(--c-sys-color-content-secondary)` | 本组件 CSS<br>`background` |
| `--c-switch-track-error-background` | 公开 | `var(--c-sys-color-content-danger)` | 本组件 CSS<br>`background`, `border-color` |
| `--c-switch-width` | 公开 | `40px` | 本组件 CSS<br>`min-width` |

</div>

## table

声明来源: `src/table/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-table-body-bg` | 公开 | `var(--c-color-bg-2)` | 本组件 CSS<br>`background-color` |
| `--c-table-body-cell-bg` | 公开 | `var(--c-color-bg-2)` | 本组件 CSS<br>`background-color` |
| `--c-table-body-cell-text-color` | 公开 | `rgb(var(--c-gray-10))` | 本组件 CSS<br>`color` |
| `--c-table-body-min-height` | 公开 | `40px` | 本组件 CSS<br>`min-height` |
| `--c-table-body-row-active-bg` | 公开 | `var(--c-color-fill-1)` | 本组件 CSS<br>`background-color` |
| `--c-table-body-row-active-dark-bg` | 公开 | `var(--c-color-neutral-2)` | 本组件 CSS<br>`background-color` |
| `--c-table-body-row-hover-bg` | 公开 | `var(--c-color-fill-1)` | 本组件 CSS<br>`background-color` |
| `--c-table-body-sorted-cell-bg` | 公开 | `var(--c-color-fill-1)` | 本组件 CSS<br>`background-color` |
| `--c-table-body-stripe-row-bg` | 公开 | `var(--c-color-fill-1)` | 本组件 CSS<br>`background-color` |
| `--c-table-border-color` | 公开 | `var(--c-color-neutral-3)` | 本组件 CSS<br>`border`, `border-bottom`, `border-left`, `border-right`, `border-top`, `box-shadow` |
| `--c-table-border-radius` | 公开 | `var(--c-border-radius-md)` | 本组件 CSS<br>`border-radius`, `border-top-left-radius`, `border-top-right-radius` |
| `--c-table-border-style` | 公开 | `solid` | 本组件 CSS<br>`border`, `border-bottom`, `border-left`, `border-right`, `border-top` |
| `--c-table-border-width` | 公开 | `var(--c-border-width-1)` | 本组件 CSS<br>`border`, `border-bottom`, `border-left`, `border-right`, `border-top`, `bottom`, `box-shadow`, `margin` |
| `--c-table-column-handle-right` | 公开 | `-4px` | 本组件 CSS<br>`inset-inline-end` |
| `--c-table-column-handle-width` | 公开 | `8px` | 本组件 CSS<br>`width` |
| `--c-table-column-insert-empty-font-size` | 公开 | `14px` | 本组件 CSS<br>`font-size` |
| `--c-table-column-insert-empty-line-height` | 公开 | `22px` | 本组件 CSS<br>`line-height` |
| `--c-table-column-insert-empty-text-color` | 公开 | `var(--c-color-text-3)` | 本组件 CSS<br>`color` |
| `--c-table-column-insert-group-margin-top` | 公开 | `16px` | 本组件 CSS<br>`margin-top` |
| `--c-table-column-insert-group-title-font-size` | 公开 | `12px` | 本组件 CSS<br>`font-size` |
| `--c-table-column-insert-group-title-line-height` | 公开 | `20px` | 本组件 CSS<br>`line-height` |
| `--c-table-column-insert-group-title-margin-bottom` | 公开 | `8px` | 本组件 CSS<br>`margin-bottom` |
| `--c-table-column-insert-group-title-text-color` | 公开 | `var(--c-color-text-3)` | 本组件 CSS<br>`color` |
| `--c-table-column-insert-item-min-height` | 公开 | `32px` | 本组件 CSS<br>`min-height` |
| `--c-table-column-insert-max-height` | 公开 | `calc(100vh - 160px)` | 本组件 CSS<br>`max-height` |
| `--c-table-column-insert-padding` | 公开 | `16px 20px` | 本组件 CSS<br>`padding` |
| `--c-table-drag-handle-col-width` | 公开 | `40px` | 本组件 CSS<br>`max-width`, `min-width`, `width` |
| `--c-table-editable-body-cell-border-color` | 公开 | `var(--c-color-white)` | 本组件 CSS<br>`border` |
| `--c-table-expand-button-border-radius` | 公开 | `2px` | 本组件 CSS<br>`border-radius` |
| `--c-table-expand-button-font-size` | 公开 | `12px` | 本组件 CSS<br>`font-size` |
| `--c-table-expand-button-margin-right` | 公开 | `var(--c-spacing-2)` | 本组件 CSS<br>`margin-inline-end` |
| `--c-table-expand-button-size` | 公开 | `14px` | 本组件 CSS<br>`height`, `line-height`, `width` |
| `--c-table-expand-content-bg` | 公开 | `var(--c-color-fill-1)` | 本组件 CSS<br>`background-color` |
| `--c-table-expand-content-hover-bg` | 公开 | `var(--c-color-fill-1)` | 本组件 CSS<br>`background-color` |
| `--c-table-expand-icon-bg` | 公开 | `var(--c-color-neutral-3)` | 本组件 CSS<br>`background-color` |
| `--c-table-expand-icon-border-color` | 公开 | `transparent` | 本组件 CSS<br>`border` |
| `--c-table-expand-icon-border-width` | 公开 | `var(--c-border-width-1)` | 本组件 CSS<br>`border` |
| `--c-table-expand-icon-col-width` | 公开 | `40px` | 本组件 CSS<br>`max-width`, `min-width`, `width` |
| `--c-table-expand-icon-color` | 公开 | `var(--c-color-text-2)` | 本组件 CSS<br>`color` |
| `--c-table-expand-icon-hover-bg` | 公开 | `var(--c-color-neutral-4)` | 本组件 CSS<br>`background-color` |
| `--c-table-expand-icon-hover-border-color` | 公开 | `transparent` | 本组件 CSS<br>`border-color` |
| `--c-table-expand-icon-hover-color` | 公开 | `var(--c-color-text-1)` | 本组件 CSS<br>`color` |
| `--c-table-expand-loading-icon-color` | 公开 | `var(--c-sys-color-content-brand)` | 本组件 CSS<br>`color` |
| `--c-table-extra-column-icon-color` | 公开 | `var(--c-color-text-2)` | 本组件 CSS<br>`color` |
| `--c-table-extra-column-icon-hover-color` | 公开 | `var(--c-color-text-1)` | 本组件 CSS<br>`color` |
| `--c-table-filters-bottom-gap` | 公开 | `8px` | 本组件 CSS<br>`margin-right` |
| `--c-table-filters-bottom-height` | 公开 | `38px` | 本组件 CSS<br>`height` |
| `--c-table-filters-bottom-line-height` | 公开 | `38px` | 本组件 CSS<br>`line-height` |
| `--c-table-filters-bottom-padding` | 公开 | `0 12px` | 本组件 CSS<br>`padding` |
| `--c-table-filters-icon-font-size` | 公开 | `16px` | 本组件 CSS<br>`font-size` |
| `--c-table-filters-icon-hover-bg` | 公开 | `var(--c-color-fill-4)` | 本组件 CSS<br>`background` |
| `--c-table-filters-item-font-size` | 公开 | `14px` | 本组件 CSS<br>`font-size` |
| `--c-table-filters-item-height` | 公开 | `32px` | 本组件 CSS<br>`height` |
| `--c-table-filters-item-line-height` | 公开 | `32px` | 本组件 CSS<br>`line-height` |
| `--c-table-filters-item-padding` | 公开 | `0 12px` | 本组件 CSS<br>`padding` |
| `--c-table-filters-list-padding` | 公开 | `4px 0` | 本组件 CSS<br>`padding` |
| `--c-table-filters-popup-bg` | 公开 | `var(--c-color-bg-5)` | 本组件 CSS<br>`background` |
| `--c-table-filters-popup-border-color` | 公开 | `var(--c-color-neutral-3)` | 本组件 CSS<br>`border` |
| `--c-table-filters-popup-border-radius` | 公开 | `var(--c-border-radius-md)` | 本组件 CSS<br>`border-radius` |
| `--c-table-filters-popup-box-shadow` | 公开 | `var(--c-shadow1-down)` | 本组件 CSS<br>`box-shadow` |
| `--c-table-filters-popup-max-height` | 公开 | `200px` | 本组件 CSS<br>`max-height` |
| `--c-table-filters-popup-min-width` | 公开 | `100px` | 本组件 CSS<br>`min-width` |
| `--c-table-filters-text-height` | 公开 | `34px` | 本组件 CSS<br>`height` |
| `--c-table-filters-text-line-height` | 公开 | `32px` | 本组件 CSS<br>`line-height` |
| `--c-table-filters-text-max-width` | 公开 | `160px` | 本组件 CSS<br>`max-width` |
| `--c-table-filters-text-padding-left` | 公开 | `10px` | 本组件 CSS<br>`padding-left` |
| `--c-table-filters-width` | 公开 | `24px` | 本组件 CSS<br>`width` |
| `--c-table-header-cell-action-color` | 公开 | `var(--c-color-text-3)` | 本组件 CSS<br>`color` |
| `--c-table-header-cell-action-hover-color` | 公开 | `var(--c-color-text-1)` | 本组件 CSS<br>`color` |
| `--c-table-header-cell-action-margin-left` | 公开 | `2px` | 本组件 CSS<br>`margin-inline-start` |
| `--c-table-header-cell-bg` | 公开 | `var(--c-color-neutral-2)` | 本组件 CSS<br>`background-color` |
| `--c-table-header-cell-text-color` | 公开 | `rgb(var(--c-gray-10))` | 本组件 CSS<br>`color` |
| `--c-table-header-filters-icon-active-color` | 公开 | `var(--c-sys-color-content-brand)` | 本组件 CSS<br>`color` |
| `--c-table-header-filters-icon-color` | 公开 | `var(--c-color-text-2)` | 本组件 CSS<br>`color` |
| `--c-table-header-filters-icon-hover-bg` | 公开 | `var(--c-color-neutral-4)` | 本组件 CSS<br>`background-color` |
| `--c-table-header-sorted-cell-bg` | 公开 | `var(--c-color-neutral-3)` | 本组件 CSS<br>`background-color` |
| `--c-table-header-sorted-cell-hover-bg` | 公开 | `rgba(var(--c-gray-4), 0.5)` | 本组件 CSS<br>`background-color` |
| `--c-table-header-sorter-icon-active-color` | 公开 | `var(--c-sys-color-content-brand)` | 本组件 CSS<br>`color` |
| `--c-table-header-sorter-icon-color` | 公开 | `var(--c-color-neutral-5)` | 本组件 CSS<br>`color` |
| `--c-table-header-sorter-icon-down-top` | 公开 | `-3px` | 本组件 CSS<br>`top` |
| `--c-table-header-sorter-icon-font-size` | 公开 | `12px` | 本组件 CSS<br>`font-size` |
| `--c-table-header-sorter-icon-height` | 公开 | `8px` | 本组件 CSS<br>`height`, `line-height` |
| `--c-table-header-sorter-icon-left` | 公开 | `1px` | 本组件 CSS<br>`left` |
| `--c-table-header-sorter-icon-margin-left` | 公开 | `var(--c-spacing-4)` | 本组件 CSS<br>`margin-inline-start` |
| `--c-table-header-sorter-icon-next-color` | 公开 | `var(--c-color-neutral-6)` | 本组件 CSS<br>`color` |
| `--c-table-header-sorter-icon-up-top` | 公开 | `-2px` | 本组件 CSS<br>`top` |
| `--c-table-header-sorter-icon-width` | 公开 | `14px` | 本组件 CSS<br>`width` |
| `--c-table-header-text-font-weight` | 公开 | `var(--c-font-weight-500)` | 本组件 CSS<br>`font-weight` |
| `--c-table-line-height` | 公开 | `var(--c-line-height)` | 本组件 CSS<br>`line-height` |
| `--c-table-pagination-margin` | 公开 | `var(--c-spacing-6)` | 本组件 CSS<br>`margin-bottom`, `margin-top` |
| `--c-table-pagination-sticky-bg` | 公开 | `var(--c-color-bg-1)` | 本组件 CSS<br>`background`, `background-color` |
| `--c-table-pagination-sticky-padding` | 公开 | `12px 0` | 本组件 CSS<br>`padding` |
| `--c-table-resizing-border-color` | 公开 | `var(--c-sys-color-content-brand)` | 本组件 CSS<br>`border-right-color` |
| `--c-table-selection-col-width` | 公开 | `40px` | 本组件 CSS<br>`max-width`, `min-width`, `width` |
| `--c-table-shadow-left` | 公开 | `inset 6px 0 8px -3px rgba(0, 0, 0, 0.15)` | 本组件 CSS<br>`box-shadow` |
| `--c-table-shadow-right` | 公开 | `inset -6px 0 8px -3px rgba(0, 0, 0, 0.15)` | 本组件 CSS<br>`box-shadow` |
| `--c-table-shadow-wrapper-width` | 公开 | `10px` | 本组件 CSS<br>`width` |
| `--c-table-size-lg-extra-icon-font-size` | 公开 | `16px` | 本组件 CSS<br>`font-size` |
| `--c-table-size-lg-extra-padding-horizontal` | 公开 | `var(--c-spacing-2)` | 本组件 CSS<br>`padding` |
| `--c-table-size-lg-font-size` | 公开 | `var(--c-table-size-md-font-size)` | 本组件 CSS<br>`font-size` |
| `--c-table-size-lg-header-font-size` | 公开 | `var(--c-table-size-md-header-font-size)` | 本组件 CSS<br>`font-size` |
| `--c-table-size-lg-padding-horizontal` | 公开 | `var(--c-table-size-md-padding-horizontal)` | 本组件 CSS<br>`margin`, `padding` |
| `--c-table-size-lg-padding-vertical` | 公开 | `var(--c-table-size-md-padding-vertical)` | 本组件 CSS<br>`margin`, `padding` |
| `--c-table-size-md-extra-icon-font-size` | 公开 | `16px` | 本组件 CSS<br>`font-size` |
| `--c-table-size-md-extra-padding-horizontal` | 公开 | `var(--c-spacing-2)` | 本组件 CSS<br>`padding` |
| `--c-table-size-md-font-size` | 公开 | `var(--c-font-size-body-3)` | 本组件 CSS<br>`font-size` |
| `--c-table-size-md-header-font-size` | 公开 | `var(--c-font-size-body-3)` | 本组件 CSS<br>`font-size` |
| `--c-table-size-md-padding-horizontal` | 公开 | `var(--c-spacing-7)` | 本组件 CSS<br>`margin`, `padding` |
| `--c-table-size-md-padding-vertical` | 公开 | `9px` | 本组件 CSS<br>`margin`, `padding` |
| `--c-table-size-sm-extra-icon-font-size` | 公开 | `14px` | 本组件 CSS<br>`font-size` |
| `--c-table-size-sm-extra-padding-horizontal` | 公开 | `var(--c-spacing-1)` | 本组件 CSS<br>`padding` |
| `--c-table-size-sm-font-size` | 公开 | `var(--c-font-size-body-3)` | 本组件 CSS<br>`font-size` |
| `--c-table-size-sm-header-font-size` | 公开 | `var(--c-font-size-body-3)` | 本组件 CSS<br>`font-size` |
| `--c-table-size-sm-padding-horizontal` | 公开 | `var(--c-spacing-7)` | 本组件 CSS<br>`margin`, `padding` |
| `--c-table-size-sm-padding-vertical` | 公开 | `5px` | 本组件 CSS<br>`margin`, `padding` |
| `--c-table-size-xs-extra-icon-font-size` | 公开 | `14px` | 本组件 CSS<br>`font-size` |
| `--c-table-size-xs-extra-padding-horizontal` | 公开 | `var(--c-spacing-1)` | 本组件 CSS<br>`padding` |
| `--c-table-size-xs-font-size` | 公开 | `var(--c-font-size-body-1)` | 本组件 CSS<br>`font-size` |
| `--c-table-size-xs-header-font-size` | 公开 | `var(--c-font-size-body-1)` | 本组件 CSS<br>`font-size` |
| `--c-table-size-xs-padding-horizontal` | 公开 | `var(--c-spacing-7)` | 本组件 CSS<br>`margin`, `padding` |
| `--c-table-size-xs-padding-vertical` | 公开 | `2px` | 本组件 CSS<br>`margin`, `padding` |
| `--c-table-sticky-scrollbar-height` | 公开 | `16px` | 本组件 CSS<br>`height` |
| `--c-table-sticky-scrollbar-opacity` | 公开 | `0.8` | 本组件 CSS<br>`opacity` |
| `--c-table-tfoot-bg` | 公开 | `var(--c-color-neutral-2)` | 本组件 CSS<br>`background-color` |
| `--c-table-th-actions-margin-left` | 公开 | `8px` | 本组件 CSS<br>`margin-inline-start` |
| `--c-table-transition-duration` | 公开 | `var(--c-transition-duration-1)` | 本组件 CSS<br>`transition` |
| `--c-table-transition-timing-function` | 公开 | `var(--c-transition-timing-function-linear)` | 本组件 CSS<br>`transition` |

</div>

## tabs

声明来源: `src/tabs/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-tabs-active-font-weight` | 公开 | `var(--c-sys-font-weight-semibold)` | 本组件 CSS<br>`font-weight` |
| `--c-tabs-active-shadow` | 公开 | `0 1px 3px rgba(0, 0, 0, 0.12)` | 本组件 CSS<br>`box-shadow` |
| `--c-tabs-animation-duration` | 公开 | `var(--c-sys-motion-duration-standard)` | 本组件 CSS<br>`animation` |
| `--c-tabs-background` | 公开 | `var(--c-sys-color-surface-default)` | 本组件 CSS<br>`background` |
| `--c-tabs-border-color` | 公开 | `var(--c-sys-color-border-default)` | 本组件 CSS<br>`background`, `border-color` |
| `--c-tabs-border-width` | 公开 | `1px` | 本组件 CSS<br>`border`, `bottom`, `height` |
| `--c-tabs-capsule-radius` | 公开 | `var(--c-sys-radius-pill)` | 本组件 CSS<br>`border-radius` |
| `--c-tabs-content-padding` | 公开 | `var(--c-sys-space-6)` | 本组件 CSS<br>`padding-block`, `padding-inline-start` |
| `--c-tabs-control-height` | 公开 | `var(--c-sys-control-height-xs)` | 本组件 CSS<br>`min-height`, `min-width` |
| `--c-tabs-focus-offset` | 公开 | `-3px` | 本组件 CSS<br>`outline-offset` |
| `--c-tabs-focus-width` | 公开 | `2px` | 本组件 CSS<br>`outline` |
| `--c-tabs-group-padding` | 公开 | `var(--c-sys-space-2)` | 本组件 CSS<br>`padding` |
| `--c-tabs-header-padding` | 公开 | `var(--c-sys-space-5)` | 本组件 CSS<br>`padding-inline` |
| `--c-tabs-hover-background` | 公开 | `var(--c-sys-color-state-hover)` | 本组件 CSS<br>`background` |
| `--c-tabs-icon-gap` | 公开 | `var(--c-sys-space-3)` | 本组件 CSS<br>`gap` |
| `--c-tabs-indicator-radius` | 公开 | `1px` | 本组件 CSS<br>`border-radius` |
| `--c-tabs-indicator-size` | 公开 | `2px` | 本组件 CSS<br>`height`, `width` |
| `--c-tabs-muted-background` | 公开 | `var(--c-sys-color-surface-muted)` | 本组件 CSS<br>`background` |
| `--c-tabs-nav-gap` | 公开 | `var(--c-sys-space-2)` | 本组件 CSS<br>`gap` |
| `--c-tabs-radius` | 公开 | `var(--c-sys-radius-md)` | 本组件 CSS<br>`border-radius` |
| `--c-tabs-size-lg-tab-font-size` | 公开 | `var(--c-sys-font-size-lg)` | 本组件 CSS<br>`font-size` |
| `--c-tabs-size-lg-tab-height` | 公开 | `var(--c-sys-control-height-lg)` | 本组件 CSS<br>`min-height` |
| `--c-tabs-size-lg-tab-padding` | 公开 | `10px var(--c-sys-space-7)` | 本组件 CSS<br>`padding` |
| `--c-tabs-size-md-tab-font-size` | 公开 | `var(--c-sys-font-size-md)` | 本组件 CSS<br>`font-size` |
| `--c-tabs-size-md-tab-height` | 公开 | `var(--c-sys-control-height-md)` | 本组件 CSS<br>`min-height` |
| `--c-tabs-size-md-tab-padding` | 公开 | `var(--c-sys-space-4) var(--c-sys-space-6)` | 本组件 CSS<br>`padding` |
| `--c-tabs-size-sm-tab-font-size` | 公开 | `var(--c-sys-font-size-sm)` | 本组件 CSS<br>`font-size` |
| `--c-tabs-size-sm-tab-height` | 公开 | `var(--c-sys-control-height-sm)` | 本组件 CSS<br>`min-height` |
| `--c-tabs-size-sm-tab-padding` | 公开 | `var(--c-sys-space-3) var(--c-sys-space-5)` | 本组件 CSS<br>`padding` |
| `--c-tabs-size-xl-tab-font-size` | 公开 | `var(--c-sys-font-size-xl)` | 本组件 CSS<br>`font-size` |
| `--c-tabs-size-xl-tab-height` | 公开 | `var(--c-sys-control-height-xl)` | 本组件 CSS<br>`min-height` |
| `--c-tabs-size-xl-tab-padding` | 公开 | `var(--c-sys-space-5) var(--c-sys-space-8)` | 本组件 CSS<br>`padding` |
| `--c-tabs-size-xs-tab-font-size` | 公开 | `var(--c-sys-font-size-xs)` | 本组件 CSS<br>`font-size` |
| `--c-tabs-size-xs-tab-height` | 公开 | `var(--c-sys-control-height-xs)` | 本组件 CSS<br>`min-height` |
| `--c-tabs-size-xs-tab-padding` | 公开 | `var(--c-sys-space-2) var(--c-sys-space-4)` | 本组件 CSS<br>`padding` |
| `--c-tabs-tab-gap` | 公开 | `var(--c-sys-space-2)` | 本组件 CSS<br>`gap` |
| `--c-tabs-title-text-color` | 公开 | `var(--c-sys-color-content-secondary)` | 本组件 CSS<br>`color` |
| `--c-tabs-title-text-color-active` | 公开 | `var(--c-sys-color-content-brand)` | 本组件 CSS<br>`background`, `color`, `outline` |
| `--c-tabs-title-text-color-disabled` | 公开 | `var(--c-sys-color-content-disabled)` | 本组件 CSS<br>`color` |
| `--c-tabs-touch-target` | 公开 | `var(--c-sys-control-touch-target)` | 本组件 CSS<br>`min-height`, `min-width` |

</div>

## tag

声明来源: `src/tag/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-tag-bg-not-checked-hover` | 公开 | `var(--c-sys-color-state-hover)` | 本组件 CSS<br>`background-color` |
| `--c-tag-blue-bg` | 公开 | `rgb(var(--c-blue-1))`<br>`rgba(var(--c-blue-6), 0.2)` (`:root[cedar-theme="dark"]`) | 本组件 CSS<br>`background-color` |
| `--c-tag-blue-bg-hover` | 公开 | `rgb(var(--c-blue-2))`<br>`rgba(var(--c-blue-6), 0.35)` (`:root[cedar-theme="dark"]`) | 本组件 CSS<br>`background-color` |
| `--c-tag-blue-border-color` | 公开 | `transparent` | 本组件 CSS<br>`border` |
| `--c-tag-blue-border-color-hover` | 公开 | `transparent` | 本组件 CSS<br>`border-color` |
| `--c-tag-blue-icon-color` | 公开 | `rgb(var(--c-blue-9))` | 本组件 CSS<br>`color` |
| `--c-tag-blue-text-color` | 公开 | `rgb(var(--c-blue-9))` | 本组件 CSS<br>`border-color`, `color` |
| `--c-tag-border-radius` | 公开 | `var(--c-sys-radius-sm)` | 本组件 CSS<br>`border-radius` |
| `--c-tag-border-type` | 公开 | `solid` | 本组件 CSS<br>`border` |
| `--c-tag-border-width` | 公开 | `1px` | 本组件 CSS<br>`border`, `line-height` |
| `--c-tag-brand-bg` | 公开 | `rgb(var(--c-brand-1))`<br>`rgba(var(--c-brand-6), 0.2)` (`:root[cedar-theme="dark"]`) | 本组件 CSS<br>`background-color` |
| `--c-tag-brand-bg-hover` | 公开 | `rgb(var(--c-brand-2))`<br>`rgba(var(--c-brand-6), 0.35)` (`:root[cedar-theme="dark"]`) | 本组件 CSS<br>`background-color` |
| `--c-tag-brand-border-color` | 公开 | `transparent` | 本组件 CSS<br>`border` |
| `--c-tag-brand-border-color-hover` | 公开 | `transparent` | 本组件 CSS<br>`border-color` |
| `--c-tag-brand-icon-color` | 公开 | `rgb(var(--c-brand-9))` | 本组件 CSS<br>`color` |
| `--c-tag-brand-text-color` | 公开 | `rgb(var(--c-brand-9))` | 本组件 CSS<br>`border-color`, `color` |
| `--c-tag-close-font-size` | 公开 | `var(--c-sys-font-size-xs)` | 本组件 CSS<br>`font-size` |
| `--c-tag-close-margin-left` | 公开 | `var(--c-spacing-2)` | 本组件 CSS<br>`margin-left`, `margin-right` |
| `--c-tag-custom-text-color` | 公开 | `var(--c-sys-color-content-on-dark)` | 本组件 CSS<br>`color` |
| `--c-tag-cyan-bg` | 公开 | `rgb(var(--c-cyan-1))`<br>`rgba(var(--c-cyan-6), 0.2)` (`:root[cedar-theme="dark"]`) | 本组件 CSS<br>`background-color` |
| `--c-tag-cyan-bg-hover` | 公开 | `rgb(var(--c-cyan-2))`<br>`rgba(var(--c-cyan-6), 0.35)` (`:root[cedar-theme="dark"]`) | 本组件 CSS<br>`background-color` |
| `--c-tag-cyan-border-color` | 公开 | `transparent` | 本组件 CSS<br>`border` |
| `--c-tag-cyan-border-color-hover` | 公开 | `transparent` | 本组件 CSS<br>`border-color` |
| `--c-tag-cyan-icon-color` | 公开 | `rgb(var(--c-cyan-9))` | 本组件 CSS<br>`color` |
| `--c-tag-cyan-text-color` | 公开 | `rgb(var(--c-cyan-9))` | 本组件 CSS<br>`border-color`, `color` |
| `--c-tag-default-bg` | 公开 | `var(--c-sys-color-state-hover)` | 本组件 CSS<br>`background-color` |
| `--c-tag-default-bg-hover` | 公开 | `var(--c-color-fill-3)` | 本组件 CSS<br>`background-color` |
| `--c-tag-default-border-color` | 公开 | `transparent` | 本组件 CSS<br>`border-color` |
| `--c-tag-default-border-color-hover` | 公开 | `transparent` | 本组件 CSS<br>`border-color` |
| `--c-tag-default-icon-color` | 公开 | `var(--c-sys-color-content-secondary)` | 本组件 CSS<br>`color` |
| `--c-tag-default-text-color` | 公开 | `var(--c-sys-color-content-primary)` | 本组件 CSS<br>`color` |
| `--c-tag-fade-duration` | 公开 | `var(--c-sys-motion-duration-fast)` | 本组件 CSS<br>`transition` |
| `--c-tag-gold-bg` | 公开 | `rgb(var(--c-gold-1))`<br>`rgba(var(--c-gold-6), 0.2)` (`:root[cedar-theme="dark"]`) | 本组件 CSS<br>`background-color` |
| `--c-tag-gold-bg-hover` | 公开 | `rgb(var(--c-gold-2))`<br>`rgba(var(--c-gold-6), 0.35)` (`:root[cedar-theme="dark"]`) | 本组件 CSS<br>`background-color` |
| `--c-tag-gold-border-color` | 公开 | `transparent` | 本组件 CSS<br>`border` |
| `--c-tag-gold-border-color-hover` | 公开 | `transparent` | 本组件 CSS<br>`border-color` |
| `--c-tag-gold-icon-color` | 公开 | `rgb(var(--c-gold-9))` | 本组件 CSS<br>`color` |
| `--c-tag-gold-text-color` | 公开 | `rgb(var(--c-gold-9))` | 本组件 CSS<br>`border-color`, `color` |
| `--c-tag-gray-bg` | 公开 | `rgb(var(--c-gray-2))`<br>`rgba(var(--c-gray-6), 0.2)` (`:root[cedar-theme="dark"]`) | 本组件 CSS<br>`background-color` |
| `--c-tag-gray-bg-hover` | 公开 | `rgb(var(--c-gray-3))`<br>`rgba(var(--c-gray-6), 0.35)` (`:root[cedar-theme="dark"]`) | 本组件 CSS<br>`background-color` |
| `--c-tag-gray-border-color` | 公开 | `transparent` | 本组件 CSS<br>`border` |
| `--c-tag-gray-border-color-hover` | 公开 | `transparent` | 本组件 CSS<br>`border-color` |
| `--c-tag-gray-icon-color` | 公开 | `var(--c-sys-color-content-secondary)` | 本组件 CSS<br>`color` |
| `--c-tag-gray-text-color` | 公开 | `var(--c-sys-color-content-secondary)` | 本组件 CSS<br>`border-color`, `color` |
| `--c-tag-green-bg` | 公开 | `rgb(var(--c-green-1))`<br>`rgba(var(--c-green-6), 0.2)` (`:root[cedar-theme="dark"]`) | 本组件 CSS<br>`background-color` |
| `--c-tag-green-bg-hover` | 公开 | `rgb(var(--c-green-2))`<br>`rgba(var(--c-green-6), 0.35)` (`:root[cedar-theme="dark"]`) | 本组件 CSS<br>`background-color` |
| `--c-tag-green-border-color` | 公开 | `transparent` | 本组件 CSS<br>`border` |
| `--c-tag-green-border-color-hover` | 公开 | `transparent` | 本组件 CSS<br>`border-color` |
| `--c-tag-green-icon-color` | 公开 | `rgb(var(--c-green-9))` | 本组件 CSS<br>`color` |
| `--c-tag-green-text-color` | 公开 | `rgb(var(--c-green-9))` | 本组件 CSS<br>`border-color`, `color` |
| `--c-tag-icon-margin-right` | 公开 | `var(--c-spacing-2)` | 本组件 CSS<br>`margin-left`, `margin-right` |
| `--c-tag-lime-bg` | 公开 | `rgb(var(--c-lime-1))`<br>`rgba(var(--c-lime-6), 0.2)` (`:root[cedar-theme="dark"]`) | 本组件 CSS<br>`background-color` |
| `--c-tag-lime-bg-hover` | 公开 | `rgb(var(--c-lime-2))`<br>`rgba(var(--c-lime-6), 0.35)` (`:root[cedar-theme="dark"]`) | 本组件 CSS<br>`background-color` |
| `--c-tag-lime-border-color` | 公开 | `transparent` | 本组件 CSS<br>`border` |
| `--c-tag-lime-border-color-hover` | 公开 | `transparent` | 本组件 CSS<br>`border-color` |
| `--c-tag-lime-icon-color` | 公开 | `rgb(var(--c-lime-9))` | 本组件 CSS<br>`color` |
| `--c-tag-lime-text-color` | 公开 | `rgb(var(--c-lime-9))` | 本组件 CSS<br>`border-color`, `color` |
| `--c-tag-magenta-bg` | 公开 | `rgb(var(--c-magenta-1))`<br>`rgba(var(--c-magenta-6), 0.2)` (`:root[cedar-theme="dark"]`) | 本组件 CSS<br>`background-color` |
| `--c-tag-magenta-bg-hover` | 公开 | `rgb(var(--c-magenta-2))`<br>`rgba(var(--c-magenta-6), 0.35)` (`:root[cedar-theme="dark"]`) | 本组件 CSS<br>`background-color` |
| `--c-tag-magenta-border-color` | 公开 | `transparent` | 本组件 CSS<br>`border` |
| `--c-tag-magenta-border-color-hover` | 公开 | `transparent` | 本组件 CSS<br>`border-color` |
| `--c-tag-magenta-icon-color` | 公开 | `rgb(var(--c-magenta-9))` | 本组件 CSS<br>`color` |
| `--c-tag-magenta-text-color` | 公开 | `rgb(var(--c-magenta-9))` | 本组件 CSS<br>`border-color`, `color` |
| `--c-tag-orange-bg` | 公开 | `rgb(var(--c-orange-1))`<br>`rgba(var(--c-orange-6), 0.2)` (`:root[cedar-theme="dark"]`) | 本组件 CSS<br>`background-color` |
| `--c-tag-orange-bg-hover` | 公开 | `rgb(var(--c-orange-2))`<br>`rgba(var(--c-orange-6), 0.35)` (`:root[cedar-theme="dark"]`) | 本组件 CSS<br>`background-color` |
| `--c-tag-orange-border-color` | 公开 | `transparent` | 本组件 CSS<br>`border` |
| `--c-tag-orange-border-color-hover` | 公开 | `transparent` | 本组件 CSS<br>`border-color` |
| `--c-tag-orange-icon-color` | 公开 | `rgb(var(--c-orange-9))` | 本组件 CSS<br>`color` |
| `--c-tag-orange-text-color` | 公开 | `rgb(var(--c-orange-9))` | 本组件 CSS<br>`border-color`, `color` |
| `--c-tag-orangered-bg` | 公开 | `rgb(var(--c-orangered-1))`<br>`rgba(var(--c-orangered-6), 0.2)` (`:root[cedar-theme="dark"]`) | 本组件 CSS<br>`background-color` |
| `--c-tag-orangered-bg-hover` | 公开 | `rgb(var(--c-orangered-2))`<br>`rgba(var(--c-orangered-6), 0.35)` (`:root[cedar-theme="dark"]`) | 本组件 CSS<br>`background-color` |
| `--c-tag-orangered-border-color` | 公开 | `transparent` | 本组件 CSS<br>`border` |
| `--c-tag-orangered-border-color-hover` | 公开 | `transparent` | 本组件 CSS<br>`border-color` |
| `--c-tag-orangered-icon-color` | 公开 | `rgb(var(--c-orangered-9))` | 本组件 CSS<br>`color` |
| `--c-tag-orangered-text-color` | 公开 | `rgb(var(--c-orangered-9))` | 本组件 CSS<br>`border-color`, `color` |
| `--c-tag-padding-horizontal` | 公开 | `var(--c-spacing-4)` | 本组件 CSS<br>`padding` |
| `--c-tag-padding-vertical` | 公开 | `0` | 本组件 CSS<br>`line-height`, `padding` |
| `--c-tag-pinkpurple-bg` | 公开 | `rgb(var(--c-pinkpurple-1))`<br>`rgba(var(--c-pinkpurple-6), 0.2)` (`:root[cedar-theme="dark"]`) | 本组件 CSS<br>`background-color` |
| `--c-tag-pinkpurple-bg-hover` | 公开 | `rgb(var(--c-pinkpurple-2))`<br>`rgba(var(--c-pinkpurple-6), 0.35)` (`:root[cedar-theme="dark"]`) | 本组件 CSS<br>`background-color` |
| `--c-tag-pinkpurple-border-color` | 公开 | `transparent` | 本组件 CSS<br>`border` |
| `--c-tag-pinkpurple-border-color-hover` | 公开 | `transparent` | 本组件 CSS<br>`border-color` |
| `--c-tag-pinkpurple-icon-color` | 公开 | `rgb(var(--c-pinkpurple-9))` | 本组件 CSS<br>`color` |
| `--c-tag-pinkpurple-text-color` | 公开 | `rgb(var(--c-pinkpurple-9))` | 本组件 CSS<br>`border-color`, `color` |
| `--c-tag-purple-bg` | 公开 | `rgb(var(--c-purple-1))`<br>`rgba(var(--c-purple-6), 0.2)` (`:root[cedar-theme="dark"]`) | 本组件 CSS<br>`background-color` |
| `--c-tag-purple-bg-hover` | 公开 | `rgb(var(--c-purple-2))`<br>`rgba(var(--c-purple-6), 0.35)` (`:root[cedar-theme="dark"]`) | 本组件 CSS<br>`background-color` |
| `--c-tag-purple-border-color` | 公开 | `transparent` | 本组件 CSS<br>`border` |
| `--c-tag-purple-border-color-hover` | 公开 | `transparent` | 本组件 CSS<br>`border-color` |
| `--c-tag-purple-icon-color` | 公开 | `rgb(var(--c-purple-9))` | 本组件 CSS<br>`color` |
| `--c-tag-purple-text-color` | 公开 | `rgb(var(--c-purple-9))` | 本组件 CSS<br>`border-color`, `color` |
| `--c-tag-red-bg` | 公开 | `rgb(var(--c-red-1))`<br>`rgba(var(--c-red-6), 0.2)` (`:root[cedar-theme="dark"]`) | 本组件 CSS<br>`background-color` |
| `--c-tag-red-bg-hover` | 公开 | `rgb(var(--c-red-2))`<br>`rgba(var(--c-red-6), 0.35)` (`:root[cedar-theme="dark"]`) | 本组件 CSS<br>`background-color` |
| `--c-tag-red-border-color` | 公开 | `transparent` | 本组件 CSS<br>`border` |
| `--c-tag-red-border-color-hover` | 公开 | `transparent` | 本组件 CSS<br>`border-color` |
| `--c-tag-red-icon-color` | 公开 | `rgb(var(--c-red-9))` | 本组件 CSS<br>`color` |
| `--c-tag-red-text-color` | 公开 | `rgb(var(--c-red-9))` | 本组件 CSS<br>`border-color`, `color` |
| `--c-tag-round-radius` | 公开 | `100px` | 本组件 CSS<br>`border-radius` |
| `--c-tag-size-lg` | 公开 | `var(--c-size-7)` | 本组件 CSS<br>`height`, `line-height` |
| `--c-tag-size-lg-font-size` | 公开 | `var(--c-sys-font-size-md)` | 本组件 CSS<br>`font-size` |
| `--c-tag-size-md` | 公开 | `var(--c-size-6)` | 本组件 CSS<br>`height`, `line-height` |
| `--c-tag-size-md-font-size` | 公开 | `var(--c-sys-font-size-xs)` | 本组件 CSS<br>`font-size` |
| `--c-tag-size-sm` | 公开 | `var(--c-size-5)` | 本组件 CSS<br>`height`, `line-height` |
| `--c-tag-size-sm-font-size` | 公开 | `var(--c-sys-font-size-xs)` | 本组件 CSS<br>`font-size` |
| `--c-tag-size-xl` | 公开 | `var(--c-size-8)` | 本组件 CSS<br>`height`, `line-height` |
| `--c-tag-size-xl-font-size` | 公开 | `var(--c-sys-font-size-md)` | 本组件 CSS<br>`font-size` |
| `--c-tag-size-xs` | 公开 | `var(--c-size-4)` | 本组件 CSS<br>`height`, `line-height` |
| `--c-tag-size-xs-font-size` | 公开 | `var(--c-sys-font-size-xs)` | 本组件 CSS<br>`font-size` |
| `--c-tag-status-danger-bg-color` | 公开 | `rgb(var(--c-danger-1))` | 本组件 CSS<br>`background-color` |
| `--c-tag-status-danger-text-color` | 公开 | `var(--c-sys-color-content-danger)` | 本组件 CSS<br>`color` |
| `--c-tag-status-info-bg-color` | 公开 | `rgb(var(--c-blue-1))` | 本组件 CSS<br>`background-color` |
| `--c-tag-status-info-text-color` | 公开 | `var(--c-sys-color-content-info)` | 本组件 CSS<br>`color` |
| `--c-tag-status-primary-bg-color` | 公开 | `rgb(var(--c-primary-1))` | 本组件 CSS<br>`background-color` |
| `--c-tag-status-primary-text-color` | 公开 | `var(--c-sys-color-content-brand)` | 本组件 CSS<br>`color` |
| `--c-tag-status-secondary-bg-color` | 公开 | `rgb(var(--c-gray-2))` | 本组件 CSS<br>`background-color` |
| `--c-tag-status-secondary-text-color` | 公开 | `var(--c-sys-color-content-secondary)` | 本组件 CSS<br>`color` |
| `--c-tag-status-success-bg-color` | 公开 | `rgb(var(--c-success-1))` | 本组件 CSS<br>`background-color` |
| `--c-tag-status-success-text-color` | 公开 | `var(--c-sys-color-content-success)` | 本组件 CSS<br>`color` |
| `--c-tag-status-tertiary-bg-color` | 公开 | `rgb(var(--c-gray-1))` | 本组件 CSS<br>`background-color` |
| `--c-tag-status-tertiary-text-color` | 公开 | `var(--c-sys-color-content-secondary)` | 本组件 CSS<br>`color` |
| `--c-tag-status-warning-bg-color` | 公开 | `rgb(var(--c-warning-1))` | 本组件 CSS<br>`background-color` |
| `--c-tag-status-warning-text-color` | 公开 | `var(--c-sys-color-content-warning)` | 本组件 CSS<br>`color` |
| `--c-tag-text-font-weight` | 公开 | `var(--c-font-weight-500)` | 本组件 CSS<br>`font-weight` |
| `--c-tag-variant-outline-default-border-color` | 公开 | `var(--c-sys-color-border-default)` | 本组件 CSS<br>`border` |
| `--c-tag-variant-outline-default-color` | 公开 | `var(--c-sys-color-content-primary)` | 本组件 CSS<br>`color` |
| `--c-tag-variant-outline-status-danger-color` | 公开 | `var(--c-sys-color-content-danger)` | 本组件 CSS<br>`border`, `color` |
| `--c-tag-variant-outline-status-info-color` | 公开 | `var(--c-sys-color-content-info)` | 本组件 CSS<br>`border`, `color` |
| `--c-tag-variant-outline-status-primary-color` | 公开 | `var(--c-sys-color-content-brand)` | 本组件 CSS<br>`border`, `color` |
| `--c-tag-variant-outline-status-secondary-color` | 公开 | `var(--c-sys-color-content-secondary)` | 本组件 CSS<br>`border`, `color` |
| `--c-tag-variant-outline-status-success-color` | 公开 | `var(--c-sys-color-content-success)` | 本组件 CSS<br>`border`, `color` |
| `--c-tag-variant-outline-status-tertiary-color` | 公开 | `var(--c-sys-color-content-secondary)` | 本组件 CSS<br>`border`, `color` |
| `--c-tag-variant-outline-status-warning-color` | 公开 | `var(--c-sys-color-content-warning)` | 本组件 CSS<br>`border`, `color` |

</div>

## textarea

声明来源: `src/textarea/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-textarea-caret-color` | 公开 | `var(--c-field-caret-color)` | 本组件 CSS<br>`caret-color` |
| `--c-textarea-counter-color` | 公开 | `var(--c-sys-color-content-secondary)` | 本组件 CSS<br>`color` |
| `--c-textarea-counter-font-size` | 公开 | `var(--c-sys-font-size-xs)` | 本组件 CSS<br>`font-size` |
| `--c-textarea-counter-margin-top` | 公开 | `var(--c-sys-space-2)` | 本组件 CSS<br>`margin-block-start` |
| `--c-textarea-font-size` | 公开 | `var(--c-sys-font-size-md)` | 本组件 CSS<br>`font-size` |
| `--c-textarea-height` | 公开 | `auto` | 本组件 CSS<br>`height` |
| `--c-textarea-line-height` | 公开 | `var(--c-line-height)` | 本组件 CSS<br>`line-height` |
| `--c-textarea-min-height` | 公开 | `var(--c-sys-control-height-xl)` | 本组件 CSS<br>`min-height` |
| `--c-textarea-padding-horizontal` | 公开 | `var(--c-sys-space-3)` | 本组件 CSS<br>`padding` |
| `--c-textarea-padding-vertical` | 公开 | `var(--c-sys-space-1)` | 本组件 CSS<br>`padding` |
| `--c-textarea-placeholder-color` | 公开 | `var(--c-sys-color-content-secondary)` | 本组件 CSS<br>`color` |

</div>

## time/picker

声明来源: `src/time/picker/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-time-picker-border-color` | 公开 | `var(--c-color-neutral-3)` | 本组件 CSS<br>`border`, `border-bottom`, `border-right`, `border-top` |
| `--c-time-picker-border-radius` | 公开 | `var(--c-border-radius-md)` | 本组件 CSS<br>`border-radius` |
| `--c-time-picker-box-shadow` | 公开 | `var(--c-shadow1-down)` | 本组件 CSS<br>`box-shadow` |
| `--c-time-picker-cell-bg-active` | 公开 | `var(--c-color-fill-2)` | 本组件 CSS<br>`background-color` |
| `--c-time-picker-cell-bg-hover` | 公开 | `var(--c-color-fill-2)` | 本组件 CSS<br>`background-color` |
| `--c-time-picker-cell-font-size` | 公开 | `var(--c-font-size-body-3)` | 本组件 CSS<br>`font-size` |
| `--c-time-picker-cell-font-weight` | 公开 | `var(--c-font-weight-500)` | 本组件 CSS<br>`font-weight` |
| `--c-time-picker-cell-font-weight-active` | 公开 | `var(--c-font-weight-500)` | 本组件 CSS<br>`font-weight` |
| `--c-time-picker-cell-height` | 公开 | `var(--c-size-6)` | 本组件 CSS<br>`height`, `line-height` |
| `--c-time-picker-cell-padding-left` | 公开 | `var(--c-spacing-9)` | 本组件 CSS<br>`padding-left` |
| `--c-time-picker-cell-spacing` | 公开 | `var(--c-spacing-2)` | 本组件 CSS<br>`height`, `padding` |
| `--c-time-picker-cell-text-color` | 公开 | `var(--c-color-text-1)` | 本组件 CSS<br>`color` |
| `--c-time-picker-cell-text-color-disabled` | 公开 | `var(--c-color-text-4)` | 本组件 CSS<br>`color` |
| `--c-time-picker-column-height` | 公开 | `224px` | 本组件 CSS<br>`height` |
| `--c-time-picker-column-width` | 公开 | `var(--c-size-16)` | 本组件 CSS<br>`width` |
| `--c-time-picker-footer-extra-font-size` | 公开 | `var(--c-font-size-body-1)` | 本组件 CSS<br>`font-size` |
| `--c-time-picker-footer-padding` | 公开 | `var(--c-spacing-4)` | 本组件 CSS<br>`padding` |
| `--c-time-picker-popover-body-reserve` | 公开 | `128px` | 本组件 CSS<br>`height` |
| `--c-time-picker-popover-column-max-height` | 公开 | `224px` | 本组件 CSS<br>`height` |
| `--c-time-picker-popover-gap` | 公开 | `32px` | 本组件 CSS<br>`max-width` |
| `--c-time-picker-range-gap` | 公开 | `var(--c-spacing-6)` | 本组件 CSS<br>`gap` |
| `--c-time-picker-range-next-day-font-size` | 公开 | `var(--c-font-size-body-1)` | 本组件 CSS<br>`font-size` |
| `--c-time-picker-range-panel-title-gap` | 公开 | `var(--c-spacing-3)` | 本组件 CSS<br>`gap` |
| `--c-time-picker-range-panel-title-line-height` | 公开 | `22px` | 本组件 CSS<br>`line-height` |
| `--c-time-picker-range-panel-title-padding-horizontal` | 公开 | `var(--c-spacing-6)` | 本组件 CSS<br>`padding` |
| `--c-time-picker-range-panel-title-padding-vertical` | 公开 | `var(--c-spacing-3)` | 本组件 CSS<br>`padding` |
| `--c-time-picker-range-wrapper-padding` | 公开 | `var(--c-spacing-4)` | 本组件 CSS<br>`padding` |

</div>

## timeline

声明来源: `src/timeline/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-timeline-alternate-horizontal-min-height` | 公开 | `var(--c-size-50)` | 本组件 CSS<br>`min-height` |
| `--c-timeline-content-text-color` | 公开 | `var(--c-color-text-1)` | 本组件 CSS<br>`color` |
| `--c-timeline-dot-bg` | 公开 | `rgb(var(--c-primary-6))` | 本组件 CSS<br>`background-color`, `border`, `color` |
| `--c-timeline-dot-bg-hollow` | 公开 | `var(--c-color-bg-2)` | 本组件 CSS<br>`background-color` |
| `--c-timeline-dot-border-radius` | 公开 | `var(--c-border-radius-circle)` | 本组件 CSS<br>`border-radius` |
| `--c-timeline-dot-border-width-hollow` | 公开 | `var(--c-border-width-2)` | 本组件 CSS<br>`border` |
| `--c-timeline-dot-size-width` | 公开 | `var(--c-spacing-3)` | 本组件 CSS<br>`bottom`, `height`, `inset-inline-start`, `left`, `margin-left`, `margin-top`, `padding-bottom`, `padding-left`, `padding-right`, `padding-top`, `top`, `width` |
| `--c-timeline-font-content-size` | 公开 | `var(--c-font-size-body-3)` | 本组件 CSS<br>`bottom`, `font-size`, `height`, `line-height`, `top` |
| `--c-timeline-font-label-size` | 公开 | `var(--c-font-size-body-1)` | 本组件 CSS<br>`font-size` |
| `--c-timeline-horizontal-dot-content-height` | 公开 | `var(--c-spacing-3)` | 本组件 CSS<br>`height`, `line-height` |
| `--c-timeline-horizontal-margin-content-spacing` | 公开 | `var(--c-spacing-7)` | 本组件 CSS<br>`margin-bottom`, `margin-top`, `padding-bottom`, `padding-top` |
| `--c-timeline-horizontal-margin-line-left` | 公开 | `var(--c-spacing-3)` | 本组件 CSS<br>`inset-inline-start` |
| `--c-timeline-horizontal-margin-line-right` | 公开 | `var(--c-spacing-2)` | 本组件 CSS<br>`inset-inline-end` |
| `--c-timeline-item-min-height` | 公开 | `78px` | 本组件 CSS<br>`min-height` |
| `--c-timeline-label-relative-horizontal-margin` | 公开 | `var(--c-size-13)` | 本组件 CSS<br>`margin-bottom`, `margin-top` |
| `--c-timeline-label-relative-margin` | 公开 | `var(--c-size-25)` | 本组件 CSS<br>`margin-left`, `margin-right` |
| `--c-timeline-label-relative-max-width` | 公开 | `var(--c-size-25)` | 本组件 CSS<br>`max-width` |
| `--c-timeline-label-text-color` | 公开 | `var(--c-color-text-3)` | 本组件 CSS<br>`color` |
| `--c-timeline-line-bg` | 公开 | `var(--c-color-neutral-3)` | 本组件 CSS<br>`border-color` |
| `--c-timeline-size-line-width` | 公开 | `var(--c-border-width-1)` | 本组件 CSS<br>`border-left-width`, `border-top-width`, `height`, `width` |
| `--c-timeline-vertical-margin-content-bottom` | 公开 | `var(--c-spacing-2)` | 本组件 CSS<br>`margin-bottom` |
| `--c-timeline-vertical-margin-content-left` | 公开 | `var(--c-spacing-7)` | 本组件 CSS<br>`margin-left`, `margin-right`, `padding-left`, `padding-right` |
| `--c-timeline-vertical-margin-line-bottom` | 公开 | `var(--c-spacing-2)` | 本组件 CSS<br>`bottom` |
| `--c-timeline-vertical-margin-line-top` | 公开 | `var(--c-spacing-2)` | 本组件 CSS<br>`top` |

</div>

## tooltip

声明来源: `src/tooltip/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-tooltip-animation-duration` | 公开 | `var(--c-sys-motion-duration-standard)` | 本组件 CSS<br>`transition` |
| `--c-tooltip-background` | 公开 | `var(--c-sys-color-surface-tooltip)` | 本组件 CSS<br>`background-color` |
| `--c-tooltip-border-radius` | 公开 | `var(--c-sys-radius-md)` | 本组件 CSS<br>`border-radius` |
| `--c-tooltip-font-size` | 公开 | `var(--c-sys-font-size-md)` | 本组件 CSS<br>`font-size` |
| `--c-tooltip-line-height` | 公开 | `var(--c-line-height)` | 本组件 CSS<br>`line-height` |
| `--c-tooltip-max-width` | 公开 | `350px` | 本组件 CSS<br>`max-width` |
| `--c-tooltip-opacity` | 公开 | `1` | 本组件 CSS<br>`opacity` |
| `--c-tooltip-padding-horizontal` | 公开 | `var(--c-sys-space-6)` | 本组件 CSS<br>`padding` |
| `--c-tooltip-padding-vertical` | 公开 | `var(--c-sys-space-4)` | 本组件 CSS<br>`padding` |
| `--c-tooltip-size-xs-font-size` | 公开 | `var(--c-sys-font-size-xs)` | 本组件 CSS<br>`font-size` |
| `--c-tooltip-size-xs-padding-horizontal` | 公开 | `var(--c-sys-space-4)` | 本组件 CSS<br>`padding` |
| `--c-tooltip-size-xs-padding-vertical` | 公开 | `var(--c-sys-space-2)` | 本组件 CSS<br>`padding` |
| `--c-tooltip-status-danger-background` | 公开 | `var(--c-sys-color-status-danger)` | 本组件 CSS<br>`background-color` |
| `--c-tooltip-status-danger-text-color` | 公开 | `var(--c-sys-color-content-on-dark)` | 本组件 CSS<br>`color` |
| `--c-tooltip-status-info-background` | 公开 | `var(--c-sys-color-status-info)` | 本组件 CSS<br>`background-color` |
| `--c-tooltip-status-info-text-color` | 公开 | `var(--c-sys-color-content-on-dark)` | 本组件 CSS<br>`color` |
| `--c-tooltip-status-primary-background` | 公开 | `var(--c-sys-color-action-primary)` | 本组件 CSS<br>`background-color` |
| `--c-tooltip-status-primary-text-color` | 公开 | `var(--c-sys-color-content-on-dark)` | 本组件 CSS<br>`color` |
| `--c-tooltip-status-success-background` | 公开 | `var(--c-sys-color-status-success)` | 本组件 CSS<br>`background-color` |
| `--c-tooltip-status-success-text-color` | 公开 | `var(--c-sys-color-content-on-dark)` | 本组件 CSS<br>`color` |
| `--c-tooltip-status-warning-background` | 公开 | `var(--c-sys-color-status-warning)` | 本组件 CSS<br>`background-color` |
| `--c-tooltip-status-warning-text-color` | 公开 | `var(--c-sys-color-content-on-dark)` | 本组件 CSS<br>`color` |
| `--c-tooltip-text-color` | 公开 | `var(--c-sys-color-content-on-dark)` | 本组件 CSS<br>`color` |

</div>

## transfer

声明来源: `src/transfer/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-transfer-border-color` | 公开 | `var(--c-color-neutral-3)` | 本组件 CSS<br>`border` |
| `--c-transfer-border-radius` | 公开 | `var(--c-border-radius-sm)` | 本组件 CSS<br>`border-radius` |
| `--c-transfer-border-width` | 公开 | `var(--c-border-width-1)` | 本组件 CSS<br>`border`, `margin-inline-start` |
| `--c-transfer-checkbox-padding-left` | 公开 | `var(--c-spacing-3)` | 本组件 CSS<br>`padding-inline-start` |
| `--c-transfer-clear-text-color` | 公开 | `var(--c-sys-color-content-brand)` | 本组件 CSS<br>`color` |
| `--c-transfer-draggable-list-padding-y` | 公开 | `var(--c-spacing-4)` | 本组件 CSS<br>`padding` |
| `--c-transfer-footer-height` | 公开 | `var(--c-size-10)` | 本组件 CSS<br>`height` |
| `--c-transfer-footer-padding-horizontal` | 公开 | `var(--c-spacing-4)` | 本组件 CSS<br>`inset-inline-end`, `padding` |
| `--c-transfer-group-title-font-weight` | 公开 | `var(--c-font-weight-500)` | 本组件 CSS<br>`font-weight` |
| `--c-transfer-group-title-height` | 公开 | `var(--c-size-9)` | 本组件 CSS<br>`height` |
| `--c-transfer-group-title-line-height` | 公开 | `var(--c-size-7)` | 本组件 CSS<br>`line-height` |
| `--c-transfer-group-title-padding-top` | 公开 | `var(--c-spacing-4)` | 本组件 CSS<br>`padding` |
| `--c-transfer-header-bg` | 公开 | `var(--c-color-fill-1)` | 本组件 CSS<br>`background-color` |
| `--c-transfer-header-count-margin-right` | 公开 | `var(--c-spacing-1)` | 本组件 CSS<br>`margin-inline-end` |
| `--c-transfer-header-flex-basis` | 公开 | `var(--c-size-11)` | 本组件 CSS<br>`flex` |
| `--c-transfer-header-font-size` | 公开 | `var(--c-font-size-body-3)` | 本组件 CSS<br>`font-size` |
| `--c-transfer-header-font-weight` | 公开 | `var(--c-font-weight-500)` | 本组件 CSS<br>`font-weight` |
| `--c-transfer-header-selected-count-margin-left` | 公开 | `var(--c-spacing-4)` | 本组件 CSS<br>`margin-inline-start` |
| `--c-transfer-header-text-color` | 公开 | `var(--c-color-text-1)` | 本组件 CSS<br>`color` |
| `--c-transfer-header-title-margin-right` | 公开 | `var(--c-spacing-4)` | 本组件 CSS<br>`margin-inline-end` |
| `--c-transfer-header-unit-font-size` | 公开 | `var(--c-font-size-body-1)` | 本组件 CSS<br>`font-size` |
| `--c-transfer-header-unit-text-color` | 公开 | `var(--c-color-text-3)` | 本组件 CSS<br>`color` |
| `--c-transfer-height` | 公开 | `400px` | 本组件 CSS<br>`height` |
| `--c-transfer-icon-bg` | 公开 | `var(--c-color-fill-3)` | 本组件 CSS<br>`background-color` |
| `--c-transfer-icon-color` | 公开 | `var(--c-color-text-2)` | 本组件 CSS<br>`color` |
| `--c-transfer-icon-font-size` | 公开 | `var(--c-font-size-body-1)` | 本组件 CSS<br>`font-size` |
| `--c-transfer-item-bg` | 公开 | `transparent` | 本组件 CSS<br>`background-color` |
| `--c-transfer-item-bg-disabled` | 公开 | `transparent` | 本组件 CSS<br>`background-color` |
| `--c-transfer-item-bg-hover` | 公开 | `var(--c-color-fill-2)` | 本组件 CSS<br>`background-color` |
| `--c-transfer-item-drag-handle-margin-right` | 公开 | `var(--c-spacing-4)` | 本组件 CSS<br>`margin-inline-end` |
| `--c-transfer-item-draggable-bg-blink` | 公开 | `var(--c-color-primary-light-1)` | 本组件 CSS<br>`background-color` |
| `--c-transfer-item-draggable-bg-dragging` | 公开 | `var(--c-color-fill-1)` | 本组件 CSS<br>`background-color` |
| `--c-transfer-item-draggable-gap-bg` | 公开 | `rgb(var(--c-primary-6))` | 本组件 CSS<br>`background-color` |
| `--c-transfer-item-draggable-gap-height` | 公开 | `var(--c-spacing-1)` | 本组件 CSS<br>`border-radius`, `bottom`, `height`, `top` |
| `--c-transfer-item-draggable-text-color-dragging` | 公开 | `var(--c-color-text-4)` | 本组件 CSS<br>`color` |
| `--c-transfer-item-font-size` | 公开 | `var(--c-font-size-body-3)` | 本组件 CSS<br>`font-size` |
| `--c-transfer-item-height` | 公开 | `var(--c-size-9)` | 本组件 CSS<br>`height`, `line-height` |
| `--c-transfer-item-padding-horizontal` | 公开 | `var(--c-spacing-5)` | 本组件 CSS<br>`padding` |
| `--c-transfer-item-text-color` | 公开 | `var(--c-color-text-1)` | 本组件 CSS<br>`color` |
| `--c-transfer-item-text-color-disabled` | 公开 | `var(--c-color-text-4)` | 本组件 CSS<br>`color` |
| `--c-transfer-item-text-color-hover` | 公开 | `var(--c-color-text-1)` | 本组件 CSS<br>`color` |
| `--c-transfer-item-tip-margin-left` | 公开 | `var(--c-spacing-4)` | 本组件 CSS<br>`margin-inline-start` |
| `--c-transfer-operation-buttons-gap` | 公开 | `var(--c-spacing-6)` | 本组件 CSS<br>`margin-top` |
| `--c-transfer-operation-menu-button-border-radius` | 公开 | `var(--c-border-radius-md)` | 本组件 CSS<br>`border-radius` |
| `--c-transfer-operation-menu-button-padding-x` | 公开 | `var(--c-spacing-6)` | 本组件 CSS<br>`padding` |
| `--c-transfer-operation-menu-button-padding-y` | 公开 | `7px` | 本组件 CSS<br>`padding` |
| `--c-transfer-operation-menu-min-width` | 公开 | `140px` | 本组件 CSS<br>`min-width` |
| `--c-transfer-operation-menu-padding` | 公开 | `var(--c-spacing-2)` | 本组件 CSS<br>`padding` |
| `--c-transfer-operation-padding-horizontal` | 公开 | `var(--c-spacing-8)` | 本组件 CSS<br>`padding` |
| `--c-transfer-operation-words-button-padding-x` | 公开 | `var(--c-spacing-6)` | 本组件 CSS<br>`padding` |
| `--c-transfer-pagination-input-width` | 公开 | `var(--c-size-6)` | 本组件 CSS<br>`width` |
| `--c-transfer-pagination-separator-gap` | 公开 | `var(--c-spacing-4)` | 本组件 CSS<br>`padding` |
| `--c-transfer-search-padding-bottom` | 公开 | `var(--c-spacing-2)` | 本组件 CSS<br>`padding-block` |
| `--c-transfer-search-padding-left` | 公开 | `var(--c-spacing-6)` | 本组件 CSS<br>`padding-inline` |
| `--c-transfer-search-padding-right` | 公开 | `var(--c-spacing-6)` | 本组件 CSS<br>`padding-inline` |
| `--c-transfer-search-padding-top` | 公开 | `var(--c-spacing-4)` | 本组件 CSS<br>`padding-block` |
| `--c-transfer-title-height` | 公开 | `var(--c-size-10)` | 本组件 CSS<br>`height`, `line-height` |
| `--c-transfer-transition-timing-function-linear` | 公开 | `var(--c-transition-timing-function-linear)` | 本组件 CSS<br>`animation-timing-function` |

</div>

## tree

声明来源: `src/tree/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-tree-checkbox-margin-right` | 公开 | `var(--c-spacing-5)` | 本组件 CSS<br>`margin-inline-end` |
| `--c-tree-custom-icon-margin-right` | 公开 | `var(--c-spacing-5)` | 本组件 CSS<br>`margin-inline-end` |
| `--c-tree-drag-icon-color` | 公开 | `var(--c-sys-color-content-brand)` | 本组件 CSS<br>`color` |
| `--c-tree-drag-icon-spacing-right` | 公开 | `var(--c-spacing-6)` | 本组件 CSS<br>`inset-inline-end` |
| `--c-tree-drag-icon-spacing-text` | 公开 | `var(--c-spacing-22)` | 本组件 CSS<br>`margin-inline-start` |
| `--c-tree-draggable-gap-bg` | 公开 | `rgb(var(--c-primary-6))` | 本组件 CSS<br>`background-color` |
| `--c-tree-draggable-gap-height` | 公开 | `2px` | 本组件 CSS<br>`border-radius`, `bottom`, `height`, `margin-top`, `top` |
| `--c-tree-focus-outline-width` | 公开 | `2px` | 本组件 CSS<br>`outline` |
| `--c-tree-loading-icon-color` | 公开 | `var(--c-sys-color-content-brand)` | 本组件 CSS<br>`color` |
| `--c-tree-node-border-radius` | 公开 | `var(--c-border-radius-sm)` | 本组件 CSS<br>`border-radius` |
| `--c-tree-showline-line-bg` | 公开 | `var(--c-color-neutral-3)` | 本组件 CSS<br>`border-left` |
| `--c-tree-showline-line-spacing-vertical` | 公开 | `var(--c-spacing-2)` | 本组件 CSS<br>`bottom`, `top` |
| `--c-tree-showline-line-style` | 公开 | `solid` | 本组件 CSS<br>`border-left` |
| `--c-tree-showline-line-width` | 公开 | `var(--c-border-width-1)` | 本组件 CSS<br>`border-left`, `width` |
| `--c-tree-showline-plus-icon-bg` | 公开 | `var(--c-color-fill-2)` | 本组件 CSS<br>`background` |
| `--c-tree-showline-plus-icon-border-radius` | 公开 | `var(--c-border-radius-sm)` | 本组件 CSS<br>`border-radius` |
| `--c-tree-showline-plus-icon-stroke` | 公开 | `2px` | 本组件 CSS<br>`height`, `margin-left`, `margin-top`, `width` |
| `--c-tree-showline-plus-icon-width` | 公开 | `6px` | 本组件 CSS<br>`height`, `margin-left`, `margin-top`, `width` |
| `--c-tree-showline-switcher-icon-size` | 公开 | `14px` | 本组件 CSS<br>`bottom`, `height`, `inset-inline-end`, `padding-inline-start`, `top`, `width` |
| `--c-tree-size-expand-icon-bg-hover` | 公开 | `var(--c-size-4)` | 本组件 CSS<br>`height`, `padding-inline-start`, `width` |
| `--c-tree-size-lg-font-size` | 公开 | `var(--c-font-size-body-3)` | 本组件 CSS<br>`font-size` |
| `--c-tree-size-lg-icon-size` | 公开 | `var(--c-size-3)` | 本组件 CSS<br>`font-size`, `padding-inline-start`, `width` |
| `--c-tree-size-lg-line-height` | 公开 | `var(--c-size-lg)` | 本组件 CSS<br>`bottom`, `height`, `line-height`, `top` |
| `--c-tree-size-lg-title-padding-vertical` | 公开 | `10px` | 本组件 CSS<br>`padding-bottom`, `padding-top` |
| `--c-tree-size-md-font-size` | 公开 | `var(--c-font-size-body-3)` | 本组件 CSS<br>`font-size` |
| `--c-tree-size-md-icon-size` | 公开 | `var(--c-size-3)` | 本组件 CSS<br>`font-size`, `padding-inline-start`, `width` |
| `--c-tree-size-md-line-height` | 公开 | `var(--c-size-md)` | 本组件 CSS<br>`bottom`, `height`, `line-height`, `top` |
| `--c-tree-size-md-title-padding-vertical` | 公开 | `8px` | 本组件 CSS<br>`padding` |
| `--c-tree-size-sm-font-size` | 公开 | `var(--c-font-size-body-3)` | 本组件 CSS<br>`font-size` |
| `--c-tree-size-sm-icon-size` | 公开 | `var(--c-size-3)` | 本组件 CSS<br>`font-size`, `padding-inline-start`, `width` |
| `--c-tree-size-sm-line-height` | 公开 | `var(--c-size-sm)` | 本组件 CSS<br>`bottom`, `height`, `line-height`, `top` |
| `--c-tree-size-sm-title-padding-vertical` | 公开 | `6px` | 本组件 CSS<br>`padding-bottom`, `padding-top` |
| `--c-tree-size-xl-font-size` | 公开 | `var(--c-sys-font-size-lg)` | 本组件 CSS<br>`font-size` |
| `--c-tree-size-xl-icon-size` | 公开 | `var(--c-size-4)` | 本组件 CSS<br>`font-size`, `padding-inline-start`, `width` |
| `--c-tree-size-xl-line-height` | 公开 | `var(--c-size-xl)` | 本组件 CSS<br>`bottom`, `height`, `line-height`, `top` |
| `--c-tree-size-xl-title-padding-vertical` | 公开 | `12px` | 本组件 CSS<br>`padding-bottom`, `padding-top` |
| `--c-tree-size-xs-font-size` | 公开 | `var(--c-font-size-body-1)` | 本组件 CSS<br>`font-size` |
| `--c-tree-size-xs-icon-size` | 公开 | `var(--c-size-3)` | 本组件 CSS<br>`font-size`, `padding-inline-start`, `width` |
| `--c-tree-size-xs-line-height` | 公开 | `var(--c-size-xs)` | 本组件 CSS<br>`bottom`, `height`, `line-height`, `top` |
| `--c-tree-size-xs-title-padding-vertical` | 公开 | `2px` | 本组件 CSS<br>`padding-bottom`, `padding-top` |
| `--c-tree-switcher-icon-color` | 公开 | `var(--c-color-text-2)` | 本组件 CSS<br>`background-color`, `color` |
| `--c-tree-switcher-icon-margin-right` | 公开 | `var(--c-spacing-5)` | 本组件 CSS<br>`margin-inline-end` |
| `--c-tree-title-bg-dragging` | 公开 | `var(--c-color-fill-1)` | 本组件 CSS<br>`background-color` |
| `--c-tree-title-bg-highlight` | 公开 | `var(--c-color-primary-light-1)` | 本组件 CSS<br>`background-color` |
| `--c-tree-title-bg-hover` | 公开 | `var(--c-color-fill-2)` | 本组件 CSS<br>`background-color` |
| `--c-tree-title-padding-horizontal` | 公开 | `var(--c-spacing-2)` | 本组件 CSS<br>`margin-inline-start`, `padding-inline-end`, `padding-inline-start` |
| `--c-tree-title-text-color` | 公开 | `var(--c-color-text-1)` | 本组件 CSS<br>`color` |
| `--c-tree-title-text-color-active` | 公开 | `var(--c-sys-color-content-brand)` | 本组件 CSS<br>`color`, `outline`, `outline-color` |
| `--c-tree-title-text-color-active-disabled` | 公开 | `var(--c-color-primary-light-3)` | 本组件 CSS<br>`color` |
| `--c-tree-title-text-color-disabled` | 公开 | `var(--c-color-text-4)` | 本组件 CSS<br>`color` |
| `--c-tree-title-text-color-dragging` | 公开 | `var(--c-color-text-4)` | 本组件 CSS<br>`color` |
| `--c-tree-title-text-color-highlight` | 公开 | `var(--c-color-text-1)` | 本组件 CSS<br>`color` |
| `--c-tree-title-text-color-hover` | 公开 | `var(--c-color-text-1)` | 本组件 CSS<br>`color` |

</div>

## tree-select

声明来源: `src/tree-select/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-tree-select-highlight-font-weight` | 公开 | `var(--c-font-weight-500)` | 本组件 CSS<br>`font-weight` |
| `--c-tree-select-option-active-background` | 公开 | `var(--c-color-fill-2)` | 本组件 CSS<br>`background` |
| `--c-tree-select-option-radius` | 公开 | `var(--c-sys-radius-sm)` | 本组件 CSS<br>`border-radius` |
| `--c-tree-select-popup-padding-left` | 公开 | `var(--c-spacing-5)` | 本组件 CSS<br>`padding-inline-start` |
| `--c-tree-select-popup-padding-right` | 公开 | `var(--c-spacing-2)` | 本组件 CSS<br>`padding-inline-end` |
| `--c-tree-select-popup-padding-vertical` | 公开 | `var(--c-spacing-2)` | 本组件 CSS<br>`padding` |

</div>

## trigger

声明来源: `src/trigger/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-trigger-arrow-background` | 公开 | `var(--c-sys-color-surface-overlay)` | 本组件 CSS<br>`background-color` |
| `--c-trigger-arrow-radius` | 公开 | `var(--c-sys-radius-sm)` | 本组件 CSS<br>`border-radius` |
| `--c-trigger-arrow-size` | 公开 | `var(--c-sys-space-4)` | 本组件 CSS<br>`height`, `width` |
| `--c-trigger-transition-duration` | 公开 | `var(--c-sys-motion-duration-fast)` | 本组件 CSS<br>`transition` |
| `--c-trigger-transition-easing` | 公开 | `var(--c-sys-motion-easing-standard)` | 本组件 CSS<br>`transition` |

</div>

## typography

声明来源: `src/typography/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-typography-blockquote-bg` | 公开 | `var(--c-color-bg-2)` | 本组件 CSS<br>`background-color` |
| `--c-typography-blockquote-border-left-color` | 公开 | `var(--c-color-neutral-6)` | 本组件 CSS<br>`border-left` |
| `--c-typography-blockquote-border-width` | 公开 | `var(--c-border-width-2)` | 本组件 CSS<br>`border-left` |
| `--c-typography-blockquote-padding-left` | 公开 | `var(--c-spacing-4)` | 本组件 CSS<br>`padding-left` |
| `--c-typography-code-bg` | 公开 | `var(--c-color-neutral-2)` | 本组件 CSS<br>`background-color` |
| `--c-typography-code-border-color` | 公开 | `var(--c-color-neutral-3)` | 本组件 CSS<br>`border` |
| `--c-typography-code-border-radius` | 公开 | `var(--c-border-radius-sm)` | 本组件 CSS<br>`border-radius` |
| `--c-typography-code-text-color` | 公开 | `var(--c-color-text-2)` | 本组件 CSS<br>`color` |
| `--c-typography-edit-border-width` | 公开 | `var(--c-border-width-1)` | 本组件 CSS<br>`left`, `margin-bottom`, `margin-right`, `margin-top` |
| `--c-typography-edit-padding-x` | 公开 | `var(--c-spacing-6)` | 本组件 CSS<br>`left`, `margin-right` |
| `--c-typography-edit-padding-y` | 公开 | `var(--c-spacing-2)` | 本组件 CSS<br>`margin-bottom`, `margin-top` |
| `--c-typography-expand-margin-x` | 公开 | `var(--c-spacing-2)` | 本组件 CSS<br>`margin` |
| `--c-typography-expand-text-color` | 公开 | `var(--c-sys-color-content-brand)` | 本组件 CSS<br>`color` |
| `--c-typography-expand-text-color-hover` | 公开 | `rgb(var(--c-primary-5))` | 本组件 CSS<br>`color` |
| `--c-typography-font-size-h1` | 公开 | `var(--c-font-size-display-1)` | 本组件 CSS<br>`font-size` |
| `--c-typography-font-size-h2` | 公开 | `var(--c-size-8)` | 本组件 CSS<br>`font-size` |
| `--c-typography-font-size-h3` | 公开 | `var(--c-size-7)` | 本组件 CSS<br>`font-size` |
| `--c-typography-font-size-h4` | 公开 | `var(--c-font-size-title-3)` | 本组件 CSS<br>`font-size` |
| `--c-typography-font-size-h5` | 公开 | `var(--c-font-size-title-2)` | 本组件 CSS<br>`font-size` |
| `--c-typography-font-size-h6` | 公开 | `var(--c-font-size-title-1)` | 本组件 CSS<br>`font-size` |
| `--c-typography-heading-font-weight` | 公开 | `var(--c-font-weight-500)` | 本组件 CSS<br>`font-weight` |
| `--c-typography-heading-margin-bottom` | 公开 | `0` | 本组件 CSS<br>`margin-bottom` |
| `--c-typography-heading-margin-top` | 公开 | `0` | 本组件 CSS<br>`margin-top` |
| `--c-typography-icon-copy-bg` | 公开 | `transparent` | 本组件 CSS<br>`background-color` |
| `--c-typography-icon-copy-bg-hover` | 公开 | `var(--c-color-fill-2)` | 本组件 CSS<br>`background-color` |
| `--c-typography-icon-copy-color` | 公开 | `var(--c-color-text-2)` | 本组件 CSS<br>`color` |
| `--c-typography-icon-copy-color-copied` | 公开 | `var(--c-sys-color-content-success)` | 本组件 CSS<br>`color` |
| `--c-typography-icon-copy-color-hover` | 公开 | `var(--c-color-text-2)` | 本组件 CSS<br>`color` |
| `--c-typography-icon-edit-bg` | 公开 | `transparent` | 本组件 CSS<br>`background-color` |
| `--c-typography-icon-edit-bg-hover` | 公开 | `var(--c-color-fill-2)` | 本组件 CSS<br>`background-color` |
| `--c-typography-icon-edit-color` | 公开 | `var(--c-color-text-2)` | 本组件 CSS<br>`color` |
| `--c-typography-icon-edit-color-hover` | 公开 | `var(--c-color-text-2)` | 本组件 CSS<br>`color` |
| `--c-typography-list-item-margin-left` | 公开 | `var(--c-spacing-8)` | 本组件 CSS<br>`margin-left` |
| `--c-typography-operation-border-radius` | 公开 | `var(--c-border-radius-sm)` | 本组件 CSS<br>`border-radius` |
| `--c-typography-operation-margin-left` | 公开 | `var(--c-spacing-1)` | 本组件 CSS<br>`margin-left` |
| `--c-typography-operation-padding` | 公开 | `var(--c-spacing-1)` | 本组件 CSS<br>`padding` |
| `--c-typography-paragraph-line-height` | 公开 | `var(--c-line-height)` | 本组件 CSS<br>`line-height` |
| `--c-typography-paragraph-line-height-close` | 公开 | `1.3` | 本组件 CSS<br>`line-height` |
| `--c-typography-text-bg-mark` | 公开 | `rgb(var(--c-yellow-4))` | 本组件 CSS<br>`background-color` |
| `--c-typography-text-color` | 公开 | `var(--c-color-text-1)` | 本组件 CSS<br>`color` |
| `--c-typography-text-color-disabled` | 公开 | `var(--c-color-text-4)` | 本组件 CSS<br>`color` |
| `--c-typography-text-color-error` | 公开 | `var(--c-sys-color-content-danger)` | 本组件 CSS<br>`color` |
| `--c-typography-text-color-primary` | 公开 | `var(--c-sys-color-content-brand)` | 本组件 CSS<br>`color` |
| `--c-typography-text-color-secondary` | 公开 | `var(--c-color-text-2)` | 本组件 CSS<br>`color` |
| `--c-typography-text-color-success` | 公开 | `var(--c-sys-color-content-success)` | 本组件 CSS<br>`color` |
| `--c-typography-text-color-warning` | 公开 | `var(--c-sys-color-content-warning)` | 本组件 CSS<br>`color` |
| `--c-typography-text-font-weight-bold` | 公开 | `var(--c-font-weight-500)` | 本组件 CSS<br>`font-weight` |
| `--c-typography-text-margin-code-horizontal` | 公开 | `var(--c-spacing-1)` | 本组件 CSS<br>`margin` |
| `--c-typography-text-padding-code-horizontal` | 公开 | `var(--c-spacing-4)` | 本组件 CSS<br>`padding` |
| `--c-typography-text-padding-code-vertical` | 公开 | `var(--c-spacing-1)` | 本组件 CSS<br>`padding` |

</div>

## upload

声明来源: `src/upload/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-upload-action-size` | 公开 | `var(--c-sys-control-touch-target)` | 本组件 CSS<br>`height`, `width` |
| `--c-upload-active-color` | 公开 | `var(--c-sys-color-action-primary)` | 本组件 CSS<br>`accent-color`, `border-color`, `outline` |
| `--c-upload-background` | 公开 | `var(--c-sys-color-surface-default)` | 本组件 CSS<br>`background` |
| `--c-upload-border-color` | 公开 | `var(--c-sys-color-border-default)` | 本组件 CSS<br>`border` |
| `--c-upload-border-radius` | 公开 | `var(--c-sys-radius-md)` | 本组件 CSS<br>`border-radius` |
| `--c-upload-card-size` | 公开 | `calc(var(--c-sys-control-height-md) * 2)` | 本组件 CSS<br>`height`, `min-height`, `width` |
| `--c-upload-disabled-opacity` | 公开 | `0.56` | 本组件 CSS<br>`opacity` |
| `--c-upload-duration-background` | 公开 | `var(--c-sys-color-surface-tooltip)` | 本组件 CSS<br>`background` |
| `--c-upload-duration-color` | 公开 | `var(--c-sys-color-content-on-dark)` | 本组件 CSS<br>`color` |
| `--c-upload-duration-font-size` | 公开 | `var(--c-sys-font-size-sm)` | 本组件 CSS<br>`font-size` |
| `--c-upload-duration-padding` | 公开 | `var(--c-sys-space-1) var(--c-sys-space-2)` | 本组件 CSS<br>`padding` |
| `--c-upload-duration-radius` | 公开 | `var(--c-sys-radius-sm)` | 本组件 CSS<br>`border-radius` |
| `--c-upload-error-color` | 公开 | `var(--c-sys-color-content-danger)` | 本组件 CSS<br>`color` |
| `--c-upload-font-size` | 公开 | `var(--c-sys-font-size-md)` | 本组件 CSS<br>`font-size` |
| `--c-upload-gap` | 公开 | `var(--c-sys-space-4)` | 本组件 CSS<br>`gap` |
| `--c-upload-hover-background` | 公开 | `var(--c-sys-color-state-hover)` | 本组件 CSS<br>`background` |
| `--c-upload-item-min-height` | 公开 | `var(--c-sys-control-height-md)` | 本组件 CSS<br>`min-height` |
| `--c-upload-item-padding` | 公开 | `var(--c-sys-space-4)` | 本组件 CSS<br>`padding` |
| `--c-upload-progress-height` | 公开 | `var(--c-sys-space-2)` | 本组件 CSS<br>`height` |
| `--c-upload-secondary-text-color` | 公开 | `var(--c-sys-color-content-secondary)` | 本组件 CSS<br>`color` |
| `--c-upload-text-color` | 公开 | `var(--c-sys-color-content-primary)` | 本组件 CSS<br>`color` |
| `--c-upload-thumb-size` | 公开 | `var(--c-sys-control-height-lg)` | 本组件 CSS<br>`height`, `width` |
| `--c-upload-trigger-draggable-min-height` | 公开 | `calc(var(--c-sys-control-height-md) * 2)` | 本组件 CSS<br>`min-height` |
| `--c-upload-trigger-min-height` | 公开 | `var(--c-sys-control-height-md)` | 本组件 CSS<br>`min-height` |
| `--c-upload-trigger-padding-horizontal` | 公开 | `var(--c-sys-space-6)` | 本组件 CSS<br>`padding-inline` |

</div>

## verification-code

声明来源: `src/verification-code/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-verification-code-cell-height` | 公开 | `initial` | 本组件 CSS<br>`height` |
| `--c-verification-code-cell-max-width` | 公开 | `initial` | 本组件 CSS<br>`flex` |
| `--c-verification-code-gutter` | 公开 | `var(--c-sys-space-2)` | 本组件 CSS<br>`gap` |
| `--c-verification-code-input-font-size` | 公开 | `initial` | 本组件 CSS<br>`font-size` |

</div>

## watermark

声明来源: `src/watermark/style/token.less`

<div class="token-reference-table" style="max-width: 100%; overflow-x: auto;">

| 变量 | 层级 | 声明值／条件 | 消费路径／CSS 属性 |
| --- | --- | --- | --- |
| `--c-watermark-content-color` | 公开 | `rgba(0, 0, 0, 0.15)` | 运行时引用（不代表可见性证明）<br>`watermark/watermark.tsx` |

</div>

---

Document: llms/zh-CN/guide/design-tokens.md

<!-- Source: docs/guide/design-tokens.md; locale: zh-CN; page: /guide/design-tokens/ -->

### 全量收尾复核（2026-10-20 14:34 起；无新增漂移）

本轮只读重查通过：当前库存 198 文件／418 CSS／184 runtime，文件键差异 0；80 份分类 hash 全部匹配，184/184 提示已分类（100%），待审 0；33/33 既有组件族已分类（100%），剩余 0（0%），分母未变。三页生成目录全量匹配，未发现新的并行重叠。两端受查生产树汇总与上轮收口快照一致；已有未提交业务改造保留，不把 dirty 状态误报为新漂移。

共享 motion 106 项及完整后续编译链、目录 47 项／三页匹配、严格消费扫描 172 文件／4565 声明／70 已分类候选／0 待审／0 错误通过。pnpm 入口因尝试在工作区外准备自身版本而被 EPERM 拦截；改用现有 Node v23.2.0 执行 package.json 中相同的 Node 检查链通过，不声称 pnpm 入口通过，未安装软件或修改权限。

本轮只更新审计文档与证据，未改生产源码、Token 默认值、库存／hash 登记或三页生成表格；未重跑全组件业务测试／类型／根 lint，不把上轮结果改写为本轮新验证。分类／Less 编译检查不是全库业务或原生验收率。Map SDK、144 组原生环境及 Button 白字 on-dark 2.305:1 非 AA 例外保留，新增原生验收 0，自动化核实仍 PAUSED。详见 design-ui/audits/token-closure-recheck-2026-10-20-1434.md 与 audits/evidence/full-closure-recheck-2026-10-20-1434/results.json；环境恢复条件仍见 token-closure-recheck-2026-10-20.md。

### 日期库存／hash／目录授权收口（2026-10-20）

本批只同步获授权的 3 处库存、2 份分类 hash 和三页共 11 个逻辑行（2 默认值变化＋9 新行，5 个新增唯一声明）。生产源码、样式／Token 默认值、范围确认／提交和并行业务未改；未复现新的产品故障，不为登记漂移制造实现修复。新增审计基线 10 项中 8 个登记／目录匹配失败、2 个真实 Less 消费通过；库存比较夹具另纠正 file 字段包装，实际 3 处位置差异已独立确认。Cedar 新夹具首轮 attrs 透传覆盖 disabledDate 的误设也已纠正，不算产品故障。

真实入口核对：Cedar date/picker/style/index.ts → index.less → token.less，预览边界 outline、悬停范围／边界 fill-2 选择器与真实 Body 类名匹配；Maple date/style/index.ts → index.less → date-picker.less，日／月／年范围底色、禁用底色、预览底色和边界 outline 消费四个新声明。目录属性仅证明编译可达性，不代表所有 DOM／局部覆盖／对比度或原生验收。

Cedar 保留原 100ms 快捷预览任务、原句柄取消和生命周期／代次／一次消费／header continuation 守卫；真实禁用 Body 清除后旧回调重复交付不覆盖新草稿。Maple onSmartMounted 挂载／新激活同步滚动，nextTick 仅做记账；鼠标／触摸范围预览不追加滚动。新 Vue 回归两端各 2 项，按技能恢复方法描述符、卸载组件、恢复模拟计时器；没有新的资源需修复。

共享 motion 106 项及后续完整编译链、目录 47 项与三页全量匹配通过；严格消费报告 172 文件／4565 声明／70 已分类候选／0 待审／0 错误。库存仍 198 文件／418 CSS／184 runtime，80 登记 hash 匹配、184/184 提示已分类（100%），待审 0；33/33 既有组件族分类收口（100%），剩余 0（0%），分母未变。这是分类口径，不是全库业务或原生验收率。

受影响回归／类型／lint 的最终结果与首轮广测、串行隔离诊断分开保留，见 design-ui/audits/evidence/date-drift-closure-2026-10-20/results.json。Map SDK／144 原生组恢复条件沿用 token-closure-recheck-2026-10-20.md；新增原生验收 0，Button 白字 on-dark 2.305:1 非 AA 例外及其他文本阈值不变，自动化仍 PAUSED。下文“3 处／2 hash／三页待交接”是授权前历史快照。

### 全量收尾复核（2026-10-20；发现新的并行漂移）

本轮不能确认“无新增漂移”：库存总量仍为 198 文件／418 CSS／184 runtime，但有 3 处文件键差异（Cedar DateRangePicker、Maple YearPickerPanel 与 date-picker.less）；80 份分类源码中 78 份 hash 匹配，两个日期文件待重验。182/184 提示仍有匹配身份（98.9%），2 条待重验（1.1%），不是新增 2 个缺陷。既有 33 族历史分类不撤销；按当前源码身份，32/33 族匹配（97.0%），Date 1/33 族待重验（3.0%），不是全库业务／原生验收率。

三页均有日期目录漂移：Cedar 2 行默认值变化＋1 行新增，Maple 中英各 4 行新增，共 11 个逻辑行、5 个新增唯一声明；不是 11 个缺陷。当前完整编译报告为 172 文件／4565 声明／70 已分类候选／0 待人工／0 错误（首轮并行快照曾为 4564，不能混成冻结结果）。日期源码／Token 在检查期间继续变化，未覆盖并行业务，未自动刷新库存／hash 或应用生成表格。

motion 首段 92/96 通过、4 失败，未执行后续串行全量编译链；目录专项 37/37 通过，但全量三页匹配失败。已存浏览器证据 202 项与完整性链通过，只验证旧记录，新增原生验收 0。Map SDK 与 144 组原生环境分别需要的输入、明确交接范围和逐项差异见 design-ui/audits/token-closure-recheck-2026-10-20.md；证据见 audits/evidence/full-closure-recheck-2026-10-20/results.json。自动化已核实仍 PAUSED。下方 10-19 通过结论保留为历史快照。

### Maple 展示编辑器 lint 收尾复验（2026-10-19）

此前 3 文件的 8 项 lint 诊断已在本轮开始时消失：EditorPanel.vue 属性换行、presentation-state.vue 的 const 定时器容器及条件块、Form 示例入口导入顺序均已整理。本轮仅核对与验证，未再改这三个源码文件，保留 pending／inert、1200ms、AbortSignal、一次结算和并行业务语义；历史失败记录不改写为通过。

当前 Maple 只读根 lint、三文件专项 lint、配置声明类型均通过；相关 Form／Select／FieldPresentation 回归 300 项／34 文件及三个 SFC 脚本／模板编译通过。配置类型排除示例，示例另以 SFC 编译／lint 核对，不冒称示例完整类型验收。共享 motion 96 项及完整后续编译链、目录 37 项／三页匹配、严格消费扫描 172 文件／4560 声明／70 已分类候选／0 待审／0 错误通过。

库存仍为 198 文件／418 CSS／184 runtime；80 份分类 hash 匹配，184/184 提示已分类，待审 0，分母无新增变化。33/33 组件族已分类（100%），剩余 0（0%）；这是分类进度，不是原生浏览器验收率。无新库存／hash／目录漂移，未刷新登记或重生成相同目录。Map SDK 与 144 原生组阻塞保持，新增原生验收 0，自动化核实仍 PAUSED。详见 design-ui/audits/evidence/field-presentation-lint-closure-2026-10-19/results.json；恢复条件沿用 token-closure-recheck-2026-10-19.md。

### FieldPresentation／Form 授权收口（2026-10-19）

末次身份核对另捕获 Cedar 搜索助手的格式变化：当前完整字节与已登记、已验的 Maple 助手相同（6731260e…），调用行／片段未变，独立重验后只刷新该 hash。全部 80 份登记 hash 当前匹配，未将晚期变化说成源码全程未变。

末轮状态：Maple 根 lint 因新并行 EditorPanel.vue、form/example/demos/presentation-state.vue、form/example/index.vue 共 8 项格式／规则诊断退出 1；首轮通过只代表当时快照，不作为当前全库 lint 结论。本批未格式化这三个文件，需要并行负责人处理或交接这三个具体文件的格式整理边界；不影响已通过的专项、类型、当前库存／分类和目录证据。以下“根 lint 通过”仅为首轮历史。

严格门禁：motion 96 项及后续完整编译检查、目录 37 项／三页匹配、消费扫描 172 文件／4560 声明／70 已分类候选／0 错误通过。移除原始文本导入兜底后另验 AST 正反 8 项、全量三页和严格消费扫描通过。随后观察到 EditorPanel／Select 渲染与控制器等并行修改，均未覆盖；当前相关补验 Cedar 80 项／10 文件、Maple 89 项／13 文件及两端类型通过。完整 186／240 和补验不混成新增用例或全库业务认证。

新授权范围已完成：先复现两端搜索各 9 项（7 失败／2 对照）、焦点各 6 项（4 失败／2 对照），再限域修任务归属。搜索只接受当前激活实例／请求票据，替换、关闭／read／禁用、停用／卸载使旧任务失效；通知前一次消费，delay 读取和取消后旧回调不遗留任务、不覆盖新句柄。关闭后的 nextTick 焦点归还检查当前 reference、开合／形态、生命周期和代次，回调只消费一次；不在重开或跨停用后夺回焦点。失败断言相互交叠，不当成独立缺陷数。

两端真实 Form→Select 新增各 3 项回归，确认匹配字段 reset 退休搜索、无关 reset 保留当前搜索、活动编辑器阻止提交的原语义保持；两端 Form.vue／控制器／提交和并行业务源码未改，只重验并刷新登记 hash。Cedar 完整受影响 186 项／25 文件、Maple 240 项／33 文件通过（各新增 18 项），两端配置类型与受影响 lint、Maple 根只读 lint 通过。Maple Option 的外部变化保留，不以本批覆盖并行业务。

审计器从真实 style/index.ts 静态导入链发现私有 style.ts → style.less → token.less，保留真实声明路径与内部可见性；注释／type-only／孤立文件／越界路径不能伪造消费，旧入口与错误门禁保留。Maple Less 原将 min(var(--mp-field-presentation-min-width), 90vw) 折叠成 90vw，已通过保持原 CSS 表达式的转义修复真实丢失的变量消费；默认值、其他设计和公开 API 不变。

仅同步 6 处已审库存、两端 Form hash 与两个搜索登记；当前库存 198 文件／418 CSS／184 runtime，80 分类源码、184/184 提示（100%），待审 0。33/33 既有组件族已分类（100%），剩余 0（0%）；私有跨组件任务归入已有 Select／Form 消费链，不新建公开组件族。分母 182→184 来自两条新增实现提示，不是额外旧缺陷；两端搜索仍各 1 条提示。三页仅新增 _components/field-presentation 私有节共 12 Token 行（两端共 8 个声明），内部实现名不因列入目录变成公开 API。

最终严格门禁结果及快照见 design-ui/audits/evidence/field-presentation-form-closure-2026-10-19/results.json。Less／受控计时器／JSDOM 与真实浏览器／OS 分层，新增原生验收 0；Map SDK 及 144 组原生环境恢复条件见 token-closure-recheck-2026-10-19.md，Button 白字 on-dark 2.305:1 非 AA 例外保留，自动化仍 PAUSED。下文“6 处／2 hash／目录入口待交接”为授权前历史。


### 全量收尾复核（2026-10-19；当前状态）

本轮发现新变化，不能沿用 10-16 的全量通过结论：当前实际库存 198 文件／418 CSS／184 runtime，6 处文件键漂移；两端 Form 共 2 份登记 hash 过期。原 33 族中 32 族的登记源身份匹配（97.0%），Form 1 族需重验（3.0%）；新私有 FieldPresentation 搜索任务归属待登记，不先扩大族分母。当前 176/184 提示有匹配身份的既有登记（95.7%），8 条需审／重验（4.3%，Form 6＋新增搜索 2）；182→184 是新增实现提示，不是新增缺陷数。

两端新私有 token.less 使用 style.ts → style.less 路径，现审计器按旧 style/index.less 结构产生 2 项入口错误；真实 Less 各自编译通过，但目录完整检查中断，三页当前是否有新增行漂移尚未确认，未自动生成／发布部分目录。motion 首段 76/79、目录 8/11 后失败；后续全量编译链未执行，不声称全局 motion／目录通过。保存的浏览器证据 202 项及完整性链通过，仅校验旧记录，新增原生验收 0。

Map SDK 需正式适配器／版本、监听与销毁／异步取消契约、业务交接及受控可运行网络环境；144 原生组需可用 Chrome 原生 200%（48）、Safari 100%（48）、Firefox 100%（48）的受支持真实入口与逐组证据。历史连接观察未重新包装成本轮探测。具体差异、恢复输入和验收清单见 design-ui/audits/token-closure-recheck-2026-10-19.md；JSON 见 audits/evidence/full-closure-recheck-2026-10-19/results.json。

本轮仅更新审计文档／证据，保留并行业务、库存／hash 登记、三页生成目录和 Token 默认值。新增 FieldPresentation／Form 与审计器需交接边界后再收口；Map／原生阻塞、Button 白字 on-dark 2.305:1 非 AA 例外保留，自动化已核实仍 PAUSED。以下 10-16 全量通过是历史快照。

### Select／菜单表面目录授权收口（2026-10-16）

最终：Cedar 41 项／3 文件、Maple 49 项／6 文件通过（本批仅新增 1＋3 项 DOM 消费回归）；两端作用域／Maple 根只读 lint、三仓 diff 通过，91 个相关生产文件 hash 全部未变，验证进程均结束。保留首轮 Select 祖先选择器和 FloatingPanel 属性转发的夹具误设记录，不计产品缺陷；Vue 技能落实 finally 卸载／宿主移除。自动化仍 PAUSED，原生新增 0。

本批仅同步已核实的 Select 3 处库存／hash 和 Select、Maple Menu／FloatingPanel 三页共 21 行目录（11 个唯一 Token）。Cedar Select 当前钩子与已登记 Maple 源文件逐字同 hash；6 条调用职责不变，仅格式／行号更新。保留平铺分组标题的首项零上边距、纵向 popup padding、选项水平 padding 别名，以及菜单现有行级选中／悬停背景与 overlay 表面，未修改生产源码、样式、Token 默认值或并行业务。

实际 Less 入口、SelectMenu 平铺 DOM、Menu 分组／选中／焦点／禁用类及 FloatingPanel Teleport 宿主已核对。FloatingPanel 应在真实 popup 祖先覆写 --mp-floating-panel-background；不要假定传给 Teleport 组件的 style 自动转发到面板。目录属性列表表示编译符号可达性，不是每个 DOM 状态或局部派生别名重新求值的保证。

全量 motion 门禁当前通过（88 项共享测试、196 文件库存、182/182 分类及后续编译检查）；目录 29 项及三页全量匹配、消费检查 170 文件／4552 声明／70 已分类候选／0 错误通过。33/33 运行时组件族已分类（100%），剩余 0/33（0%）；78 源码、182/182 提示（100%），待审 0，分母未变。不是全库业务或原生验收率。

Map SDK 正式清理／异步身份契约、144 组原生环境阻塞和 Button 白字 on-dark 2.305:1 非 AA 设计例外继续保留；自动化保持 PAUSED。回归与最终快照见 design-ui/audits/evidence/select-catalog-closure-2026-10-16/results.json。以下 Select 3 处／目录 21 行未授权阻塞为历史。

### 原 6 处库存／DateRangePicker hash 授权收口（2026-10-16）

最终收尾：Maple 根只读 lint、Cedar 新夹具 lint、三仓 diff 与证据 JSON 均通过。保留首轮新夹具 curly 错误及第二轮并行 DatePanelContent 导入格式失败；本任务只修新夹具，观察到并行导入格式已变化后有界重跑通过。17 个相关生产快照中 16 个未变；RangeContent 并行改为移动端上下文导入，当前 8 项消费回归再次通过，未覆盖该业务文件或声称全族并行稳定。所有验证进程结束，自动化仍 PAUSED。

本批获授权的 6/6 处库存重叠已核实并刷新（100%，剩余 0）；连同上批，原 31 处已审记录全部同步。Cedar DateRangePicker 的时间选择业务分支保留；仅在内存还原该分支即可恢复上次登记的完整 hash 0e223655…，证明 100ms 预览任务只是 639→644 的行号移动。当前 hash 2a47d80d…、调用片段和 interaction-delay 职责已独立重验后登记，不改变 100ms 策略、提交／确认语义或头部任务所有权。

6 处库存基线均失败，新增 5 组真实 Less 消费检查已通过；DateRange／TimeRange 生成目录另有 4 项旧节基线失败。最终局部门禁 51 项通过；Cedar 25 项／3 文件通过（含新增 2 项时间选择与旧回调重复交付），Maple 32 项／5 文件通过（含新增 8 项 Carousel 三种 effect 与范围面板 DOM 消费）。Cedar 首次新增夹具仅错误要求所有计时器为零，已改为核对原预览句柄物理取消；不是已复现产品故障。生产 SFC、样式、Token 默认值和并行业务均未修改。

Carousel 的实际 track／fade／card 消费及 reduce 规则、Less 原样输出 grid-area 均核对；范围背景已有局部 picker／date／time body 别名，支持相应后代背景路径。目录 background-image 仅表示符号依赖可达；Picker 的根级派生 mask 别名不保证随局部背景覆写重新求值，需直接覆写 --mp-picker-mask-background-image 定制遮罩，本批不改其默认策略。Date／Time 还含历史转换选择器，不能以编译存在推断每种模式命中或完整 reduced-motion／原生验收。

授权的 Maple 中英 DateRange／TimeRange 共 4 行生成目录已同步。新增范围外变更独立保留：两端 Select 样式行号、Cedar select/hooks/use-select.ts 运行时行号及 hash；全量库存当前因此仍有 3 行漂移，分类 CLI 因 Select 失败，不再是 DateRangePicker。目录还保留 Select／Maple Menu／FloatingPanel 共 21 行、3 页的并行漂移，未整页应用。历史运行时登记仍 33/33 族、78 文件、182/182 提示、待分类 0，分母未变；当前 Select hash 待重验与未分类提示是不同统计，不声称全局门禁通过。

Map SDK 清理／异步身份契约、144 组原生环境阻塞、Button 白字 on-dark 2.305:1 非 AA 例外和自动化 PAUSED 保留。本次 Vue 技能用于原资源／回调交付复核及 finally 卸载／计时器恢复；Less、JSDOM 与真实浏览器分层，本批原生新增 0。证据：design-ui/audits/evidence/remaining-six-inventory-closure-2026-10-16/results.json。以下 6 处待授权／DateRangePicker hash 阻塞均为历史。

### 库存漂移分批收口（2026-10-16；自动化保持暂停）

最终收尾：Maple 根级只读 lint 退出 0；25 个已审生产文件 hash、三仓 diff 和证据 JSON 核验通过，验证进程均已结束。全量库存和分类 CLI 的已说明失败仍保留，不以局部通过掩盖。

重新扫描以文件键计为 31 处差异（Cedar 4／Maple 27），历史“26 处”不是当前固定分母；本轮最初“32”计数口误已更正。已核对并仅刷新 25/31 处库存记录（80.6%），保留 6/31 处（19.4%）重叠。25 处包含：5 处前批已审 FieldDecorator／Input／FilterForm 的行号更新、14 处无未提交样式变化的候选行号漂移、6 处已提交的 Checkbox／Radio／Progress／ProgressGroup／Rate／Slider 样式候选扩展。后六项虽部分文档／示例并行，未发现相应样式源码冲突，不能整族视为阻塞。没有把 25 处旧快照当作 25 个产品缺陷。

新增 31 项回归的有效基线为 25 个库存匹配失败／6 个真实编译消费通过；局部刷新后与既有 4 项扫描器回归合计 35 项通过。25 个实际 Less 入口均编译，6 组扩展核对正常 duration／animation 路径与 reduced-motion 对应规则；Maple 受影响真实控件回归 85 项／7 文件通过（不是 85 项新增）。保留 Rate 非法 count 测试的预期 Vue warning。仅建立候选位置／编译可达性证据，不外推 14 个旧样式完整 reduced-motion 覆盖、CSS 动画帧或原生验收；未修改生产源码、Token 默认值或业务。

6 处重叠保留：Cedar date/picker/DateRangePicker.vue；Maple carousel/style/index.less、date-range/style/date-range-picker.less、date/style/date-picker.less、time-range/style/time-range-picker.less、time/style/time-picker.less。日期／时间关联模板和 Token 仍有并行变化，日期范围／时间范围 Less 在审查期间也继续变化；Carousel 有并行 fade 样式及主体改造。本批未接管这些源码或刷新其库存。继续前需要相应源码／关联 Token 可交接的具体边界，或明确限域接管授权。

当前库存快照仅纳入已审变更：196 文件、414 条 CSS 提示；实际源码为 196 文件、416 条 CSS 提示，差额及行号差异仍由 6 处保留造成。实际 CSS 提示由旧 392→416，含已有实现／none 覆盖及两个新增库存文件，不是新增 24 个缺陷。运行时提示仍 182，历史登记 33/33 族、78 源码、182/182 提示、待分类 0，分母不变；但当前分类 CLI 退出 1，Cedar DateRangePicker 为 78 份中唯一 hash 过期，需重验，不能沿用历史 100% 当当前 hash 验收。全量库存 CLI 也退出 1；未称全局 motion-themes 通过。

Map SDK 正式清理／异步身份契约、144 组原生环境阻塞及 Button 白字 on-dark 2.305:1 非 AA 例外保留。本聊天自动化仍 PAUSED，不恢复调度。仅库存／门禁测试／审计文档变更，无新组件 API／发布语义，不为旧快照新建产品修复 Changeset 或 Demo。逐项边界和验证：design-ui/audits/evidence/inventory-drift-review-2026-10-16/results.json。以下“26 处保留”描述为历史。

### FieldDecorator 焦点／caret 目录收口与自动化暂停（2026-10-16）

最终收尾：Maple 根只读 lint 与 Cedar 新测试作用域 lint 通过；Maple 首轮仅新夹具的 28 项格式／导入排序诊断已限文件格式化修正，修正后 9 项专项再次通过。12 个生产文件 hash 不变、三仓 diff 与证据 JSON 核验通过，所有验证进程结束；自动化保持 PAUSED。

用户限域授权后，核对两端实际 FieldDecorator／Input／Textarea／InputNumber、静态样式导入链及 Less 编译：外壳外环移除与原生 caret 改为 currentColor 已由并行实现和当前规范确定，保留变体焦点反馈、按钮 focus-visible、错误／禁用优先级与现有 Token。未复现需修改生产源码的缺陷；本批不回退设计，不改业务、SFC、样式或 Token 默认值。目录中 outline-offset／caret-color 的旧消费行已过期，仅应用三页共 9 行生成差异。focus-color 不承诺控制 caret；错误态焦点可辨识性仍需原生验收。

有效 9 项共享基线 6 通过／3 页目录失败；首轮另有 2 项探针错误要求所有样式直接导入 FieldDecorator，按真实“Textarea／InputNumber → Input → FieldDecorator”链修正，不能计作产品缺陷。最终共享目录 17 项通过，三页全量目录匹配；既有 field-focus 编译检查与 384 项错误／禁用颜色和覆盖检查通过。Cedar 106 项／13 文件、Maple 129 项／15 文件通过，各新增 9 项真实控件 DOM 回归。Vue 技能落实 finally 卸载；Less／JSDOM 与真实浏览器分层，本批原生新增 0，未复跑无变化原生入口。

运行时候选仍 33/33 族（100%），剩余 0 族（0%）；78 登记源码、182/182 提示（100%），待审 0，分母不变。这不是全库业务或原生验收率；26 处其他库存漂移、Map 正式 SDK 清理／异步身份契约、144 组原生 Chrome 200%／Safari／Firefox 环境阻塞及 Button 白字 on-dark 2.305:1 非 AA 例外保留。用户要求停止的本聊天自动化 cedar-maple-14-00-2 已暂停（PAUSED），不再周期启动工作；本次明确授权的手动收尾已执行。

共享规范、两端指南／相关组件说明、Changesets、既定 OpenSpec 和证据同步：design-ui/audits/evidence/field-focus-caret-catalog-2026-10-16/results.json。以下 FieldDecorator 未授权／目录阻塞描述为历史。

### Cedar FilterForm／Form 目录消费收口（2026-10-16）

用户已授权限域审查相关样式／Token。历史“5 处目录差异”不是 5 个缺陷；按当前生成器合并为 2 个上下文差异块，现已只同步 Cedar 的 FilterForm／Form 两节。真实 Less 编译、Form 样式入口和实际 DOM 共同确认 13 个 FilterForm Token 的消费者；Form 的行高／标签下间距通过 action-offset 别名传递至 padding-top。单列 stacked 状态覆盖为 0；Grid colGap 是数字属性，不冒充 CSS Token。组件局部覆盖建议直接设置 --c-filter-form-action-offset，不假定根级派生别名会随局部依赖重新计算。未修改生产样式、Token 默认值、SFC 或并行业务代码。

新增目录回归基线 5 项中 3 通过／2 失败，失败仅为旧目录两节；同步后共享 8 项通过，Cedar FilterForm／Form 合计 75 项／17 文件通过（只新增 2 项 DOM 回归），作用域 lint 与全量消费检查通过。Vue 技能落实夹具卸载／媒体描述符恢复。Less／JSDOM 不等于原生布局或焦点验收，本批原生新增 0。

全量目录门禁仍受新出现的范围外 FieldDecorator 消费漂移阻塞：Cedar 与 Maple 中英共 3 页、9 行涉及 outline-offset／caret-color。未自动应用这部分生成补丁，也未据此认定业务／可访问性缺陷；需要另行审查授权或负责人交接。Map SDK 清理／异步身份契约、144 组原生环境阻塞与 26 处其他库存漂移保留。运行时候选分类仍为 33/33 族（100%），剩余 0 族（0%）；78 源码、182/182 提示（100%），待审 0，分母不变；不是全库验收率。Button 白字 on-dark 2.305:1 非 AA 例外不变。

证据：design-ui/audits/evidence/filter-form-token-catalog-2026-10-16/results.json。以下旧“5 处待交接”描述为历史，不再作为当前授权阻塞。

### Form／Picker运行时候选分类收口（2026-10-16）

最终受影响验证：Cedar Form64项／14文件、Maple合并532项／95文件全部通过（含Form115／19、Picker30／4）；两端相应lint／配置类型、共享29项及分类CLI182／0通过，最终hash／三仓diff／JSON核验通过。Maple中间531／532仅新增夹具错误禁止合法A通知，修正后205.86s最终全通过；NodeList类型适配改为局部Array.from，未改配置。原生新增0，所有验证进程已结束。

用户新授权仅接管 Cedar Form／Maple Picker 的运行时调度和资源清理，保留并行业务改造。Cedar 原11项基线7失败／4对照，Maple Picker有效7项5失败／2对照，Maple Form完成等待5项4失败／1对照；交叠断言不是独立缺陷数量，候选上的重复offset／重复注册／通知重入另行取证后修复。Cedar当前实例／验证／字段与一次消费守卫、原注销身份；Picker原媒体绑定／列／scroller完成票据与通知代次；Maple Form渲染后按当前CSS duration＋delay等待，零／无过渡不固定等300ms。正时长有可取消准备帧，300ms仅不可读样式保底，插值仍保留原300ms。控制器、FormItem、并行submitEpoch／提交、disabled／ARIA／级联及CSS Token不替换。

分类为33/33族100%，剩余0族0%；78登记源码、182/182调用提示100%，待审0条0%。本批只刷新四处已审候选（含新增私有完成助手）；分母181→182净增1条实现提示（新增助手2、移出Form旧timer1），不是额外旧缺陷，亦不把历史178→181重算。**这是本轮运行时候选职责分类，不是整库／所有业务协议／原生验收100%。** 受影响回归、类型、lint和共享门禁最终结果以逐组证据为准，不沿用旧18/33或旧NavMenu快照。

Vue技能落实原资源、停用／卸载、一次消费、重入和finally恢复。JSDOM受控Promise／timer／RAF／媒体／CSS与真实Less编译分层，原生浏览器／OS新增0。FormDetails当前Less编译仍为0.2s；未改CSS／公开Token／API。既有基础、异步、键盘和禁用示例保留并行修改，必要行为说明已同步组件文档；历史RPC、夹具失败、类型／lint诊断均保留，不降测试阈值。

原两族运行时接管授权阻塞已解除；不再要求重复授权。仍保留上次Cedar FilterForm／Form目录5差异块（需样式／Token稳定交接后人工整合，未覆盖生成）、Map正式SDK清理／异步身份契约、144组Chrome原生200%／Safari／Firefox环境条件及26其他库存漂移；不声称全局motion-themes通过。Button白字on-dark2.305:1非AA例外保持。Date／Time并行展示业务未接管，分类及受影响回归不等于整族稳定。新证据：design-ui/audits/evidence/form-picker-runtime-closure-2026-10-16/results.json。

### Maple Form自动滚动资格获授权修复（2026-10-16，阶段三）

用户明确允许仅补Form.vue内验证开始／清除／重置到自动滚动资格接线。基线10项6失败／4对照（exit1，11.80s）后，加入独立滚动资格版本、验证请求／策略快照及原字段成员／名称／目标复核；清除、重置、设置字段和新验证退休自动等待／插值，保留显式手动命令。校验回调重入后旧自动滚动不再覆盖新命令；停用前验证结果不能跨激活排滚动。校验Promise／回调、并行submitEpoch和提交语义保持，form-controller.ts／FormItem.vue、CedarForm／MaplePicker未改。

首修31项通过；补9项命令／物理取消／回调替换／字段身份对照后，最终Form106项18文件通过（exit0，60.18s），含本阶段19项＋前批87项，不记106个新增用例或六个独立缺陷。根只读lint、配置类型、共享29项和分类CLI165/16通过。首轮新增声明排版lint失败已手工修正，不以当时类型通过掩盖lint失败。Vue技能落实原资源、KeepAlive及finally恢复；均为JSDOM受控Promise／timer／RAF／几何层，真实浏览器／OS新增0，无Less／构建或无变化环境复跑。

分类仍31/33族93.9%，剩Form／Picker2族6.1%；74登记源码、165/181提示91.2%，16待审8.8%（Form7／Picker9），本批分母不变。只手动刷新Maple Form五行提示100／103／114／131／165，不刷新26其他漂移。固定300ms完成等待与FormDetails0.2s／reduce关系仍待审，Form不提前归档。CedarForm／MaplePicker仍需具体source＋test交接／冻结或限域授权；Date／Time候选已分类不等于并行面板全族稳定。目录5差异块、Map正式SDK契约、144原生环境组及Button白字2.305:1非AA例外保留。证据：design-ui/audits/evidence/form-scroll-validation-baseline-2026-10-16/results.json。

### 历史：Maple Form异步滚动资格授权前基线（2026-10-16，阶段三）

本批仅新增独立scroll-validation-eligibility探针，产品Form仍为324148a9…，阶段一／二滚动实现及并行submitEpoch均未改。有效10项基线6失败／4对照（exit1，11.80s）：验证旧结果跨停用／激活排自动滚动、原字段注销但节点仍连接仍排、清除错误／关闭自动滚动未取消等待、字段目标替换后旧等待仍排RAF、校验回调清除错误后仍排。组合／交叠不计六个独立缺陷。当前错误结果及Promise返回、成功无滚动、显式手动滚动不受自动策略变化影响、新激活后新验证四类对照通过。

按Vue技能核对了异步归属／KeepAlive和原timer／descriptor finally清理。真实Form/provider注册字段、受控Promise／300ms队列与RAF探针是JSDOM层，不是原生输入／布局／OS／adopt验收，真实新增0。新测试保持失败基线，不跳过／不称当前整套Form通过；前批87/17通过是前批测试集历史。作用域lint通过；最终只读根lint及hash/diff记录见证据。

需要明确扩展到Form.vue内“验证开始、清除、重置到自动滚动资格”的局部接线；只抑制失效自动滚动，不改校验返回、回调、submitEpoch、提交语义或form-controller.ts／FormItem.vue。已请求用户决定，未先行修改该接线。成员／目标检查可与该请求归属一起审查，固定300ms等待策略保持待审；FormDetails源样式0.2s只作源级依据，不当Less／原生测量。

分类不变：31/33族93.9%，剩Form／Picker2族6.1%；74登记源码、165/181提示91.2%，16待审8.8%（Form7／Picker9），分母无变化，无库存／分类刷新。保留26其他漂移、目录5差异块、Map正式SDK、144原生环境组、Button白字2.305:1非AA例外及CedarForm／MaplePicker并行边界。证据：design-ui/audits/evidence/form-scroll-validation-baseline-2026-10-16/results.json。

### Maple Form已启动插值的生命周期（2026-10-16，阶段二）

最终本批：Form87项17文件全部通过、exit0、275.40s，含本阶段11新插值专项＋前批10等待项＋既有／并行66项，不把21项都算本批新写。共享29项、分类CLI165/16、类型及根／最终作用域lint通过，三仓diff及最终hash／JSON检查通过；验证进程已结束。中间偏移夹具失败与前批默认RPC历史保留，无原生新增验收。

延续用户仅接管Maple Form.vue滚动段的授权。原5c3bf495…与真实共享scrollTo组合，6项有效基线4失败／2对照（3.05s）：新等待替换、停用、跨激活与卸载后旧帧仍写入。正常300ms线性／重复帧拒绝原本通过，不算新缺陷。仅Form内部私有插值接管原scroller窗口的RAF及取消器，逐帧一次消费、原请求／生命周期资格、读媒体／初始位置与写入后复核；取消物理释放原帧且逻辑拒绝晚交付，保留已发生偏移，不回滚或污染新请求。共享utils/elements.ts与HEAD同hash cdb1c340…，API未改，其他消费者不外推认证；并行submitEpoch保持。

原6插值项首修全通过；再补5项初始／动态reduce、原生写入卸载、激活新请求及位置读取卸载。前批10等待探针改为观察真实RAF／窗口写入，保留原职责；中间15/16及86/87仅偏移对照NaN，未明确初始窗口坐标的夹具补零并finally恢复后21专项通过（5.67s），不计产品缺陷。最终受影响Form／共享／类型及lint见逐组证据。Vue技能用于原窗口资源、KeepAlive、重入与descriptor恢复。保留原等待300ms＋插值300ms线性、初始reduce不排帧／动态reduce下一帧到位；固定等待与FormDetails0.2s／reduce关系、异步校验资格及字段成员仍未认证，本族不提前归档。

分类31/33族93.9%，剩Form／Picker2族6.1%；74登记源码、165/181提示91.2%，16待审8.8%（Form7／Picker9）。分母178→181只因本次私有实现新增3条提示，非新增3个旧缺陷、也非已分类倒退。只手动更新Maple Form为89／92／103／120／146及本端81→84、local query=true；26其他漂移不刷新，不称全局motion-themes通过。JSDOM真实组件／原helper基线及受控RAF／媒体／几何不是原生布局／OS／adopt验收，真实新增0。目录5差异块、Map SDK、144原生环境组、Button白字2.305:1非AA例外、CedarForm／MaplePicker并行边界与前批默认RPC失败历史保持。证据：design-ui/audits/evidence/form-scroll-animation-lifecycle-2026-10-16/results.json。

### Maple Form等待任务获授权修复（2026-10-16）

最终验证：单worker受影响Form76项16文件通过（含本批10专项），类型通过、只读根lint未报错。原默认模式60项通过但2文件RPC加载失败／1未处理错误、exit1保留；一次有界补验通过不证明原失败仅由负载造成。无原生新增验收。

用户明确允许仅接管Maple Form.vue滚动任务段；保留原submitEpoch及所有并行提交改造，CedarForm／MaplePicker未接管。有效原6项基线3失败／3对照；补几何读取卸载后原源码7项4失败／3对照（4.60s），不记四个独立缺陷。授权后等待任务加入代次、一次消费、mounted／active／disposed资格；停用／卸载取消，激活只接受新请求，几何读取后复核，不退休重入创建的新请求。

首修7项通过（14.99s），补inactive／fresh activation、几何重入替换与offset／linear正对照后10项专项通过；受影响Form整套、类型和lint最终结果见逐组证据。Vue技能用于原timer／KeepAlive／finally descriptor清理。仅控制委托前的等待，不宣称下游已启动RAF可取消；共享scrollTo仍只返回Promise，无取消器。本次保留原300ms等待／global timer、默认线性helper、API及Token。FormDetails样式当前0.2s，固定300ms等待的完成策略／reduce与共享插值接线仍待单独取证，不偷改为business-delay或宣称全motion通过。

分类仍31/33族93.9%，剩Form／Picker2族6.1%；74登记文件、165/178提示92.7%，13待审7.3%，分母不变。Maple Form两条未提前登记，仅手动刷新已改库存42／52→70／84，26其他漂移保持；JSDOM受控timer／几何、mock下游不是原生插值／OS／跨document验收，真实新增0。待审仍包括共享helper取消、验证完成后的滚动资格、字段成员和当前配置等，不能用本批10项冒充Form整族收口。证据：design-ui/audits/evidence/form-scroll-wait-task-2026-10-16/results.json。

### Form滚动任务只读基线／待授权修复（2026-10-16，16:39上海起）

未接管两端Form或MaplePicker并行源码。Maple Form仍为94c525ac…快照，仅新增独立scroll-task-ownership探针：6项基线3通过／3失败（exit1，6.98s）。正常300ms调度、普通卸载取消及未知字段通过；手工交付已取消旧回调／重复当前回调／跨KeepAlive激活旧回调仍调用scroll助手。属于受控队列归属缺口，不计三个独立缺陷，不宣称原生timer实际重复或已修复。原300ms是否为视觉完成等待及滚动helper取消接线仍需进一步审查，不提前分类。

Vue技能用于原timer清理／KeepAlive核对和finally恢复全局descriptor；实际Form＋注册字段，mock下游scrollTo仅观察派发，非真实插值／布局／原生／OS验收。源码未改、未归档新文件／提示；仍31/33族93.9%，剩Form／Picker2族6.1%，165/178提示92.7%，13待审7.3%（Form4／Picker9），分母不变。基线测试故意保留失败，不能称整套Form通过。新增夹具import顺序lint已修正，最终只读lint结果见证据。

需要用户／负责人明确允许仅接管Maple Form.vue滚动任务段，保留现有submitEpoch等并行提交改造；未把“继续”扩大为覆盖并行源码。CedarForm／MaplePicker仍各自保留；26漂移、目录5差异块、Map SDK、144环境组及Button白字2.305:1非AA例外不变。证据：design-ui/audits/evidence/form-scroll-ownership-baseline-2026-10-16/results.json。

### Maple 年面板原生对齐／Date候选分类收口（2026-10-16）

YearPickerPanel源码保持9a51ffd…不变：挂载及后续激活同步查询当前选中Button，优先primary、其次outline，无标记不滚动。实际onSmartMounted源码与解析构建一致，首次KeepAlive激活不重复；nextTick只更新挂载标记，没有延迟滚动、私有RAF／timer／监听需取消。7项实际YearPanel／Button＋KeepAlive受控对照通过（含空列表、立即卸载、停用后当前节点重激活），未复现产品缺陷，不制造修复；Vue技能用于核对资源归属及夹具descriptor恢复。

**31/33族分类收口93.9%，剩Form／Picker两族6.1%；74文件、165/178提示92.7%，13待审7.3%，分母不变。** Form4／Picker9；Date／Time候选归档不等于并行展示层稳定或整组件验收。仅登记原有年面板236行native-scroll，无库存行变化／API／Token／默认值修改，保留block:center及浏览器滚动策略。JSDOM方法探针不是原生布局／smooth／reduce／OS／adopt验收，真实新增0。受影响回归与门禁实际结果见design-ui/audits/evidence/date-year-native-scroll-2026-10-16/results.json。

Form两端及MaplePicker源码hash与上批相同，但仍有并行source／test修改且无明确交接，不能用mtime安静认定稳定；需具体文件可审／冻结边界或明确接管授权。保留26其他漂移、Cedar FilterForm／Form目录5差异块、Map正式SDK契约、144原生环境组及Button白字2.305:1非AA例外，不自动生成覆盖或重试无变化入口。Cedar上批175项断言通过但close-timeout告警仍保留，本批不机械复跑。

### Cedar Date 范围预览与表头续体（2026-10-16，阶段二）

原clean的DateRangePicker与私有range-header helper独立审查，stub并行范围面板。有效13项旧基线10失败／3对照，正常100ms不提交模型、普通卸载及宽限内表头结算原本通过；首修候选另复现新单元格选择未使旧清理失效，单列而不加入原基线。当前21范围专项通过，其余分层验证见逐组证据。

100ms仍是interaction-delay，不是CSS完成时长或应被reduce跳过的动画。timer代次和preview代次分开，离开不取消仍有效的预览表头；所有preview写入退休旧timer／表头归属，失效配置／模型、停用卸载取消，新激活只接受新hover。preview／input setter后复核；私有resetHeaderValue可接原归属检查，nextTick一次消费，取消不删除Vue队列。默认其他调用方／所有select-confirm-input协议不据此认证。保留100ms／global timer、公开API／CSS Token；Vue技能用于原资源／停用卸载和测试descriptor恢复。

分类仍30/33族90.9%，剩Date／Form／Picker三族9.1%；73文件、164/178提示92.1%，14待审7.9%，分母不变。仅范围Picker库存605→639；helper无扫描hint，独立记hash，不虚增登记。Date仅剩Maple年面板1提示，不等于并行日期整族稳定。JSDOM／KeepAlive、stub面板、受控timer／nextTick非原生hover／OS／adopt，真实新增0。保留26其他漂移、Cedar FilterForm/Form目录5差异块、Map正式SDK／144环境组和Button白字2.305:1非AA例外，不机械复跑无变化入口／生成覆盖。证据：design-ui/audits/evidence/date-range-shortcut-preview-2026-10-16/results.json。

### Cedar Date 单值快捷预览任务（2026-10-16，阶段一）

原clean的单值Picker只审100ms离开悬停预览宽限，归interaction-delay，不是CSS完成时长，reduce不应跳过业务宽限。有效11项旧基线9失败／2对照；正常100ms清理且不提交模型、普通卸载取消原本通过。代次＋一次消费拒绝取消／已消费旧回调；可见性、禁用、只读、previewShortcut和模型变更同步失效，停用／卸载取消并清预览，激活只接受新hover。保留hover命令检查当前资格，预览写入重入后不清新输入草稿；正值100ms、global timer归属、API／CSS Token保持。

16专项及Cedar配置类型／受影响lint通过，其他日期回归单列逐组证据。使用实际Picker／KeepAlive＋stub PickerPanel和受控100ms队列，Vue技能用于原资源／停用卸载／descriptor恢复；不接管并行展示面板，不认证原生hover／OS、范围预览或所有select／confirm／input保留命令。真实浏览器／OS新增0。

分类仍30/33族90.9%，剩Date／Form／Picker三族9.1%；72文件、163/178提示91.6%，15待审8.4%，分母不变。仅单值Picker库存427→453，Date仍余范围预览与Maple年面板2提示；26其他漂移、Cedar FilterForm/Form目录5差异块、Map正式SDK及144环境组保持，不自动刷新／覆盖。Button白字2.305:1保留非AA例外。证据：design-ui/audits/evidence/date-shortcut-preview-2026-10-16/results.json。

### Cedar TimeColumn 消费者与候选分类收口（2026-10-16）

TimeColumn起点clean；有效11项旧基线9失败／2对照，正常100ms线性选择和Vue卸载后拒绝通知原本通过。组件现拥有私有滚动取消器：隐藏、停用、卸载及当前value／visible／list变化同步失效；visibility的渲染等待一次消费，几何读取后复核原root／value／元素，旧续体不能覆盖新请求。保留点击核对当前可见／可用及原item仍在列表且未禁用；注销核对原item，不删同值替换。激活只对齐当前值，不重放旧插值；Vue技能用于停用／卸载和引用／测试descriptor清理。正值100ms线性、公开API／CSS Token保持，必要渲染结算不是CSS完成时长。

最终16组件＋14工具专项，受影响Cedar Time149项30文件通过（含并行2项step示例，不算本批新写）；配置类型和受影响lint通过。当前**30/33族90.9%，剩Date／Form／Picker三族9.1%；71文件、162/178提示91.0%，剩16条9.0%，分母不变**。Time运行时候选归档不是并行Time面板／Maple滚轮稳定或整族所有行为认证；JSDOM受控nextTick／RAF／KeepAlive／几何不是原生输入、OS或adopt证据，新增真实验收0。任意同item引用回调乱序仍未认证。

只更新TimeColumn已审库存76→89；26其他漂移、上批Cedar FilterForm/Form生成目录5差异块、正式Map SDK和144原生环境组保持，不机械复跑无变化入口、不自动覆盖并行源码或生成页。Button白字2.305:1仍为非AA设计例外。证据：design-ui/audits/evidence/time-column-lifecycle-2026-10-16/results.json。

### Cedar Time 私有滚动任务／并行边界（2026-10-16）

未接管并行 Date／Form／Time 面板／Maple Picker；只修复原工作树 clean 的 Cedar `time/picker/utils/index.ts`。零／负／非有限时长及初始 reduce 直接到位且不排帧；正时长保留调用方100ms线性策略，动态 owner reduce 下一帧到位。WeakMap请求、逐帧一次消费与私有取消器隔离替换／旧回调／重入，不引入CSS Token或公开API。取消保持当前偏移，不替用户完成选择。

有效旧实现基线10项9失败／1正常100ms对照；修复后14专项（补取消／getter与setter重入）和Cedar Time共131项28文件通过，配置类型及受影响lint通过。Vue技能用于私有资源与测试descriptor恢复；此批尚未把取消器接入TimeColumn的停用／卸载，watch／nextTick与保留命令继续待审，不能把工具通过说成整族生命周期通过。JSDOM iframe／受控RAF／媒体模拟不是原生浏览器或OS证据，新增真实验收0。

当前29/33族87.9%，剩Date／Form／Time／Picker四族12.1%；70文件、161/178提示90.4%，17未分类9.6%，分母不变。仅本工具2提示登记，Time尚余1。26处库存漂移、Map正式SDK及144环境组保持；Button白字2.305:1仍为非AA设计例外。最新生成目录检查定位Cedar FilterForm声明与Form消费路径漂移（5个差异块）；Maple两页匹配，不自动覆盖并行样式／目录，不称全局motion-themes通过。证据：design-ui/audits/evidence/time-scroll-task-2026-10-16/results.json。

### 分类快照重验与并行实现边界（2026-10-16）

两端Ripple／VirtualList四源码逐份重读，测试前后hash相同；Cedar83项11文件／Maple74项9文件通过后手动更新职责登记，不接管或修复并行实现。800ms触摸兼容去重是Date.now门槛，不新增timer／CSS duration；Ripple仍task-dispatch，VirtualList实测行高／自身scroll校正仍nextTick state-settlement。各15生命周期＋2测量、各3鼠标与Cedar7 Tree组合为受控证据，不认证任意破坏性几何重入、可信输入／adopt／OS。

分类仍29/33族87.9%，剩4族12.1%；69文件、159/178提示89.3%，剩19条10.7%，分母不变。只更新四份已审行／hash；26处其他漂移、Date／Form／Time／Picker、Map SDK及144环境组保持，不称全局motion-themes通过；真实浏览器／OS新增0。证据：design-ui/audits/evidence/classification-revalidation-2026-10-16/results.json。

### 测试时钟清理不等于产品计时修复（2026-10-16）

最终整套复验：串行与默认线程各401项／63文件通过且exit0，不累加为802用例；旧超时／串行异常保留为历史，不再列当前复验失败，不推断旧超时全由此夹具或纯负载造成。

已安装Vitest0.22.1的timer spy／假时钟卸载组合可删除全局setTimeout，隔离回归先失败。本聊天四组Scheduler计时夹具现捕获进入fake clock前的原始timer描述符，并在卸载／mock清理后以finally恢复；不改产品业务时钟、交互节奏或CSS Token。新增3项恢复专项及受影响63项通过，包含拖动之后执行的workbench。旧整套失败以本批实际复验结果分别判断，四处并行hash／26漂移、SDK及144环境阻塞不据此解除。分类仍29/33族87.9%，剩4族12.1%；159/178提示89.3%，剩19条10.7%，分母不变。真实浏览器／OS新增0。证据：design-ui/audits/evidence/scheduler-timer-fixture-2026-10-16/results.json。

2026-10-16证据补充：两端Ripple／VirtualList四处并行hash包含鼠标去重／实测行高校正等行为变化，不能自动刷新为已验。Scheduler有界串行23项通过，但实际workbench先于event-drag，不排除清理顺序污染，旧整套失败保留。分类仍29/33族、159/178提示；无新API／Token或原生验收。证据：design-ui/audits/evidence/classification-drift-review-2026-10-16/results.json。

### Cedar Scheduler：TimeGrid范围会话与分类收口（2026-10-16）

350ms触摸武装归interaction-delay，0ms范围点击解锁归state-settlement，不是CSS duration。会话live／代次、原root／columns及步长／snap／小时／资格复核隔离旧move／up／cancel／hold／unlock；取消只释放原绑定，不清新请求。pointercancel匹配pointerId；hit-test和几何读取后检查，配置同步失效。停用／卸载取消，激活只接受新手势。保留350ms／8px／5px／snap／结束小时和global document/window，API／Token不变。

本次登记TimeGrid两条后，候选分类29/33族87.9%，剩4族12.1%（Date／Form／Time／Picker）；69文件、159/178提示89.3%，19未分类10.7%，分母不变。Scheduler运行时候选分类收口不等于整组件／完整测试／原生验收；all-day／overlap／focus与非range保留命令独立待验。Vue技能用于原监听／timer、停用卸载和探针恢复；JSDOM不认证可信Pointer／原生click／跨document／OS。旧全套超时／串行异常、4hash／26漂移、SDK／144环境组保留。证据：design-ui/audits/evidence/scheduler-time-grid-range-2026-10-16/results.json。

### Cedar Scheduler：Event入口归属与职责登记（2026-10-16，阶段三）

原生drag协议的开始／结束属于当前内部请求：停用不写dataTransfer、不发start；结束先消费归属，再通知；配置／停用／卸载取消并使旧end回调失效，传输回调返回后复核资格。resize入口与可见性共用当前resizable／非milestone条件；移除的保留句柄不能重新启动。实际Button已经拒绝inactive普通click，本批不重复添加父级修复。无新API／Token／默认策略变化。

Event四提示归interaction-delay2（350ms）与state-settlement2（0ms）。三阶段受控源码证据后登记该文件，Scheduler仍待TimeGrid两条；28/33族84.8%，剩5族15.2%；68文件、157/178提示88.2%，21未分类11.8%，分母不变。登记不是干净完整测试或原生验收：旧整套超时／串行timer、四旧hash与环境／SDK阻塞仍保留。合成drag/dataTransfer不是可信系统拖放、Pointer／OS／跨文档证明；Vue技能用于失效与清理。证据：design-ui/audits/evidence/scheduler-event-native-2026-10-16/results.json。

### Cedar Scheduler：独立拖动会话隔离（2026-10-16，Event阶段二）

独立卡片拖动按请求代次、原event／root、活动资格和本地live位隔离。旧move／up／cancel／hold／0ms解锁不能跨取消、事件替换或重新激活；pointercancel只消费对应pointerId。清理先解除原处理器并摘除自己的闭包，再结算dragging／ghost和通知，回调重入的新手势不被旧外层清理覆盖。几何／样式及通知、响应式写入后复核；350ms／8px触摸、5px启动、拖影宽度160–240px和位置策略不变，无新Token／API。

父级prop异步传递与当前对象同步改变应分开建探针；父级disabled ref尚未渲染到子组件不算同步取消失败。Vue技能用于停用／卸载、原监听／计时器和夹具清理；JSDOM合成事件／几何／模拟时钟不认证原生Pointer、native drag或跨document。原global窗口归属保持，native drag／保留click仍待下一阶段，不提前归档Event整文件。登记保持28/33族84.8%，剩5族15.2%；67文件、153/178提示86.0%，25未分类14.0%，分母不变；既有4hash／26漂移／SDK／144环境阻塞保留。证据：design-ui/audits/evidence/scheduler-event-drag-2026-10-16/results.json。

### Cedar Scheduler：受管指针长按与点击结算（2026-10-16，Event阶段一）

受管卡片350ms触摸等待是interaction-delay，0ms释放点击抑制是state-settlement，不是CSS动效时长。等待取消同时撤销旧回调资格，回调及父级finished各消费一次；新按下、配置／事件替换、停用／卸载使旧finished／解锁失效。Escape／blur释放待长按监听，激活只接受新手势。mounted／active和代次保护不等于原生手势验收；保留global document/window、350ms／8px策略及公开协议，不新增Token／Maple组件。

本批仅受管分支专项；独立拖动、原生drag与跨文档仍需独立审查，不提前登记整个Event文件或Scheduler族。进度保持28/33族84.8%，剩5族15.2%；67文件、153/178提示86.0%，25未分类14.0%，分母不变。4个旧hash、26处库存漂移、地图SDK与144环境组继续保留。Vue技能指导停用／卸载及夹具恢复；JSDOM／模拟时钟不替代原生浏览器或OS。证据：design-ui/audits/evidence/scheduler-event-managed-2026-10-16/results.json。

### Cedar Scheduler：时间线指针帧归属（2026-10-16）

边缘自动滚动是会话拥有的visual-scroll，不是CSS duration。保留40px边缘／12px每帧与5px启动策略；统一RAF先消费帧身份，拒绝旧／重复帧写入、分叉或取消替换手势。停用／卸载释放帧与监听，旧move／blur／nextTick失效，激活只接受新手势。几何与start／drop／finished及拖影写入后复核；先摘旧清理闭包再通知，保护回调重入的新会话。

Vue技能用于生命周期／探针清理；JSDOM受控RAF／几何不是原生手势／OS。本批保留原global document/window/RAF归属，跨document与原生减少动效策略独立待验。无API／Token／默认值变化，不造Maple组件。登记28/33族84.8%，剩5族15.2%；67文件、153/178提示86.0%，25未分类14.0%，Scheduler剩6条。两RAF入口合一令分母179→178，不是额外缺陷或验收；4个旧hash、26处漂移、SDK与144环境阻塞保留。证据：design-ui/audits/evidence/scheduler-pointer-lifecycle-2026-10-16/results.json。

### Cedar Scheduler：虚拟行双阶段恢复（2026-10-16）

两次nextTick结算尺寸缓存重建、锚点key转发及偏移／水平恢复，归state-settlement，不是CSS duration／原生smooth滚动。队列逻辑失效，按请求、数据／布局／options及新list／viewport身份复核；停用／卸载失效旧续体，dirty激活按当前数据重新恢复，scroll绑定代次及来源检查拒绝旧列表写heading。原key回退／几何／API／Token不变，未修改并行VirtualList。

受控带前缀列表夹具只验证父级，不认证下游；同步watch渲染中卸载的Vue内部错误探针改为第二阶段几何，才计有效基线。父级延迟inactive props到激活，直接缓存子组件收取inactive props仍另待验。登记28/33族84.8%，剩5族15.2%；66文件，152/179提示84.9%，27未分类15.1%，分母不变，Scheduler剩8条；4个旧hash重验继续阻塞全局门禁。证据：design-ui/audits/evidence/scheduler-timeline-restore-2026-10-16/results.json。

### Cedar Scheduler：依赖连线测量调度（2026-10-16）

连线RAF归measurement-scheduling，不是CSS duration，不因reduce删除必要测量。原host窗口申请／取消帧，原scroll／ResizeObserver按绑定释放；binding、frame、render三种代次分别隔离旧监听／已消费帧／nextTick。几何后复核，换host／数据、停用和卸载使旧任务失效，缺host清旧路径，激活新绑定重新测量。公开API／默认路径坐标／Token不变，其他并行核心保留。

登记28/33族84.8%，剩5族15.2%；65文件，151/179提示84.4%，28未分类15.6%，分母不变；Scheduler剩9条。4个既有Ripple／VirtualList源码hash失效仍阻塞全局门禁，不自动刷新。JSDOM几何／iframe／KeepAlive不是原生浏览器／OS或同节点跨document证明。证据：design-ui/audits/evidence/scheduler-dependency-lifecycle-2026-10-16/results.json。

### Cedar Scheduler：当前时间业务时钟（2026-10-16）

收尾门禁：两端Ripple及两份VirtualList共4个既有分类文件因并行修改hash失效，需重验、不自动刷新。下列28/33与150/179是登记进度，不代表当前全局门禁通过；这4文件不与剩5族混加。Scheduler新行独立校验通过。

当前时间指示器每30000ms刷新墙钟，归business-clock，不是CSS duration，不因视觉减少动效停止。停用／卸载取消原interval及原document的visibility监听；独立计时代次和绑定身份使旧回调不能越过禁用、销毁或重新激活。激活刷新当前时间后重新开始节奏，不补播遗漏tick；周期interval不是一次性timeout，当前合法tick可重复。

Vue清理规范用于停用／卸载和重入清理。保护并行改动按文件／依赖边界：资源core改动保留，未重叠use-now可以独立验收，不再把Scheduler整族都视为阻塞。没有公开API／Token／默认时长变化；模拟时钟／KeepAlive不认证真实浏览器或OS。族仍28/33（84.8%），剩5族15.2%；64文件，150/179提示83.8%，29待审16.2%，分母未变；Scheduler剩10提示。证据：design-ui/audits/evidence/scheduler-now-lifecycle-2026-10-16/results.json。

### Cedar Map：SDK 抑制窗口与分类边界（2026-10-15）

300ms的model中心更新窗口和500ms的地点选择窗口用于释放isUpdating、抑制程序化moveend反向解析，属于interaction-delay，不是CSS动效完成时长；不新增Token，不随reduced-motion改变业务抑制规则。map-core运行时导入已因迁移注释，三个declare不是依赖实现；缺任一SDK依赖时initMap先返回，不注册model watcher／moveend或两个timer。

本批只验证真实组件的缺SDK降级路径，不调用地图服务、不虚构off／destroy API、不修改产品源码。实际SDK的计时取消、停用／卸载、旧回调／异步请求、监听资源和MapSelect地址回填／定位仍独立待验。分类新增1文件／2提示：28/33族84.8%，剩5族15.2%；63文件，149/179提示83.2%，30待审16.8%，分母不变。分类不是生命周期／真实浏览器完成率；Maple无对应运行时。保留其他并行区域／26处漂移、144环境阻塞和Button白字例外。证据：design-ui/audits/evidence/map-sdk-boundary-2026-10-15/results.json。

### Cedar Tree：滚动命令转发分类（2026-10-15）

Tree.scrollIntoView(options)只向当前VirtualList转发原options；701行为函数声明，702行为delegated-scroll，不是两次原生滚动、RAF或CSS完成等待。Tree没有因此新增本地时钟／duration Token。保持已有公开方法、key/index/align语义及非虚拟模式无操作；停用／卸载和旧校正队列由实际下游已有availability／request守卫处理，不为分类制造父级重复调度器。

本批没有产品修复：Tree及VirtualList源码hash保持。真实Tree＋真实VirtualList、stub TreeNode、fixedSize30／模拟90px viewport验证7项：index/top600、key/bottom390、替换命令90、inactive保持37、激活新命令120、卸载后旧校正与保留命令保持37、非虚拟无操作。Tree原契约1＋TreeSelect既有1一并过滤运行，总9项通过；不把TreeSelect一项当其生命周期认证。Vue技能用于核对既有停用／卸载清理和夹具卸载。

新增1候选文件／2提示（declaration-only16、delegated-scroll5）：27/33族81.8%，剩6族18.2%；62分类文件，147/179提示82.1%，32待审17.9%，分母／库存不变。JSDOM属性滚动与模拟视口不是原生布局／smooth／CSS减少动效／OS，浏览器新增0；Tree其他保留方法、loadMore异步及任意行高仍独立待验。Maple无对应Tree运行时，只同步指南，不造组件。其他并行／26处漂移、144环境阻塞和Button白字例外保持。证据：design-ui/audits/evidence/tree-scroll-consumer-2026-10-15/results.json。


### Maple PullRefresh：手势、监听与滚动锁（2026-10-15，阶段二）

touchcancel是取消，不走刷新释放路径；新手势、target／根节点切换、禁用、停用／卸载终止当前手势，释放原锁和旧监听。touching／手势代次及原root／control／scroller身份在几何／滚动读取后复核；geometry getter中卸载不继续读旧事件目标。每次绑定保存原节点和独立代次，旧move／end不能跨激活；根ref同步绑定，不让初始post任务取消用户第一段同步手势。保留既有下拉比例、阈值和第一阶段计时／受控ack规则。

滚动锁是私有资源租约，不是CSS Token或公开API。按原HTMLElement和类名计数，同实例重复加锁不重复持有；释放幂等，最后一个租约才移除库新增class，预先存在的外部class保持。Window目标使用其document.body，不再误用全局body。这里只协调同一Maple模块的PullRefresh持有者，外部代码在租约中途改同名class、重复运行时副本、默认iframe scroller发现／adopt仍独立待验，不把它变成全库锁协调器。

有效10项基线6失败／4对照；修复中post-watch曾使两个原有立即操作用例回归，改同步根绑定后未修改原断言即恢复。最终15手势专项＋17计时专项，完整37项通过。Vue技能用于停用／卸载、原监听全组释放与锁租约／夹具清理。实际组件／KeepAlive、stub图标、模拟touch／几何及timer为JSDOM，非可信输入／真实CSS或OS；浏览器新增0。初始modelValue=true显示、动态时长／真实reduce、共享useTouch RAF及跨文档默认查找仍独立待验。

新增1文件／1条task-dispatch（4），26/33族78.8%，剩7族21.2%；61分类文件，145/179提示81.0%，34待审19.0%，分母未变。无扫描命中的私有scroll-lock helper单列hash，不虚增分类文件。仅更新本源码库存81→96及hash，193文件／392CSS／179runtime保持；其他26处漂移与并行改造、144环境阻塞和Button白字例外保留，不称全局motion-themes通过。证据：design-ui/audits/evidence/pull-refresh-gesture-lifecycle-2026-10-15/results.json。


### Maple PullRefresh：计时与刷新续体（2026-10-15，阶段一）

成功展示success-duration默认2000ms是业务期限；animation-duration默认300ms同时驱动内联回弹与复位等待；ICON_TRANSITION=150ms同时传给图标过渡并用于名称等待。三者不是同一system duration，不新增CSS Token、不把成功展示缩为视觉减少动效。统一timer入口只归task-dispatch，具体时序仍由调用方拥有。

待执行集合和原generation约束一次消费；新modelValue／手势、disabled、停用／卸载取消当前timer和图标Promise等待，取消会resolve(false)，不留下永久挂起。图标等待返回与nextTick刷新通知都核对当前请求／活动状态；nextTick只逻辑失效。当前本地update:modelValue=true的受控回填不是新请求，仍恰好发一次refresh；外部新loading取消旧成功／复位，激活按当前modelValue结算，不重放成功时钟。无公开签名／默认值变化。

有效10项基线8失败／2对照，追加取消Promise结算、受控回填、回调卸载、inactive命令、disabled完成、0时长与闲置实例保留外部锁后，17专项／完整22项通过。收尾探针在本批中间实现复现清理误移外部锁，修正为只移除本实例新增的原节点锁；该失败不并入原始基线，多实例引用计数仍待阶段二。Vue技能用于停用／卸载、timer／Promise清理及夹具恢复。实际组件／KeepAlive、stub图标、模拟touch／几何与timer为JSDOM，不认证原生输入、CSS覆盖／真实减少动效、共享useTouch RAF或OS；浏览器新增0。完整手势／touchcancel、滚动锁和旧监听／测量留阶段二，不提前归档PullRefresh。

分类仍25/33族75.8%，剩8族24.2%；60分类文件／144提示不变。四处timer合为一处，库存runtime182→179（Maple84→81），当前144/179提示80.4%，35待审19.6%；分母减3不是额外三项验收或缺陷删除。仅刷新本文件四行→81，193文件／392CSS不变，其余26处漂移及并行／144环境阻塞／Button白字例外保留，不称全局motion-themes通过。证据：design-ui/audits/evidence/pull-refresh-timer-lifecycle-2026-10-15/results.json。


### Maple SwipeCell：拖动会话与点击解锁（2026-10-15，阶段二）

拖动结束的0ms解锁是state-settlement事件顺序，不是CSS动效时长，不能跟随reduced-motion删除点击抑制。unlock独立代次且消费一次，新手势／disabled／停用／卸载物理取消计时；旧回调不能解锁新拖动或清新句柄。手势代次在回调和几何读取后复核；touchcancel及停用恢复手势前偏移、不触发打开，激活只接受新触摸。拖动标记为响应式，夹到同一偏移后释放也恢复既有CSS过渡。

每次绑定保存原root／document和独立回调，停用／卸载／节点变化解绑全组touch监听，旧move／outside跨激活无效。click通知若重入open或卸载，旧后续关闭不再执行；open通知发起新拖动时不排旧解锁。保持30%阈值、公开API、CSS变量／视觉默认值及阶段一业务确认规则；Cedar无对应运行时，不造组件。

有效14项基线12失败／2对照，最终21拖动专项＋18关闭专项、完整48项通过。补充监听探针初轮误取VTU通用eventListener，已排除包装并验证实际move／outside注册与移除；timer类型初轮编译错误已改明确DOM number，未放宽配置。Vue技能用于停用／卸载取消与测试清理。实际组件／KeepAlive、模拟touch和受控timer不等于可信触摸／原生click顺序／OS；真实浏览器新增0。共享useTouch RAF、完整测量续体、同节点跨文档adopt和事件触发的hook拒绝策略仍独立待验。

分类新增1文件／1条state-settlement：25/33族75.8%，剩8族24.2%；60文件，144/182提示79.1%，38待审20.9%，分母不变。仅更新已审SwipeCell库存248→351及hash，不刷新其他26处漂移，不称全局motion-themes通过。保留Form／日期／关联Time、Picker／Scheduler／并行样式、144环境阻塞与Button白字例外。证据：design-ui/audits/evidence/swipe-cell-drag-lifecycle-2026-10-15/results.json。


### Maple SwipeCell：关闭确认请求（2026-10-15，阶段一）

beforeClose 是业务确认 Promise，不是 CSS 动效完成或可参数化时长。每个 close 保存原命令代次；新 open（含同侧重开）、新 close、新手势、name／beforeClose／disabled 变化、停用和卸载使旧确认失效。停用／卸载后保留的 open／close 不改状态、不调用业务钩子，激活只允许新请求。禁用触发的当前关闭仍尊重 beforeClose 的 false；显式 close 的 Promise 拒绝仍向调用方传递，不新增 API／Token或改变滑动阈值／默认视觉时长。

有效12项基线10失败／2正常对照；首次夹具取错 exposed 入口的12错误不算产品失败。最终18专项／完整27项通过；Vue清理规范用于停用／卸载失效，实际组件／KeepAlive与受控Promise为JSDOM证据，不是原生手势／OS，真实浏览器新增0。0ms点击解锁、旧监听交付和完整拖动资源留待阶段二，不提前归档整族。

分类保持24/33族72.7%，剩9族27.3%；59文件，143/182提示78.6%，39待审21.4%，分母不变。只更新SwipeCell库存205→248，其他26处并行漂移、Form／日期／关联Time／Picker／Scheduler、144环境阻塞和Button白字例外保留。证据：design-ui/audits/evidence/swipe-cell-close-lifecycle-2026-10-15/results.json。


### Maple Counter：长按重复与生命周期（2026-10-15）

Counter的600ms等待＋100ms重复是interaction-repeat交互节奏：第一次长按步进在700ms，正常点击仍即时。它不是CSS动效时长，不新增Token，也不强行改为InputNumber的800／150ms。两个方向独立拥有代次与消费位；同方向新按替代旧按，释放／touchcancel／停用／卸载取消当前两计时，旧交付不清新句柄、不跨激活复活。

禁用／只读（含Form继承）、press／lazyChange、controls／方向按钮、方向禁用与数值边界使长按不可用时同步失效；激活不恢复旧手势，允许新请求。重复步进返回后再核对归属，回调内release或卸载不续排。停用的保留press／直接步进无效；未改变数值格式、步长、精度或beforeChange公开协议，异步beforeChange的请求替代身份仍独立待验，不接管Form。

有效24项基线20失败／4对照（两方向重复覆盖，不算20独立缺陷）；32专项、完整55项通过。Vue技能用于停用／卸载均取消及清理假时钟／探针。实际Counter／KeepAlive、stub按钮和受控timer不等于原生触摸／点击去重／跨文档／OS；真实浏览器／OS新增0。

分类新增1文件／4条interaction-repeat（8），24/33族72.7%，剩9族27.3%；59文件，143/182提示78.6%，39待审21.4%，分母不变。仅刷新Counter四行库存／hash，26处并行漂移、Form／日期／关联Time／Picker／Scheduler、144环境阻塞和Button白字例外保留。证据：design-ui/audits/evidence/counter-press-lifecycle-2026-10-15/results.json。

### Maple LoadingBar：任务与渲染续体归属（2026-10-15）

LoadingBar统一timer归task-dispatch：200ms显示／进度节奏、公开finishDelay、error的300ms策略，以及按computed width／opacity完成等待的300／250ms清理下限，各自保留语义，不全转为CSS duration。公开动效Token、默认值及原timer窗口归属不变；Cedar无LoadingBar运行时，不新增对应变量或组件。

每个timer在原generation且仍为待执行成员时消费一次；旧任务不能删除新句柄，重复progress不再多推进／分叉。两段渲染等待均为state-settlement，按原generation及消费位逻辑失效，不声称删除Vue队列。计算样式读取可能重入start／error，后续schedule必须显式携带旧generation，不能用读取结束时的新代次给旧hide／cleanup授权。

有效7项基线5失败／2对照；原正常完成和重启拒绝旧show回调本已通过。补旧progress／两渲染续体重启对照后10专项、完整22项通过。Vue清理规范用于取消／复用及测试时钟／mock／服务节点清理。证据为实际服务DOM＋受控nextTick／fake timers，非原生时序／OS；新真实浏览器／OS0，旧IAB6组不重复计，清理hook中重入start及任意中途样式变化另待验。

分类新增1文件／1条task-dispatch，23/33族69.7%，剩10族30.3%；58文件，139/182提示76.4%，43待审23.6%，分母不变。只更新本源码库存77→79，其他26处漂移、Form／日期／关联Time／Picker及并行样式、144环境阻塞和Button白字例外保持。证据：design-ui/audits/evidence/loading-bar-scheduler-delivery-2026-10-15/results.json。

### Ripple：统一任务派发与取消后交付（2026-10-15）

新增内部审计分类task-dispatch：统一setTimeout入口只负责任务归属／一次性消费，调用方才决定业务含义；不能把同一helper里的所有delay当成CSS duration。Ripple的30ms创建等待、20ms激活结算、最小250ms展示及删除策略、computed transform／opacity完成等待分别保留，不新增CSS Token／公共API或改变默认节奏。

schedule先核对原指令状态，再从待执行集合原子删除任务；已取消／消费回调不执行，也不能清新请求的tasker。禁用清空集合，即使同一state重新启用，旧创建／淡出仍无资格。几何／样式读取后重检当前实例与wave身份；波纹在读取其样式前登记，使读取中卸载也能移除刚插入的节点，激活读取中卸载不补写opacity。普通卸载拒绝旧创建原本通过，不重复记缺陷。

两端各8项有效基线6失败／2对照，最终各11专项（追加淡出取消／重复和激活读取卸载）、完整Ripple Cedar28／Maple33通过；类型、受影响lint／Maple根lint、两端独立源码与基础Less配对检查同步验证。首次新增Maple测试的格式lint失败已格式化并复跑，不算产品失败。Vue技能指导取消／卸载、探针清理；这是受控timer交付、模拟performance与JSDOM，不是实际OS／触摸／KeepAlive停用或跨文档adopt；本批真实浏览器／OS新增0，旧IAB6组不重复计。

分类新增两文件／两条task-dispatch，22/33族66.7%，剩11族33.3%；57文件，138/182提示75.8%，44待审24.2%，分母与库存不变。LoadingBar待下一批，其他并行改造／26处库存漂移及144环境阻塞保持，不称全局motion-themes或全库原生验收通过。证据：design-ui/audits/evidence/ripple-scheduler-delivery-2026-10-15/results.json。

### 反馈展示计时的分类补录（2026-10-15）

Message两端与Cedar Notification的duration属于business-clock：有限正值决定展示期限，0常驻；它不消费CSS进出场时长，也不因减少视觉动效缩短业务展示。hover保留Message剩余时间，KeepAlive重新激活按完整当前期限重新开始；取消／停用／卸载与旧回调归属沿用已审代次／active／open或closed规则。服务清理和CSS完成另走真实Transition完成链，不重新引入固定离场timer。

当前三份计时源码hash与2026-10-13证据完全一致，本批无产品修复／API／Token变更。复跑Cedar Message＋Notification48项、Maple Message39项通过；补录3文件／3条business-clock职责，非新增三处缺陷或新的原生验收。历史Message IAB8组、Notification6组保持独立，不再累计；本批真实浏览器／OS新增0。跨文档adopt、Message服务nextTick更新身份等属于独立消费者边界，不被计时文件分类自动认证。Vue技能用于复核停用／卸载清理职责。

分类21/33族63.6%，剩12族36.4%；55文件，136/182提示74.7%，46待审25.3%，分母不变。Ripple／LoadingBar仍需补统一调度入口取消后旧回调及重复交付，不在本批提前归档；只是源级候选，尚未复现，不制造修复。Form／日期／关联Time、其他并行样式／Picker、26处库存漂移、144环境阻塞及Button白字例外保留。证据：design-ui/audits/evidence/feedback-clock-classification-2026-10-15/results.json。

### NavMenu：根级命令与注册收口（2026-10-15，阶段六）

停用／卸载后保留的showOption、setCollapsed、setActiveItem、select、expand、activateItem及根键盘入口不通知、不改状态或消费事件。内部停用关闭仍由原cleanup更新，不把公开入口守卫套到清理路径。激活允许新命令、不恢复旧工作；卸载清空元素／所属节点与独立Item注册表，拒绝新注册。

独立Item互斥关闭按快照与activation代次遍历，新注册不被旧轮次消费，重入新activation替代旧轮次；关闭回调卸载后停止剩余回调与selection／expand写入。selection在通知之间复核生命周期／焦点请求，新的selection替代旧select后续通知。元素注销核对原NavMenuNode身份，旧同key节点不能误删替换注册。无公开API／Token／视觉默认值变化，nextTick仍只是逻辑失效。

有效12项基线10失败／2对照；最初六项停用探针误在移出后findComponent，改为预存wrapper才取有效基线，不计产品失败。最终17专项、完整NavMenu103项7文件通过，既有前五阶段一并回归。Vue清理规范用于停用、卸载和注册释放。JSDOM真实根组件／KeepAlive、stub子节点／observer及受控续体不替代原生键盘／布局／跨文档／OS；本批真实浏览器／OS新增0。Maple无NavMenu运行时，仅同步说明。

新增menu的1条declaration-only分类（扫描命中scrollTo函数声明，底层optional native调用另有行为证据），只更新其库存147行／源码hash；NavMenu两候选文件现均归档。分类19/33族57.6%，剩14族42.4%；52文件、133/182提示73.1%，49待审26.9%，分母不变。其他26处并行漂移、Form／日期／关联Time、144环境阻塞和Button白字设计例外保持，不声称全局motion-themes或全库／浏览器完成。证据：design-ui/audits/evidence/nav-menu-root-commands-2026-10-15/results.json。

### NavMenu：根级外部焦点接管（2026-10-15，阶段五）

selection返回与响应式折叠归位在排队时保存原root、所属document和原焦点，执行前核对当前焦点归属；当前外部连接控件已接管时放弃，不抢回。原焦点仍持有或移除后落到body时保留正常归位，显式context.focus仍是主动命令。折叠查询目标后再次核对代次／可用性及焦点。nextTick为渲染结算，不新增CSS时长Token／API，不撤销已执行focus。

新增3项基线2失败／1正常折叠归位对照，最终根级16专项、完整NavMenu86项通过；实际NavMenu根组件与KeepAlive、stub NavNode／observer、受控nextTick和JSDOM焦点，不是原生布局／键盘或跨文档验收，真实浏览器／OS新增0。Vue清理规范沿用已有停用／卸载失效边界。Maple无NavMenu运行时，不制造对应组件。

分类仍18/33族54.5%，剩15族45.5%；51文件，132/182提示72.5%，50待审27.5%，分母不变。仅更新menu库存129→133，其他26处并行漂移不刷新。根级保留命令及注册身份仍待审，不提前归档NavMenu。Form／日期／关联Time、并行样式、144环境阻塞和Button白字例外保留。证据：design-ui/audits/evidence/nav-menu-root-focus-2026-10-15/results.json。

### NavMenu.Item：监听、测量与焦点任务（2026-10-15，阶段四）

Item 的窗口 resize／捕获 scroll 监听归原 reference.ownerDocument.defaultView 所有；每次绑定使用独立代次和回调，正常关闭／目标变化通过 post-watch 解绑，停用／卸载直接释放。受控 open 即使拒绝关闭，也不能保留后台监听；停用仍发既有关闭请求，但保留 close／select／setOpen 与键盘／点击入口无效。激活对仍打开的当前面板重新绑定，不恢复旧回调。共享 ResizeObserver 不改，消费者启用条件跟随可用状态。

同步几何测量按 operation／原reference／可用状态核对；rect及属性读取后复核，避免 getter 中卸载后写状态或新注册窗口监听。面板／返回焦点任务按 open/close 方向、代次及原reference消费一次；配置变化取消旧任务，当前文档外部连接控件已接管焦点时放弃归位。保持受控接受／拒绝语义、公开签名及布局公式，不引入 CSS duration Token，也不回滚已执行的focus。

有效9项基线7失败／2对照；正常测量与普通卸载解绑原本通过。中间关闭焦点对照因夹具每次渲染重建options触发真实配置取消，改稳定options后补正向／重复交付／外部焦点回归。最终13专项、完整NavMenu83项通过；这是受控nextTick、stub Trigger／ResizeObserver和JSDOM几何／实际owner EventTarget证据，非原生布局／键盘／跨文档adopt。真实浏览器／OS新增0。根级其他保留命令、注册身份与根级外部焦点仍待审。

仍18/33族收口54.5%、剩15族45.5%，51分类文件、132/182提示72.5%、50待审27.5%，分母不变。Item无扫描命中，仅记录hash，不提前归档NavMenu或刷新其他26处漂移。Form／日期／关联Time、并行样式、144环境阻塞及Button白字例外保留。Maple无对应NavMenu组件，不新造副本。证据：design-ui/audits/evidence/nav-menu-item-lifecycle-2026-10-15/results.json。

### NavMenu：节点 enter／Escape 焦点归属（2026-10-15，阶段三）

节点级 nextTick 是渲染后焦点结算，不是视觉完成时长。enter／Escape 请求各由当前节点的焦点代次拥有；新请求、关闭、禁用／节点／模式／折叠配置变化、KeepAlive停用和卸载使旧续体失效。enter在展开回调返回、等待渲染后及查询目标后复核，Escape核对原reference／Trigger并消费一次。激活只允许新命令；停用保留键盘／点击／浮层回调无效，不preventDefault来吞掉旧键盘事件。Trigger原有hover延迟不改，不新增duration Token／公共API。

执行前检查reference所属文档当前焦点；若已被其他连接中的外部控件接管，不再把焦点抢回。body或原焦点仍可按正常路径结算；不能撤销已执行focus，不认证跨文档adopt、原生键盘时序或所有瞬时焦点迁移。原8项基线5失败／3对照（正常enter、禁用和卸载原本通过）；另两项外部焦点候选在无归属检查的中间实现均失败，单列而不混成原始10项基线。最终12项专项。

仍须独立审查Item的测量／监听／焦点、根级其他保留命令／注册身份及根级外部焦点接管。Maple无NavMenu运行时，不制造副本。真实浏览器／OS新增0；本批是实际NavNode与KeepAlive、stub Trigger持久面板、受控nextTick与JSDOM焦点探针，不是完整浮层或浏览器验收。候选仍18/33族收口54.5%、剩15族45.5%，51分类文件、132/182提示72.5%、50待审27.5%；node无扫描命中，仅单列hash，不新增分类文件／提示或刷新库存。Form／日期／关联Time、26处并行漂移、144环境阻塞及Button白字例外保持。证据：design-ui/audits/evidence/nav-menu-node-focus-2026-10-15/results.json。

### NavMenu：根级焦点与测量续体（2026-10-15，阶段二）

根级响应式测量与焦点归位均是渲染结算，不是 CSS 动效完成，不新增 duration Token。afterRender 按配置／生命周期代次校验并消费一次；停用／卸载失效，激活重新排当前测量与 roving tabindex，不重放旧任务。测量保留 resize 公共签名，停用时不读取几何；每次同步测量拥有独立 operation 和原 root／measure 身份，在 clientWidth／子节点 rect 读取后复核，防止 getter 中卸载后继续访问或提交。共用 ResizeObserver 工具不改，不能据此认证所有消费者。

根级 context.focus 不操作停用／卸载节点；最新 selection 或显式 context.focus 替代旧 selection 返回焦点。布局变化后的焦点归位受同一代次保护，nextTick 只是逻辑失效，不能撤销已经执行的焦点。原8项有效基线6失败／2对照，新增探针最初用了错误 BEM 类名，修正后重新取基线，不算产品缺陷。最终13专项；节点级 enter／Escape、独立 Item 的测量／监听／焦点以及其他保留命令仍待审，未称 NavMenu 全部收口。真实浏览器／OS新增0；受控 nextTick、stub NavNode／ResizeObserver 和JSDOM几何只证明根级消费者，不能代替真实布局／焦点时序。

候选进度保持18/33族（54.5%），剩15（45.5%）；51分类文件、132/182提示（72.5%），50待审（27.5%），分母未变。仅刷新menu库存行104→129，未提前归档分类。Form／日期／关联Time、26处并行CSS／日期漂移、144环境阻塞和Button白字例外保持。证据：design-ui/audits/evidence/nav-menu-root-scheduling-2026-10-15/results.json。

### NavMenu：原生滚动续体（2026-10-15，阶段一）

`scrollTo(key)` 是渲染后原生定位，不是 CSS 动效完成计时，不新增 duration Token 或公共取消 API。新命令替代旧命令；禁用、options／fieldNames／mode／responsive／折叠配置变化、KeepAlive 停用和卸载使旧 nextTick 续体失效。激活不恢复旧请求，只接受新命令；`Promise<void>` 签名、showOption 的正常展开及 nearest 对齐保持。nextTick 只逻辑失效，不物理撤销已排续体，也不回滚已发生的原生滚动。

有效基线6项中4失败／2对照；修复后8专项及全部 NavMenu45项通过。JSDOM 使用真实组件／KeepAlive和原生方法探针，不证明浏览器布局、paint或原生滚动动画；真实浏览器／OS新增0。Vue清理规范用于停用／卸载及激活边界。Maple无NavMenu运行时，不制造对应移动组件。焦点恢复、节点 enter／Escape 续体、响应式测量和保留的其他命令尚待下一阶段，不能由本批scroll测试推断通过。

候选分类进度不变：18/33族已收口（54.5%），剩15族（45.5%）；51文件、132/182提示已分类（72.5%），50待审（27.5%），分母未变。NavMenu仍部分已分类；只更新其库存行号96→104，不提前归档整个消费者。Form／日期与关联Time、其他26处并行CSS／日期库存漂移和144环境阻塞保留，不称全局motion-themes通过。证据：design-ui/audits/evidence/nav-menu-scroll-2026-10-15/results.json。

### Scrollbar Thumb：拖动会话与监听资源（2026-10-15）

承接前一批消费者边界，独立审查 Cedar 公共／旧目录及 Maple selection-scrollbar 三份 Thumb。本批直接使用真实 Thumb 与实际 EventTarget，并补实际 Parent＋Thumb 组合；只stub父级ResizeObserver并控制几何／鼠标事件，不是原生浏览器、可信鼠标／OS或跨iframe拖出认证。无RAF、计时器、CSS Token、颜色／布局或公开API新增；鼠标拖动依然是同步几何与scroll通知，不应套动效duration。

每次左键按下建立独立session：代次、track／thumb节点、不可变轴／起点及实际 thumb.ownerDocument.defaultView 共同拥有move/end。监听 mousemove、mouseup、contextmenu和blur只注册于原owner window；正常抬起、右键菜单取消、窗口失焦、几何／方向变化、停用和卸载都解除整组监听并清dragging／mouseOffset。修复原contextmenu未解绑、卸载／停用无清理及iframe误绑全局window。旧move不能推动新手势，旧end不能释放新手势；激活只允许新按下，不恢复旧drag。

方向、max、thumbSize、ratio的有效值变化取消当前手势；仅替换等值data对象不取消连续拖动。最终偏移仍由父级新测量／setOffset结算。几何读取与响应式写入后重新核对会话，防止同步卸载后绑定或通知。停用／卸载保留按下／轨道点击／setOffset入口无效且不preventDefault；非左键不启动／跳转。当前setOffset夹取、拖动期间忽略外部setOffset和轨道一thumb-size步进保持。没有Pointer／touch拖动协议迁移或原生滚动回滚承诺。

各18有效基线15失败／3对照，最终各21（补等值data／几何变化、轨道重入、实际Parent组合），Cedar42专项、Maple21；含下游Cedar168／Maple133通过。初轮iframe方法描述符／Window对象断言导致探针失败与Cedar旧报告器报错，改为自有方法包装＋布尔identity断言后重取有效基线，不算产品缺陷。Vue技能落实停用／卸载与原owner解绑、测试descriptor／iframe／监听恢复。

三Thumb在既有计时／scrollTo源码扫描无runtime提示，纳入本批hash证据但不虚增候选分类：仍47候选文件／125已分类提示、54待审（非缺陷数）。其他并行CSS／日期库存不刷新，Form与144环境阻塞保留；旧“Thumb未验”章节为历史边界，本批只新增受控证明，真实浏览器／OS新增0。证据：design-ui/audits/evidence/thumb-drag-2026-10-15/results.json。

### Scrollbar：同步测量、绑定事件与原生滚动（2026-10-15）

审查 Cedar 公共 Scrollbar、旧目录独立副本和 Maple Select 内部 selection-scrollbar 三份消费者。它们没有 RAF／计时器：读几何、更新 thumb 与 DOM scrollTo 都是同步操作，不应增加 CSS duration Token 或伪造“取消动画”API。每份扫描7提示中6处为 native-scroll，1处 function scrollTo 定义为 declaration-only；测量意义单独描述，不虚增扫描数量。

生命周期 availability 控制保留 scrollTo／scrollTop／scrollLeft、thumb命令、scroll通知与resize测量。停用／卸载使操作和绑定代次失效；激活重读当前几何，只接受当前绑定事件。旧resize／scroll／thumb入口即使在重新激活后交付仍无效。几何读取、响应式提交和子thumb回调之后核对操作／原容器／生命周期，防止同步卸载或新测量重入后由外层旧任务覆盖结果。同步滚动一旦交给浏览器已经发生，逻辑失效不能撤销它；原生 smooth 插值及其取消不在本批证明范围。

scrollTo(0,0)／单轴0是合法坐标，不用真值判断；恢复零位置也同步thumb，不保留上次偏移。水平测量使用水平比例（旧代码误用了垂直比例）。零／无效视口用有限、非负thumb数据，不显示该零尺寸轴；正常最小thumb20px与track15px布局策略不变。禁用／隐藏轴的旧thumb命令无效，但禁用条不等于禁止内容或公开原生滚动。对象选项直接透传、不模拟JS动画；公开方法签名／样式变量不变。

每副本13有效基线11失败／2对照；最终各16（补重新激活新命令、原生选项透传和水平比例），Cedar两副本32专项、Maple16；含下游 Select／AutoComplete／Cedar Mention 回归 Cedar126／Maple112。测试stub ResizeObserver／Thumb并控制几何，不等于实际观察器、Thumb拖动监听、原生smooth／paint或OS验收；真实新增0。Vue清理规范落实停用／卸载、绑定与重入归属，底层Thumb拖动可留下一批独立验收。

累计47文件／125分类提示、54未分类（非缺陷数），只刷新三Scrollbar源码行／hash；并行CSS／日期库存不刷新，Form与144环境阻塞保留。旧数字为历史。证据：design-ui/audits/evidence/scrollbar-consumer-2026-10-15/results.json。

### Carousel：播放节奏、循环结算与绑定归属（2026-10-15）

自动播放的间隔是业务播放节奏（business-clock），不是 CSS 动效时长；默认关闭，启用 true 时默认3000ms，数字／配置间隔、hover/focus/隐藏暂停规则保持。取消或重排使旧播放任务失效；当前回调消费一次后才调用导航。停用／卸载保留 next／prev／to、键盘和滚轮入口无效，不能翻页或拦截输入。激活建立新观察器／事件绑定，解绑前迟交付不得借新 active 状态重新排任务。

循环切换的 nextTick 负责等渲染，结算计时属于 visual-completion，随后双帧属于 state-settlement。请求／轨道节点／窗口核对及每阶段消费位，避免旧计时清新偏移、重复首帧分叉、旧次帧释放新的 noMotion。取消物理计时与原窗口所持 RAF；即使已出队的回调再交付，也必须先核对权限。内容重排与配置后的渲染测量任务同样绑定代次，停用后不重放。自动播放和动效阶段分别管理，不把播放间隔套进系统 duration Token。

move-speed、现有 CSS 变量和减少动效样式不变；当前 JS 结算仍按显式 move-speed 或既有 computed transitionDuration 读取（样式不可读保留180ms fallback），本批不新增 CSS Token，也不声称多属性 duration/delay、运行中时长变化或 OS 偏好已完整认证。计时仍使用原全局机制，帧使用原 owner window；同节点跨文档迁移、原生绘制另待验。

两端各14有效基线：12失败／2正常对照；最终各18专项，完整 Carousel Cedar44／Maple45。受控 nextTick／timer／observer／RAF spies 不是原生浏览器／OS 验收，真实新增0。Vue 生命周期规范用于停用／卸载、绑定清理和请求消费。累计44文件／104已分类提示、75待审（非缺陷数）；只刷新两Carousel运行时行／hash，其他并行 CSS 库存漂移不刷新。Form、日期及144环境阻塞保持，旧章节数字为历史。证据：design-ui/audits/evidence/carousel-scheduler-2026-10-15/results.json。

### Card：浮起测量与回落结算（2026-10-14）

Card 的 500ms 是 `ripple=true` 时的交互等待策略，不是 Ripple CSS 动效时长；`ripple=false` 保留零延迟。等待后读取 Card 几何并交给现有 doubleRaf 做布局稳定，再展开。doubleRaf 是 state-settlement，不是 CSS 时长，也不能通过这个既有 Promise helper 物理撤销底层 RAF；本批只撤销旧续体写布局的权限，不宣称帧被取消。文档／窗口归属仍使用既有全局计时与 helper，实际跨文档和原生绘制另待验。

渲染任务在源变化时同步递增请求代次；关闭、方向切为横向、新任务、停用或卸载后，旧 nextTick／计时器／双帧续体无权改变新阶段。渲染和计时交付消费一次，几何读取返回后再次核对节点／请求／生命周期，避免测量钩子同步卸载后继续排双帧。停用／卸载清理两计时并禁止保留 close／click 输入；激活依当前 floating／direction 发起新阶段，不重放旧任务，初始 KeepAlive 激活不重复等待。

公开 `floating-duration` 当前默认 250ms，仍同时供布局 transition 和回落恢复等待；浮起内容／按钮 opacity 仍用其两倍。它是组件公开参数，不被强行改为 system Token，本批不改公共 API／CSS 变量／默认时长／色彩语义。回落恢复归 visual-completion，500ms 等待归 interaction-delay，doubleRaf 布局意义单独解释（本扫描未命中该调用，不虚增候选数量）。

两端各 12 基线：9 失败／3 对照；最终各 15 专项（补初始激活、几何重入卸载和停用双帧），完整 Card Cedar21／Maple44 通过。受控 nextTick／doubleRaf Promise／fake timers／几何 spies，不是原生浏览器／OS 或底层 RAF 取消证明，真实新增0。累计42候选文件／96已分类提示、83未分类（非缺陷数），保存库存仍为192文件／392 CSS／179运行时提示；live扫描发现其他并行CSS变更，未刷新这些未审快照。Vue 生命周期规范用于停用／卸载、请求消费与测试资源清理。Form、日期库存漂移、144环境阻塞保持；旧章节数字为历史。证据：design-ui/audits/evidence/card-scheduler-2026-10-14/results.json。

### PreviewGroup：轨道重定位与双帧释放（2026-10-14）

循环轨道保留三份图片与中间段规范坐标；双帧 RAF 是跳转后恢复 transition 的 state-settlement，不是动效时长，零时长／减少动效仍需此稳定过程。轨道节点的 ownerDocument.defaultView 申请和取消帧／计时器；关闭、替换图片（含等长替换和原位编辑）、改变 loop、停用、卸载及新导航使旧任务失效。帧／渲染回调只消费一次，旧交付不能释放新 instant 阶段；停用／卸载保留命令无效，激活只规范化当前坐标，不恢复旧任务。图片内容监听在 post 阶段结算，避免子图片 watchEffect 注册被同步轨道读取污染。

CSS 两端轨道共同消费 `--c-sys-motion-duration-slow`／`--mp-sys-motion-duration-slow`（当前 240ms）与 `--c-sys-motion-easing-standard`／`--mp-sys-motion-easing-standard`；Maple 原固定 280ms／自定义曲线改用既有系统语义，不新增公开变量。instant、moving 和减少动效关闭 CSS transition。JS visual-completion fallback 在渲染后读取当前 transform／all 的实际 computed duration 与 delay，遵守列表对应、负 delay 和零时长；仅样式缺失／不可解析时使用私有 400ms 保底，不是上限或 CSS Token。当前自身 transform transitionend 可提前结算；忽略冒泡及时间戳早于新命令的事件，不承诺无时间戳旧事件或所有原生跨文档情形已验收。

专项最终两端各 27 项，完整 Image Cedar 62／Maple 114 项；32 组 Less／条件级联检查、16 组时长与曲线成对覆写、32 组 instant/moving 消费检查。受控 nextTick／RAF／假时钟／iframe owner 与编译检查均不算真实浏览器／OS，新真实验收 0。新增两候选文件／6 提示：40 文件／92 已分类提示、87 待审（不是缺陷数）；库存仍 192 文件／392 CSS／179 运行时提示。Form、日期库存漂移和 144 环境阻塞保留。旧章节中的“PreviewGroup 待审”与数字为历史批次。证据：design-ui/audits/evidence/preview-group-track-2026-10-14/results.json。

第 6 阶当前验证：80 项主题前景／实心背景角色检查及 64 组 primary 白字检查通过。200 组文字／中性表面对比度中 94 组低于 4.5:1，本次配色不声明普通文字对比度全部通过。

当前已统一改为第 6 阶；前文第 7 阶的对比度统计属于历史结果，不适用于当前配色。primary 实心按钮继续使用白色文案。


全组件品牌与 info/success/warning/danger 的前景色、实心操作／状态背景统一使用第 6 阶；原先直接引用色板的前景声明已接入共享 content 角色。浅色表面、禁用淡色与显式预设色板保留各自职责。此前第 6／8 阶的对比度结果不能作为本次第 6 阶调整的通过结论。

Button 禁用配色按 Arco 的变体逻辑区分：彩色实心使用淡化状态背景；text/outline 保持透明背景并淡化状态文字；tonal 保留浅色背景。中性按钮使用中性禁用色。禁用时暂停 color/text-color 覆盖，关闭 hover/active 反馈和阴影。

# Design Token 与 CSS 变量分层

### Anchor：滚动、测量帧和注册归属（2026-10-15）

Anchor滚动消费者同时拥有视觉滚动、容器scroll监听、测量RAF和render后change通知，职责不能混成CSS完成计时。私有slide从无取消句柄的b-tween包装改为目标owner window拥有的可取消RAF，保留300ms／quartOut；每帧读取当前减少动效偏好，已开启直接定位，运行中开启下一帧完成。取消停在当前位置、不跳到目标也不发finish。保留现有滚动节奏，不新增公共API／duration Token／CSS变量／颜色；共用throttleByRaf及b-tween依赖的其他消费者（含日期）不修改。

消费者按operation、binding／frame序列和change代次隔离；新点击、停用、卸载、scroll-container／boundary变化取消私有滚动与原owner测量帧、解除原容器监听。旧finish不能解锁新滚动；旧帧、几何读取重入和重复交付不能提交旧测量。change在nextTick后交付且消费一次，同hash重复点击不吞掉仍有效的待发通知。nextTick只能逻辑失效，不声称物理取消续体或回滚已执行滚动。停用保留点击无通知且不preventDefault；激活重新绑定／测量，不恢复旧动画。

AnchorLink按href与原节点注册／注销，自动watch清理覆盖href替换和卸载；父级用节点identity避免旧清理删除同hash新注册。移除当前链接会取消旧工作并重新测量。原来无cleanup的两项注册基线均失败，已修复。Maple无Anchor运行时，不新造移动端副本。

有效原基线24项：消费者15（13失败／2对照）、slide7（6失败／1对照）、Link注册2（均失败），合计21失败／3对照；对照保留正常点击、卸载几何重入边界和300ms／quartOut。新owner RAF路径需spy实际document.defaultView，不再只spy测试global window；更正探针后重跑。修复中同hash取消过度导致一次中间回归，补保留有效通知并验证。最终Anchor31（消费者18／slide9／注册2／实际组件接线1／契约1）、含Affix／BackTop64通过；配置类型、受影响lint、Maple根lint、demo编译1、分类／扫描／Message／目录28测试及3生成页通过。Vue技能落实KeepAlive停用／卸载、原owner取消与原型／descriptor恢复。实际组件测试仍在JSDOM控制几何和RAF，不证明native布局／paint、OS偏好、跨文档或同节点adopt；真实浏览器／OS新增0。

进度：33组件族中18已分类收口（54.5%），15剩余（45.5%）；51已分类源码文件。只收口原Anchor2条待审，同时新实现显式增加3条提示（测量RAF1、私有slide的RAF／偏好2），所以分母179→182，已分类127→132（72.5%），待审52→50（27.5%），不是把新增实现当成额外旧缺陷。保存候选193文件／392 CSS／182 runtime；live C103/202/98、M92/214/84，其他26处并行CSS／日期行漂移保留，不能称全局motion-themes通过。Form／Date／关联Time、其他并行样式及144环境阻塞不动。证据：design-ui/audits/evidence/anchor-scroll-2026-10-15/results.json。

### Mention：镜像重定位与观察器交付（2026-10-15）

Cedar textarea镜像滚动是render后的state-settlement，不是CSS动效完成，不添加duration Token。原来只在open变化时排nextTick，现于当前文本／候选项等变化后同步偏移，包含scrollTop回到0。sync失效代次与post-render捕获的input实例／textarea／mirror共同约束任务，交付前消费一次，几何读取后再核对；关闭、禁用、模式切换、停用和卸载令旧任务无权写入。nextTick无法物理取消，只取消旧续体提交权限；已执行native scroll不回滚，也不声称取消原生smooth动画。

镜像样式每次从当前textarea.ownerDocument.defaultView读取，不再缓存全局window样式；style读取和属性枚举后重检，拒绝重入卸载提交。观察器绑定携带lifecycleEpoch，旧resize不能跨激活读取，新绑定仍能刷新。停用／卸载保留input、clear、选择／浮层事件和focus／blur无效；禁用时不接受输入／focus，active blur仍允许。focus／blur搬入setup闭包但保持公开签名，无新API／CSS变量／颜色改变。Maple无Mention运行时，不为对齐新造移动端副本。

有效13项基线10失败／3对照；正常40px定位、卸载refs清空和scrollTop getter卸载原本通过。初轮exposed方法读取和全局window样式探针不准确，修正为真实exposed spy／实际owner view后取证，不算产品缺陷。最终21项专项＋1项实际Mention/Textarea/useSelect/Trigger组合（仅拦截native scroll记录），含既有2项Mention契约；完整消费者组合Cedar129通过。配置类型、受影响lint与Maple根lint通过，1份demo脚本／模板编译；分类／扫描／Message／目录28测试和3生成页通过。Vue技能落实KeepAlive停用／卸载、代次和测试原型／descriptor恢复。受控JSDOM／回调队列不证明真实字体、换行／IME、paint或跨文档浏览器行为，真实浏览器／OS新增0。

每批固定附候选进度：目前33组件族，17已分类收口（51.5%），16未收口（48.5%）；49已分类源码文件、127/179提示（70.9%），52待审（29.1%，不是缺陷数）。这是运行时候选分类，不是全库验收率；有已验但未归档分类的反馈组件，NavMenu仍部分分类。只刷新Mention一行库存／hash，其他26处并行CSS／日期行漂移不动。Form、Date及关联Time、其他并行样式与144环境阻塞保留。证据：design-ui/audits/evidence/mention-mirror-2026-10-15/results.json。

### Typography：复制反馈与省略测量（2026-10-15）

Cedar Typography 的 copy-delay（默认3000ms）是交互反馈等待，不是CSS动效时长；省略 RAF／CSS高度检查是测量调度，不新设duration Token。重复复制替换计时，关闭copyable、disabled或copy-delay变化清除反馈；停用／卸载取消timer和RAF，旧完成、重放、重入和旧观察器绑定不能覆盖新阶段。激活只做当前测量，不恢复旧任务；展开、关闭省略或进入编辑取消旧测量。禁用态仍测量文字布局，复制／编辑／展开交互无效。保持既有公共API、默认值和全局raf/caf归属，不宣称跨文档owner或字体／剪贴板权限认证。Maple只有Typography工具指南，无对应运行时组件，不新增移动端实现。

有效14项基线11失败／3对照；首轮stub命名和监听器读取错误不计产品缺陷。修复中发现局部ellipsis变量遮蔽导致TDZ，已纠正并重跑。最终22项专项＋3项既有测试通过，含激活新绑定、CSS测量、重入替换、copy-delay／copyable变化。Vue技能用于KeepAlive停用／卸载清理及模拟资源恢复。真实浏览器／OS新增0；Form、日期库存、其他并行样式及144环境阻塞保留。

候选覆盖率按源文件归并组件族（排除下划线内部目录及utils，同名跨端合并），不是全库验收率。当前33族：16已分类收口（48.5%）、17未收口（51.5%）；其中nav-menu部分已分类，未收口不等于从未验收或存在缺陷。运行时提示126/179已分类（70.4%），53待审（29.6%），48个已分类文件。aliased raf/caf没有被现有扫描命中，单列本批证明，不额外虚增提示。仅刷新Typography源码hash与该行库存，不覆盖其他并行漂移。证据：design-ui/audits/evidence/typography-scheduler-2026-10-15/results.json。

### ImagePreview：交互窗口与模式监听（2026-10-14）

500ms用于触摸长按通知，320ms用于双击识别窗口到期，不是CSS动画完成／关闭等待。私有tapTimer只清理双击状态，旧名tapCloseTimer已纠正；公开期限／缩放／拖动协议不变，不新增CSS Token。计时器分别核对代次并消费一次，取消／移动／抬手／关闭／换src／停用／卸载后的旧交付不能通知或清掉新句柄。

停用／卸载清理键盘、计时器、pointer capture与moving状态；保留交互入口无效，激活只允许新手势，不恢复旧手势。关闭和src变化同步清理输入。输入模式helper在停用解绑coarse-pointer MQL，绑定代次拒绝迟交付，激活重新读取当前模式；不是reduced-motion查询。文档／窗口归属仍使用既有全局document/window，本批不认证实际跨文档或原生触控。

各端17项基线15失败／2正常对照，最终17全部通过，完整Image Cedar35／Maple87通过。控制队列、fake timers／MQL／pointer events与capture spies不是原生浏览器／OS证据；真实新增0。Vue技能落实停用／卸载、消费归属、测试descriptor及假时钟恢复。证据：design-ui/audits/evidence/image-controller-scheduler-2026-10-14/results.json。

候选分类新增两Controller文件／四条interaction-delay，累计38文件／86提示、93待审（非缺陷数），库存192文件／392 CSS／179运行时提示不变。另两份useInteraction源码无本扫描runtime命中，纳入专项hash证据但不虚增分类数字。PreviewGroup轨道重定位仍待单独审查；Form、日期库存漂移和144环境阻塞保留。旧数字保持历史批次。

### Select：渲染后滚动与键盘派发（2026-10-14）

Select shared hook 的 nextTick 是等待渲染／选项登记，不是“弹层动画结束”或CSS动效完成。打开任务在关闭、重新打开、键盘新滚动、活动键命令、停用或卸载后失效；回调消费一次，即使当时没有可用选项也不能在选项稍后到达时重放。停用／卸载保留键盘、选项选择与滚动入口无效，激活允许新命令但不恢复旧任务。正常晚注册下拉节点仍可收到当前打开的滚动。

虚拟列表调用是delegated-scroll；随后可能发生的DOM scrollTo是native-scroll。虚拟回调返回后重新核对生命周期、open、请求及ref归属，防止同步关闭／卸载／替换后继续写DOM。键盘Arrow的本地同步派发新增interaction-dispatch分类，与interaction-delay区别：它没有延迟／计时器，不应生成CSS时长Token。nextTick调用点归state-settlement，实际IO独立标注。不新增CSS变量／公开API，不改变键盘与选项身份协议。

两端12项有效基线各10失败／2对照，修复后各14通过（补晚登记与空列表消费对照）；含共享hook的AutoComplete及Cedar Mention回归Cedar93／Maple96通过。Cedar旧Vitest TSX与.ts hook转换模式导致nextTick mock未接入，专项采用.test.ts取得有效基线；不是产品缺陷。受控队列／DOM几何及fake虚拟列表不等于真实浏览器／OS或完整下游组件验收。Vue技能用于停用／卸载和旧任务清理。证据：design-ui/audits/evidence/select-scheduler-2026-10-14/results.json。

当前192文件／392 CSS／179运行时提示不变，36文件／82提示已分类、97待审（不是缺陷数）。Maple本轮全库lint通过，未修改日期文件，之前23项日期示例错误属并行历史，不计本批修复；1019示例编译0失败。Form、日期库存漂移及144环境阻塞保留，真实浏览器／OS新增0。下文数字保留历史批次。

### BackTop：测量帧与滚动插值分离（2026-10-14）

显示阈值RAF属于measurement-scheduling；duration（默认200ms）／easing驱动JS插值，属于visual-scroll，不是CSS transition Token。减少动效入口直接回顶，运行中偏好变化在下一有效帧完成；必要显示测量仍保留。保持横向位置、事件与scrollToTop，不新增取消API／CSS变量。

绑定代次隔离旧监听；测量与动画帧分别核对归属并只消费一次。换目标、取消、停用及卸载使旧任务失效，不能清新句柄、更新新目标或激活后复活。自定义easing后再次核对请求归属，防止其同步取消／卸载后继续写入或排帧。RAF、cancelAnimationFrame及performance.now来自target.ownerDocument.defaultView。激活绑定新监听／更新显示，不恢复旧动画。

两端初测各14项10失败／4对照；测量回放需先等待挂载watch稳定，探针调整单列，不额外计产品缺陷。旧契约改为替换实际owner RAF／时钟。最终专项各14、完整各30通过；模拟iframe验证owner时钟与取消，不是实际跨文档浏览器／OS认证。Vue技能用于停用／卸载与descriptor恢复。证据：design-ui/audits/evidence/back-top-scheduler-2026-10-14/results.json。

合并动画排帧入口，每端候选4→3条（未删功能）；当前192文件／392 CSS／179运行时提示，34文件／70提示已分类，109待审（不是缺陷数）。Maple1017示例编译0失败；两端受影响lint通过，但Maple全库lint被并行日期示例23项格式／curly错误阻塞，按范围保留，不宣称全库通过。Form、日期库存漂移和144环境阻塞保持，真实浏览器／OS新增0。以下旧数字保留各批历史时点。

### InfiniteScroll：测量任务与观察器绑定（2026-10-14）

InfiniteScroll 的 RAF 与零延迟 setTimeout fallback 用于合并触底几何检查，归入 measurement-scheduling；不是视觉插值／完成等待，不应新增 CSS duration Token 或套用 reduced-motion。绑定被替换、停用或卸载时取消待任务并使代次失效；已出队旧回调不得清掉新句柄、检测新目标或在激活后复活，已消费回调不可重放。ResizeObserver／内容及可见性 MutationObserver 同时核对绑定代次，解绑后的迟交付不能安排新测量。

两端各10项受控队列基线7失败／3正常对照，修复后各10通过。保留 immediate 初始通知策略、状态循环与同步去重、target／阈值、check／retry 及事件顺序；本轮不接管业务请求。Vue清理规范用于停用／卸载和解绑旧观察器。受控 JSDOM 队列不等于原生浏览器、观察器时序或跨文档验收，真实浏览器／OS新增0。

累计32文件／64提示分类，117提示待审（不是缺陷数），库存192文件／392 CSS／181运行时提示不变。Form、日期库存漂移及144环境阻塞保持。证据：design-ui/audits/evidence/infinite-scroll-scheduler-2026-10-14/results.json。以下数字和待审范围保留历史批次时点。

### VirtualList：渲染后补偿与命令归属（2026-10-14）

两端 List 下游 VirtualList 当前使用 Vue nextTick 进行渲染后滚动补偿，不再直接安排 RAF；这是 state-settlement，不是 CSS 动效时长，不新增 Token 或取消 API。新命令／新滚动、数据键或虚拟模式改变、KeepAlive 停用及卸载会使旧补偿失效；回调同时核对请求代次与原容器，渲染后补偿只消费一次。停用／卸载后的保留 scrollTo 或 List.scrollIntoView 无效，重新激活不重放旧补偿，新的有效命令可正常执行。逻辑取消不会删除 Vue 已排队的回调，也不撤销先前同步完成的滚动。

各端14项受控基线10失败／4正常对照，修复后各15项通过（新增对象补偿重复交付对照）；连同既有 List 回归 Cedar41／Maple34通过。Vue 清理规则促使停用和卸载均失效；受控 nextTick／JSDOM 验证不等于浏览器或原生 RAF 验收，新增真实浏览器／OS为0。key／index／align、阈值、测量及公开 API 保持，不宣称任意几何／跨文档场景完成。

累计30文件／60提示已分类，121提示待审，库存192文件／392 CSS／181运行时提示不变。全局库存仍有并行日期 CSS 行漂移，Form 与144环境阻塞保持，不刷新未审日期快照。证据：design-ui/audits/evidence/virtual-list-lifecycle-2026-10-14/results.json。下文数字及“待审”范围保留各批历史时点，以本节为当前 VirtualList 状态。

### Icon 名称切换：视觉完成等待

Icon 的 transition 是公开JS名称切换时长，默认0；内联CSS transition-duration与JS等待使用同一个归一化值，负值／非有限值按0。不新增CSS变量、不把业务时间或交互延迟改成Token。运行时改变transition取消旧阶段并立即提交当前名称；名称被替换、减少动效变化、停用或卸载取消旧计时，已出队／已消费回调不能回滚名称或清除新动画。

KeepAlive停用期间不安排名称动画，移除减少动效监听；数据保持最新名称，激活直接显示最新值，不重放旧动画。监听从真实span.ownerDocument.defaultView读取，绑定代次拒绝解绑旧监听的延迟交付；重新激活重新绑定并读取当前偏好。具名注册、slot优先、spin与默认值保持。模拟iframe／MQL／计时器各端9项基线6失败／3正常对照，修复后完整Icon Cedar20／Maple21通过；不是实际OS／浏览器验收。同节点不停用直接跨文档adopt仍待验。

分类新增visual-completion（视觉替换等待，含偏好分支）和delegated-scroll（调用另一组件滚动，非原生DOM操作）。两端List.scrollIntoView只是方法声明及向VirtualList转发options，不能把这些源码提示当作本地动画或原生scrollIntoView通过；下游VirtualList的RAF和保留命令仍独立待审。累计28文件／58提示已分类，剩余123提示，库存192文件／392 CSS／181运行时提示不变。123不是缺陷数。Form并行改造、日期开发和144环境阻塞保持。

### IndexBar 消费者：取消与状态稳定帧

IndexBar 的 duration 是 JS 插值参数，默认0、正值保留 cubic easing，不是CSS Token。组件私有可取消任务接管入口、插值、列表／clickedName两帧等待，不再调用不能取消的通用滚动工具；两端共享工具及并行Form不改。替换／停用／卸载取消实际owner窗口待帧并让等待返回false，不跳旧目标；已交付帧及微任务仍核对归属，旧完成不能解锁新跳转。停用／卸载保留方法无效；激活等子锚点登记后恢复active/event:false。公开void scrollTo及事件／默认值不变，不新增取消API／CSS变量。

新增职责state-settlement：两帧等待是状态顺序，不是CSS动效时长。减少动效只跳插值，不跳必要稳定帧。初始10项纠正探针后基线7失败／3对照，真实IAB又复现激活定位早于子登记，补第11项。消费者11＋任务4＋既有9共24通过；最终真实IAB四组4/4、节点0、无warn/error。入口原生点击，内部命令／scroll事件脚本派发；不认证原生手势／OS／组件跨文档。固定0／480坐标及几何探针错误单列，不计产品缺陷。

证据见共享audits/evidence/index-bar-lifecycle-2026-10-14/results.json。当前库存192文件／392 CSS／181运行时提示，24文件／50提示已分类、131未分类；不是131个缺陷。Cedar无对应IndexBar，不虚构组件。144环境阻塞、其他主题／窗口、并行Form仍独立待验；下文旧数字及待验范围保留各批历史时点。

### 共享滚动真实 IAB 八组

两端各主文档默认300ms／0ms、真实同源iframe HTMLElement／Window，共8/8通过。默认实际完成302.5–313.9ms，各19次owner原生RAF、含中间坐标；0ms为0.1／0.6ms，owner RAF0。iframe四组宿主RAF0，终点left80／top220且50ms后稳定，目标节点清零，控制台无warn/error。

入口原生点击；夹具自己的计数包装原样转发native RAF，不替换时钟／帧实现。数据是原生回调首／中／末坐标摘要，不是全帧像素证明。当前reduce查询观察为false，未切换／认证OS偏好；Form／IndexBar取消、其他easing／时长／引擎仍待验。原始JPEG已查看及hash验证；18项新增证据门禁、全浏览器证据185项通过。本批无产品修复／Token/API变化，144环境阻塞保持。

### JS 滚动工具：时长、窗口与减少动效

两端 elements.scrollTo 的默认300ms与调用方 easing 保持；0／负值／NaN／Infinity直接到目标，不排插值 RAF。HTMLElement 使用实际 ownerDocument.defaultView，Window 使用目标自身；不从宿主全局 window 借帧。初始减少动效偏好直接到目标，运行中偏好变化在下一帧收敛；没有额外监听资源。每帧验证并消费代次，已消费／完成帧不能再写入或调度。

这是JS视觉滚动的执行策略，duration是函数参数，不是CSS变量；不用CSS Token冒充其消费。Maple IndexBar公开duration默认0，仍保持0；自身首帧与doubleRaf流程仍异步，工具零时长不意味着整组件没有RAF。Maple Form是实际另一个消费者，但正在并行改造，本批不接管。

两端各10项工具测试通过（基线9失败／1默认300ms对照通过），Maple既有IndexBar9项通过。Cedar探针在修复后需改绑实际document.defaultView，宿主包装对象差异不记新产品失败。减少动效与iframe均为模拟，不等于OS或真实浏览器。未新增取消API／跨调用自动替换：调用方卸载／停用、Form并行归属、IndexBar clickedName／doubleRAF／保留命令及真实滚动仍待专项，不能外推为全消费者生命周期已通过。

### InputNumber／Countdown 真实 IAB 四组

default/light、父文档，两端各长按取消／卸载与Countdown暂停／KeepAlive一组，4/4真实浏览器通过，最终组件节点均0、无warn/error。入口按钮原生点击；内部pointerdown／pointercancel由夹具脚本派发，Countdown使用公开方法。不声称原生长按、已出队竞态、跨窗口或OS通过。

长按实际首次重复间隔Cedar803.1ms／Maple802.3ms，后续152.8／153.1ms；取消后约220ms和重新按下后约100ms卸载、超过800ms期限观察都无额外更新。Countdown暂停回调计数保持13，停用保持Cedar25／Maple26，停用重置900ms后26／27保持；激活恢复计时至703／700ms，卸载后40／41保持。减少动效、业务时钟和交互节奏的边界不变。

初测直接缓存组件，父级不渲染inactive vnode导致time只在激活时传入，是夹具覆盖问题而非产品失败；改稳定缓存容器后冻结服务重启／重载，最终四组完整重跑，不重复计初测。原始JPEG已查看／校验哈希；19项新增证据门禁及浏览器证据全链167项通过。没有新增产品源码／API／Token修复；144环境阻塞仍独立。

### Countdown 业务时钟与停用边界

Countdown 的 RAF 刷新业务剩余时间，不是视觉插值；CSS duration／减少动效不能改变业务计时。暂停与 KeepAlive 停用冻结剩余时间，重新激活按冻结值续跑，不把停用期间计入消耗。停用时更新 time／reset 可更新剩余数据及 change 通知，但不申请 RAF；auto-start 的启动延后到激活，手动 pause 取消待恢复。停用期间直接 start 被忽略，卸载后的 start／reset 不再通知或调度。

每帧在清空句柄、计算和通知前验证代次，并在 change 回调后再次核对；回调内 reset／pause／start 的新任务不能被旧帧覆盖，已消费帧不能再次更新或抢占后继帧。结束只通知一次，reset 允许新一轮结束。两端受控时钟／RAF各8项通过，其中6项基线失败；完整Countdown Cedar18／Maple20项通过。没有新增CSS变量／公开API，模拟RAF不等于真实浏览器／OS验收。

### InputNumber 长按回调归属

长按每个计时回调在步进前校验并消费自身代次，取消、替换、释放、停用和卸载后的旧回调不修改值；步进内部重新开始长按，也不能被旧回调的返回值停止。停用期间不接受新的长按任务，重新激活后需要新的用户长按，不自动恢复旧手势。首次800ms、重复150ms是交互节奏，不是CSS动效时长，不新增动效Token。两端各8项受控计时／旧回调测试通过（其中7项先失败），完整InputNumber Cedar45／Maple48项通过；不等于真实浏览器或OS验收。

### 运行时计时的职责边界（分类第二批）

不能按“出现 RAF／setTimeout”就统一替换为动效 Token。本批核对两端8个文件／26条源码提示；累计22文件／44条已分类，133条未分类。提示数量包括方法声明，不是组件数量、缺陷数量或验收通过数；未分类也包含此前已有专项验收的组件。

| 职责 | 当前例子与使用场景 | Token／验收边界 |
| --- | --- | --- |
| business-clock | Countdown 用 deadline 与 performance.now 更新业务剩余时间 | 不消费 CSS 动效时长；减少视觉动效不能缩短业务时间 |
| interaction-repeat | InputNumber 长按首次800ms、重复150ms | 交互节奏不是 CSS 过渡；取消、旧回调与停用需生命周期专项 |
| test-support | delay／flushRaf、RAF与scroll mock | 保留原始扫描提示但不当产品动效；模拟方法声明也不证明浏览器调用 |
| visual-scroll | elements.scrollTo 的 JS 插值，默认300ms、调用方 easing | 与直接 native-scroll 转发区分；须按实际消费者核对窗口、取消、零时长及减少动效，不盲目接全局 CSS Token |

Maple Form 的滚动到校验项调用默认时长／linear；IndexBar 使用公开 duration／easeInOutCubic。Picker 的同名局部方法不是此工具；Cedar 未找到此工具的具名生产调用，不能据此宣称产物不可达。src 排除 __tests__ 后未发现上述 test.ts 路径导入，也不替代打包依赖图认证。

分类批次历史候选包含长按先 step 后验代次；该项已由后续 InputNumber 受控回归复现并修复，见长按回调归属小节。Countdown 暂停／重启及停用更新已由后续受控业务时钟回归复现并修复，见对应小节；滚动工具执行／当前偏好已在后续受控回归修复，但消费者取消和真实减少动效仍待专项，不外推生命周期通过。分类记录逐文件绑定完整源码哈希、当前候选行与原文，变化必须重新审阅，不自动刷新哈希。本批无产品源码／API／CSS变量变化，无新增真实浏览器或OS通过；144组环境阻塞保持。

### Trigger 真实 IAB 生命周期四组

default/light，两端各延迟取消／KeepAlive尺寸测量，共4组真实浏览器通过。原生点击夹具入口，内部mouseenter由脚本发出：不能称原生hover、人工已出队竞态、跨窗口视觉或OS证明。300ms待打开在约101ms卸载，约553ms后仍无打开／面板；重新挂载同路径实际打开（正向对照），最终节点0。KeepAlive活动实际resize计数1→2，停用期间保持2，恢复后3，重新打开并最终卸载。

真实浏览器计时／ResizeObserver／公开回调与DOM阶段保存相对performance.now摘要，截图原始JPEG已查看并校验哈希，控制台无warn/error。没有新增产品修复或Token/API；此前模拟旧回调验证仍独立，144组原生200%／Safari／Firefox阻塞保持，其他主题／位置和原生hover仍待验。


### ResizeObserver 测量批次的归属

ResizeObserver通知与RAF测量分别保存绑定代次／帧代次。换目标、关闭、停用或卸载使旧绑定和旧帧失效；已断开的observer不能把旧entries混入新批次，旧RAF不能清空／提前消费新任务。帧执行前验证代次并消费一次；保留当前窗口取消和必要测量，不新增动效Token、不把测量减少成视觉零时长。绑定代次不因正常一帧完成而失效，当前observer后续通知仍能调度。

两端模拟回归各新增3项先失败后通过，Trigger完整Cedar63／Maple76项通过，resize专项各8项。范围是工具及Trigger模拟生命周期，不等于所有消费者／真实浏览器或OS已通过；同节点跨document adopt与未刷新目标边界仍需专项验证。


### Trigger 已绑定监听窗口的清理

scroll监听记录实际绑定窗口，解绑不从当前popup ref反查。更换窗口、ref被清空或watcher尚未刷新就卸载，都在原窗口移除原处理器；RAF取消仍使用原申请窗口。两端新增模拟回归各3项先失败后通过，完整Trigger Cedar60／Maple73项通过；初轮Window spy不一致及初始化remove记录污染均属探针问题，不记产品失败。内部窗口引用不是CSS变量或API，不新增Token；同一DOM节点不换ref直接跨document adopt、真实浏览器视觉／OS仍需独立验收。


### Trigger 测量 RAF 的窗口归属

定位／滚动关闭使用 RAF 合并测量，不是视觉动效时长。元素滚动优先用事件节点 ownerDocument.defaultView；窗口滚动用当前浮层所在窗口。保存申请窗口并由同一窗口取消，代次守卫隔离已出队旧帧；在调用业务处理前清空本次事件，旧帧不能消费后续新滚动或清掉新任务。必要几何测量不因 reduced-motion 被取消，不新增 RAF 时长 Token。

两端 iframe 模拟回归各4项：正确绑定夹具后先3失败／1通过，修复后完整 Trigger Cedar57／Maple70项通过。初轮夹具未触发绑定 watcher、不作产品证据。此为模拟窗口／回调验证；真实跨文档视觉和OS偏好仍独立。旧scroll监听原窗口解绑已在后续专项完成模拟回归；同节点跨document adopt和真实浏览器／OS仍不在此证明范围。


### Trigger 交互延迟的归属

mouse-enter-delay／mouse-leave-delay 是交互请求延迟，不是 CSS 视觉时长。取消、替换请求、停用或卸载使已出队旧回调失效；当前回调只提交一次，不能清理新任务。停用仍发原有关闭请求，随后拒绝保留方法启动任务；重新激活只接受新请求，不重放旧 hover 延迟。卸载后保留方法永久不调度。内部代次／活动状态不公开、不成为 Token；受控 open 仍由调用方决定，不新增 API 或修改延迟默认值。

两端新增模拟回调归属各6项先失败后通过，完整 Trigger Cedar53／Maple66项通过；这不是浏览器帧／真实OS证明。RAF owner-window取消及跨文档定位仍需下一批独立验证；职责分类中的旧“尚待回归”说明属于首批分类时点，不把延迟回归扩大为整个 Trigger 验收。


### 运行时调度不等于动效 Token

源码扫描是逐行线索，不是缺陷或验收计数。先判定职责：声明／类型签名没有运行；测量 RAF 只合并几何读写；交互延迟决定何时请求状态变化；业务期限决定展示／轮询多久；视觉完成等待才应跟随实际 CSS 过渡完成。前四类不能仅因出现 setTimeout／RAF 就改用 CSS 动效时长，减少动效也不能取消必要测量或缩短业务期限。

首批人工分类 14 文件／18 条线索：6 声明、6 测量调度、4 交互延迟、2 原生滚动调用。Layout 原生 scrollTo 保留调用者 options，不等于已验证 smooth 或减少动效；Trigger RAF 的 owner-window 取消、已出队回调归属，交互延迟的失效回调，仍需独立生命周期回归。分类保存源码哈希／原行，变更时重新审阅，不能自动刷新哈希冒充复核。剩余159条尚未录入此分类表，包含已有专项审计，不等于159个未修问题。分类新增浏览器／OS通过均为0，不改变变量层级、默认值或公开API。


### Button 配色、7 阶与对比度边界

色板的 primary-7 是颜色档位，不是 7:1 对比度，也不保证白字可读。两端 on-dark 始终是白色前景、on-bright 始终是黑色前景。用户已明确选择主色 Button 保留 on-dark 白字，将 default/light 的 2.305:1 记录为设计例外，不声称该组合满足 AA。此前最低 6.277:1 的 on-bright 候选方案不采用。色板／背景不改，业务仍可手动选择 7 阶及配套前景；此窄范围设计决定不降低其他文字检查阈值。

普通可操作按钮文字按 4.5:1；符合大字号条件的文字可按 3:1，纯功能图标按非文字 3:1 条款评估，禁用态文字不套普通文字阈值。按钮背景与页面并非一律要求 4.5:1。icon 容器仍可能有文字插槽，不能只凭 icon 属性就放宽文字标准。目前全变体文字门禁仍保留失败，不把局部通过说成全库通过。依据：[文字对比度](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html)、[非文字对比度](https://www.w3.org/WAI/WCAG22/Understanding/non-text-contrast.html)。

业务可以使用 color/textColor 或组件变量手动选 primary-7：例如在实际 Button 根节点设置 --c-button-primary-color: rgb(var(--c-primary-7)) 与 --c-button-primary-text-color: var(--c-sys-color-content-on-bright)，Maple 对应换成 mp 前缀。背景与文字成对选择，并复核 hover/active 叠色及实际主题／底色；必要时再覆盖状态层变量。不会自动改色或禁止低对比度覆写，但默认配色通过不替业务覆写背书。若坚持白字／指定色阶，可明确记录设计取舍，不声称该组合满足 AA。

### Message 展示计时的回调归属

Message 的 duration 是业务展示计时，不是 CSS 进出动效 Token。重启、hover 暂停、clear、停用或卸载使已出队的旧回调失效；执行时核对活动状态和 open，同一调度只处理一次。KeepAlive 停用取消，激活从当前配置的完整 duration 重启（与 Notification 一致），不是继续停用前剩余时间；停用更新或卸载后保留的 restart 不启动任务。hover 仍保存剩余时间，正时长已耗尽时 resume 请求关闭一次，不误变常驻；暂停期间显式重置为0则仍常驻。只有有限正 duration 安排自动关闭，0、负数及非有限值不安排；内部代次／状态不是公开 API／CSS 变量。两端独立源码的模拟回归不是实际浏览器／OS 动效证明。

Message 服务退出由组件真实 Transition 的 after-leave→closed→条目清理负责：不再强制150ms完成，也不以200ms兜底提前卸载。公开 transition-duration／timing-function 的覆写能决定实际离场；显式零或减少动效仍走完成链，不延长业务 duration。尚未挂载就 close/clear 的条目没有离场，直接清理并报告服务 onClosed；不伪造组件 open/opened/close 动画事件。clear 用当前条目快照，同步删除不跳项；同ID重开时忽略仍为open的旧完成。模拟完成协议与源码门禁不是实际浏览器长时长通过，原生IAB仍待补。

Message 真实 IAB default/light、top 服务八组已通过：两端默认、600ms/linear、显式零和离场途中同ID重开。默认离场 Cedar104.4ms／Maple153.8ms，长离场603.8ms／604.8ms，重开最终604.7ms／612.6ms；重开后的业务展示期限约1204.9ms／1203.6ms，最终closed各一次、节点归零。重开会取消旧根DOM并创建新根，不将旧节点移除算作完成600ms离场；不保证所有退出捕获原生end事件，以真实leave-to→清理链留证。原生JPEG和规范化时序摘要见 design-ui/audits/evidence/message-native-2026-10-13。未覆盖hover、KeepAlive、其他主题／位置、真实OS、原生缩放或Safari／Firefox。

Message 局部 reduce 规则在独立组件样式生效：Cedar 取消根/进出过渡及图标淡入动画；Maple 取消进出过渡和动画位移，但保留独立提示的 translateX(-50%)／居中 translate(-50%, -50%) 静态定位。不能用 transform:none 抹掉布局定位。现有 duration/easing 消费者与覆写编译28项、减少动效选择器/布局68项通过；不更改 Token 默认值、显示期限或颜色，不依赖全局极短时长。这里的 !important 仅用于内置动效偏好，不授权普通主题覆盖。子图标自身 spin 属于 Icon 的独立规范；不冒充真实 OS 动态切换验收。

### Maple LoadingBar 动效与生命周期

LoadingBar 为 Maple 独有服务，不新增 Cedar 对应 Token。公开 --mp-loading-bar-transition-duration 默认 250ms、--mp-loading-bar-transition-timing-function 默认 ease，控制 width、opacity、background-color；不再使用 transition: all。设置在服务真实祖先（通常 documentElement/body），业务卡片内部无法传到服务。transitionDuration 内部 0ms 用于起始复位，不是公开选项。

200ms 显示等待／进度 tick、300ms 完成停留与 250ms 清理下限是调度策略，不是 CSS Token。完成宽度更新并刷新 DOM 后，等待 max(300ms, 实际 width transition duration+delay) 再隐藏；隐藏刷新后等待 max(250ms, 实际 opacity duration+delay) 卸载服务，下一次 start/error 重新挂载。解析实际节点计算样式，支持 s/ms、all、列表重复和负 delay；不承诺开始等待后的任意 CSS 改动或自定义 animation。reduce 关闭视觉过渡，进度与清理仍工作；显式 0ms 仍保留下限。

重复 finish 在延迟及关闭阶段去重；start/error 取消过时任务并使已出队回调失效。setDefaultOptions 替换完整配置，resetDefaultOptions 清除全部已拥有配置；无 DOM 的 SSR 调用不挂载或安排计时器。Vue 清理规范用于计时器归属与完成后卸载；命令服务不冒充调用页面自动绑定的生命周期。模拟时钟／计算样式、SSR 与 Less 编译不能记为真实浏览器／OS 验收。

真实 IAB 补验：默认、长时长加 delay、显式零、重复完成、重启、失败六组通过，最终服务节点归零；长时长隐藏／卸载等待实测 700.9ms／802.9ms。MutationObserver、真实计算样式与原生 JPEG 证据见 design-ui/audits/evidence/loading-bar-native-2026-10-13。原生点击触发夹具的明确业务序列，不外推真实 OS 偏好、原生缩放、Safari／Firefox 或设备触摸。

Cedar 独有 Notification：duration（3000ms，0 持续）是业务展示时长；六项 CSS transition Token 独立控制 opacity 和左右进出。close 每个挂载实例只发一次并取消计时；关闭／停用／卸载后的过时回调失效。reset-on-update 仅重启活动且未关闭实例；KeepAlive 停用取消，激活从完整配置时长重新开始。列表由 TransitionGroup 的实际离场完成负责卸载。17 项服务／组件／SSR、20项正常编译消费者／成对覆写及44项减少动效选择器通过。局部 reduce 取消 opacity／方向过渡和起始位移，不依赖全局兜底；真实 IAB 的 default/light 服务六组已通过；真实 OS 和其他引擎／主题／位置矩阵仍待验收，不新增 Token 或伪造 Maple 对应组件。

Notification 真实证据见 design-ui/audits/evidence/notification-native-2026-10-13：默认／长离场／零、clear同ID重加、活动身份保持与原生手动关闭，保留原生JPEG。框架空测量克隆不算通知实例；以公开transition elapsedTime或真实leave-to／移除链核对完成，class时间戳不冒充帧级时钟，显式零不等于真实OS减少动效。

clear 同步释放逻辑 ID；clear 后重加相同 ID 使用新的内部条目／组件身份及完整展示计时，更新仍活动的 ID 则保持实例。WeakMap 实例键仅是实现细节，不作为业务 API 或 CSS 变量。clear 保持静默，指定位置清理不影响其他位置。

> 本页是共享规范的文档站镜像。事实来源为 `design-ui/standards/design-tokens.md`；规范更新时应同步更新本页与 Maple 对应页面。

Cedar 与 Maple 使用同一套逻辑 Token 语义，只允许品牌前缀不同：Cedar 为 `--c-`，Maple 为 `--mp-`。共享不是要求所有像素值都相同，而是要求同名 Token 表达同一职责；确需不同的触控尺寸、密度和平台结构必须显式登记。

## 重构时保留 Token 职责（2026-10-09）

组件主体或 DOM 同源化后，公开变量必须重新核验到终端 CSS 属性的完整链路；保留声明和文档并不代表定制仍有效。内部适配层只连接平台默认值，不得把不同职责合并成一个时长或用硬编码绕过已有公开入口。

Rate 是一个具体例子：两端的 `--{p}-rate-transition-duration` 控制普通颜色／hover 过渡，`--{p}-rate-scale-duration` 控制选中缩放动画，`--{p}-rate-transition-timing-function` 控制两者缓动（p 为 c 或 mp）。Cedar 与 Maple 的默认时长和曲线允许平台差异，但三个入口必须真实消费。内部映射声明在组件根节点，而不是 :root，确保实例及祖先的公开变量覆盖在当前作用域解析。减少动态效果偏好优先关闭这些动效。

文档站布局不是组件 Token API。断点、目录与预览区的排列由站点样式负责，不加入 system 颜色或组件尺寸契约；长变量表应局部滚动。源码消费检查、断点布局、键盘导航和真实设备验收应分别记录，不能互相替代。

### 可选覆盖与按实例尺寸回退

VerificationCode 的公开变量 `--{p}-verification-code-cell-height`、`cell-max-width`、`input-font-size` 默认声明为 `initial`：它表示未指定覆盖，而不是最终高度／宽度／字号。在这些未注册的自定义属性上，`initial` 使消费处的 `var()` fallback 生效；消费处再读取当前实例 size 对应的私有映射。不要在 `:root` 中引用仅在组件根节点定义的私有尺寸，否则默认值无法在正确作用域解析。

`cell-height` 控制单格高度，`cell-max-width` 控制单格首选宽度（空间不足时允许收缩），`input-font-size` 控制字符字号，`gutter` 控制相邻格间距。前三项未覆盖时跟随 xs/sm/md/lg/xl 字段尺寸，gutter 默认引用 system space-2；组件 gutter 属性会写入同名内联变量。业务在组件实例或业务容器上覆盖这些公开变量，不依赖私有映射，也不应把一个平台的像素值当作跨端统一标准。

这是明确的“可选覆盖 → 实例 size”契约，不是为缺失的内部 system Token 兜底。取消某个覆盖以恢复 size 时可在目标实例设置该变量为 `initial`；`unset` 对普通可继承的自定义属性会继承祖先值，不能当作同义重置。验收应同时放置不同 size、自定义实例和未覆盖邻居，并检查明暗主题与窄屏收缩。

## 当前状态与阅读方式（2026-09-30）

本轮源码、契约和消费路径的自动检查已形成闭环。System 默认值分为共享语义与明确的平台值；组件颜色、几何、排版、阴影、动效和层级按同义同值或平台差异登记。契约会随新增组件更新，当前数量以机器校验输出和菜单中的完整变量参考为准，不在各阶段叙述中维护另一份总数。

原 91 项消费候选已经逐项处置：恢复真实定制入口，删除无效历史变量，并复核运行时引用。InputTag、Form、Tree 的五档相关缺口已补齐；Tag 预设色、FieldDecorator 错误／禁用优先级、非颜色角色与 reduced-motion 均有持久检查。Message 已统一为 neutral / tonal / solid 三个强调层级，Cedar 默认 neutral、Maple 默认 solid，保留原有默认外观，不再属于待决设计。

在 design-ui 运行 `node bin/token-inventory.mjs --check-consumers --summary` 验证未审消费候选为零；去掉 `--summary` 可查看声明条件、public/internal 层级、终端 CSS 属性和已审核运行时路径。普通字面引用只是线索，只有登记的实际绑定或有限动态名称可作为消费依据。扫描统计针对组件 token 文件，不是 foundation/system 所有变量的总数。

完成记录与后续验收见 `design-ui/audits/token-closure-progress.md`。实际 Chrome 已抽查两端 Message 三变体、主题切换、局部覆盖和关闭，以及 InputTag／输入控件和常用反馈组件；这不等于跨浏览器、真机触摸或全库视觉验收。本文后续带“阶段／本批”的范围、旧名称和数字是历史设计记录；如与当前状态冲突，以本节、完整变量参考和机器契约为准。

### FieldDecorator：状态专属入口

以下后缀属于 `--c-field-` / `--mp-field-`，两端职责相同：

| 变量后缀 | 默认值与消费场景 |
| --- | --- |
| variant-outline-border-color-error | system status-danger；outline 错误态的边框和焦点边框。 |
| variant-standard-line-color-error | field-error-color；standard 错误态的底线及焦点底线。 |
| variant-standard-line-color-disabled | system border-subtle；standard 禁用底线，优先于 error、focus、hover。 |

这些入口此前有声明但没有真实消费；现在局部覆盖会生效。普通错误提示文字仍使用 field-error-color，不因某个变体边框定制而跟着变化。禁用底线从错误的“文字禁用色”定义改为“弱边框”语义，默认渲染延续原有禁用边框颜色。公开 Token 的有效性必须同时验证声明、选择器消费和覆盖结果，不能只对齐名字。

逐变量名称、值与消费位置见[组件 CSS 变量参考](llms/zh-CN/guide/design-token-reference.md)。

## 完整收尾后的设计规则

### 同义、同值与平台差异分开管理

共享名称表示相同职责，不代表强迫桌面与触摸布局使用相同像素。系统变量的每个默认值都必须进入契约：跨端相同的值登记在 systemTokenValues，控件高度和浮层层级等明确差异登记在 platformSystemTokenValues。组件同值入口用 componentTokenValues；有依据的密度／结构差异用 platformComponentTokenValues。一个变量不能同时登记为共享默认和平台例外，避免两份事实来源。

字号、字重、间距、普通圆角和状态过渡优先消费对应 system 角色；不能因为数值碰巧相等就把图标尺寸、徽标点径或布局补偿绑定到 control-height。百分比、无单位比例、布局结构、循环时长与专属形状可以留在 component 层，必须说明原因。减少动态效果设置应停掉非必要过渡／循环，而不只是调暗颜色。

### 状态与定制的优先级

- filled 外壳由 FieldDecorator 单独负责，正常、hover、focus 递进；Form 只提供校验与说明，不再次绘制外壳。
- disabled / readonly 是交互约束，不能由子标签的 closable / checkable 或局部属性绕过。只读可以保持可读外观，但不得修改值。
- pressed（按下）、selected（持久选中）、focus（键盘／输入焦点）不是同一种 active。每个组件明确叠加规则，不能用统一的 hover 选择器覆盖所有状态。
- 颜色变量成对设计：背景与正文、图标、边框、关闭按钮分别有职责。透明背景必须先与真实宿主表面合成再计算对比度。
- 弹层／Teleport 的定制放到实际挂载祖先或弹层根节点；外层触发按钮上的变量不一定能继承过去。行内 color / textColor 是显式业务定制，不纳入默认主题的对比度承诺。

### Message 的三个强调层级

| variant | 场景与颜色职责 | 默认 |
| --- | --- | --- |
| neutral | 中性 overlay 面板，正文 primary，状态由图标表达，关闭按钮 secondary。适用于常规操作反馈。 | Cedar |
| tonal | 低强调状态底色，正文保持可读内容色，图标表达状态。适用于需要轻量区分状态的反馈。 | 两端显式选择 |
| solid | 高强调状态实色底，使用对应明亮／深色表面的前景；default/loading 保留专属深色面板。适用于强调提示。 | Maple |

两端统一 message-{variant}-{status}-{bg|content-color|icon-color|border-color|close-color}。status 为 default/info/success/warning/danger/loading。默认外观和平台密度保留，不把原移动端实色错误命名为 tonal；原隐式颜色变量直接迁移到明确变体，无别名。边框颜色的语义一致不代表必须给移动端新增边宽。

### 从声明到验收

变量必须有真实消费路径：本组件CSS、跨组件CSS、已登记的运行时绑定或有限动态名称展开。文档、注释、主题赋值和相互引用都不能单独证明变量有效。无实际功能的旧变量删除；已有DOM与职责却没接通的变量修复消费。自动目录提供每个变量的声明值、选择器条件、层级及传递消费属性，实际状态覆盖仍由针对性测试和浏览器验证。

新增或修改 Token 时同步五件事：源码及调用者、共享／平台契约、状态与覆盖测试、组件参考文档、迁移说明。自动生成的变量表不手工改；check:token-reference 防止它与源码漂移。

## 四层模型

| 层级 | 职责 | 外部使用 |
| --- | --- | --- |
| Foundation / reference | 原始色板、尺寸刻度等基础值 | 不建议业务直接依赖 |
| System | 跨组件的稳定语义角色 | 全局主题可以覆盖 |
| Component | 单个组件公开的定制入口 | 业务定制首选 |
| Internal | 组件实现细节 | 禁止外部依赖 |

## System 颜色语义

| 组 | Token | 场景 |
| --- | --- | --- |
| surface | `page / default / raised / overlay / muted / tooltip` | 页面、普通容器、浮层、覆盖层、弱化填充表面 |
| scrim | `sys-color-scrim` | 半透明遮罩；与承载内容的 surface 分开。 |
| content | `primary / secondary / tertiary / decorative / disabled / on-dark / on-bright` | 普通表面上的内容层级，及已确认深色／亮色底上的对比前景；后两者须成对选择 |
| content（语义色） | `brand / info / success / warning / danger` | 普通中性表面上的彩色文字、图标及同色描边；品牌色与 info/success/warning/danger 均使用对应色板第 6 阶 |
| border | `subtle / default / strong` | 弱分隔、常规边框、强调边框 |
| action | `primary` | 主操作及品牌交互强调 |
| status | `info / success / warning / danger` | 状态填充和强调色；普通表面上的可读彩色文字选对应 `content-*` |
| state | `hover / selected` | 与组件无关的通用交互状态表面 |

System Token 使用 `--c-sys-{category}-{role}`。同一个颜色角色在 Cedar 与 Maple 必须映射到相同逻辑基础值，标准值由 `theme-contract.json#systemTokenValues` 管理。完成治理的公开组件 Token 默认值登记在 `componentTokenValues`，目前已覆盖 FieldDecorator、Collapse、Dialog、Card、Divider、Empty 与 Avatar 的关键颜色语义。Dialog 的边框、尺寸与布局允许平台差异。Card 悬浮按钮容器使用 `content-primary`，固定深色关闭按钮上的文字使用 `content-on-dark`；其 `#212121` 背景是组件专属值，不代表主操作色。Divider 线条使用 `border-default`、文字使用 `content-secondary`；文字留白 Cedar 为 `16px`、Maple 为 `8px`。Empty 描述使用 `content-tertiary`，非文字装饰图标使用 `content-decorative`。即使两端数值相同，也应检查组件默认值及主题覆盖是否使用正确的 system 语义，不能以相同的硬编码值代替语义。

Avatar 也已纳入跨端颜色治理：文字、汇总数量和按钮图标使用 `content-primary`；描边使用 `surface-default`；仅深色遮罩图标使用 `content-on-dark`。默认 `fill-4` 背景、触发按钮 `fill-2 → fill-3` hover 阶梯、半透明遮罩是组件视觉值。按实例覆盖背景（`color` 属性）时须检查文字对比度，必要时覆盖 `--c-avatar-text-color`；system 角色不能保证任意前景／背景组合的对比度。Maple 暗色 Avatar 背景 `#303030` 是主题专属组件值。

Badge 第三阶段治理：填充背景使用 `status-*`／`action-primary`，轮廓文字和描边使用 `content-info/success/warning/danger/brand`；default 轮廓使用 `content-primary`，secondary／tertiary 使用 `content-secondary`。轮廓背景变量对所有状态和 `color` 属性均生效。两端的 Maple 浅色品牌均为填充 primary 配置浅字。编译后的 CSS 验证覆盖 640 个内置配色组合及 64 个轮廓背景覆盖场景，填充文字最低 4.56:1，轮廓文字最低 4.97:1；自定义色与背景需重新验证，其余未登记变量仍待治理。

`content-brand` 引用 primary 第 6 阶；`content-info/success/warning/danger` 引用对应色板第 6 阶，适用于普通中性表面上的可读彩色文字、图标和同色描边。`content-brand` 与 `content-primary`（主要内容层级）、`action-primary`（主操作强调）职责不同；仅覆盖主操作色不会自动改变品牌文字色。

Card 预发布变量迁移：`--c-card-close-button-primary-color` → `--c-card-close-button-background`，不保留旧名别名。

## Component 与 Internal

公开组件 Token 使用 `--c-{component}-...`，必须在组件文档中说明；默认值优先引用 system Token。业务侧应优先覆盖这一层。

按实例属性写入的 CSS 变量（如 `--c-divider-opacity`）是运行时传值通道，不代表 `:root` 中存在同名主题默认值；组件文档应标明来源。

Internal Token 使用 `--c-internal-{component}-...`，只用于内部节点协作、运行时测量或不稳定实现。主题、业务代码和公开文档不得依赖它；需要开放定制时，应提升为公开 component Token。

## 选择顺序

1. 已有公开 component Token：直接使用。
2. 跨组件通用语义：使用或新增 system Token。
3. 单组件且需要外部定制：新增公开 component Token，以 system Token 作为默认值。
4. 纯实现细节：使用 internal Token。
5. 不添加无人消费的兼容别名来制造表面对齐。

## 命名与平台差异

Token 名顺序固定为：组件 → variant/status/size → interaction state → CSS property。状态统一使用 `hover`、`focus-visible`、`active`、`disabled`、`loading`、`selected`、`error`。

允许不同：控件高度、触控目标、移动端 safe-area、桌面 hover 能力、平台层级实现。禁止不同：system 颜色角色、同名组件 Token 的职责、状态名称和公开/私有边界。

## 完整 System Token 目录

以下用 `--{p}-` 表示平台前缀：Cedar 的 `p=c`，Maple 的 `p=mp`。颜色映射是跨端契约，不应因组件或主题作者的个人判断改变角色；主题可以改变基础色板的具体色值。完整机器可校验清单在 `theme-contract.json#tokens.system`，下表说明每个角色的职责。

| System 颜色后缀 | 默认基础值后缀 | 应用场景与边界 |
| --- | --- | --- |
| `surface-page` | `color-bg-1` | 应用页面底色；不用于弹窗。 |
| `surface-default` | `color-bg-2` | 卡片、普通容器及展开后的内容表面。 |
| `surface-raised` | `color-bg-3` | 高于普通内容的浮层，如 Dialog。 |
| `surface-overlay` | `color-bg-5` | 更高层的弹出内容表面；不是半透明遮罩。 |
| `surface-tooltip` | `#373739` | 明暗主题均保持深色的提示表面，搭配 on-dark。 |
| `scrim` | `rgba(0, 0, 0, 0.6)` | 半透明遮罩，不是正文表面。 |
| `surface-muted` | `color-fill-1` | filled 默认态或弱化填充；不是禁用态的统称。 |
| `content-primary` | `color-text-1` | 标题、主要正文及普通表面上的主要图标。 |
| `content-secondary` | `color-text-2` | 辅助文字、次要操作与 Divider 标签。 |
| `content-brand` | `primary-6`（RGB） | 普通中性表面上的品牌文字、图标及同色描边。 |
| `content-info` | `blue-6`（RGB） | 普通中性表面上的信息文字、图标及同色描边。 |
| `content-success` | `success-6`（RGB） | 普通中性表面上的成功文字、图标及同色描边。 |
| `content-warning` | `warning-6`（RGB） | 普通中性表面上的警告文字、图标及同色描边。 |
| `content-danger` | `danger-6`（RGB） | 普通中性表面上的危险文字、图标及同色描边。 |
| `content-tertiary` | `color-text-3` | 占位、低强调说明；必要时检查文字对比度。 |
| `content-decorative` | `color-text-4` | 空状态等非文字装饰图形；不可用于需要阅读的文字。 |
| `content-disabled` | `color-text-disabled` | 真正不可交互的内容；不能拿来表示装饰。 |
| `content-on-dark` | `color-white` | **已确认深色表面**上的文字与图标；背景可变时不能盲用。 |
| `content-on-bright` | `color-black` | **已确认亮色表面**上的文字与图标；暗色主题也保持深色，仍须按配色核验。 |
| `border-subtle` | `color-border-1` | 弱分隔、低强调边界。 |
| `border-default` | `color-border-2` | 普通控件描边与 Divider 线条。 |
| `border-strong` | `color-border-4` | hover 等需要更明确边界的状态。 |
| `action-primary` | `color-primary` | 品牌主操作及焦点强调；不是“颜色深”的同义词。 |
| `status-info` | `color-info` | 信息填充和强调色；普通表面上的可读信息文字使用 `content-info`。 |
| `status-success` | `color-success` | 成功填充和强调色；普通表面上的可读文字使用 `content-success`。 |
| `status-warning` | `color-warning` | 警告填充和强调色；普通表面上的可读文字使用 `content-warning`。 |
| `status-danger` | `color-danger` | 危险填充和强调色；普通表面上的可读文字使用 `content-danger`。 |
| `state-hover` | `color-fill-2` | 中性组件的 hover 表面；仅在可 hover 的设备上使用。 |
| `state-selected` | `color-primary-light-1` | 选中项的品牌浅色表面；不等于按下态。 |

非颜色 system Token 是跨组件可复用的基础节奏，名称相同但可允许平台密度不同。当前完整类别如下：

| 类别 | Token 后缀与标准值 | 设计用途 |
| --- | --- | --- |
| 间距 | `space-1…8` = `2 / 4 / 6 / 8 / 12 / 16 / 20 / 24px` | 内边距、元素间距与组合间距；新增刻度前优先复用现有八档。 |
| 圆角 | `radius-sm/md/lg/pill` = `2 / 4 / 8 / 999px` | 常规控件、容器和胶囊形状；圆形头像的 `50%` 属于组件几何，不必强套。 |
| 字号 | `font-size-xs/sm/md/lg/xl` = `12 / 13 / 14 / 16 / 18px` | 组件文字层级；超出刻度的大标题仍可作为组件专属值。 |
| 字重 | `font-weight-regular/medium/semibold` = `400 / 500 / 600` | 常规、强调和强强调；避免每个组件另造一套数字。 |
| 动效 | `motion-duration-fast/standard/slow` = `120 / 180 / 240ms`；`motion-easing-standard` = `cubic-bezier(0.4, 0, 0.2, 1)` | 普通交互时长；动效应尊重 `prefers-reduced-motion`。 |
| 层级 | `layer-behind/base/raised` = `-1 / 0 / 1`；`layer-popup/modal` 映射平台层级 | 组件堆叠关系；不要把某端的绝对 z-index 值当作跨端语义。 |
| 控件 | `control-height-xs/sm/md/lg/xl`；`control-touch-target` | 高度按平台密度确定：Cedar `28/32/36/40/44px`，Maple `44/48/52/56/60px`；触控目标两端均为 `44px`。 |

## 组件 Token 的设计维度

组件 Token 名应回答“哪个组件、哪个部位、什么视觉分支、什么状态、控制哪个 CSS 属性”。推荐顺序是 `--{p}-{component}-{part?}-{variant/status/size?}-{state?}-{property}`；可省略无关维度，不为对称而制造空变量。属性名要对应实际消费属性：控制背景用 `background`，控制文字用 `text-color`，不能用模糊的 `primary-color` 指代深色背景。现存历史名称可分批迁移，迁移必须同步契约与文档。

| 维度 | 何时需要 | 示例 |
| --- | --- | --- |
| part | 同一组件有多个独立可定制部位 | `dialog-title-text-color`、`card-close-button-background` |
| variant | 视觉结构互斥 | `field-decorator-variant-filled-background` |
| status | 信息或操作语义 | `dialog-status-danger-color` |
| size | 几何档位 | `card-size-sm-title-font-size` |
| state | 交互／可用性变化 | `field-decorator-variant-filled-background-hover` |
| property | 对应实际 CSS 职责 | `background`、`border-color`、`text-color`、`padding` |

状态 Token 只在需要不同值时创建；默认态、hover、focus-visible、active、disabled 的优先级由组件交互定义，不能仅依赖 Less/CSS 规则的书写先后。特别是 filled 输入框：默认 `fill-1`、hover `fill-2`、focus `fill-3`；同时 hover 与 focus 时 focus 必须胜出。`focus` 表示实际焦点样式，`focus-visible` 专指键盘可见焦点，不可混名。禁用态不应继续显示 hover/focus 强调。

组件默认值原则上从 system Token 引用；只有跨组件没有稳定语义的特定形状或对比表面，才允许组件专属常量，并在组件文档说明。例如 Card 的深色关闭按钮背景 `#212121`，不能因为它很醒目就映射到 `action-primary`。尺寸、触控目标与布局可以不同，但两端同名组件变量的职责必须相同。

## 覆盖与主题解析

推荐链路为 `foundation → system → component → CSS 消费点`。业务只改一个组件时覆盖公开 component Token；品牌／明暗主题改变跨组件角色时覆盖 system 或其基础色板。主题文件若直接写入组件 Token，同样要保持该 Token 的角色语义，不允许暗色主题把 `content-secondary` 偷换成无解释的 `#aaa`。组件样式消费 component Token，不越层直接使用基础色板。

```css
/* 只改变某个对话框，不影响其他浮层 */
.my-dialog { --c-dialog-background: #fff8ef; }

/* 改变整套主题的浮层表面 */
[data-theme='custom'] { --c-sys-color-surface-raised: #fff8ef; }
```

覆写组件背景时，应同时检查其文字、图标、边框和交互态的对比度；`content-on-dark` 只适合背景确实保持深色的场景。`var()` 的 fallback 仅用于明确的外部兼容边界或已记录的可选覆盖（如 VerificationCode 的实例 size 回退），不应掩盖缺失的内部 system Token。颜色混合和透明度属于需要解释的组件行为，不应靠孤立的硬编码颜色掩盖。

`--{p}-internal-{component}-...` 是私有实现变量，允许因内部重构改变。按实例由属性注入的变量则属于“运行时传值通道”，例如 Divider 的 `opacity`：它可能与公开组件 Token 同名空间，但没有可供主题作者覆盖的 `:root` 默认值。组件文档要明确是静态默认值、主题覆盖值、还是运行时写入值。

## 跨端治理与变更流程

1. 确定视觉职责：先判断是 surface、content、border、action、status、state，还是组件独有的几何值。不要因为现值相同就认定语义相同。
2. 查找现有角色；若无法准确表达，先讨论新增 system 角色或登记有理由的组件特例，不强行套用“最接近”的颜色。
3. 同步 Cedar 与 Maple 的 Token 名称、消费属性、默认值及主题覆盖；平台差异必须写明原因，必要时进入契约 allowlist。
4. 将共享默认值写入 `theme-contract.json#componentTokenValues`，新增 system 名称和值写入 `tokens.system` 与 `systemTokenValues`；更新组件文档和两端菜单镜像。
5. 检查亮／暗主题、hover/focus/disabled 组合、CSS 变量引用是否可解析；运行契约检查、相关组件测试、文档检查及差异检查。

早期颜色阶段从 FieldDecorator、Collapse、Dialog、Card、Divider、Empty、Avatar、Badge、Tag、Alert、Button 展开；当前已扩展为完整声明目录及颜色／非颜色契约。共享契约管理名称及已治理的默认值；尚未纳入 `componentTokenValues` 的组件变量并不自动合规。修改公开 Token 名称时先确认发布阶段，提供迁移映射，不能偷偷留下无人消费的别名。

## Tag：状态色、选中态与定制边界

Tag 的 default 是浅色填充，不是 Badge 的高强调实心背景。primary / info / success / warning / danger 的文字及 outline 同色描边分别使用 content-brand / info / success / warning / danger；secondary 与 tertiary 使用 content-secondary。彩色填充背景使用对应 primary / blue / success / warning / danger 色板第 1 阶，secondary 使用 gray-2，tertiary 使用 gray-1。这些背景是 Tag 专属配对表面，不新增含糊的通用 system 角色；不能仅因历史颜色相似就把 success / warning / danger 固定到 green / orange / red。

| 变量族（省略平台前缀） | 职责与使用场景 |
| --- | --- |
| tag-status-*-text-color / bg-color | 已选中 default 变体的成对前景与背景；修改背景须同时验证文字。 |
| tag-variant-outline-status-*-color | 已选中 outline 的文字与边框共用色；背景透明，不复用实心填充色。 |
| tag-variant-outline-default-color / default-border-color | 默认及未选中 outline 的中性文字、边框。 |
| tag-default-bg / default-bg-hover | 中性已选中 default 背景：fill-2 → fill-3；不是输入框的 fill-1 → fill-2 → fill-3 规则。 |
| tag-bg-not-checked-hover | 未选中可交互 Tag 的中性 hover 背景，使用 state-hover。 |
| tag-default-text-color / default-icon-color | 默认文字 content-primary、默认前缀图标 content-secondary。 |
| tag-custom-text-color | 自定义 default 背景且未传 text-color 时的前景；默认 content-on-dark，调用方必须保证背景够深。 |
| tag-{色名}-* | color 预设色板入口，不表达成功、警告等业务语义；彩色前景使用色板第 9 阶、灰色使用 content-secondary；默认配色的非 loading、已选中状态纳入预设对比度检查。 |
| tag-size-* / padding-* / icon-* / close-* | 密度与部位几何；保留桌面紧凑、移动较大的尺寸，不机械统一像素。 |

交互规则：非 checkable 的 Tag 按已选中呈现；checkable 未选中时状态配色不生效，hover 只显示中性提示；已选中状态配色不能被通用 hover 覆盖。中性已选中 default 支持独立 hover；已选中 outline 保持透明。loading 不参与本批中性／状态 hover 强调。此规则不改变 checked 的受控事件协议。

覆盖顺序：color（预设色或自定义色）优先于 status；text-color 只用于显式文字定制。自定义 default 背景没有自动对比度推导，自定义 outline 使用 color 作为描边及未指定 text-color 时的文字。业务改色需验证可读性。预设色的 outline、hover、暗色 Token 覆盖已补齐，详见后文；几何／动效与预设色对比度已在后续收尾阶段登记。

本批新增 28 项 Tag 默认值契约。运行 design-ui 的 pnpm check:tag-themes：编译两端实际 Less，并检查 2 平台 × 2 品牌 × 2 明暗 × 8 状态 × 2 变体 × 2 选中 × 2 hover × 2 loading，共 1024 个级联组合；已选中、非 loading、非 hover 的默认配色在五类 system 表面上检查 640 组文字对比度，最低 4.681:1。脚本使用 DOM 选择器匹配和针对现有选择器的 specificity 计算，不代替真实浏览器视觉验收；不涵盖任意业务背景、预设／自定义色或 loading 透明度。主题或选择器结构改变时应同步扩展检查器。

## Alert：信息语义与主题继承

Alert 使用 status=info/success/warning/danger/default 和 standard/tonal/outline 三种变体。彩色标题、正文、图标及 outline 描边使用对应 sys-color-content-info/success/warning/danger，而不是 status 填充色；默认标题使用 content-primary，正文和图标使用 content-secondary，默认描边使用 border-default。

| 公开变量族（省略平台前缀） | 默认来源与场景 |
| --- | --- |
| alert-standard-{status}-bg / border | 彩色背景取 blue/success/warning/danger 第 1 阶，弱描边取第 3 阶；用于信息容器，不是交互按钮边界。 |
| alert-tonal-{status}-bg | 与 standard 同浅底，仅去掉描边，不再描述为“加深一档”。 |
| alert-outline-{status}-border | 彩色描边与可读 content 同色；背景透明，依赖外层表面。 |
| alert-{variant}-{status}-title / content / icon | 分别控制标题、正文、状态图标；彩色三者使用同一语义角色，但保留独立定制入口。 |
| alert-{standard/tonal}-default-bg | 中性 fill-2 配对表面，属于组件静态背景，不借用名称含 hover 的交互角色。 |
| alert-{variant}-{status}-content | 同时作为根容器继承色，保证关闭图标及未显式设色的 action/正文插槽跟随信息语义；自带颜色的业务组件不被强制覆盖。 |
| alert-padding-* / icon-size / *-margin-* / font-* / line-height* | 布局、图标及文字几何，独立于颜色；Maple 暗色仍保留现有较大图标和内边距，未在本批强行统一。 |

颜色链路为 foundation → system content / component-specific paired surface → component → CSS。标准变体的第 3 阶边框是弱分隔，不承诺作为控件边界的 3:1 对比度；不能把这项检查误认为所有边框都已满足非文本对比度要求。未增加新的 system Token，也未更名公开变量。

Maple 暗色主题移除独立的 Alert 颜色覆盖，继承同一组件默认值并由暗色色板解析，避免 info 从 blue 变为另一套 info 色，以及正文层级、透明混色随平台漂移。保留的主题尺寸不属于共享颜色契约。color 属性只覆盖背景，不会自动选择文字色；修改背景时需要同时检查 title/content/icon，以及继承正文颜色的关闭图标和操作内容。业务自定义颜色、图片背景和自行设色插槽不在默认配色保证范围内。

本批登记全部 65 项 Alert 颜色默认值；几何和动效仍待治理。运行 design-ui 的 pnpm check:alert-themes（或 node bin/alert-theme-check.mjs）：编译两端 Less，覆盖 2 平台 × 2 品牌 × 2 明暗 × 3 变体 × 5 状态，共 120 组；对五类 system 表面的标题、正文、状态图标、关闭图标及继承色操作内容检查 3000 组前景配对，最低 4.802:1。另验证局部 title/content/icon 变量能到达消费点。此检查使用实际 CSS 的选择器匹配与级联计算，不替代真实浏览器视觉验收。Tag 与 Alert 共用解析工具，后续组件应扩展同一工具而不是复制临时脚本。

## Button 大阶段：四种变体与交互状态

本阶段完成 Button 的颜色与交互状态闭环，不代表所有组件或 Button 几何、动效已经完成治理。覆盖 8 种 status、default/text/outline/tonal、icon-container、两套品牌的明暗主题，以及 hover/active/focus-visible/disabled/loading。不改 Props 名称或事件协议。

### 颜色职责与历史变量名

| 公开变量族（省略平台前缀） | 职责、默认值与使用场景 |
| --- | --- |
| button-{status}-color | 普通 default 变体的实心背景。primary 使用 action-primary，info/success/warning/danger 使用 status-*；default 使用 surface-default，secondary/tertiary 为 gray-6/7。不能再直接当 text/outline 的文字。 |
| button-{status}-text-color | 普通 default 的对比前景。彩色与 secondary 默认用 content-on-bright；tertiary 浅色用 on-dark、暗色用 on-bright；default 用 content-primary。Maple 品牌浅色的深橙 primary 使用 on-dark。 |
| button-{status}-icon-color | 历史名称保留，实际是 text、outline、tonal 及 default icon-container 的可读前景。primary 使用 content-brand，业务状态使用对应 content-*，default 使用 content-primary，secondary/tertiary 使用 content-secondary。不是只作用于图标。 |
| button-{status}-icon-container-color | 历史名称保留，实际是 tonal、default icon-container 及透明变体交互反馈的浅色表面。彩色取 primary/blue/success/warning/danger 第 1 阶；secondary/tertiary 取 gray-2/1；default 使用 surface-muted。 |
| button-disabled-color / disabled-text-color / disabled-solid-text-color / {status}-disabled-color | 中性禁用底色／文字、彩色实心禁用文字和状态淡色；按 variant 与 status 使用。text/outline 保持透明，tonal 保留浅底，disabled 暂停内联颜色覆盖。 |
| button-focus-color / focus-width / focus-offset | 焦点环独立于按钮文字，默认 content-brand / 2px / 2px；避免实心按钮的白色文字变成白底上不可见的焦点环。 |

Maple 暗色不再用一套独立的白字与实心图标容器颜色覆盖上述关系；它继承组件默认值及暗色色板。只保留现有几何覆盖。两端同名 Token 职责相同，不要求把所有尺寸都套成输入框的控制高度。

### 交互反馈与优先级

| 变量 | 用途 |
| --- | --- |
| button-state-opacity-hover / active | 实心、tonal 与图标容器覆盖层强度，默认 0.08 / 0.12。 |
| button-plain-state-opacity-hover / active | text/outline 使用浅色容器的反馈强度，默认 0.5 / 1；不直接以高饱和状态色压在文字后面。 |
| button-{status}-state-layer-color | 普通实心按钮覆盖层颜色。彩色和 secondary 用浅色层搭配深字；tertiary 浅色模式用深色层搭配浅字，暗色反过来；Maple 品牌浅色 primary 同样使用深层搭配浅字。default 用 content-primary 产生中性反馈。 |
| button-state-layer-color | tonal 和图标容器的覆盖层，默认 surface-page；不承担所有变体的统一着色。text/outline 的层颜色来自对应 icon-container-color。 |
| internal-button-state-layer-color / internal-button-state-opacity-* | 私有解析变量，将变体和状态选择映射为覆盖层使用值；业务不可覆盖或依赖。 |

优先级是 disabled/loading 阻止交互反馈，active 高于 hover，focus-visible 独立叠加；禁用不保留焦点强调。实心 default 的 icon-container 颜色必须高于 variant × status，不能因为 class 同时存在而被实心配色覆盖。覆盖层在隔离的层叠上下文中位于内容之后，不覆盖文字、图标或 loading 内容。原有瞬时 ripple 动画保留，不作为稳定状态对比度承诺的一部分。

loading 保留按钮原来的视觉配色但阻止激活；加载指示器默认传 currentColor，跟随按钮前景，显式 loading-color 仍优先。色彩定制边界：color/text-color、loading-color、直接 style 和自行设色的插槽属于使用者定制，不保证任意配对可读；只改背景时必须同时检查实心文字、浅色变体、交互层和焦点环。禁用配色不要求满足普通可操作文字的 4.5:1 检查。

### 契约与验收

Button 阶段新增 13 个公开交互层变量、48 项颜色／状态默认值；截至该阶段共享契约累计 223 项组件默认值，最新总数见浮层阶段。组件文档列出完整 :root 默认值和明暗／品牌例外；不为旧名字另造重复别名。

运行 design-ui 的 pnpm check:button-themes（或 node bin/button-theme-check.mjs）。编译实际 Less，覆盖 2 平台 × 2 品牌 × 2 明暗 × 8 状态 × 4 变体 × 2 icon-container × 3 可用性 × 2 hover × 2 active × 2 focus，共 12288 个级联组合。启用及 loading 的默认前景在五类 system 表面上检查 40960 组配色，最低 4.563:1。disabled 对比度、业务定制和瞬时 ripple 不在此数字内。另有原生 button/a、禁用自定义色恢复、loading 继承和事件阻断测试；真实浏览器抽查基础明暗四变体、禁用、键盘焦点和 hover 层叠。解析检查不是跨浏览器截图测试，也不意味着全仓 lint／主题快照基线已清零。

## 浮层与提示：表面、遮罩、箭头

本阶段治理 Tooltip、Popover、Overlay、Trigger，新增两个 system 颜色：

| 角色 | 默认值 | 意义与场景 |
| --- | --- | --- |
| `sys-color-surface-tooltip` | `#373739` | 明暗主题都保持深色的紧凑提示表面，搭配 `content-on-dark`；不是随模式反转的 inverse surface。主题改变它时须成对验证文字。 |
| `sys-color-scrim` | `rgba(0, 0, 0, 0.6)` | 压暗被遮挡内容的半透明黑色遮罩；不承担正文背景，不通过父节点 opacity 实现。 |

`surface-overlay` 仍是 Popover 等弹出内容的实体表面，映射 `color-bg-5`，不能用于替代 scrim。Tooltip 中性提示采用固定深灰，使两端提示外观一致；彩色 status 背景继续使用 `action-primary/status-*`，不是浅色文字专用背景。默认彩色文字使用 `content-on-bright`；两端 Maple 浅色品牌的深橙 primary 使用 `content-on-dark`。

Maple 暗色主题删除 Tooltip 颜色／opacity、Popover 背景和 Overlay 背景的旧覆盖，避免绕过 system。Tooltip 默认 opacity 在两端所有内置主题均为 1；降低它会同时淡化内容和箭头，须重新检查对比度与连接处。

Tooltip 与 Popover 的箭头和内容读取同一个组件背景 Token；Popover 边框也成对读取。上层组件箭头选择器优先于 Trigger 默认箭头，避免 CSS 加载顺序改变外观。Trigger 单独使用时仍以 `surface-overlay` 作为箭头默认背景；它不定义业务内容表面。

### 外部定制和继承边界

- 全局主题使用 system；单个组件优先使用 Tooltip／Popover／Overlay 的公开变量。不要为定制 Tooltip 箭头而覆盖 Trigger 背景变量。
- 浮层可能 Teleport：变量必须落在实际 popup 的祖先作用域；只放在触发按钮上不会跨 DOM 自动继承。可通过 `popup-style` 设置公开变量，使内容与箭头共同继承。
- Tooltip `color` 同时设置内容／箭头背景，`text-color` 设置内容文字；`content-style` 和 `arrow-style` 是各节点的显式覆盖，优先于这些默认属性。只改 content-style 的背景不会自动改箭头。自定义颜色必须成对检查。
- Popover 可用 popup-style 上的 `--{p}-popover-background` 同时改变箭头与面板；content-style／arrow-style 的直接颜色属性会覆盖变量消费。
- Overlay 的 background-color 只影响 backdrop，不给内容设置 opacity。内部定位／测量变量不构成公开主题入口。

### 契约、差异与验证范围

共享契约新增 35 项组件默认值：Tooltip 全部 23 项、Popover 的 4 项颜色、Overlay 全部 3 项、Trigger 全部 5 项。累计 64 个 system 名称、29 个 system 标准值、258 个组件默认值。

Popover 阴影保留 Cedar shadow2-down 与 Maple 三段阴影的平台差异；Maple 暗色 Tooltip 保留圆角 4px、字号 14px、纵向／横向内边距 8px／16px，Popover 保留圆角 2px。这些几何主题例外不等于同名语义不同，后续密度／动效阶段继续评估。此浮层阶段尚未涉及 Dialog／Popup；其后续治理见下方模态表面阶段，仍不能宣称所有局部遮罩已统一。

`check:floating-themes` 已纳入共享主题检查：编译两端 Less，读取品牌与明暗主题覆盖，验证 72 个组合、320 对文字颜色（5 种宿主表面），最低 5.178:1；同时检查主体／箭头配色、公开变量实际消费及 Trigger 最后加载时的优先级。该检查不代替浏览器布局测试，不涵盖任意自定义色、透明度或入退场动画中间帧。

## 模态表面阶段：Dialog、Drawer、Popup

本阶段把两端 Dialog、Cedar Drawer、Maple Popup 接入上一阶段定义的 scrim。Drawer 与 Popup 是平台组件，不为凑齐名称而在另一端创建无人消费的变量。

| 消费者 | 公开组件变量（省略平台前缀） | System 默认语义 |
| --- | --- | --- |
| Dialog（两端） | `dialog-overlay-background` | `color-scrim` |
| Dialog（两端） | `dialog-background` | `color-surface-raised` |
| Drawer（Cedar） | `drawer-overlay-bg / drawer-bg` | `color-scrim / color-surface-raised` |
| Drawer（Cedar） | `drawer-header-text-color / drawer-content-text-color` | `color-content-primary`；关闭按钮也用标题颜色 |
| Drawer（Cedar） | `drawer-border-color` | `color-border-default` |
| Popup（Maple） | `popup-overlay-background-color` | `color-scrim` |
| Popup（Maple） | `popup-content-background-color / popup-content-text-color` | `color-surface-raised / color-content-primary` |

### 变量必须连接实际节点

Maple Dialog 之前只声明了遮罩变量，引用的基础变量不存在，实际遮罩却消费 Popup 变量。这种“名称对齐但没有消费者”的状态不算完成治理。现在通过限定到 Dialog 容器的选择器直接消费 Dialog 遮罩变量，优先于通用 Popup 规则；独立 Popup 不受影响。检查会故意后加载 Popup CSS，防止顺序回归。

Maple 暗色主题删除 Dialog 背景、标题和正文硬编码覆盖，以及 Popup 背景／遮罩旧覆盖。两端 Dialog 标题和正文继续使用 content-primary，关闭按钮使用 content-secondary。Dialog 的四种状态图标从 status 填充角色迁到对应 content 状态角色，使普通面板上的图标有足够对比度。字段名保留，改变的是正确的语义映射；自定义图标、面板或品牌色仍需重新验证。

Popup 新增公开 `--mp-popup-content-text-color`，与面板背景成对定制；`unstyled` 同时停用默认背景和文字色，交给业务内容自行配色。Popup 的声明移到 token.less，主样式只负责消费。Drawer 不再在组件 Less 中内嵌整套主题；基础样式仍由 style/index.ts 引入。移除未被任何样式消费的 Drawer close-icon-right 变量，不保留无效别名；关闭按钮仍由标题布局与 close-btn-margin-left 控制。

### 实例定制与 Teleport

- 全局遮罩统一覆盖 `--{p}-sys-color-scrim`；局部遮罩优先使用各组件的公开变量。
- Dialog／Drawer 的遮罩与面板是兄弟节点：overlay-style 作用于遮罩，dialog-style／drawer-style 作用于面板；变量不会从面板继承给遮罩。
- Maple Popup 的 style 透传到内容节点；遮罩使用 overlay-style。在面板上设置 scrim 并不会改变其兄弟遮罩。
- Teleport 后，变量按实际 DOM 祖先继承，而不是按 Vue 调用位置继承。共同作用域主题放在实际挂载祖先或全局主题中。
- 显式 backgroundColor 样式覆盖变量消费。遮罩透明度使用颜色 alpha，不给面板或公共父节点设置 opacity。
- 多个遮罩叠加会按 alpha 合成变深；统一 Token 不代表只能存在一个遮罩，本阶段不改变模态堆栈逻辑。

### 契约与验证边界

共享契约更新 Dialog 的 5 项既有默认值（遮罩及四种状态图标），不增加共享组件数量。仍为 64 个 system 名称、29 个 system 标准值、258 项共享组件默认值。平台专属 Drawer 的 5 项颜色与 Popup 的 3 项颜色由 `check:modal-themes` 验证，不计入共享默认值总数。

检查编译后的真实 Less，覆盖 16 个平台／品牌／明暗组合、72 组文字及图标配色，最低 5.102:1；同时验证组件覆写、全局 scrim 传播、Dialog 与独立 Popup 的隔离、unstyled 边界及加载顺序。组件测试使用实际 Teleport 目标，不依靠 transition stub 验证直接子节点结构。颜色检查不等于浏览器视觉或动效验收，不覆盖任意自定义色、嵌套遮罩组合或动画中间帧。

本阶段保留各平台几何、圆角、阴影、动效和层级默认值。头像、图片预览等组件的局部遮罩是否属于同一种 scrim，需按用途继续判断，不能批量替换所有半透明黑色。

## 反馈组件阶段：Message、Notification、LoadingBar（历史记录）

> 以下记录统一变体之前的端侧颜色治理。旧 Message 名称已迁移到三变体接口，原“待迁移”结论不再是当前待办；现行模型见前文 Message 强调层级。

本阶段处理两端 Message、Cedar Notification 和 Maple LoadingBar 的颜色角色、暗色覆盖和实际消费者。统一的是语义职责，不在没有变体设计的情况下把移动端彩色提示强行改成桌面端中性面板。

| 消费者 | 表面／色块 | 前景／指示色 | 说明 |
| --- | --- | --- | --- |
| Cedar Message | 所有状态使用 surface-overlay；边框 border-default | 正文 content-primary，关闭 content-secondary；图标按 content 状态色 | default 图标 primary；loading 图标 brand；info 使用 info 而非品牌填充色 |
| Cedar Notification | 所有状态使用 surface-overlay；边框 border-default | 标题／正文 content-primary，关闭 content-secondary；图标按 content 状态色 | normal 图标 primary；现有 error 名称映射 content-danger，不新增危险色别名 |
| Maple Message：default／loading | 组件专属深色 #333 | content-on-dark | 保留现有移动提示外观，不冒用 surface-overlay 或 scrim |
| Maple Message：彩色状态 | status-info/success/warning/danger | content-on-bright | 浅色文字不能默认适配所有状态填充；必须成对设置前景和背景 |
| Maple LoadingBar | 细线本身为可辨识的内容标记 | content-brand／content-danger | 普通／失败状态，不使用 action／status 填充阶；背景由宿主页面决定 |

### 实际消费与外部定制

- Maple 新增四个公开变量：message-info-color、message-success-color、message-warning-color、message-danger-color（完整前缀为 `--mp-`）。message-color 继续控制 default／loading，不再默认为所有背景提供同一个浅色前景。
- Maple Message 的图标、正文、纯文本 action、关闭按钮和 currentColor 焦点描边共享对应状态前景。插槽内的 Button、链接或自带颜色的节点不会自动变成合适配色，业务必须单独验证。
- Cedar Message／Notification 根节点消费当前状态的正文颜色，保证未自行着色的 action／footer 文本可读。Notification normal-icon-color 现在有真实消费者，定制默认图标颜色不再失效。
- Maple 暗色主题移除这些组件的旧颜色覆盖，保留既有尺寸；Message 的专属深色表面留在 component 层，不把固定 #333 冒充通用系统表面。
- Maple Message／LoadingBar 的公开声明集中到 token.less；Cedar Message／Notification 不再在组件 Less 内嵌整套基础主题，由 style/index.ts 负责依赖。
- 全局主题在实际挂载祖先提供 system 变量；局部定制优先用对应 component 变量。Teleport 不改变 CSS 的 DOM 继承规则。LoadingBar 的 color／errorColor 选项显式覆盖默认变量，改变颜色或页面背景后须重新检查。

### 治理范围与仍待处理的差异

新增 `check:feedback-themes`，纳入共享检查入口，按各平台现有名称治理 63 项颜色默认值：Cedar Message 25、Notification 26、Maple Message 10、LoadingBar 2。编译真实 Less 并读取暗色和品牌覆盖，检查 76 个组合、1500 组前景／表面配色，最低 4.681:1，同时验证映射与公开变量消费。

这些实现的颜色矩阵尚不属于同名共享组件默认值契约，因此不增加 258 项共享默认值总数；两端仍为 64 个 system 名称、29 个 system 标准值。Message 的颜色后缀、状态背景形态仍有平台差异，后续需要单独设计变体与命名迁移，不能把本阶段描述为完整 API／Token 名称对齐。Notification 和 LoadingBar 是平台专属组件，不在另一端创建空壳。

几何、阴影、动效、关闭按钮交互细节以及其余历史变量的消费审计不在本阶段；不以颜色检查替代浏览器视觉验收。检查覆盖内置静态配色，不包括自定义插槽颜色、业务背景和动画中间帧。LoadingBar 在五类内置表面上按更严格的 4.5:1 检查；这不意味着任意宿主背景都自动合规。

## 输入与菜单颜色阶段：Input、AutoComplete、Select

本阶段只收敛这三个组件的颜色职责及其默认值，不把输入外壳、菜单选项和反馈图标当成同一种交互表面。新增 26 项共享颜色默认值契约：Input 5 项、AutoComplete 10 项、Select 11 项；共享总数从 258 增至 284，system 名称／默认值仍为 64／29，组件名称契约仍为 35。没有新增或重命名公开变量。

### Input：反馈与输入外壳分开

以下逻辑变量名省略 `--c-`／`--mp-` 前缀；表中的 system 名也需补上对应前缀。

| 变量 | 默认引用 | 职责与定制场景 |
| --- | --- | --- |
| input-counter-color | field-suffix-text-color | 字数统计；跟随字段辅助内容色，可单独覆盖 |
| input-feedback-success-color | sys-color-content-success | 成功反馈 SVG 的 currentColor |
| input-feedback-warning-color | sys-color-content-warning | 警告反馈 SVG 的 currentColor |
| input-feedback-error-color | sys-color-content-danger | 错误反馈图标，不复用填充型 field-error-color |
| input-feedback-validating-color | sys-color-content-brand | 校验中图标；转动时仍需与字段背景可辨识 |

输入背景、边框、光标和焦点环仍属于 FieldDecorator／原生输入样式；Input 的反馈变量不负责这些部位。覆盖 field-error-color 或 field-focus-color 不再连带改变反馈图标，需覆盖对应 input-feedback 变量。filled 的 fill1 → fill2 → fill3 规则没有改变。禁用、只读、校验状态的业务行为也没有修改。

Maple 暗色 Field 的历史覆盖会把 filled 改回 fill2／fill3／普通背景，还会覆写正文、辅助文字、错误及边框色。本阶段移除这些旧颜色覆盖，仅保留几何配置，使暗色也遵循 FieldDecorator 的既有语义契约；不是新增另一套暗色状态阶梯。检查显式载入 dark/field.ts，防止只验证 token.less 而漏掉主题覆写。

### 菜单：同样的颜色角色，不同的变量命名

下表为完整的本阶段菜单颜色契约。AutoComplete 保留已有 option 名称，并在自己的 dropdown 根节点映射到 Select 变量；不新增另一套菜单规则。公开覆盖应使用所属组件的变量，不依赖这层内部适配。

| AutoComplete 后缀 | Select 后缀 | 默认 system 角色 |
| --- | --- | --- |
| popup-bg | popup-bg | surface-overlay |
| popup-border-color | popup-border-color | border-default |
| option-bg-default | popup-option-bg | surface-overlay |
| option-bg-hover | popup-option-bg-hover | state-hover |
| option-bg-selected | popup-option-bg-selected | surface-overlay |
| option-bg-disabled | popup-option-bg-disabled | surface-overlay |
| option-text-color-default | popup-option-text-color | content-primary |
| option-text-color-hover | popup-option-text-color-hover | content-primary |
| option-text-color-selected | popup-option-text-color-selected | content-primary |
| option-text-color-disabled | popup-option-text-color-disabled | content-disabled |
| 无独立分组标题变量 | popup-group-title-text-color | content-secondary |

完整名称例如 `--c-auto-complete-option-bg-hover` 与 `--mp-select-popup-option-bg-hover`。Select 的分组标题使用 secondary 而不是 tertiary：它是可读的小字号标题，不是禁用信息。Maple 暗色不再单独覆写 selected 为品牌文字和 selected 背景；两端都从相同默认角色解析暗色值。

菜单中的 active 是键盘导航项，使用 hover 配色，不是鼠标按压层级。颜色优先级为 disabled > active／hover > selected > default；selected 的字重仍保留，颜色相同不代表丢失选择状态。业务覆盖 selected 颜色后，与 hover 叠加时仍由 hover 颜色胜出，这是明确的导航反馈规则。

### 检查范围与边界

`check:selection-themes` 已纳入共享主题检查入口：编译真实 Less，覆盖两端、两个品牌、明暗主题，共 384 个状态组合、296 组对比度。正文／字数／分组标题至少 4.5:1；反馈图标是非文字指示，至少 3:1。本次矩阵最低 3.991:1 出现在图标检查，不能把它说成正文最低标准。禁用项检查优先级及变量消费，不宣称符合正文对比度门槛。

检查通过哨兵色逐项验证本阶段颜色变量的实际消费者，包含 AutoComplete 的局部映射。它不等于浏览器视觉验收，也不覆盖自定义插槽颜色、任意业务背景、伪元素、动画中间帧或 Teleport 祖先继承；弹层局部定制仍必须放在真实挂载祖先或 popup 根节点。此次未治理 Input 尺寸、菜单几何／阴影及 Select highlight 历史变量，也没有处理 Checkbox／Radio／Switch／Form／Textarea 的独立 Token。

## 选择控件颜色与状态优先级：Checkbox、Radio、Switch（历史记录）

> 此节记录最初的颜色／优先级范围；后续 Switch 配色、RadioButton 与非颜色收尾见对应组件规范和当前契约，不把阶段性未覆盖项重复视为未完成。

本批为 Checkbox、Radio 各登记 6 项颜色默认值，共新增 12 项；变量名称和尺寸 API 不变。Maple 的默认值移入各组件的 token.less，暗色主题仅保留移动端几何，不再重新写死颜色。

| 公开变量后缀（checkbox / radio） | 两端相同的 system 角色 | 意义与使用场景 |
| --- | --- | --- |
| control-color | content-secondary | 未选中轮廓／图标；这是识别控件的非文字内容，不是装饰性边框 |
| control-color-checked | content-brand | 选中与半选标记；需要与所在表面保持辨识度，不直接等同于 action-primary 按钮填充 |
| control-color-error | content-danger | 可交互控件的校验错误轮廓／标记，不改变标签正文色 |
| control-color-disabled | content-disabled | 禁用标记；禁用优先于错误、选中颜色和 hover |
| label-text-color | content-primary | 标签正文；错误说明由表单反馈承担 |
| label-text-color-disabled | content-disabled | 禁用标签；移动端标签自身的 disabled 类必须消费此变量 |

以上后缀分别加 --c-checkbox- / --mp-checkbox- 或 --c-radio- / --mp-radio-。局部覆盖放在组件真实 DOM 祖先上。Maple 已有 checked-color / unchecked-color 属性仍是内联颜色覆盖，优先于 CSS 变量；需要系统状态色时不要同时传这些自定义颜色。自定义插槽、任意业务背景与属性颜色需自行验证对比度。

状态规则：disabled > error > checked / indeterminate > unchecked；hover 仅提供可交互提示，不取消选中或错误。Cedar 修复错误边框被 hover 覆盖、Checkbox 半选禁用缺失及禁用 hover 恢复普通边框；RadioButton 的错误色也不再被普通选中规则覆盖。Maple 错误色仅作用于 action，不染标签，且不覆盖 disabled。

Cedar 的内部勾选／半选标记及 Radio 圆点用 surface-default 表达“镂空表面”，与 content-brand / content-danger 的实心标记成对使用；这不是通用“彩色背景上的文字”角色。internal 变量仍不是跨端公开承诺。桌面 14px 与移动 24px 的控制尺寸及命中区域继续保留，未作机械数值统一。

Switch 本批仅修复状态优先级：可交互 error 轨道高于 tonal 未选中背景；disabled / loading 保留正常 checked 状态并抑制错误覆盖。现有自定义轨道颜色在普通状态保留，校验错误仍使用 error Token。轨道、滑块、文字及 tonal 配对颜色尚未登记共享默认值，不能据此声称 Switch 配色已统一；RadioButton 的完整配色、伪元素和几何也仍需后续审计。

回归入口：design-ui 的 pnpm check:choice-themes（也可直接 node bin/choice-theme-check.mjs），已接入 check:theme-contract。覆盖两端 × 两品牌 × 明暗主题共 832 个状态组合；Checkbox / Radio 校验 640 组颜色对比（标签 ≥4.5:1、控件 ≥3:1），最低 4.681:1。哨兵色检查公开颜色变量的消费者；Switch 仅检查四种变体与 checked / disabled / loading / error 的级联结果。禁用态不设对比阈值。此检查不是浏览器视觉验收，不覆盖伪元素绘制、动画、焦点环及内联自定义色。

## 表单说明与多行输入：Form、Textarea

本批新增 5 项共享颜色默认值：Form 3 项、Textarea 2 项；不新增或重命名公开变量。默认值集中到 token.less，Maple FormDetails 暗色主题不再用 #888 或 action 填充色覆盖文字语义。

| 变量后缀 | 默认角色 | 消费者与场景 |
| --- | --- | --- |
| form-label-text-color | content-primary | 表单标签正文，不随校验错误染色 |
| form-extra-text-color | content-secondary | Cedar 的 extra / 普通 help，Maple 的 help；辅助说明仍需可读 |
| form-required-symbol-color | content-danger | 必填标记，不是错误背景填充 |
| textarea-placeholder-color | content-secondary | 原生 textarea 的 placeholder；两端均实际消费，默认焦点／错误不会把它改成品牌／错误色 |
| textarea-counter-color | content-secondary | 字数统计；Cedar 位于输入区内，Maple 位于输入区外，因此同时按 filled 各级背景校验 |

上表分别添加 --c- / --mp- 前缀。Cedar 的 form-tooltip-text-color 使用 content-secondary；status-success / warning / error / validating 的 tip-text-color 与 tip-icon-color 分别使用 content-success / warning / danger / brand。它们是桌面扩展，不伪造移动端同名变量。Maple FormDetails 使用自己的 error-message-color（content-danger）和 extra-message-color（content-secondary）；Form 的 extra 属性由 FormDetails 展示，因此定制该段应覆盖 --mp-form-details-extra-message-color，而不是 --mp-form-extra-text-color。组件组合不意味着所有子组件变量自动别名化。

Textarea 的 disabled 优先于 error，placeholder 及原生禁用文字使用 field-control-text-color-disabled。Maple 显式 blur-color / focus-color 仍可定制可交互、非错误状态的 placeholder；未传属性时不再写入内联默认值，从而允许祖先 CSS 变量覆盖。disabled 时也不再注入 text-color。hint 模式由 FieldDecorator 的标签承担提示，不能用 textarea-placeholder-color 定制浮动标签。

职责边界：Form 管理标签、说明、必填符号与校验反馈；FieldDecorator 管理 outline / filled / standard 外壳。Cedar Form 不再通过旧 selection-field 选择器重绘背景、边框与焦点阴影，避免校验状态破坏 fill1 → fill2 → fill3。Picker 等旧状态适配仍保留；InputTag 的旧重绘规则已在后续阶段移除，详见后文；本批不宣布所有 form-status-* 背景变量已统一。两端高度、间距、计数器位置、清除按钮布局与其它几何差异未改。

检查入口：pnpm check:form-textarea-themes（或 node bin/form-textarea-theme-check.mjs），已接入 check:theme-contract。两端 × 两品牌 × 明暗主题共 276 项消费者／状态检查、200 组对比检查，最低 4.681:1。Form 说明／反馈校验 surface-default 与 surface-muted；Textarea 额外校验 state-hover 与 fill3。文字阈值 4.5:1，反馈图标 3:1；禁用态无对比阈值。检查扩展到编译后的 ::placeholder 选择器，并用哨兵色验证覆盖能到达消费者，但不等于真实浏览器伪元素、焦点、主题切换或自定义背景的视觉验收。

## Switch：实心轨道与 tonal 变体的成对配色

当前主题入口为 Themes.default.light / dark 与 Themes.maple.light / dark。Switch 的 tonal 是造型，不是主题；公开变体与八项专用变量统一使用 tonal 命名，不保留旧名称别名。

本阶段登记 10 项共享颜色默认值，其中 8 项为既有变量，新增 tonal-text-color / tonal-handle-color 两项。两端只差 --c-switch- / --mp-switch- 前缀。规范变更记录位于 Cedar openspec/changes/govern-switch-colors；Maple 暗色主题不再单独写死轨道及文字颜色。

| Switch 变量后缀 | system 默认角色 | 职责 |
| --- | --- | --- |
| track-background | content-secondary | 普通未选中实心轨道 |
| track-active-background | content-brand | 选中轨道及键盘焦点环 |
| track-error-background | content-danger | 可交互错误轨道及 tonal 错误边框 |
| handle-background | surface-default | 普通／选中／错误滑块底色 |
| handle-color | content-brand | 普通／选中／错误滑块图标色 |
| text-color | surface-default | 实心轨道上的文字色 |
| tonal-track-background | surface-muted | tonal 未选中轨道底色 |
| tonal-border-color | content-secondary | tonal 未选中边框及滑块底色 |
| tonal-text-color | content-secondary | 新增：tonal 未选中轨道文字 |
| tonal-handle-color | surface-default | 新增：tonal 未选中滑块图标 |

轨道是用于识别开关状态的控件标记，采用 content-secondary / brand / danger，与 Checkbox / Radio 的标记语义一致，不直接沿用按钮 action 填充色。surface-default 在实心轨道中表示镂空式前景，与所在主题的轨道色成对设计，不是任意彩色背景的通用文字色。暗色 surface-muted 带透明度，只适合叠加表面，不能充当深色滑块上的反差图标色。

tonal 未选中采用独立前景组合；选中或可交互错误状态切回普通文字／滑块 Token。迁移注意：若过去仅覆盖 text-color / handle-color 来定制所有变体，现在还应同时设置 tonal-text-color / tonal-handle-color。tonal-border-color 仍同时影响未选中边框和滑块底色。错误状态会一起切换轨道、滑块与文字，避免只换轨道而遗留低对比度前景。

优先级保持 disabled / loading 抑制 error，并保留 checked 身份；hover、active 和 focus 不抹去该状态。只调整默认配色，不新增 hover 变色。checked-color / unchecked-color 仍写入内部 current-track，覆盖普通轨道；可交互 error 仍优先使用 track-error-background。loading-color 覆盖加载图标，否则继承滑块图标色。自定义轨道需一起选定前景；这不是自动纠正任意业务颜色的算法。scale、local-*、current-track、loading-color 等运行时变量不是公开主题默认值。

验证入口：pnpm check:switch-themes（或 node bin/switch-theme-check.mjs），已纳入 check:theme-contract。覆盖 circle / round / line / tonal × checked / disabled / loading / error / hover / active / focus-visible × 两端 × 两品牌 × 明暗主题，共 4096 个状态；8704 组默认色对比最低 4.681:1。按 host → track → handle → icon 实际顺序混合透明颜色；文字 ≥4.5:1，控件边界、滑块／轨道、图标和焦点环 ≥3:1。哨兵色验证公开颜色变量及自定义轨道消费者。line 实际不显示文字，因此不计虚构文字对比。

边界：检查使用 md 尺寸、surface-default / surface-muted 承载背景，不覆盖 disabled / loading 降低整体透明度后的对比、任意自定义颜色／插槽、动画中间帧、真实浏览器布局或焦点可见性验收。sm 隐藏文字、尺寸缩放、阴影与几何／动效默认值仍未进入本批契约。

## 导航颜色：Tabs 与 Steps

本批新增 64 项共享颜色默认值：Tabs 7 项、Steps 57 项，没有新增公开变量。Maple Tabs 暗色覆盖移除；两端保留尺寸与布局差异。

### Tabs 颜色职责

| 后缀（添加 --c-tabs- / --mp-tabs-） | system 角色 | 场景 |
| --- | --- | --- |
| background | surface-default | card / capsule / enclosed 选中表面 |
| title-text-color | content-secondary | 普通标题 |
| title-text-color-active | content-brand | 选中标题、焦点环与指示条，不使用 action 填充色 |
| title-text-color-disabled | content-disabled | 禁用标题 |
| muted-background | surface-muted | 分组或未选中表面 |
| border-color | border-default | 装饰性分隔线和边框 |
| hover-background | state-hover | fine pointer 下可交互且未选中项 |

hover 不覆盖选中项背景；line / outline 的 hover 只改变可交互文字。coarse pointer 不应用桌面 hover 规则。禁用优先于选中／hover 文字色，但保留选中位置。

### Steps 颜色职责

所有后缀加 --c-steps- / --mp-steps-。状态为 wait / process / finish / error，disabled 只禁止交互，保留进度身份；circle 同时供 navigation 使用。

| 变量组 | wait | process | finish | error |
| --- | --- | --- | --- | --- |
| circle-item-bg-* | surface-muted | content-brand | state-selected | content-danger |
| circle-item-border-color-* | transparent | transparent | transparent | transparent |
| circle-item-icon-text-color-* | content-secondary | surface-default | content-brand | surface-default |
| circle-item-title-color-*、dot-item-title-color-* | content-secondary | content-primary | content-primary | content-primary |
| circle-item-description-color-*、dot-item-description-color-* | content-secondary | content-secondary | content-secondary | content-secondary |
| dot-item-bg-*、dot-item-border-color-* | content-secondary | content-brand | content-brand | content-danger |
| arrow-item-bg-* | surface-muted | content-brand | state-selected | content-danger |
| arrow-item-title-color-* | content-secondary | surface-default | content-primary | surface-default |
| arrow-item-description-color-* | content-secondary | surface-default | content-secondary | surface-default |

circle / dot 的 item-tail-color-wait 为 border-default，item-tail-color-process 为 content-brand，item-tail-color-error 为 content-danger；没有虚构 finish 尾线变量，已完成连线使用 process 色。连接线为辅助提示，不作为唯一状态信息。navigation-arrow-color 使用 content-secondary；navigation-ink-bg 与 changeable-hover-text-color 使用 content-brand。

bg 是节点／箭头表面，icon-text-color 是编号或图标，title / description 是正文。实心 process / error 箭头使用反差前景，hover 不能将其改成同色文字；其他可交互非 active 项仍可 hover 提亮。navigation-ink-bg 现在实际消费于导航指示线，不再误用 hover 文字变量。surface-default 在这里表示配对的镂空式前景，不是任意业务背景上的通用文字色。

验证入口：pnpm check:navigation-themes（或 node bin/navigation-theme-check.mjs），已接入 check:theme-contract。覆盖 Tabs fine / coarse 媒体、六种变体及选中／禁用／hover，Steps 四种造型与四状态叠加 active／disabled／hover：共 1792 个状态、1792 组颜色对比，最低 4.681:1；文字和编号要求 4.5:1，dot 要求 3:1。哨兵色验证被测消费者，包括 Tabs 指示条及导航指示线伪元素。

边界：未逐项验收所有连接线／箭头伪元素、焦点环、尺寸、阴影、动画或自定义插槽／背景；禁用不设对比阈值，真实浏览器布局与触摸交互另行验收。主题、组件 variant 与交互状态必须分层描述。

## 数值与进度：内容层级与图形指示

本批登记 12 项共享颜色默认值；两端仅前缀不同。颜色角色描述职责，不依据组件所在平台或品牌改变意义。

| 组件与变量后缀 | system 角色 | 意义与场景 |
| --- | --- | --- |
| count-to / countdown：text-color | content-primary | 独立数值、计时文字；计时结束不自动表示错误或成功 |
| statistic：value-color | content-primary | 主要读数；内部 CountTo 动画继承此色，不抢占父组件颜色 |
| statistic：title-color / prefix-color / suffix-color / extra-color | content-secondary | 标题、单位、前后缀和补充说明；不能因为字号小就降低到装饰文字对比 |
| progress-group：text-color | content-primary | 主内容与环形中心文字 |
| progress-group：muted-color | content-secondary | 数值、百分比等辅助信息，仍须满足正文可读性 |
| progress-group：track-color | state-hover | 中性 fill2 轨道底色；这里只复用填充层级，不意味着发生 hover |
| progress-group：tooltip-bg / tooltip-color | surface-tooltip / content-on-dark | 固定深色提示表面及其反差文字，明暗主题都使用此配对 |

ProgressGroup 默认分段、图例图标引用 content-brand，作为需要辨识的图形标记而非按钮背景。运行时优先级为 item.color → 组件 color → system content-brand；用户自定义颜色不保证对比度，需要自行验收。当前未新增组件颜色别名。不要使用百分比或正负数猜测业务上的成功／危险；业务状态由调用方明确指定。

这批只治理颜色：两端字号、间距、圆角等密度差异暂保留，不能把颜色一致理解为全部默认值一致。Maple 暗色 CountDown / Statistic 删除颜色覆盖，保留现有几何值；Cedar 移除四个 token.less 内嵌的全局主题，基础样式仍由模块入口负责。

验证入口为 node bin/numeric-theme-check.mjs，亦纳入 check:theme-contract。检查编译后 CSS 消费者及变量覆盖、普通／弱表面的文本对比、线形／环形轨道、Tooltip 成对颜色、Statistic 动画继承。自定义色、实际浏览器布局、动画和交互视觉不在此次静态检查结论内。

## 基础表现：状态层、表面、占位与间距

本批登记 Hover 2、Icon 1、Paper 5、Ripple 2、Skeleton 20、Space 10，共 40 项完整 root 默认值。共享变量名只差 c / mp 前缀，没有新增别名。Space 依赖的 system space-1…8 同时登记为受管默认值：2 / 4 / 6 / 8 / 12 / 16 / 20 / 24px。

| 组件／变量后缀 | 默认职责与使用场景 |
| --- | --- |
| hover：overlay-opacity / overlay-focusing-opacity | 0.04 / 0.12；用宿主 currentColor 作覆盖层，以 opacity 表示强度，不是独立文字色或实心填充色。无状态为 0；focus 高于 hover，不累加。显式 focusing 不因设备类别被隐藏，焦点触发策略由宿主负责。 |
| icon：size | inherit；随宿主字号缩放，图形为 1em，颜色继承。显式 size 属性覆盖 CSS 变量；需要旧移动端 20px 外观时显式设置 size="20" 或 icon-size:20px，不恢复全局固定大小。独立 SVG 图标不自动消费 Icon 包装器变量。 |
| paper：background / border-color | surface-default / border-default；普通承载表面不是浮层，也不因暗色而跳到 bg4。内容颜色由宿主继承，调用方需提供适配表面的文字色。 |
| paper：border-radius / border-width / transition-duration | 4px / 1px / system slow（240ms）；bordered 才消费边框宽度和颜色，round 使用圆形形状，radius 属性覆盖默认圆角。背景变化时长通过组件变量引用 system slow。 |
| ripple：color / cubic-bezier | currentColor / cubic-bezier(0.68,0.01,0.62,0.6)；波纹继承宿主颜色，曲线控制扩散，不控制文字、宿主背景或整个指令生命周期。自定义波纹颜色由指令参数优先提供。 |
| skeleton：card / avatar / title-background-color | 均引用 state-hover，即中性 fill2；这里是占位填充层级，不表示发生 hover。title 色同时用于行、Shape 和 fullscreen 占位，不是 scrim 或真实内容背景。 |
| skeleton：animation-background | transparent → surface-default → transparent 的横向渐变；shimmer 层以 0.3 opacity 混合，避免硬编码白色导致暗色不同。仅 animation 开启时消费；覆盖渐变后仍受此层透明度影响。 |

Skeleton 几何变量保持两端一致：content-padding 16px；card 高 160px、圆角 4px、下间距 16px；avatar 大小 34px、圆角 50%、右间距 16px；title 宽 50%、圆角 10px；row 高 12px、圆角 10px、上间距 10px；Shape 的 sm/md/lg 为 36/48/60px，圆角 4px。这些是组件形态，不为追求数量而全部映射到 spacing；圆形覆盖形状圆角，不覆盖颜色。

Space 使用物理 CSS row-gap / column-gap，与 flex direction 不交换：xs 为 4/4px、sm 为 8/6px、md 为 12/8px、lg 为 16/12px、xl 为 24/16px。对应 system spacing 引用，不改变原有数值。自定义数值同时应用两轴，数组按 [rowGap,columnGap]，不经过预设变量；split 插槽仍保留间距。Space 不应拥有文字或背景颜色变量。

移除 Maple 这六个组件族的重复暗色覆盖（HoverOverlay、Icon、Paper、Ripple、Skeleton、Space），从同一语义与几何默认值继承；Cedar 清除相关 Less 的全局主题内嵌。验证入口 node bin/foundation-theme-check.mjs 纳入 check:theme-contract：两端 × 两品牌 × 明暗主题 448 项检查，包括实际 CSS 消费者、变量覆盖、focus 优先级和间距解析。占位及反馈状态层不是正文，不套用正文对比度阈值。实际浏览器动画、全库 reduced-motion 覆盖、强制颜色模式及任意业务自定义色仍需后续验收；本批不是全库样式完成声明。

## 基础动效：时长职责与减少动态效果

本阶段新增 6 项组件变量、登记 2 项既有 system 时长默认值。不把所有动效压成同一个时长，也不使用颜色主题切换来改变动效策略。

| 变量后缀（两端只差 c / mp 前缀） | 默认值与职责 |
| --- | --- |
| sys-motion-duration-fast | 120ms；轻量状态反馈过渡，不是所有动画的最快档替代品 |
| sys-motion-duration-slow | 240ms；此批用于承载表面、占位表面的颜色变化 |
| hover-transition-duration | 引用 system fast；hover / focus 覆盖层透明度过渡，两端一致，focus 仍优先 |
| paper-transition-duration | 既有变量改为引用 system slow；仅背景色过渡，不影响点击、尺寸或业务时序 |
| skeleton-transition-duration | 引用 system slow；card、avatar、title、row、fullscreen 占位色变化 |
| skeleton-animation-duration | 1s；横向扫光单周期，不等同于表面过渡时长 |
| icon-spin-duration | 1s；内置旋转单周期，不控制名称替换的等待时间 |
| ripple-expand-duration / ripple-fade-duration | 200ms / 140ms；分别控制 CSS transform 扩散与 opacity 变化，保留 ripple-cubic-bezier 的扩散曲线职责 |

所有 CSS 时长需要有效、非负的时间值。Icon 的 transition 属性依然表示毫秒数的名称切换等待，不能通过 spin-duration 改变。Ripple 的 expand-duration（200ms）控制 transform 扩散，fade-duration（140ms）控制 opacity 显现／消退，cubic-bezier 仅控制扩散曲线；两端默认值与消费者一致。运行时从实际波纹节点所属文档读取计算后的 transform／opacity transition 时长与 delay（支持 s/ms、列表重复与 all），不直接解析未解析的 var()。250ms 分别是从节点创建起的最小展示时间和开始淡出后的最小移除等待，不是视觉 duration、总生命周期或 CSS Token。创建 30ms／激活 20ms 是内部调度；快速释放仍走最小展示流程。

释放等待扩散的实际激活时间 + transform duration/delay 与创建时间 +250ms 的较晚者；开始淡出后等待 max(250ms, opacity duration+delay) 才删除。默认节奏不变，600ms／800ms 等较长覆写不再截断；显式 0ms、无样式或 reduce 隐藏仍保留清理下限。扩散时序在创建／激活阶段采样，消退时序在开始淡出时采样，不承诺之后任意 CSS 改动或 animation 的时序。计时器不是设计 Token，不能从调色或密度层推导。

每个波纹只安排一次释放，禁用／卸载取消所属定时器和直接子波纹，不误删嵌套指令；文档释放事件注册／清理使用挂载时 ownerDocument，跨文档搬迁的监听重新绑定不在本契约内。键盘只接管本宿主 Enter／Space，对应 keyup 或 blur 释放，无关键不抢占。指令不授予宿主按钮语义、可访问名称或点击业务能力；在已有交互元素上使用，不能只加 v-ripple 便声称普通 div 可访问。真实 IAB 默认／长时长／0ms 六组与两端永久回归分别留证；不外推真机触摸、真实 OS 偏好或全库动效通过。

prefers-reduced-motion: reduce 是用户偏好，不是主题或公开 CSS 开关。内置策略如下：Hover / Paper / Skeleton 表面立即响应、保留状态颜色；Icon 停止 spin，内置缩放取消，名称立即切到最新值；Skeleton 隐藏扫光但保留占位；Ripple 不显示装饰波纹，指令仍正常清理节点，不影响宿主事件。必要的 !important 仅用于压过 Icon 内联 transition、Ripple 内联 opacity 及已列明的模态／Notification／Message 内置过渡和起始位移，不用于普通主题覆盖。用户显式 rotate 朝向保持不变。

Icon 在挂载后订阅偏好，减少动态效果在切换途中开启时会取消旧计时器；关闭偏好不会对未变化的名称重新播放动画。卸载移除监听并清理等待。SSR 不读取 window，也不建立监听。自定义 animation-class、外部 SVG 的自有动画和业务加载指示器需调用方另行适配；本策略并不替代可访问名称或加载状态提示。

验证入口 check:motion-themes 已接入 check:theme-contract：96 组主题／偏好组合、88 项时长覆盖、176 项模态 active 选择器消费检查，并检查 reduce 下起始 transform 与 Popup 基础过渡。Icon 单测仍负责初始／动态偏好、切换取消与卸载。motion-source-inventory.mjs --check 维护源码候选清单：两端 192 个文件、389 处 CSS 动效声明候选、179 处运行时调用候选（新增 setTimeout 调度线索）；存在局部 media 或计时器不代表已通过，源清单也不证明选择器可达。此检查是实际 Less 编译及模拟状态，新增真实 OS／浏览器验收为 0。

漂移门禁使用 design-ui/audits/motion-source-inventory.json 当前基线，历史证据快照保持不变。逐行线索包含非动效计时器，数量不代表缺陷或完成的验收。

BackTop 的 duration（200ms）与 easing（quartOut）是 JS requestAnimationFrame 滚动参数，不是 CSS 动效 Token；现有组件变量只负责几何、配色、焦点及层级。减少动效偏好读取滚动目标 ownerDocument 的窗口；动画途中开启时在下一帧立即回顶，保留横向滚动，不承诺同步 OS 事件回调。重复点击、目标切换、停用或卸载使旧帧失效，包括已经出队的回调。滚动可见性合帧不是视觉动画。此处以模拟 RAF／iframe 文档与 SSR 回归验证，不增加真实浏览器／OS 通过数。

模态动效补验：Cedar Drawer 的 fade／四方向 slide 和 Maple Popup 的 fade／center 缩放／四方向 pop，在 reduce 下关闭内置过渡与起始位移／缩放。规则在组件样式入口生效，不依赖全局入口的极短时长兜底；必要的 !important 仅作用于这些内置动效和 Popup 基础过渡，不覆盖主题颜色。Maple Popup 通过 --mp-popup-transition-duration（250ms）与 --mp-popup-transition-timing-function（ease）控制内置 fade／pop 和内容／遮罩基础过渡；职责命名与 Cedar Drawer 对齐，但保留平台组件默认值，不借用 Dialog Token，也不伪造 Cedar Popup 变量。两项应设置在 Teleport 后实际共同祖先或挂载宿主；style 只传给内容、overlay-style 只传给遮罩，不能控制整层关闭时长。CSS 时间必须有效且非负；reduce 规则优先于常规覆写。

生命周期由实际 Transition 完成回调驱动，不设固定 250ms JS 等待：unmountOnClose 在关闭途中保留内容与锁，完成后卸载；快速重开取消关闭，保留内容状态；每个有效打开／关闭阶段的完成事件只发一次，销毁后的回调不再发事件。自定义动画及内容／外层不同步的覆写由调用方负责；初始打开保留既有 mounted 通知行为，不承诺完整 appear 动画计时。IAB 默认／600ms／0ms、五方向与重开／销毁实测另存证据，0ms 是显式 CSS 覆写，不是 OS reduced-motion 验收。

模态配色补验：16 个平台／主题组合，72 组默认配色加 80 组显式背景／文字覆写，最低显示值 5.102:1。透明表面先合成到已知不透明实际背景，再合成透明前景；文字门禁按未舍入比值与 4.5 比较。低对比度自定义覆盖、未知半透明底层及非法颜色必须拒绝，不把覆盖可消费误当成可读性通过。这里覆写的是直接组件变量，不保证根 system 别名会随任意局部覆盖重新计算；业务插槽、图片／渐变背景、自定义状态图标及 unstyled 的配色由调用方负责。依据：[WCAG 文字对比度](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html)；动效偏好参考 [交互动效说明](https://www.w3.org/WAI/WCAG22/Understanding/animation-from-interactions.html)，后者为 AAA 条款，不宣称本批完成 WCAG 认证。

## 自动闭环与后续视觉验收

原消费审查、Message 模型与非颜色默认值登记的源码清单已经收敛；不再把已完成事项重复列作“下一批”。共享组件和平台专属组件都进入目录与消费检查，不为同名而创建无效别名或另一端的空壳。具体变量处置见 token-consumer-resolution，非颜色职责见 non-color-token-resolution，Message 迁移见 message-token-resolution。

自动门禁分别检查声明／引用可解析、同义默认值与平台差异、状态和覆盖级联、动态消费者登记、文档生成漂移。它们不能证明任意业务插槽、背景、缩放倍率和浏览器组合的像素结果。构建、类型与发布产物检查以对应运行日志为证据，也不能代替视觉验收。

尚需持续完成的是有明确环境范围的 QA：

- Safari／Firefox／Chromium 的代表性交互回归，特别是 error × focus × hover、selected × pressed、禁用与键盘顺序。
- iOS／Android 真机、窄屏与粗指针，确认输入法、触摸目标、悬停限制和安全区域。
- 浏览器减少动态效果偏好及动态切换、动画生命周期、焦点可见性与屏幕阅读器。
- 长文本、多语言、大字号／缩放、嵌套 Teleport 浮层及业务局部覆盖；自定义颜色需自行验证对比度。

实际已抽查与未覆盖场景以 `design-ui/audits/token-browser-validation.md` 为准。后续发现真实问题仍应同步修改规范、实现、契约和测试；消费候选为零不是“永远没有 CSS 错误”的承诺。

## Badge 与 Tag：语义色、预设色及覆盖边界

Badge 的默认 status 是 danger；无状态匹配时的 bg-color 兜底也引用 system status-danger，不再固定为 #ef4444。status-default-bg-color 的 #e0e0e0 是有意保留的固定中性底，搭配 content-on-bright（黑色）；secondary / tertiary 保留 gray-6 / gray-7。tertiary 在暗色使用深字，Maple 浅色品牌的 primary 使用浅字。隔离环 border-color 跟随 surface-default；放到其他宿主背景上时可局部覆盖。Maple 暗色主题仅保留必要的 tertiary 文字差异，不重复声明全套默认值。

Tag 的 color 预设色表示色板选择，不是业务 status。13 种预设色在两端遵循同一规则：

| 状态／变量 | 职责 |
| --- | --- |
| 已选中 default：{色名}-bg / bg-hover | 正常／可交互 hover 背景；loading 不消费 hover 值。暗色默认分别为该色第 6 阶的 20% / 35% 透明混合，通过 Token 声明而非选择器写死。 |
| 已选中 outline：{色名}-text-color | 文字及描边共用，背景始终透明，hover 不套用填充背景。 |
| {色名}-icon-color | 已选中的前缀、关闭和加载图标颜色，与显式 text-color 的文字覆盖分开。 |
| {色名}-border-color / border-color-hover | default 变体边框，默认透明；不控制 outline 的同色描边。 |
| 未选中 checkable | 预设颜色不生效，维持中性；仅非 loading 的 hover 使用 bg-not-checked-hover。 |

背景变量可在实例根元素覆盖，在暗色同样生效；根级自定义声明需注意与主题 :root 属性选择器的优先级。color（预设／自定义）优先于 status。自定义 default 的背景与边框由 color 属性内联设置，text-color 可覆盖前景；自定义 outline 的 color 控制描边和默认文字，背景透明。自定义色当前不随 checked 自动回到中性，这与预设色不同，不应假定两条路径完全一致。业务负责自定义颜色、透明混合后的文字可读性。

本阶段新增 98 项既有颜色默认值约束，总计 566 项组件默认值；登记不等于每个声明都有消费点。预设 icon-bg-hover 等无消费声明已在下一阶段移除，详见后文；上一阶段的 566 为当时统计。Badge 新增持久化 check:badge-themes：288 个级联状态、720 对配色和 288 项背景覆盖检查，最低 4.563:1。Tag 新增 1664 个预设级联状态与 416 项背景覆盖检查；原有 1024 个语义状态及 640 对对比度检查继续保留。预设色现已追加 2080 对对比度检查，最低 4.529:1：覆盖两端、两品牌、明暗、default / outline、hover 及五类 system 表面；彩色前景使用第 9 阶，灰色使用 content-secondary，gold 的浅色 hover 背景从第 3 阶调整为第 2 阶。自定义色及 loading 透明度不在对比度保证范围；这些是静态编译与级联检查，不是浏览器视觉验收。

## Token 必须有消费路径

公开变量必须能沿 var() 引用链到达实际 CSS 属性，或有明确记录的运行时／跨组件消费者。仅有声明、文档、主题覆盖，甚至变量之间互相引用，都不代表可定制。审核先编译 Less（展开 mixin 和动态变量名），再追踪属性到变量的引用链；不能只在组件目录中按字符串出现次数判断。

本次两端 Tag 同步移除 15 个无消费入口：13 种预设色的 {色名}-icon-bg-hover，以及 icon-hover-size、icon-hover-bg-size。不保留兼容别名；应用中对这些旧变量的覆盖可以删除，没有对应的新变量。删除的是无效定制入口，不是已有 hover 效果。

custom-icon-bg-hover 在上一阶段暂保留（现已清理，见后文）：Cedar InputTag 仍通过 icon-hover-bg mixin 引用它，因此不能按 Tag 自身未引用直接删除。该引用依赖旧 c-icon-hover DOM；当前 Tag 使用 close-btn，编译中存在引用不等于实际可见。后续应结合 InputTag 渲染结构清理或重新设计；Maple 保留同名声明以保持两端契约，在 Tag 自身没有消费效果。

该阶段的 check:token-consumers 只检查两端 Badge / Tag，包含引用链、嵌套 fallback、循环和主题多值的测试，以及当时的显式跨组件保留项（现已清理）。它会拒绝新增无消费声明，但不证明选择器在运行时可达、级联获胜或任意覆盖可见；这些仍由组件测试、主题级联和浏览器验收负责。本次减少 13 项颜色默认值约束，该阶段总数为 553；另外 2 项移除的尺寸变量此前仅登记名称。

## InputTag 旧图标引用收尾

Cedar InputTag 实际嵌入 Tag 的 close-btn，不渲染旧 c-icon-hover 伪元素。本次移除旧 mixin 导入、默认／focus 的伪元素背景规则，以及重复的自定义 Tag 文字规则（文字由 Tag 自身负责）。关闭按钮的现有外观、点击删除和 readonly / disabled 行为不变；没有新增 hover 背景效果。

同步删除两端 tag-custom-icon-bg-hover，以及 Cedar input-tag-tag-remove-icon-color-bg / input-tag-tag-remove-icon-color-bg-focus。旧变量没有替代项，业务中对此的无效覆盖可删除；不保留别名。Maple 没有 InputTag 组件，仅同步清理共享 Tag 变量。

此前的跨组件保留项已关闭。check:token-consumers 现在检查 414 项 Badge / Tag 声明且无豁免，并编译 InputTag 防止旧图标选择器／变量回流；实际 DOM、关闭交互和自定义颜色由 InputTag 集成测试验证。553 项共享默认值数量不变：本次删除的共享变量此前仅登记名称。此阶段仍不代表 InputTag 全部 Token、浏览器视觉或键盘交互已完成治理。

## InputTag 外壳与内容职责

InputTag 的 outline / filled / standard 外壳由 FieldDecorator 管理。Form 不应重新设置其背景、边框或焦点阴影；本次删除了 Form 对旧 InputTag 状态类的重绘规则，保留校验提示职责。filled 的默认／hover／focus 继续走 FieldDecorator 的 fill-1 / fill-2 / fill-3 规则。

InputTag 的内容密度、默认标签底色和禁用文字由 input-tag-* 控制。内容选择器现在匹配实际的 c-field-decorator--size-* / --focus / --disabled 类名，而非不存在的旧 InputTag 状态类；disabled 优先于 focus。五档 xs / sm / md / lg / xl 内容规则均已覆盖；xl 的标签高度为 32px、输入文字为 16px、垂直内边距为 4px。

移除 33 项没有实际 CSS 消费的旧外壳变量：size-{xs,sm,md,lg}-height；color-text-error；color-placeholder、color-icon-clear、color-icon-clear-bg-hover；color-border-{default,error,disabled}（及其 -hover / -focus）；color-bg-{default,error}（及其 -hover / -focus）、color-bg-disabled（及 -hover）；color-shadow-{default,error}-focus、size-shadow-{default,error}-focus；border-radius、border-width、size-icon-clear、size-icon-clear-hover。以上后缀均属于 --c-input-tag-。没有兼容别名。

迁移时按职责选择实际入口：外壳背景用 field-variant-{variant}-background 系列，圆角用 field-border-radius，占位文字用 field-placeholder-text-color，清除图标用 field-clear-icon-color / field-clear-icon-size。几何优先使用 size 属性；不要覆盖 internal 变量。旧无消费变量不存在逐项等价替代；内容标签使用下列 InputTag 自身变量。

InputTag 保留 27 项内容变量，已加入无消费检查；两端 Badge / Tag 加 Cedar InputTag 共检查 441 项声明，内容 size / focus / disabled 级联覆盖 80 组。共享默认值契约仍为 553 项；Cedar-only InputTag 不冒充跨端共享组件。默认文字、禁用文字、标签底色与焦点底色分别引用 content-primary、content-disabled、surface-default、state-hover。禁用状态只重绘中性标签，不覆盖显式 color / status；业务自定义颜色的可读性由业务负责。父级 disabled / readonly 优先于 tagProps.closable / checkable，loading 或显式不可关闭的标签也不能用 Backspace 删除。已完成 Cedar 浏览器五档布局、xl 输入与键盘删除、明暗模式以及禁用自定义色的抽验，不代表全组件视觉验收。
## 字段键盘焦点与错误状态

当前 FieldDecorator 不额外绘制外圈 outline；outline 通过 border-state 边框、filled 通过背景、standard 通过底线响应 `--focus` 或 `:focus-within`。内部清除、密码切换和数字步进按钮保留自身键盘焦点指示。只读保留聚焦，禁用和错误的颜色优先级不变；不据此宣称错误态焦点可辨识性或原生可访问性已验收。

Input、Textarea、InputNumber 的实际原生控件使用 `caret-color: currentColor`，不再由 field-focus-color／field-error-color 染色。field-focus-color、field-error-color 和 field-border-width 仍有提示、边框或按钮 outline 消费，不能因移除 caret／外偏移路径而删除 Token。实例 focus-color 控制现有支持的变体／提示通道，不承诺改变 caret；没有新变量、默认值或业务 API 变更。

检查 `node bin/field-focus-check.mjs` 与 `node --test bin/field-focus-caret.test.mjs` 核对实际 Less 产物、静态导入链、保留消费和三页生成目录；DOM 回归连接真实 Input／Textarea／InputNumber。Less／JSDOM 不替代原生键盘、焦点对比、绘制或浏览器验收。

## 声明归档与真实消费路径（2026-10-12）

组件公共默认变量统一声明在所属 `style/token.less`，实现样式只消费变量；内部状态变量仍可贴近实现。此次将 34 个实现样式文件中的 375 处公共声明归档，归档前后有效默认值与非根规则均经两端 Less 编译比对一致。不要把 CSS 归档理解为重新设计默认配色。

全量目录同时检查 `style/index.less` 和 `style/index.ts` 直接导入的 Less。共享 selection 的 presentation 样式是合法入口；忽略它会误判变量无消费者。Watermark 在运行时读取变量并用于画布，FloatingPanel、Time 时钟和 TabBar 通过实际行内样式消费变量；这些可执行路径需单独登记，不接受注释或主题赋值充当证据。

属性与变量应有明确优先级：显式属性优先，未传属性时使用对应 CSS 变量。Maple TabBar 的 `z-index` 现遵循此规则，默认视觉值仍为 `1`，属性默认值为 `undefined`。ImagePreview 的箭头 hover 变量仅在可悬停设备且箭头可用时生效。Counter 无消费的 disabled-color 已移除，禁用仍由 disabled-opacity 及实际文字／背景变量表达。

动效规则须同时约束 CSS 与 JavaScript：Maple Picker 在 reduced-motion 下立即提交选择，不等待 transitionend；偏好动态变为 reduce 时收束待提交滚动。键盘列为 listbox，当前项为 option，方向键与 Home/End 跳过禁用项；这不改变 selected-values 的附加勾选标记语义。Time 打开面板先提交输入草稿而不提前 blur，确保弹层关闭后回到原输入。

检查入口：`check:token-placement`、`check:field-focus` 和 `check:theme-contract`；完整变量名称、值、条件和消费路径以自动生成的组件变量参考为准。编译与单测不能替代跨浏览器、真机和屏幕阅读器验收。

弹层焦点根必须指向实际具有 tabindex 的面板，而不是外层遮罩容器。Maple Popup 已补齐内部焦点根标记；打开、嵌套层接管、Tab/Shift+Tab 循环及关闭后的触发器恢复均需以真实组件验收。这个内部 data 属性不是业务 CSS/API 扩展入口。

## 变量作用域、别名求值与 Teleport

同文档切换弹层宿主时，即使面板引用和 ownerDocument 不变，DOM 移动仍可能让原生焦点丢失。顶层活动模态须在迁移完成后恢复面板内焦点，并保留最初的关闭返回目标，不抢占更高弹层。验收必须读取实际 activeElement，而不是只检查挂载与颜色；同源单测和旧截图不能代替修复后的原生复验。截图格式按实际编码保存，导出像素尺寸与 CSS viewport 分开记录，不用于推断原生缩放。

2026-10-13 修复后 IAB 原生跟进：两端在 default/dark、长文本、320×640 CSS viewport 下各五次 host／inline／body 迁移，10/10 焦点包含检查通过，并验证 Tab／Shift+Tab 循环、Enter 关闭与原触发器恢复。证据独立保存在 design-ui/audits/evidence/portal-focus-2026-10-13/after.json；旧八次失败不改写。这不是 200% 原生缩放或 Safari／Firefox 通过证明。运行环境重置后应重新确认浏览器类型与当前 ID，避免将旧句柄误认成同一浏览器。

同日 14:12 有界环境复查没有新增通过：Chrome 支持接口调用仍超时，Safari／Firefox 无支持会话，Firefox 标准应用路径未找到。三套各 48 组必须等待相应支持入口恢复；历史 IAB 证据不外推。最新阻塞记录见 design-ui/audits/evidence/browser-environment-2026-10-13/recheck-1412.json。

修复前后证据采用独立截图清单，校验实际编码尺寸及 SHA-256；连接复查、夹具准备和静态规则检查不增加浏览器通过数量。后续可先推进 IAB 真实同源 iframe 与嵌套弹层键盘验收，必须记录目标文档的样式、activeElement 焦点链和滚动锁；这些仍是待执行计划，不替代外部浏览器、真机、真实 OS reduced-motion 或屏幕阅读器。详细场景见 design-ui/refactors/token-validation/browser/README.md。

更新：真实同源 iframe 批次已完成 8/8，嵌套弹层批次也已完成 8/8。每个目标 Document 必须独立加载组件 CSS 与主题；跨文档 Teleport 不复制父文档变量，也不会让父文档样式表自动进入 iframe。自定义绝对定位宿主必须建立定位、尺寸和滚动边界。父文档触发 iframe 模态时，应沿可访问同源焦点链保存最初触发器，关闭后恢复，不抢占用户已移至外部控件的焦点。跨源不可访问边界不绕过，不能外推为已验收。两端焦点修复无 API／Token 变更；最终证据见 design-ui/audits/evidence/iframe-2026-10-13/results.json。

嵌套模态按两端 × 四主题实测，分别执行子层先关、父层先关与父层单独重开：仅栈顶响应 Tab／Escape，子层关闭回到仍可见的父层触发器，最后一层关闭回到页面原始触发器。父层先关闭时不能抢占仍打开的子层焦点；子层须在打开时保存祖先 opener 链，关闭时跳过已隐藏、禁用、inert 或断开的候选，避免焦点落到 BODY。两端 modal-focus 已修复该问题，无新 API／CSS 变量。滚动锁保留至最后一个使用者退出，滚动条补偿不重复累加。本批使用默认保留挂载、同库嵌套和 body 目标；背景抑制仅证明真实键盘约束与遮罩命中，不声称屏幕阅读器隔离、跨库协调、父层 unmountOnClose 移除或跨源已通过。18 张原图及分步证据见 design-ui/audits/evidence/nested-2026-10-13/results.json；后续为 reduced-motion 规则／配色准备，真实 OS 偏好另验。

原生缩放与跨浏览器验收必须分别记录浏览器／版本、浏览器自身显示的缩放百分比、实际 DOM 挂载祖先和截图。DPR、缩窄 viewport、CSS zoom／transform 只能提供其他类型的证据，不能单独证明原生 200% 页面缩放。Safari／Firefox 需要对应产品的实际浏览器结果；连接超时、缺少安装或缺少控制入口标为环境阻塞，不作为组件失败，也不能沿用 Chromium 结果记为通过。


局部主题有两道边界：真实 DOM 祖先，以及变量的声明位置。自定义属性中的 `var()` 在继承前解析；子节点改 system 变量，不会自动重新计算从根节点继承的组件别名。[CSS 变量规范](https://www.w3.org/TR/css-variables-1/#cycles)

| 场景 | 正确入口 |
| --- | --- |
| 全局切换主题 | 在文档根作用域通过本库 StyleProvider 全局方法切换；根层依赖链一起重算 |
| 定制局部组件 | 覆盖实际消费的公开 component 变量；只改 palette/system 不等于完整的局部主题重建 |
| 局部 system 到 component 映射 | 在同一局部宿主显式重新声明需要的组件别名，不依赖根层旧映射 |
| Teleport 到 body | 继承 body/html；触发器、调用处 Provider 的局部变量不自动复制过去 |
| 指定 popup-container | 宿主必须已经存在；变量放在目标宿主或真正面板上 |
| popup-container=false | 保留调用位置的 DOM 继承；同时承担祖先 overflow、transform、定位和层叠的约束 |
| iframe 宿主元素 | 允许来自另一文档的 HTMLElement；对方文档必须自行加载样式并提供变量，字符串选择器只查调用方文档 |

从自定义宿主经 inline 切回 body 时，必须真正迁出旧宿主，恢复 body/html 的变量继承；“仍属于 body 的后代”不是有效断言，因为旧宿主也可能位于 body 内。打开中切换和关闭后重新打开都遵守此规则。inline 状态的滚动锁按实际面板文档的 body 归属，不沿用之前的宿主锁。

浮层尺寸以实际包含块为边界；`100vw` 可能包含页面滚动条宽度，不能用它替代容器可用宽度。Cedar Drawer 对显式宽度保留 `max-width: 100%` 上限，这是结构约束，不是新增设计 Token。长内容允许面板内部滚动；任意业务插槽的断词、字号与前景／背景配对仍由业务显式设计。

例如同一页面的 Cedar Drawer 与 Maple Popup 可以共享一个真实宿主，但各自覆盖本库变量，不能依赖另一端前缀：

```css
.portal-theme {
  --c-drawer-bg: #182230;
  --c-drawer-header-text-color: #f8f9fc;
  --c-drawer-content-text-color: #f8f9fc;
  --mp-popup-content-background-color: #182230;
  --mp-popup-content-text-color: #f8f9fc;
}
```

若需要联动局部 system 色，在该宿主同时声明对应组件变量，例如 `--mp-popup-content-background-color: var(--mp-sys-color-surface-raised)`；只在宿主设置 surface-raised 不足以重算根上已经声明的别名。面板与遮罩是兄弟节点，面板变量不会向上或横向传给遮罩；共同覆盖放在共同宿主，或分别使用各组件现有的面板／overlay 样式属性。

不自动复制触发器 computed style、不批量重写 root 默认值，也不为另一端不存在的组件制造变量。本条明确现有定制范围，不新增 Token、不承诺局部 StyleProvider 会自动重建全部主题依赖链。自定义前景和背景需配对检查，本文的示例不是任意插槽配色保证。

`check:portal-scope` 使用真实 Teleport，检查 body／选择器／元素／inline 挂载、宿主切换后的实例状态、旧宿主滚动锁释放、跨文档参数与事件归属及卸载清理。DOM 和生命周期测试不计算浏览器像素；CSS 检查器验证局部覆盖时不能把根层的原始别名表达式带到子节点后重新求值。窄屏、200% 浏览器缩放、长文本、跨文档焦点和浏览器实际继承仍需独立实测。

打开中的模态面板跨文档切换挂载目标时，事件监听、焦点约束、弹层栈和滚动锁必须随实际目标迁移；同一 DOM 被 adopt 后 ownerDocument 会变化，但 Vue 元素引用可能不变，内部逻辑不得仅依赖该引用触发重绑。迁回原文档和卸载都要清理旧监听。此契约不增加公开 CSS 变量，真实 iframe 焦点与样式仍需浏览器验收。

---

Document: llms/zh-CN/guide/empty-values.md

<!-- Source: docs/guide/empty-values.md; locale: zh-CN; page: /guide/empty-values/ -->

# 空值识别、清空输出与阅读空文案

## 先判断你要解决什么问题

| 需求                                             | 使用的属性                 | 示例                 |
| ------------------------------------------------ | -------------------------- | -------------------- |
| 点击清空后提交 null、-1 或组件允许的其他值       | empty-value / emptyValue   | 清空按钮与手动删空   |
| 接口返回 -1 时，界面应显示“未选择”并无法通过必填 | empty-values / emptyValues | 空值标记与必填校验   |
| 空字符串代表合法的“全部”选项                     | empty-values 排除空字符串  | 合法空字符串选项     |
| 阅读模式为空时显示 '-' 或“暂无”                  | empty-text / emptyText     | 阅读空文案与配置继承 |

三个属性各有职责，不互相推导。emptyValue 只决定一次清空动作的输出；emptyValues 只声明空值身份；emptyText 只提供展示文案。配置与阅读展示不回写模型，不改变受控判断。

## 按场景理解

### 清空按钮与手动删空

在输入框中点击清空图标，模型变为 null；点击“恢复初值”后用 Backspace 删光，模型为 `''`。下方模型输出用引号区分空字符串与 null。

Example source: src/input/__demos__/empty-value.vue

```vue
<script setup lang="ts">
import { reactive } from "vue";
const model = reactive({ text: "Hello" as string | null });
</script>
<template>
  <c-space direction="column">
    <p>点击清空图标得到 null；用 Backspace 删光得到空字符串。</p>
    <c-form :model="model" layout="vertical">
      <c-form-item field="text" label="关键词">
        <c-input
          v-model="model.text"
          edit-mode="direct"
          clearable
          :empty-value="null"
        />
      </c-form-item>
    </c-form>
    <c-button @click="model.text = 'Hello'">恢复初值</c-button>
    <p>
      当前模型: <output>{{ JSON.stringify(model.text) }}</output>
    </p>
  </c-space>
</template>
```

手动输入是普通输入事件，不会自动调用 emptyValue。Form reset 则恢复记录的初始值，也不是用户清空。详见 [Input 的值模型与交互](llms/zh-CN/components/input.md)。

### 合法空字符串选项

“全部”的 value 是 `''`，仍应显示为已选。此时 emptyValues 使用 `[null, undefined]`；清空输出独立配置为 null。点击清空，再点击“选择全部”，比较两种模型值。

Example source: src/select/__demos__/empty-value.vue

```vue
<script setup lang="ts">
import { reactive, ref } from "vue";
const model = reactive({ status: "" as string | null });
const multiple = ref(["active"]);
const optional = ref<string | undefined>("active");
const options = [
  { value: "", label: "全部" },
  { value: "active", label: "启用" },
];
</script>
<template>
  <c-space direction="column">
    <p>“全部”的值是空字符串，仍是有效选项；点击清空返回 null。</p>
    <c-form :model="model" layout="vertical">
      <c-form-item field="status" label="状态">
        <c-select
          v-model="model.status"
          :options="options"
          edit-mode="direct"
          clearable
          :empty-values="[null, undefined]"
          :empty-value="null"
        />
      </c-form-item>
    </c-form>
    <c-button @click="model.status = ''">选择“全部”</c-button>
    <p>
      当前模型: <output>{{ JSON.stringify(model.status) }}</output>
    </p>
    <c-form layout="vertical">
      <c-form-item label="多选：清空返回 []">
        <c-select
          v-model="multiple"
          :options="options"
          edit-mode="direct"
          multiple
          clearable
          :empty-value="() => []"
        />
        <output>{{ JSON.stringify(multiple) }}</output>
      </c-form-item>
      <c-form-item label="单选：清空返回 undefined">
        <c-select
          v-model="optional"
          :options="options"
          edit-mode="direct"
          clearable
          :empty-value="() => undefined"
        />
        <output>{{ String(optional) }}</output>
      </c-form-item>
    </c-form>
  </c-space>
</template>
```

Select 默认保留合法空字符串选项。显式配置便于让字段和表单必填使用同一规则；删除选择器的搜索词只改变查询，不删除已选值。详见 [Select 的值模型与联动](llms/zh-CN/components/select.md)。

### 空值标记与有效的 0

接口用 -1 表示未填写时，将它加入 emptyValues；需要清空也返回 -1 时，再配置 emptyValue=-1。初始界面空白，但下方模型仍为 -1。点击“设为 0”，应显示有效数字 0；清空后再回到 -1。

Example source: src/input-number/__demos__/empty-value.vue

```vue
<script setup lang="ts">
import { reactive, ref } from "vue";
const model = reactive({ quantity: -1 as number | null | undefined });
const restored = ref<number | null | undefined>(12);
</script>
<template>
  <c-space direction="column">
    <p>-1 表示未填写，输入框显示空白；0 仍显示为有效数字。清空返回 -1。</p>
    <c-form :model="model" layout="vertical">
      <c-form-item field="quantity" label="数量">
        <c-input-number
          v-model="model.quantity"
          edit-mode="direct"
          clearable
          :empty-values="[null, undefined, -1]"
          :empty-value="-1"
        />
      </c-form-item>
    </c-form>
    <c-space wrap>
      <c-button @click="model.quantity = 0">设为 0</c-button>
      <c-button @click="model.quantity = -1">设为 -1</c-button>
    </c-space>
    <p>
      当前模型: <output>{{ String(model.quantity) }}</output>
    </p>
    <p>此字段清空后恢复为 0，0 仍是有效值，不会显示为空。</p>
    <c-form layout="vertical">
      <c-form-item label="清空恢复有效的 0">
        <c-input-number
          v-model="restored"
          edit-mode="direct"
          clearable
          :empty-value="0"
        />
        <output>{{ String(restored) }}</output>
      </c-form-item>
    </c-form>
  </c-space>
</template>
```

0 和 false 默认都不是空值。不要用 `!value` 一次性判断它们。InputNumber 手动删光后的提交仍遵循数值解析规则，可能输出 undefined，不自动套用按钮的清空输出。详见 [InputNumber 的数值输入与格式](llms/zh-CN/components/input-number.md)。

### 接口空标记与必填校验

本例在 Form 设置 `[null, undefined, -1]`，供字段继承；Select 单独设置清空输出 -1。先校验初始值，再选择部门并校验；清空后再次校验会失败。

Example source: src/form/__demos__/empty-values-validation.vue

```vue
<script setup lang="ts">
import { reactive, ref } from "vue";
const model = reactive({ department: -1 as number | null | undefined });
const form = ref();
const result = ref("尚未校验");
const options = [
  { value: 1, label: "研发" },
  { value: 2, label: "产品" },
];
async function validate() {
  const errors = await form.value.validate();
  result.value = errors ? "存在必填错误" : "校验通过";
}
</script>
<template>
  <c-space direction="column">
    <p>先校验初始 -1，再选择部门并校验；点击清空后会回到 -1。</p>
    <c-form
      ref="form"
      :model="model"
      layout="vertical"
      :empty-values="[null, undefined, -1]"
    >
      <c-form-item field="department" label="部门" required>
        <c-select
          v-model="model.department"
          :options="options"
          edit-mode="direct"
          clearable
          :empty-value="-1"
        />
      </c-form-item>
    </c-form>
    <c-button @click="validate">校验</c-button>
    <p role="status">{{ result }}</p>
    <p>
      当前模型: <output>{{ String(model.department) }}</output>
    </p>
  </c-space>
</template>
```

只有 emptyValue=-1，不能声明 -1 为空；只有 emptyValues 包含 -1，也不会改变原有清空输出。required 在主动校验或既有触发时机运行，不会因为页面显示空白就自动运行。详见 [Form 的校验与提交](llms/zh-CN/components/form.md)。

### 阅读空文案与配置继承

初始阅读模式下，姓名继承 Form 的默认 `'-'`，编号使用 FormItem 的“未分配”，昵称使用字段的“匿名”，数量保持 0。点击“使用暂无”，只有继承 Form 的空字段改变文案；再切换阅读/编辑，观察下方模型保持原值。

Example source: src/form/__demos__/empty-text.vue

```vue
<script setup lang="ts">
import { reactive, ref } from "vue";
const reading = ref(true);
const emptyText = ref("-");
const model = reactive({
  name: null as string | null,
  code: null as string | null,
  nickname: null as string | null,
  quantity: 0 as number | null | undefined,
});
</script>
<template>
  <c-space direction="column">
    <p>初始阅读模式：姓名显示“-”，编号和昵称使用各自覆盖；数量 0 仍显示 0。</p>
    <c-space wrap>
      <c-button @click="reading = !reading">切换阅读/编辑</c-button>
      <c-button @click="emptyText = '暂无'">使用“暂无”</c-button>
      <c-button @click="emptyText = '-'">使用默认“-”</c-button>
    </c-space>
    <c-form
      :model="model"
      layout="vertical"
      :read-pretty="reading"
      :empty-text="emptyText"
    >
      <c-form-item field="name" label="姓名：继承 Form"
        ><c-input v-model="model.name"
      /></c-form-item>
      <c-form-item field="code" label="编号：覆盖 FormItem" empty-text="未分配"
        ><c-input v-model="model.code"
      /></c-form-item>
      <c-form-item field="nickname" label="昵称：覆盖字段" empty-text="未分配"
        ><c-input v-model="model.nickname" empty-text="匿名"
      /></c-form-item>
      <c-form-item field="quantity" label="数量"
        ><c-input-number v-model="model.quantity"
      /></c-form-item>
    </c-form>
    <p>
      当前模型: <output>{{ JSON.stringify(model) }}</output>
    </p>
  </c-space>
</template>
```

优先级为 **字段 > FormItem > Form > '-'**。显式 emptyText=`''` 表示空白；自定义 read 插槽始终优先。emptyText 不等于输入框 placeholder，也不会作为校验值或提交数据。详见 [Form 的字段呈现与交互](llms/zh-CN/components/form.md)。

## 配置规则与边界

### emptyValues：识别当前模型是否为空

字段配置覆盖 FormItem，FormItem 覆盖 Form；列表完整替换，不合并。未配置时采用组件族默认：字符串识别 null/undefined/空字符串，Select 和数值字段保留各自的 nullish 默认。

标量用 includes 比较，0/false 默认有效；对象按引用识别，不做任意深比较。空数组始终是空集合，非空 `[null]` 不自动算空。显式 emptyValues=[] 可以移除额外标量空标记，但不能把空集合变成有选中项。

固定状态控件（Switch、Checkbox、Radio、Slider、Rate）与 Upload 在阅读和必填判断中使用策略，不因此重写 checked、数值范围或文件传输逻辑。非法日期、未完成的数字草稿仍由领域规则处理。

### emptyValue：清空动作产生什么值

省略时保留组件原有默认返回；具体允许的类型见组件 API。Input 当前支持字符串/null 及其工厂；对于支持 undefined 输出的 InputNumber、日期时间字段等，使用 `:empty-value="() => undefined"` 显式输出 undefined，直接绑定 undefined 仍表示未指定覆盖。

工厂在实际清空动作中求值，不在初始化、阅读或校验时执行。数组按原有解析规则生成独立结果。emptyValue 不会自动加入 emptyValues：例如清空恢复到 0 时，0 可以仍是有效值。

部分共享弹层在未配置 emptyValue 时会恢复 defaultValue；清空先修改草稿，确认后提交，取消则不提交。按钮清空、手动删空、移除最后一项和 reset 的差异按各组件既有规则执行。

### 必填与自定义规则

显式配置 emptyValues 后，内置 required 使用主字段策略。未显式配置时保留两库已有校验行为，不假定 Cedar 的 b-validate 与 Maple 的函数/Zod 在所有边界值上完全一致。

自定义 validator、Zod、min/max、enum 继续收到原始值。UI 识别 -1 为空，并不代表 `number().positive()` 会接受它；业务 schema 必须自己规定可缺省值。识别为空也不等于所有业务约束合法。

false 默认有效，因此“必填”不等于“必须勾选同意”。协议字段可显式将 false 标为空，或用自定义规则要求 true。一个 FormItem 建议对应一个主字段；多个独立值应拆成多个 FormItem。

### 与受控判断的关系

受控身份与业务空值是两件事。添加 -1 到 emptyValues 不会使外部绑定失去受控身份；移除 undefined 也不会改变组件既有的所有权判断。不要把内部所有 undefined 判断都替换为 isEmpty：模型所有权、数值解析失败、非法日期和业务空标记各有含义。

## 与 Element Plus 的对应关系

本设计借鉴 [Element Plus 空值配置](https://element-plus.org/zh-CN/component/config-provider.html#empty-values-configurations)和 [useEmptyValues](https://github.com/element-plus/element-plus/blob/dev/packages/hooks/use-empty-values/index.ts)的职责拆分。emptyValue 对应 valueOnClear，保留现有名称，不增加同义属性。

继承范围采用 Form/FormItem，工厂在清空动作时求值；保留组件族默认输出与空集合规则，没有照搬它的数组深比较、清空输出警告或 ConfigProvider 实现。

---

Document: llms/zh-CN/guide/i18n.md

<!-- Source: docs/guide/i18n.md; locale: zh-CN; page: /guide/i18n/ -->

## 国际化

默认中文，其他语言设置如下：

```typescript
import { addI18nMessages, useLocale } from '@cedar-design/ui'

if (Env.getLanguage() !== 'zh-CN') {
  addI18nMessages({
    [Env.getLanguage()]: require('@cedar-design/ui/es/locale/lang/en-us').default,
  })
  useLocale(Env.getLanguage())
}
```

---

Document: llms/zh-CN/guide/llms.md

<!-- Source: docs/guide/llms.md; locale: zh-CN; page: /guide/llms/ -->

# LLM 文档

Cedar Design Web 提供面向大语言模型（LLM）的纯文本与 Markdown 文档，包含指南、组件 API 和 Vue 示例源码。将在线地址交给 AI 编码助手，即可在编写代码前查阅相关文档。

## 在线文档

无需下载，支持读取网页的 AI 助手可以直接访问以下地址。**推荐从文档索引开始，按需读取相关组件。**

| 文档 | 在线地址 | 适用场景 |
| --- | --- | --- |
| 文档索引 | [https://cedar.show/llms.txt](https://cedar.show/llms.txt) | 查找指南和组件的单页 Markdown，推荐优先使用 |
| 完整文档 | [https://cedar.show/llms-full.txt](https://cedar.show/llms-full.txt) | 一次读取全部文档与示例，适合上下文容量充足的工具 |

索引中的每个组件都有独立的 Markdown 地址，可以直接打开、交给助手读取，或保存到本地。

## 在 AI 助手中使用

### 直接提供文档地址

复制下面的提示词，在末尾补充你的需求：

```text
请使用 Cedar Design Web 和 Vue 3 实现我的需求。
先读取官方文档索引：https://cedar.show/llms.txt
再根据任务读取快速开始和相关组件的单页文档，核对安装、引入与样式配置。
严格按照文档中的 props、事件、插槽和示例编写代码。
如果文档没有说明某个 API，请明确指出，不要猜测。

我的需求：
```

### 添加为项目参考资料

如果你的编码助手支持配置文档来源，可以添加上面的在线索引地址，并在项目说明中注明：使用 `@cedar-design/ui` 时先查阅官方文档。

如果工具无法访问网页，可打开在线文件，将所需内容保存为 `.txt` 或 `.md` 后作为附件提供。全文文件较大，可能超过工具的读取限制；通常读取索引和任务相关的单页文档即可。

## 按语言选择

| 语言 | 文档索引 | 完整文档 |
| --- | --- | --- |
| 中文 | [https://cedar.show/llms.zh-CN.txt](https://cedar.show/llms.zh-CN.txt) | [https://cedar.show/llms-full.zh-CN.txt](https://cedar.show/llms-full.zh-CN.txt) |
| English | [https://cedar.show/llms.en-US.txt](https://cedar.show/llms.en-US.txt) | [https://cedar.show/llms-full.en-US.txt](https://cedar.show/llms-full.en-US.txt) |

各语言文件只收录已有的对应语言文档，未翻译的页面不会自动转换为英文。需要查阅全部页面时，请使用上方的综合索引。

## 内容与更新

文本文件从指南与组件文档自动生成，保留 API 表格，并将 Demo 引用展开为 Vue 源码。示例中的相对模块导入仍以标注的源码路径为基准。

每次构建文档站点时重新生成，并与站点一起发布。使用时请核对文档与项目中安装的组件库版本。

---

Document: llms/zh-CN/guide/questions.md

<!-- Source: docs/guide/questions.md; locale: zh-CN; page: /guide/questions/ -->

## 常见问题

---

Document: llms/zh-CN/guide/quickstart.md

<!-- Source: docs/guide/quickstart.md; locale: zh-CN; page: /guide/quickstart/ -->

# 快速开始

## 安装

```shell
# npm
npm i @cedar-design/ui @cedar-design/icons-vue

# pnpm
pnpm add @cedar-design/ui @cedar-design/icons-vue
```

## 自动按需引入（推荐）

Cedar 提供内部维护的 `@cedar-design/resolver`。配合 `unplugin-vue-components`，模板中使用到的组件、独立 SVG 图标、指令及组件样式会在编译时自动按需引入。

```shell
npm i @cedar-design/resolver unplugin-auto-import unplugin-vue-components -D
```

### Vite

```ts
// vite.config.ts
import vue from "@vitejs/plugin-vue";
import AutoImport from "unplugin-auto-import/vite";
import Components from "unplugin-vue-components/vite";
import { CedarResolver } from "@cedar-design/resolver";
import { defineConfig } from "vite";

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

配置后可直接使用，无需在组件中手动导入：

```vue
<template>
  <c-button status="primary">确认</c-button>
  <c-icon size="40" color="red">
    <c-icon-check-circle-fill />
  </c-icon>
</template>
```

Resolver 会分别生成：

```ts
import { Button, Icon } from "@cedar-design/ui";
import { IconCheckCircleFill } from "@cedar-design/icons-vue/icon-check-circle-fill";
import "@cedar-design/ui/button/style";
import "@cedar-design/ui/icon/style";
```

独立 SVG 图标通过 `currentColor` 继承容器颜色，因此图标子包不需要额外 CSS；`c-icon` 容器自身需要加载 `@cedar-design/ui/icon/style`。

### 动态名称与显式注册

`<c-icon name="check-circle-fill" />` 只查询显式注册到 Vue 应用的图标，组件内部不会导入图标全集。建议只注册动态场景需要的图标：

```ts
// main.ts
import { createApp } from "vue";
import { IconCheckCircleFill, IconWarning } from "@cedar-design/icons-vue";
import App from "./App.vue";

const app = createApp(App);
app.component("IconCheckCircleFill", IconCheckCircleFill);
app.component("IconWarning", IconWarning);
app.mount("#app");
```

如果业务需要通过任意名称使用全部图标，也可以主动批量注册；这种写法会加载完整图标集合：

```ts
import * as CedarIconsVue from "@cedar-design/icons-vue";

for (const [name, component] of Object.entries(CedarIconsVue)) {
  if (name.startsWith("Icon")) app.component(name, component);
}
```

### 直接使用 SVG 图标

`@cedar-design/icons-vue` 中的每个 SVG 图标都是独立的 Vue 组件，也可以不使用 `c-icon` 容器直接渲染：

```vue
<script setup lang="ts">
import {
  IconDelete,
  IconEdit,
  IconSearch,
  IconShareExternal,
} from "@cedar-design/icons-vue";
</script>

<template>
  <!-- 直接使用 SVG 图标时不会自动提供业务布局属性 -->
  <!-- 请根据使用场景设置宽高、间距等属性 -->
  <IconEdit style="width: 1em; height: 1em; margin-right: 8px" />
  <IconShareExternal style="width: 1em; height: 1em; margin-right: 8px" />
  <IconDelete style="width: 1em; height: 1em; margin-right: 8px" />
  <IconSearch style="width: 1em; height: 1em; margin-right: 8px" />
</template>
```

这里的“布局属性”是指 `width`、`height`、`margin` 等业务样式；图标组件自身仍支持 `size`、`color`、`rotate` 和 `spin`。直接使用同样支持 Tree Shaking。需要统一控制布局、尺寸、颜色、旋转或交互区域时，推荐再使用 `c-icon` 包裹。

### 自动引入函数 API

上面的同一个 `CedarResolver()` 也会为 `unplugin-auto-import` 解析 `Message`、`Dialog`、`Notification` 等函数 API：

```ts
Message.success("保存成功");
```

`importStyle` 会统一控制模板组件、Icon 容器和函数 API 的样式导入。只有明确不希望解析函数 API 时，才需要设置 `CedarResolver({ autoImport: false })`。

### 自动引入指令

同一个 `CedarResolver()` 支持 `v-c-loading` 和 `v-tooltip`，无需配置第二个 Resolver。加载指令使用 `c-` 前缀，避免与其他组件库的同名指令冲突。可通过 `CedarResolver({ directives: false })` 关闭。

## 手动按需引入

不使用自动导入插件时，可手动导入组件、图标和组件样式：

```vue
<script setup lang="ts">
import { Button } from "@cedar-design/ui";
import { IconCheckCircleFill } from "@cedar-design/icons-vue/icon-check-circle-fill";
import "@cedar-design/ui/button/style";
</script>

<template>
  <Button status="primary">确认</Button>
  <IconCheckCircleFill :size="24" />
</template>
```

## 完整引入

完整引入会注册全部 Cedar UI 组件和指令，并加载全部样式，适合原型或对包体积不敏感的项目：

```ts
import { createApp } from "vue";
import Cedar from "@cedar-design/ui";
import "@cedar-design/ui/style";
import App from "./App.vue";

createApp(App).use(Cedar).mount("#app");
```

独立 SVG 图标不会随 UI 包全部注册；请继续显式导入，或使用 `CedarResolver()` 自动按需引入。

## 全局设置组件默认值

每个组件都提供 `setPropsDefaults`，用于统一修改之后创建的声明式组件默认值。请在应用挂载前调用：

```ts
import { Button, StyleProvider } from "@cedar-design/ui";

Button.setPropsDefaults({
  status: "primary",
  variant: "tonal",
  size: "lg",
});

// 其他组件使用相同方式
StyleProvider.setPropsDefaults({
  tag: "section",
});
```

组件上显式传入的属性优先级更高。设置不会追溯更新已经挂载的实例；对象和数组默认值会按实例创建副本。

## TypeScript 配置

确保自动生成的声明文件被 TypeScript 包含：

```json
{
  "include": ["src", "components.d.ts", "auto-imports.d.ts"]
}
```

## 样式控制

Resolver 默认自动引入组件样式。如项目已完整引入 Cedar 样式，可关闭重复的按需样式：

```ts
CedarResolver({ importStyle: false });
```

---

Document: llms/zh-CN/guide/roadmap.md

<!-- Source: docs/guide/roadmap.md; locale: zh-CN; page: /guide/roadmap/ -->

# Roadmap

本文档记录 Cedar Design Web 相对成熟组件库的补齐节奏，并与 Maple Design Mobile 公共 API 对齐。

## 当前阶段：P0（立刻）

| 项                         | 状态   | 说明                                                                             |
| -------------------------- | ------ | -------------------------------------------------------------------------------- |
| 公开 Roadmap               | ✅     | 本文档                                                                           |
| 一等 Dark Theme            | ✅     | `Themes` + `StyleProvider` / `ConfigProvider` + [主题定制](llms/zh-CN/themes.md)             |
| 样式按需引入               | ✅     | Resolver 默认引入 CSS；组件样式与基础主题拆分                                    |
| Segmented                  | ✅     | [Segmented](llms/zh-CN/components/segmented.md)                                              |
| Menu               | ✅     | [Menu 下拉命令菜单](llms/zh-CN/components/menu.md)（Trigger + MenuOption） |
| Tour                       | 待开始 | 新手引导                                                                         |
| VirtualList / Table 虚拟化 | 待开始 | 公开虚拟列表能力                                                                 |
| a11y 落地                  | 待开始 | 组件文档可访问性章节 + 键盘/ARIA 测试                                            |

## 下一波：P1

- QRCode、FloatButton、Comment（验证码输入已由 VerificationCode 覆盖，不另建 InputOTP）
- SSR 使用文档、VSCode / web-types
- Playground

## 可择机：P2

- CheckTag、DynamicTags
- 更多 i18n 语言包
- Theme Editor、截图视觉回归

## 与 Maple 的关系

公共 API（如 `variant` / `size` / `Segmented` 选项结构）以 **Cedar（PC）为准**，Maple 同步对齐。跨端破坏性变更走 OpenSpec。

## 不做硬跟的部分

Naive Heatmap / Equation、Vant 电商套件等差异化组件，按业务需要再评估，不进入默认 Roadmap。

---

Document: llms/zh-CN/guide/theme.md

<!-- Source: docs/guide/theme.md; locale: zh-CN; page: /guide/theme/ -->

# 主题定制

文档已迁移至 [主题定制 /themes](llms/zh-CN/themes.md)。

Cedar 与 Maple 对齐：

- `import { StyleProvider, Themes } from '@cedar-design/ui'`
- `StyleProvider.setStyleVars(Themes.default.dark)` 使用默认青绿色暗色主题
- `StyleProvider.setStyleVars(Themes.maple.light)` 使用枫叶亮色主题
- 两套主题都提供 `light` / `dark`
- 亦可用 `ConfigProvider` 的 `theme` 或直接改 DOM 属性

---

Document: llms/zh-CN/practices.md

<!-- Source: docs/practices/README.md; locale: zh-CN; page: /practices/ -->

# 最佳实践

Example source: docs/practices/__demos__/overview.vue

```vue
<script setup>
import { useRoute, useRouter } from "vue-router";
import { usePracticeData } from "./shared/usePracticeData.js";
import { usePracticeNavigation } from "./shared/usePracticeNavigation.js";
const { projects, done, overdue, savedDraft } = usePracticeData();
const { go } = usePracticeNavigation();
const route = useRoute();
const router = useRouter();
const pages = [
  {
    slug: "dashboard",
    title: "团队工作台",
    doc: "practiceDashboard",
    summary: "范围筛选、指标联动、待办完成与详情查看。",
  },
  {
    slug: "list",
    title: "查询列表页",
    doc: "practiceList",
    summary: "查询、重置、分页、选择、批量完成、新建与详情。",
  },
  {
    slug: "card",
    title: "项目卡片页",
    doc: "practiceCard",
    summary: "响应式项目空间、筛选、收藏、新建与详情。",
  },
  {
    slug: "detail",
    title: "业务详情页",
    doc: "practiceDetail",
    summary: "动态项目资料、交付任务、进度、跟进与可恢复归档。",
  },
  {
    slug: "form",
    title: "分步表单页",
    doc: "practiceForm",
    summary: "必填校验、草稿恢复、信息确认、失败重试与结果。",
  },
  {
    slug: "result",
    title: "结果与异常页",
    doc: "practiceResult",
    summary: "成功、服务失败、无权限、页面丢失和空结果。",
  },
];
function open(page) {
  router.push(
    `${route.path.startsWith("/en/") ? "/en" : ""}/practices/${page.slug}/`,
  );
}
</script>
<template>
  <c-space direction="column" block size="lg"
    ><c-page-header
      title="常用业务页面"
      subtitle="从查询、创建到处理与反馈，全部使用自有组件"
      :show-back="false"
    /><c-grid :cols="{ xs: 2, md: 4 }" :col-gap="16" :row-gap="16"
      ><c-grid-item
        ><c-card
          ><c-statistic
            title="在管项目"
            :value="projects.length" /></c-card></c-grid-item
      ><c-grid-item
        ><c-card
          ><c-statistic title="已交付" :value="done" /></c-card></c-grid-item
      ><c-grid-item
        ><c-card
          ><c-statistic
            title="逾期待处理"
            :value="overdue" /></c-card></c-grid-item
      ><c-grid-item
        ><c-card
          ><c-space direction="column"
            ><c-tag>{{ savedDraft ? "有未提交草稿" : "没有未提交草稿" }}</c-tag
            ><c-button @click="go('form')">{{
              savedDraft ? "继续填写草稿" : "创建第一份申请"
            }}</c-button></c-space
          ></c-card
        ></c-grid-item
      ></c-grid
    ><c-card
      ><c-typography-paragraph
        >以项目协作为同一业务背景，演示真实的查询、校验、取消、提交和恢复。所有页面共享项目台账与操作记录，刷新保留会话数据，归档可恢复。</c-typography-paragraph
      ></c-card
    ><c-grid
      style="width: 100%"
      :cols="{ xs: 1, md: 2 }"
      :col-gap="16"
      :row-gap="16"
      ><c-grid-item v-for="(page, index) in pages" :key="page.slug"
        ><c-card
          :title="page.title"
          :subtitle="'0' + (index + 1)"
          :description="page.summary"
          ><template #footer
            ><c-button status="primary" @click="open(page)"
              >打开{{ page.title }}</c-button
            ></template
          ></c-card
        ></c-grid-item
      ></c-grid
    ></c-space
  >
</template>
```

参考页面的信息分组与操作流程，界面全部由本库组件实现，不引入 Ant Design、Arco 或 TDesign 的组件和样式。

参考：[Ant Design 表单页面设计](https://ant.design/docs/spec/research-form/) · [Arco Design Pro](https://github.com/arco-design/arco-design-pro) · [TDesign Starter](https://tdesign.tencent.com/starter)。

---

Document: llms/zh-CN/practices/card.md

<!-- Source: docs/practices/card.md; locale: zh-CN; page: /practices/card/ -->

# 项目卡片页

收藏、组合筛选、项目计划和快速编辑。

## 完整业务体验

收藏项目，勾选“仅看收藏”并查询；进入完整详情后修改负责人或执行计划，再返回卡片或列表核对结果。

Example source: docs/practices/__demos__/card/basic.vue

```vue
<script setup>
import { computed, ref } from "vue";
import { usePracticeData, projectError } from "../shared/usePracticeData.js";
import { usePracticeNavigation } from "../shared/usePracticeNavigation.js";
const data = usePracticeData();
const {
  workspace,
  rows,
  projects,
  favorites,
  activity,
  savedDraft,
  latest,
  query,
  applied,
  current,
  selected,
  notice,
  statusOptions,
  categories,
  categoryOptions,
  priorities,
  filtered,
  pageRows,
  done,
  budget,
  overdue,
  active,
  detailOpen,
  createOpen,
  archiveOpen,
  editingKey,
  draft,
  fresh,
  search,
  clear,
  show,
  finish,
  finishSelected,
  startCreate,
  startEdit,
  create,
  requestArchive,
  confirmArchive,
  restore,
  favorite,
  reset,
  exportCsv,
} = data;
const { route, go, href } = usePracticeNavigation();
const required = [
  { required: true, whitespace: true, message: "此项不能为空" },
];
const money = (value) =>
  Number(value).toLocaleString("zh-CN", { maximumFractionDigits: 2 });
</script>
<template>
  <c-space class="practice-page" direction="column" block size="lg"
    ><c-page-header
      title="项目协作空间"
      subtitle="按业务类型发现项目，收藏与编辑在列表同步"
      :show-back="false"
      ><template #extra
        ><c-space wrap
          ><c-button status="primary" @click="startCreate"
            >快速新建</c-button
          ></c-space
        ></template
      ></c-page-header
    ><c-space wrap size="sm"
      ><c-button @click="go('dashboard')">工作台</c-button
      ><c-button @click="go('list')">项目列表</c-button
      ><c-button @click="go('card')">卡片视图</c-button
      ><c-button status="primary" @click="go('form')"
        >创建申请</c-button
      ></c-space
    ><c-typography-paragraph
      >本地演示工作区 ·
      各页面共享数据，刷新保留本次会话。归档可恢复，重置会还原整个工作区。</c-typography-paragraph
    ><c-card title="项目筛选"
      ><c-form :model="query" layout="vertical" @submit="search"
        ><c-grid :cols="{ xs: 1, md: 3 }" :col-gap="16" :row-gap="8"
          ><c-grid-item
            ><c-form-item label="关键词"
              ><c-input
                v-model="query.keyword"
                placeholder="项目、编号、负责人或类型"
                edit-mode="direct"
                clearable /></c-form-item></c-grid-item
          ><c-grid-item
            ><c-form-item label="项目状态"
              ><c-select
                v-model="query.status"
                :options="statusOptions"
                edit-mode="direct" /></c-form-item></c-grid-item
          ><c-grid-item
            ><c-form-item label="业务类型"
              ><c-select
                v-model="query.category"
                :options="categoryOptions"
                edit-mode="direct" /></c-form-item></c-grid-item></c-grid
        ><c-space wrap
          ><c-checkbox v-model="query.archived" edit-mode="direct"
            >查看已归档项目</c-checkbox
          ><c-checkbox v-model="query.favorites" edit-mode="direct"
            >仅看收藏</c-checkbox
          ><c-button html-type="submit" status="primary">查询项目</c-button
          ><c-button @click="clear">清空筛选</c-button></c-space
        ></c-form
      ></c-card
    ><c-typography-paragraph
      >共 {{ filtered.length }} 个项目 · 已收藏
      {{ favorites.length }} 个</c-typography-paragraph
    ><c-grid :cols="{ xs: 1, md: 2, xl: 3 }" :col-gap="16" :row-gap="16"
      ><c-grid-item v-for="row in filtered" :key="row.key"
        ><c-card
          :title="row.name"
          :subtitle="row.key"
          :description="row.owner + ' · ' + row.category"
          ><template #title-action
            ><c-tag :status="row.status === '已完成' ? 'success' : 'primary'">{{
              row.status
            }}</c-tag></template
          ><c-space direction="column" block
            ><c-typography-paragraph>{{
              row.description
            }}</c-typography-paragraph
            ><c-progress :percent="row.progress" /><c-tag
              >截止 {{ row.dueDate || "待安排" }} · 预算
              {{ money(row.budget) }} 元</c-tag
            ></c-space
          ><template #footer
            ><c-space wrap
              ><c-button
                status="primary"
                @click="go('detail', { project: row.key })"
                >进入项目</c-button
              ><c-button
                :aria-pressed="favorites.includes(row.key)"
                @click="favorite(row)"
                >{{
                  favorites.includes(row.key) ? "取消收藏" : "收藏项目"
                }}</c-button
              ><c-button v-if="!row.archived" @click="startEdit(row)"
                >编辑资料</c-button
              ><c-button v-else @click="restore(row)"
                >恢复项目</c-button
              ></c-space
            ></template
          ></c-card
        ></c-grid-item
      ></c-grid
    ><c-empty
      v-if="!filtered.length"
      description="暂无匹配项目，调整条件或新建项目"
    /><c-typography-paragraph role="status" aria-live="polite">{{
      notice
    }}</c-typography-paragraph
    ><c-dialog
      v-model:open="createOpen"
      :title="editingKey ? '编辑项目资料' : '快速创建项目'"
      :footer="false"
      :unmount-on-close="true"
      ><c-form :model="draft" layout="vertical" @submit="create"
        ><c-grid :cols="{ xs: 1, md: 2 }" :col-gap="16" :row-gap="8"
          ><c-grid-item
            ><c-form-item
              label="项目名称"
              field="name"
              :rules="required"
              feedback
              ><c-input
                v-model="draft.name"
                edit-mode="direct"
                placeholder="项目名称" /></c-form-item></c-grid-item
          ><c-grid-item
            ><c-form-item
              label="负责人"
              field="owner"
              :rules="required"
              feedback
              ><c-input
                v-model="draft.owner"
                edit-mode="direct"
                placeholder="负责人" /></c-form-item></c-grid-item
          ><c-grid-item
            ><c-form-item label="业务类型" field="category"
              ><c-select
                v-model="draft.category"
                :options="categories"
                edit-mode="direct" /></c-form-item></c-grid-item
          ><c-grid-item
            ><c-form-item label="优先级" field="priority"
              ><c-select
                v-model="draft.priority"
                :options="priorities"
                edit-mode="direct" /></c-form-item></c-grid-item
          ><c-grid-item
            ><c-form-item label="开始日期" field="startDate"
              ><c-date
                v-model="draft.startDate"
                value-format="YYYY-MM-DD"
                edit-mode="direct" /></c-form-item></c-grid-item
          ><c-grid-item
            ><c-form-item label="截止日期" field="dueDate"
              ><c-date
                v-model="draft.dueDate"
                value-format="YYYY-MM-DD"
                edit-mode="direct" /></c-form-item></c-grid-item
          ><c-grid-item
            ><c-form-item label="项目预算（元）" field="budget"
              ><c-input-number
                v-model="draft.budget"
                :min="0"
                :precision="2"
                edit-mode="direct" /></c-form-item></c-grid-item></c-grid
        ><c-form-item label="项目说明" field="description"
          ><c-textarea
            v-model="draft.description"
            edit-mode="direct"
            placeholder="项目目标、交付物和验收要求" /></c-form-item
        ><c-space wrap
          ><c-button html-type="submit" status="primary">{{
            editingKey ? "保存项目" : "创建项目"
          }}</c-button
          ><c-button @click="createOpen = false">取消</c-button></c-space
        ><c-typography-paragraph role="status" aria-live="polite">{{
          notice
        }}</c-typography-paragraph></c-form
      ></c-dialog
    ></c-space
  >
</template>
<style scoped>
.practice-page {
  width: 100%;
  min-width: 0;
}
.practice-page :deep(.c-grid-item) {
  min-width: 0;
}
.practice-page :deep(.c-grid) {
  width: 100%;
}
.practice-page :deep(.c-space__item) {
  min-width: 0;
}
</style>
```

## 实现与边界

页面的布局、字段、表格、卡片、弹层、反馈和分页全部使用 Cedar 自有组件。六类页面共享本地项目工作区；刷新保留本次浏览器会话的数据，归档可恢复，重置还原整个工作区。数据模型与行为在 `__demos__/shared/usePracticeData.js` 中，页面可按自身业务接入接口。

示例使用合成数据，不访问业务后端，不模拟服务端权限。CSV 导出只包含本地当前查询结果。

参考信息组织：[Ant Design 表单页面](https://ant.design/docs/spec/research-form/) · [Arco Design Pro](https://github.com/arco-design/arco-design-pro) · [TDesign Starter](https://tdesign.tencent.com/starter)。全部界面使用本库组件组合。

[最佳实践入口](llms/zh-CN/practices.md) · [特色与场景](llms/zh-CN/showcase.md)

---

Document: llms/zh-CN/practices/dashboard.md

<!-- Source: docs/practices/dashboard.md; locale: zh-CN; page: /practices/dashboard/ -->

# 团队工作台

按类型汇总项目指标、预算、待办与最近动态。

## 完整业务体验

选择业务范围，处理待办中的项目；再进入列表或详情，核对同一个项目的状态。创建、编辑、归档和跟进都会进入最近动态。

Example source: docs/practices/__demos__/dashboard/basic.vue

```vue
<script setup>
import { computed, ref } from "vue";
import { usePracticeData, projectError } from "../shared/usePracticeData.js";
import { usePracticeNavigation } from "../shared/usePracticeNavigation.js";
const data = usePracticeData();
const {
  workspace,
  rows,
  projects,
  favorites,
  activity,
  savedDraft,
  latest,
  query,
  applied,
  current,
  selected,
  notice,
  statusOptions,
  categories,
  categoryOptions,
  priorities,
  filtered,
  pageRows,
  done,
  budget,
  overdue,
  active,
  detailOpen,
  createOpen,
  archiveOpen,
  editingKey,
  draft,
  fresh,
  search,
  clear,
  show,
  finish,
  finishSelected,
  startCreate,
  startEdit,
  create,
  requestArchive,
  confirmArchive,
  restore,
  favorite,
  reset,
  exportCsv,
} = data;
const { route, go, href } = usePracticeNavigation();
const required = [
  { required: true, whitespace: true, message: "此项不能为空" },
];
const money = (value) =>
  Number(value).toLocaleString("zh-CN", { maximumFractionDigits: 2 });
const category = ref("全部");
const visible = computed(() =>
  projects.value.filter(
    (row) => category.value === "全部" || row.category === category.value,
  ),
);
const completed = computed(
  () => visible.value.filter((row) => row.status === "已完成").length,
);
const completion = computed(() =>
  visible.value.length
    ? Math.round((completed.value / visible.value.length) * 100)
    : 0,
);
const totalBudget = computed(() =>
  visible.value.reduce((sum, row) => sum + row.budget, 0),
);
const visibleEvents = computed(() =>
  activity.value
    .filter(
      (event) =>
        !event.project ||
        visible.value.some((row) => row.key === event.project),
    )
    .slice(0, 6),
);
const pending = computed(() =>
  visible.value.filter((row) => row.status !== "已完成").slice(0, 4),
);
const timeLabel = (value) => new Date(value).toLocaleString("zh-CN");
</script>
<template>
  <c-space class="practice-page" direction="column" block size="lg"
    ><c-page-header
      title="团队工作台"
      subtitle="一份项目数据驱动指标、待办、交付与操作动态"
      :show-back="false"
      ><template #extra
        ><c-space wrap
          ><c-button @click="reset">重置工作区</c-button></c-space
        ></template
      ></c-page-header
    ><c-space wrap size="sm"
      ><c-button @click="go('dashboard')">工作台</c-button
      ><c-button @click="go('list')">项目列表</c-button
      ><c-button @click="go('card')">卡片视图</c-button
      ><c-button status="primary" @click="go('form')"
        >创建申请</c-button
      ></c-space
    ><c-typography-paragraph
      >本地演示工作区 ·
      各页面共享数据，刷新保留本次会话。归档可恢复，重置会还原整个工作区。</c-typography-paragraph
    ><c-card title="业务概况"
      ><c-form layout="vertical"
        ><c-form-item label="业务范围"
          ><c-select
            v-model="category"
            :options="categoryOptions"
            edit-mode="direct" /></c-form-item></c-form
      ><c-grid :cols="{ xs: 2, md: 4 }" :col-gap="16" :row-gap="16"
        ><c-grid-item
          ><c-statistic
            title="范围内项目"
            :value="visible.length" /></c-grid-item
        ><c-grid-item
          ><c-statistic title="已交付项目" :value="completed" /></c-grid-item
        ><c-grid-item
          ><c-statistic
            title="预算（元）"
            :value="totalBudget"
            show-group-separator /></c-grid-item
        ><c-grid-item
          ><c-statistic
            title="交付完成率"
            :value="completion"
            suffix="%" /></c-grid-item></c-grid></c-card
    ><c-grid :cols="{ xs: 1, lg: 2 }" :col-gap="16" :row-gap="16"
      ><c-grid-item
        ><c-card title="我的待办"
          ><c-space direction="column" block
            ><c-card
              v-for="row in pending"
              :key="row.key"
              :title="row.name"
              :description="row.owner + ' · 截止 ' + row.dueDate"
              ><c-progress :percent="row.progress" /><template #footer
                ><c-space wrap
                  ><c-button @click="go('detail', { project: row.key })"
                    >处理项目</c-button
                  ><c-button @click="finish(row)">完成交付</c-button></c-space
                ></template
              ></c-card
            ><c-empty
              v-if="!pending.length"
              description="该范围内的项目均已交付" /></c-space></c-card></c-grid-item
      ><c-grid-item
        ><c-space direction="column" block
          ><c-card title="类型交付分布"
            ><c-space direction="column" block
              ><c-space
                v-for="item in categories"
                :key="item.value"
                direction="column"
                block
                ><c-typography-paragraph
                  >{{ item.label }} ·
                  {{
                    projects.filter(
                      (row) =>
                        row.category === item.value && row.status === "已完成",
                    ).length
                  }}
                  /
                  {{
                    projects.filter((row) => row.category === item.value).length
                  }}
                  已完成</c-typography-paragraph
                ><c-progress
                  :percent="
                    projects.filter((row) => row.category === item.value).length
                      ? Math.round(
                          (projects.filter(
                            (row) =>
                              row.category === item.value &&
                              row.status === '已完成',
                          ).length /
                            projects.filter(
                              (row) => row.category === item.value,
                            ).length) *
                            100,
                        )
                      : 0
                  " /></c-space></c-space></c-card
          ><c-card title="最近动态"
            ><c-space direction="column" block
              ><c-typography-paragraph
                v-for="event in visibleEvents"
                :key="event.key"
                >{{ timeLabel(event.at) }} ·
                {{ event.text }}</c-typography-paragraph
              ><c-empty
                v-if="!visibleEvents.length"
                description="暂无操作记录" /></c-space></c-card></c-space></c-grid-item></c-grid
    ><c-typography-paragraph role="status" aria-live="polite">{{
      notice
    }}</c-typography-paragraph></c-space
  >
</template>
<style scoped>
.practice-page {
  width: 100%;
  min-width: 0;
}
.practice-page :deep(.c-grid-item) {
  min-width: 0;
}
.practice-page :deep(.c-grid) {
  width: 100%;
}
.practice-page :deep(.c-space__item) {
  min-width: 0;
}
</style>
```

## 实现与边界

页面的布局、字段、表格、卡片、弹层、反馈和分页全部使用 Cedar 自有组件。六类页面共享本地项目工作区；刷新保留本次浏览器会话的数据，归档可恢复，重置还原整个工作区。数据模型与行为在 `__demos__/shared/usePracticeData.js` 中，页面可按自身业务接入接口。

示例使用合成数据，不访问业务后端，不模拟服务端权限。CSV 导出只包含本地当前查询结果。

参考信息组织：[Ant Design 表单页面](https://ant.design/docs/spec/research-form/) · [Arco Design Pro](https://github.com/arco-design/arco-design-pro) · [TDesign Starter](https://tdesign.tencent.com/starter)。全部界面使用本库组件组合。

[最佳实践入口](llms/zh-CN/practices.md) · [特色与场景](llms/zh-CN/showcase.md)

---

Document: llms/zh-CN/practices/description.md

<!-- Source: docs/practices/description.md; locale: zh-CN; page: /practices/description/ -->

# 详情信息组织

详情页面按“对象身份与主要操作 → 流程进度 → 基本信息 → 操作记录”组织。使用自有 PageHeader、Steps、Tabs、Descriptions 和 Card。

Example source: docs/practices/__demos__/detail/basic.vue

```vue
<script setup>
import { computed, ref } from "vue";
import { usePracticeData, projectError } from "../shared/usePracticeData.js";
import { usePracticeNavigation } from "../shared/usePracticeNavigation.js";
const data = usePracticeData();
const {
  workspace,
  rows,
  projects,
  favorites,
  activity,
  savedDraft,
  latest,
  query,
  applied,
  current,
  selected,
  notice,
  statusOptions,
  categories,
  categoryOptions,
  priorities,
  filtered,
  pageRows,
  done,
  budget,
  overdue,
  active,
  detailOpen,
  createOpen,
  archiveOpen,
  editingKey,
  draft,
  fresh,
  search,
  clear,
  show,
  finish,
  finishSelected,
  startCreate,
  startEdit,
  create,
  requestArchive,
  confirmArchive,
  restore,
  favorite,
  reset,
  exportCsv,
} = data;
const { route, go, href } = usePracticeNavigation();
const required = [
  { required: true, whitespace: true, message: "此项不能为空" },
];
const money = (value) =>
  Number(value).toLocaleString("zh-CN", { maximumFractionDigits: 2 });
const project = computed(() =>
  rows.value.find(
    (row) => row.key === (route.query.project || projects.value[0]?.key),
  ),
);
const noteText = ref("");
const projectEvents = computed(() =>
  activity.value.filter((event) => event.project === project.value?.key),
);
const info = computed(() =>
  project.value
    ? [
        { label: "项目编号", value: project.value.key },
        { label: "负责人", value: project.value.owner },
        { label: "业务类型", value: project.value.category },
        { label: "优先级", value: project.value.priority },
        { label: "开始日期", value: project.value.startDate },
        { label: "截止日期", value: project.value.dueDate },
        { label: "预算", value: money(project.value.budget) + " 元" },
        {
          label: "当前状态",
          value: project.value.archived ? "已归档" : project.value.status,
        },
      ]
    : [],
);
function addNote() {
  if (workspace.note(project.value, noteText.value)) {
    noteText.value = "";
    notice.value = "跟进已添加到项目记录和工作台动态。";
  }
}
const timeLabel = (value) => new Date(value).toLocaleString("zh-CN");
</script>
<template>
  <c-space class="practice-page" direction="column" block size="lg"
    ><c-result
      v-if="!project"
      status="404"
      title="项目不存在"
      subtitle="该项目可能已重置或编号无效"
      ><template #extra
        ><c-button @click="go('list')">返回项目列表</c-button></template
      ></c-result
    ><template v-else
      ><c-page-header
        title="项目业务详情"
        subtitle="项目资料、任务清单和操作记录在所有页面同步"
        :show-back="false"
        ><template #extra
          ><c-space wrap
            ><c-button v-if="!project.archived" @click="startEdit(project)"
              >编辑项目</c-button
            ><c-button
              v-if="!project.archived"
              :disabled="project.status === '已完成'"
              status="primary"
              @click="finish(project)"
              >完成交付</c-button
            ><c-button v-if="project.archived" @click="restore(project)"
              >恢复项目</c-button
            ><c-button v-else @click="requestArchive([project.key])"
              >归档项目</c-button
            ></c-space
          ></template
        ></c-page-header
      ><c-space wrap size="sm"
        ><c-button @click="go('dashboard')">工作台</c-button
        ><c-button @click="go('list')">项目列表</c-button
        ><c-button @click="go('card')">卡片视图</c-button
        ><c-button status="primary" @click="go('form')"
          >创建申请</c-button
        ></c-space
      ><c-card
        :title="project.name"
        :subtitle="project.key"
        :description="project.description"
        ><template #title-action
          ><c-tag>{{
            project.archived ? "已归档" : project.status
          }}</c-tag></template
        ><c-progress :percent="project.progress" /><c-steps
          :model-value="
            project.status === '已完成'
              ? 3
              : project.status === '进行中'
                ? 2
                : 1
          "
          ><c-step>项目创建</c-step><c-step>执行交付</c-step
          ><c-step>交付完成</c-step></c-steps
        ></c-card
      ><c-tabs default-value="info"
        ><c-tab-pane name="info" title="基本资料"
          ><c-card title="项目资料"
            ><c-descriptions
              :data="info"
              :column="{ xs: 1, md: 2 }"
              bordered /></c-card></c-tab-pane
        ><c-tab-pane name="tasks" title="任务清单"
          ><c-card title="交付任务"
            ><c-space direction="column" block
              ><c-checkbox
                v-for="task in project.tasks"
                :key="task.key"
                :model-value="task.done"
                :disabled="project.archived"
                @update:model-value="
                  (checked) => workspace.toggleTask(project, task.key, checked)
                "
                >{{ task.title }}</c-checkbox
              ></c-space
            ></c-card
          ></c-tab-pane
        ><c-tab-pane name="history" title="操作记录"
          ><c-card title="项目动态"
            ><c-space direction="column" block
              ><c-typography-paragraph
                v-for="event in projectEvents"
                :key="event.key"
                >{{ timeLabel(event.at) }} ·
                {{ event.text }}</c-typography-paragraph
              ><c-empty
                v-if="!projectEvents.length"
                description="项目尚无新增记录" /></c-space></c-card></c-tab-pane></c-tabs
      ><c-card title="新增跟进"
        ><c-form layout="vertical"
          ><c-form-item label="跟进内容"
            ><c-textarea
              v-model="noteText"
              placeholder="记录当前进展、风险或下一步计划"
              :disabled="project.archived"
              edit-mode="direct" /></c-form-item></c-form
        ><c-button
          status="primary"
          :disabled="!noteText.trim() || project.archived"
          @click="addNote"
          >添加跟进</c-button
        ></c-card
      ><c-typography-paragraph role="status" aria-live="polite">{{
        notice
      }}</c-typography-paragraph
      ><c-dialog
        v-model:open="createOpen"
        :title="editingKey ? '编辑项目资料' : '快速创建项目'"
        :footer="false"
        :unmount-on-close="true"
        ><c-form :model="draft" layout="vertical" @submit="create"
          ><c-grid :cols="{ xs: 1, md: 2 }" :col-gap="16" :row-gap="8"
            ><c-grid-item
              ><c-form-item
                label="项目名称"
                field="name"
                :rules="required"
                feedback
                ><c-input
                  v-model="draft.name"
                  edit-mode="direct"
                  placeholder="项目名称" /></c-form-item></c-grid-item
            ><c-grid-item
              ><c-form-item
                label="负责人"
                field="owner"
                :rules="required"
                feedback
                ><c-input
                  v-model="draft.owner"
                  edit-mode="direct"
                  placeholder="负责人" /></c-form-item></c-grid-item
            ><c-grid-item
              ><c-form-item label="业务类型" field="category"
                ><c-select
                  v-model="draft.category"
                  :options="categories"
                  edit-mode="direct" /></c-form-item></c-grid-item
            ><c-grid-item
              ><c-form-item label="优先级" field="priority"
                ><c-select
                  v-model="draft.priority"
                  :options="priorities"
                  edit-mode="direct" /></c-form-item></c-grid-item
            ><c-grid-item
              ><c-form-item label="开始日期" field="startDate"
                ><c-date
                  v-model="draft.startDate"
                  value-format="YYYY-MM-DD"
                  edit-mode="direct" /></c-form-item></c-grid-item
            ><c-grid-item
              ><c-form-item label="截止日期" field="dueDate"
                ><c-date
                  v-model="draft.dueDate"
                  value-format="YYYY-MM-DD"
                  edit-mode="direct" /></c-form-item></c-grid-item
            ><c-grid-item
              ><c-form-item label="项目预算（元）" field="budget"
                ><c-input-number
                  v-model="draft.budget"
                  :min="0"
                  :precision="2"
                  edit-mode="direct" /></c-form-item></c-grid-item></c-grid
          ><c-form-item label="项目说明" field="description"
            ><c-textarea
              v-model="draft.description"
              edit-mode="direct"
              placeholder="项目目标、交付物和验收要求" /></c-form-item
          ><c-space wrap
            ><c-button html-type="submit" status="primary">{{
              editingKey ? "保存项目" : "创建项目"
            }}</c-button
            ><c-button @click="createOpen = false">取消</c-button></c-space
          ><c-typography-paragraph role="status" aria-live="polite">{{
            notice
          }}</c-typography-paragraph></c-form
        ></c-dialog
      ><c-dialog v-model:open="archiveOpen" title="确认归档项目" :footer="false"
        ><c-space direction="column" block
          ><c-typography-paragraph
            >将归档所选项目。项目、任务和操作记录会保留，可在“已归档”筛选中恢复。</c-typography-paragraph
          ><c-space wrap
            ><c-button status="warning" @click="confirmArchive"
              >确认归档</c-button
            ><c-button @click="archiveOpen = false">取消归档</c-button></c-space
          ></c-space
        ></c-dialog
      ></template
    ></c-space
  >
</template>
<style scoped>
.practice-page {
  width: 100%;
  min-width: 0;
}
.practice-page :deep(.c-grid-item) {
  min-width: 0;
}
.practice-page :deep(.c-grid) {
  width: 100%;
}
.practice-page :deep(.c-space__item) {
  min-width: 0;
}
</style>
```

[业务详情页](llms/zh-CN/practices/detail.md) · [最佳实践总览](llms/zh-CN/practices.md)

---

Document: llms/zh-CN/practices/detail.md

<!-- Source: docs/practices/detail.md; locale: zh-CN; page: /practices/detail/ -->

# 业务详情页

动态项目资料、任务清单、交付进度、跟进、操作记录与归档。

## 完整业务体验

从列表或卡片进入一个具体项目；编辑资料后取消，确认原值未变；保存编辑、完成任务并添加跟进，再到工作台查看操作动态。

Example source: docs/practices/__demos__/detail/basic.vue

```vue
<script setup>
import { computed, ref } from "vue";
import { usePracticeData, projectError } from "../shared/usePracticeData.js";
import { usePracticeNavigation } from "../shared/usePracticeNavigation.js";
const data = usePracticeData();
const {
  workspace,
  rows,
  projects,
  favorites,
  activity,
  savedDraft,
  latest,
  query,
  applied,
  current,
  selected,
  notice,
  statusOptions,
  categories,
  categoryOptions,
  priorities,
  filtered,
  pageRows,
  done,
  budget,
  overdue,
  active,
  detailOpen,
  createOpen,
  archiveOpen,
  editingKey,
  draft,
  fresh,
  search,
  clear,
  show,
  finish,
  finishSelected,
  startCreate,
  startEdit,
  create,
  requestArchive,
  confirmArchive,
  restore,
  favorite,
  reset,
  exportCsv,
} = data;
const { route, go, href } = usePracticeNavigation();
const required = [
  { required: true, whitespace: true, message: "此项不能为空" },
];
const money = (value) =>
  Number(value).toLocaleString("zh-CN", { maximumFractionDigits: 2 });
const project = computed(() =>
  rows.value.find(
    (row) => row.key === (route.query.project || projects.value[0]?.key),
  ),
);
const noteText = ref("");
const projectEvents = computed(() =>
  activity.value.filter((event) => event.project === project.value?.key),
);
const info = computed(() =>
  project.value
    ? [
        { label: "项目编号", value: project.value.key },
        { label: "负责人", value: project.value.owner },
        { label: "业务类型", value: project.value.category },
        { label: "优先级", value: project.value.priority },
        { label: "开始日期", value: project.value.startDate },
        { label: "截止日期", value: project.value.dueDate },
        { label: "预算", value: money(project.value.budget) + " 元" },
        {
          label: "当前状态",
          value: project.value.archived ? "已归档" : project.value.status,
        },
      ]
    : [],
);
function addNote() {
  if (workspace.note(project.value, noteText.value)) {
    noteText.value = "";
    notice.value = "跟进已添加到项目记录和工作台动态。";
  }
}
const timeLabel = (value) => new Date(value).toLocaleString("zh-CN");
</script>
<template>
  <c-space class="practice-page" direction="column" block size="lg"
    ><c-result
      v-if="!project"
      status="404"
      title="项目不存在"
      subtitle="该项目可能已重置或编号无效"
      ><template #extra
        ><c-button @click="go('list')">返回项目列表</c-button></template
      ></c-result
    ><template v-else
      ><c-page-header
        title="项目业务详情"
        subtitle="项目资料、任务清单和操作记录在所有页面同步"
        :show-back="false"
        ><template #extra
          ><c-space wrap
            ><c-button v-if="!project.archived" @click="startEdit(project)"
              >编辑项目</c-button
            ><c-button
              v-if="!project.archived"
              :disabled="project.status === '已完成'"
              status="primary"
              @click="finish(project)"
              >完成交付</c-button
            ><c-button v-if="project.archived" @click="restore(project)"
              >恢复项目</c-button
            ><c-button v-else @click="requestArchive([project.key])"
              >归档项目</c-button
            ></c-space
          ></template
        ></c-page-header
      ><c-space wrap size="sm"
        ><c-button @click="go('dashboard')">工作台</c-button
        ><c-button @click="go('list')">项目列表</c-button
        ><c-button @click="go('card')">卡片视图</c-button
        ><c-button status="primary" @click="go('form')"
          >创建申请</c-button
        ></c-space
      ><c-card
        :title="project.name"
        :subtitle="project.key"
        :description="project.description"
        ><template #title-action
          ><c-tag>{{
            project.archived ? "已归档" : project.status
          }}</c-tag></template
        ><c-progress :percent="project.progress" /><c-steps
          :model-value="
            project.status === '已完成'
              ? 3
              : project.status === '进行中'
                ? 2
                : 1
          "
          ><c-step>项目创建</c-step><c-step>执行交付</c-step
          ><c-step>交付完成</c-step></c-steps
        ></c-card
      ><c-tabs default-value="info"
        ><c-tab-pane name="info" title="基本资料"
          ><c-card title="项目资料"
            ><c-descriptions
              :data="info"
              :column="{ xs: 1, md: 2 }"
              bordered /></c-card></c-tab-pane
        ><c-tab-pane name="tasks" title="任务清单"
          ><c-card title="交付任务"
            ><c-space direction="column" block
              ><c-checkbox
                v-for="task in project.tasks"
                :key="task.key"
                :model-value="task.done"
                :disabled="project.archived"
                @update:model-value="
                  (checked) => workspace.toggleTask(project, task.key, checked)
                "
                >{{ task.title }}</c-checkbox
              ></c-space
            ></c-card
          ></c-tab-pane
        ><c-tab-pane name="history" title="操作记录"
          ><c-card title="项目动态"
            ><c-space direction="column" block
              ><c-typography-paragraph
                v-for="event in projectEvents"
                :key="event.key"
                >{{ timeLabel(event.at) }} ·
                {{ event.text }}</c-typography-paragraph
              ><c-empty
                v-if="!projectEvents.length"
                description="项目尚无新增记录" /></c-space></c-card></c-tab-pane></c-tabs
      ><c-card title="新增跟进"
        ><c-form layout="vertical"
          ><c-form-item label="跟进内容"
            ><c-textarea
              v-model="noteText"
              placeholder="记录当前进展、风险或下一步计划"
              :disabled="project.archived"
              edit-mode="direct" /></c-form-item></c-form
        ><c-button
          status="primary"
          :disabled="!noteText.trim() || project.archived"
          @click="addNote"
          >添加跟进</c-button
        ></c-card
      ><c-typography-paragraph role="status" aria-live="polite">{{
        notice
      }}</c-typography-paragraph
      ><c-dialog
        v-model:open="createOpen"
        :title="editingKey ? '编辑项目资料' : '快速创建项目'"
        :footer="false"
        :unmount-on-close="true"
        ><c-form :model="draft" layout="vertical" @submit="create"
          ><c-grid :cols="{ xs: 1, md: 2 }" :col-gap="16" :row-gap="8"
            ><c-grid-item
              ><c-form-item
                label="项目名称"
                field="name"
                :rules="required"
                feedback
                ><c-input
                  v-model="draft.name"
                  edit-mode="direct"
                  placeholder="项目名称" /></c-form-item></c-grid-item
            ><c-grid-item
              ><c-form-item
                label="负责人"
                field="owner"
                :rules="required"
                feedback
                ><c-input
                  v-model="draft.owner"
                  edit-mode="direct"
                  placeholder="负责人" /></c-form-item></c-grid-item
            ><c-grid-item
              ><c-form-item label="业务类型" field="category"
                ><c-select
                  v-model="draft.category"
                  :options="categories"
                  edit-mode="direct" /></c-form-item></c-grid-item
            ><c-grid-item
              ><c-form-item label="优先级" field="priority"
                ><c-select
                  v-model="draft.priority"
                  :options="priorities"
                  edit-mode="direct" /></c-form-item></c-grid-item
            ><c-grid-item
              ><c-form-item label="开始日期" field="startDate"
                ><c-date
                  v-model="draft.startDate"
                  value-format="YYYY-MM-DD"
                  edit-mode="direct" /></c-form-item></c-grid-item
            ><c-grid-item
              ><c-form-item label="截止日期" field="dueDate"
                ><c-date
                  v-model="draft.dueDate"
                  value-format="YYYY-MM-DD"
                  edit-mode="direct" /></c-form-item></c-grid-item
            ><c-grid-item
              ><c-form-item label="项目预算（元）" field="budget"
                ><c-input-number
                  v-model="draft.budget"
                  :min="0"
                  :precision="2"
                  edit-mode="direct" /></c-form-item></c-grid-item></c-grid
          ><c-form-item label="项目说明" field="description"
            ><c-textarea
              v-model="draft.description"
              edit-mode="direct"
              placeholder="项目目标、交付物和验收要求" /></c-form-item
          ><c-space wrap
            ><c-button html-type="submit" status="primary">{{
              editingKey ? "保存项目" : "创建项目"
            }}</c-button
            ><c-button @click="createOpen = false">取消</c-button></c-space
          ><c-typography-paragraph role="status" aria-live="polite">{{
            notice
          }}</c-typography-paragraph></c-form
        ></c-dialog
      ><c-dialog v-model:open="archiveOpen" title="确认归档项目" :footer="false"
        ><c-space direction="column" block
          ><c-typography-paragraph
            >将归档所选项目。项目、任务和操作记录会保留，可在“已归档”筛选中恢复。</c-typography-paragraph
          ><c-space wrap
            ><c-button status="warning" @click="confirmArchive"
              >确认归档</c-button
            ><c-button @click="archiveOpen = false">取消归档</c-button></c-space
          ></c-space
        ></c-dialog
      ></template
    ></c-space
  >
</template>
<style scoped>
.practice-page {
  width: 100%;
  min-width: 0;
}
.practice-page :deep(.c-grid-item) {
  min-width: 0;
}
.practice-page :deep(.c-grid) {
  width: 100%;
}
.practice-page :deep(.c-space__item) {
  min-width: 0;
}
</style>
```

## 实现与边界

页面的布局、字段、表格、卡片、弹层、反馈和分页全部使用 Cedar 自有组件。六类页面共享本地项目工作区；刷新保留本次浏览器会话的数据，归档可恢复，重置还原整个工作区。数据模型与行为在 `__demos__/shared/usePracticeData.js` 中，页面可按自身业务接入接口。

示例使用合成数据，不访问业务后端，不模拟服务端权限。CSV 导出只包含本地当前查询结果。

参考信息组织：[Ant Design 表单页面](https://ant.design/docs/spec/research-form/) · [Arco Design Pro](https://github.com/arco-design/arco-design-pro) · [TDesign Starter](https://tdesign.tencent.com/starter)。全部界面使用本库组件组合。

[最佳实践入口](llms/zh-CN/practices.md) · [特色与场景](llms/zh-CN/showcase.md)

---

Document: llms/zh-CN/practices/form.md

<!-- Source: docs/practices/form.md; locale: zh-CN; page: /practices/form/ -->

# 分步表单页

基础资料、计划预算、核对提交、办理结果四阶段。

## 完整业务体验

先提交空资料查看校验；填写名称和负责人，设置计划与预算。保存草稿后离开并回来恢复；确认页模拟失败并重试，成功后点击“查看项目详情”。新项目同时进入列表、卡片和工作台。

Example source: docs/practices/__demos__/form/basic.vue

```vue
<script setup>
import { computed, ref } from "vue";
import { usePracticeData, projectError } from "../shared/usePracticeData.js";
import { usePracticeNavigation } from "../shared/usePracticeNavigation.js";
const data = usePracticeData();
const {
  workspace,
  rows,
  projects,
  favorites,
  activity,
  savedDraft,
  latest,
  query,
  applied,
  current,
  selected,
  notice,
  statusOptions,
  categories,
  categoryOptions,
  priorities,
  filtered,
  pageRows,
  done,
  budget,
  overdue,
  active,
  detailOpen,
  createOpen,
  archiveOpen,
  editingKey,
  draft,
  fresh,
  search,
  clear,
  show,
  finish,
  finishSelected,
  startCreate,
  startEdit,
  create,
  requestArchive,
  confirmArchive,
  restore,
  favorite,
  reset,
  exportCsv,
} = data;
const { route, go, href } = usePracticeNavigation();
const required = [
  { required: true, whitespace: true, message: "此项不能为空" },
];
const money = (value) =>
  Number(value).toLocaleString("zh-CN", { maximumFractionDigits: 2 });
const step = ref(0);
const failNext = ref(false);
const committed = ref(null);
const formMessage = ref(
  savedDraft.value
    ? "存在可恢复草稿，可先恢复继续办理。"
    : "填写基础信息后，设置计划与预算，再核对提交。",
);
function next({ errors } = {}) {
  if (errors) {
    formMessage.value = "请补全必填项。";
    return;
  }
  if (step.value === 1 && projectError(draft.value)) {
    formMessage.value = projectError(draft.value);
    return;
  }
  step.value++;
  formMessage.value =
    step.value === 2
      ? "请确认全部资料，返回修改不会生成项目。"
      : "设置项目执行计划。";
}
function saveDraft() {
  savedDraft.value = JSON.parse(JSON.stringify(draft.value));
  formMessage.value = "草稿已保存，切换页面或刷新后仍可恢复。";
}
function restoreDraft() {
  if (savedDraft.value) {
    draft.value = JSON.parse(JSON.stringify(savedDraft.value));
    step.value = 0;
    formMessage.value = "已恢复上次保存的草稿。";
  }
}
function submit() {
  if (failNext.value) {
    failNext.value = false;
    formMessage.value = "模拟保存失败，草稿已保留，请重试提交。";
    return;
  }
  const row = workspace.save(draft.value);
  if (!row) {
    formMessage.value = projectError(draft.value);
    return;
  }
  committed.value = row;
  savedDraft.value = null;
  step.value = 3;
  formMessage.value = "项目已创建，列表、卡片和工作台已同步。";
}
function resetForm() {
  step.value = 0;
  draft.value = fresh();
  committed.value = null;
  failNext.value = false;
  formMessage.value = "已清空当前表单，工作区里的项目不受影响。";
}
</script>
<template>
  <c-space class="practice-page" direction="column" block size="lg"
    ><c-page-header
      title="创建项目申请"
      subtitle="基础资料 → 计划预算 → 核对提交 → 办理完成"
      :show-back="false"
      ><template #extra
        ><c-space wrap
          ><c-button @click="resetForm">清空当前表单</c-button></c-space
        ></template
      ></c-page-header
    ><c-space wrap size="sm"
      ><c-button @click="go('dashboard')">工作台</c-button
      ><c-button @click="go('list')">项目列表</c-button
      ><c-button @click="go('card')">卡片视图</c-button
      ><c-button status="primary" @click="go('form')"
        >创建申请</c-button
      ></c-space
    ><c-card
      ><c-steps :model-value="step + 1"
        ><c-step>基础资料</c-step><c-step>计划预算</c-step
        ><c-step>核对提交</c-step><c-step>办理完成</c-step></c-steps
      ></c-card
    ><c-card v-if="step === 0" title="基础资料"
      ><c-form :model="draft" layout="vertical" @submit="next"
        ><c-grid :cols="{ xs: 1, md: 2 }" :col-gap="16" :row-gap="8"
          ><c-grid-item
            ><c-form-item
              label="项目名称"
              field="name"
              :rules="required"
              feedback
              ><c-input
                v-model="draft.name"
                edit-mode="direct"
                placeholder="项目名称" /></c-form-item></c-grid-item
          ><c-grid-item
            ><c-form-item
              label="负责人"
              field="owner"
              :rules="required"
              feedback
              ><c-input
                v-model="draft.owner"
                edit-mode="direct"
                placeholder="负责人" /></c-form-item></c-grid-item
          ><c-grid-item
            ><c-form-item label="业务类型" field="category"
              ><c-select
                v-model="draft.category"
                :options="categories"
                edit-mode="direct" /></c-form-item></c-grid-item
          ><c-grid-item
            ><c-form-item label="优先级" field="priority"
              ><c-select
                v-model="draft.priority"
                :options="priorities"
                edit-mode="direct" /></c-form-item></c-grid-item></c-grid
        ><c-space wrap
          ><c-button html-type="submit" status="primary"
            >下一步：计划预算</c-button
          ><c-button @click="saveDraft">保存草稿</c-button
          ><c-button :disabled="!savedDraft" @click="restoreDraft"
            >恢复草稿</c-button
          ></c-space
        ></c-form
      ></c-card
    ><c-card v-else-if="step === 1" title="计划与预算"
      ><c-form :model="draft" layout="vertical" @submit="next"
        ><c-grid :cols="{ xs: 1, md: 2 }" :col-gap="16" :row-gap="8"
          ><c-grid-item
            ><c-form-item label="开始日期" field="startDate"
              ><c-date
                v-model="draft.startDate"
                value-format="YYYY-MM-DD"
                edit-mode="direct" /></c-form-item></c-grid-item
          ><c-grid-item
            ><c-form-item label="截止日期" field="dueDate"
              ><c-date
                v-model="draft.dueDate"
                value-format="YYYY-MM-DD"
                edit-mode="direct" /></c-form-item></c-grid-item
          ><c-grid-item
            ><c-form-item label="项目预算（元）" field="budget"
              ><c-input-number
                v-model="draft.budget"
                :min="0"
                :precision="2"
                edit-mode="direct" /></c-form-item></c-grid-item></c-grid
        ><c-form-item label="项目说明" field="description"
          ><c-textarea
            v-model="draft.description"
            edit-mode="direct"
            placeholder="项目目标、交付物和验收要求" /></c-form-item
        ><c-space wrap
          ><c-button html-type="submit" status="primary"
            >下一步：核对提交</c-button
          ><c-button @click="step = 0">上一步</c-button
          ><c-button @click="saveDraft">保存草稿</c-button></c-space
        ></c-form
      ></c-card
    ><c-card v-else-if="step === 2" title="核对项目申请"
      ><c-space direction="column" block
        ><c-typography-paragraph
          >项目：{{ draft.name }} · 负责人：{{
            draft.owner
          }}</c-typography-paragraph
        ><c-typography-paragraph
          >类型：{{ draft.category }} · 优先级：{{ draft.priority }} · 预算：{{
            money(draft.budget)
          }}
          元</c-typography-paragraph
        ><c-typography-paragraph
          >执行计划：{{ draft.startDate || "待安排" }} 至
          {{ draft.dueDate || "待安排" }}</c-typography-paragraph
        ><c-typography-paragraph
          >项目说明：{{ draft.description || "未填写" }}</c-typography-paragraph
        ><c-checkbox v-model="failNext">模拟本次提交失败</c-checkbox
        ><c-space wrap
          ><c-button status="primary" @click="submit">{{
            formMessage.includes("失败") ? "重试提交" : "确认创建项目"
          }}</c-button
          ><c-button @click="step = 0">返回修改</c-button></c-space
        ></c-space
      ></c-card
    ><c-card v-else
      ><c-result
        status="success"
        title="项目已创建"
        :subtitle="committed.key + ' · ' + committed.name"
        ><template #extra
          ><c-space wrap
            ><c-button
              status="primary"
              @click="go('detail', { project: committed.key })"
              >查看项目详情</c-button
            ><c-button @click="go('list')">返回项目列表</c-button
            ><c-button @click="resetForm">继续创建</c-button></c-space
          ></template
        ></c-result
      ></c-card
    ><c-typography-paragraph role="status" aria-live="polite">{{
      formMessage
    }}</c-typography-paragraph></c-space
  >
</template>
<style scoped>
.practice-page {
  width: 100%;
  min-width: 0;
}
.practice-page :deep(.c-grid-item) {
  min-width: 0;
}
.practice-page :deep(.c-grid) {
  width: 100%;
}
.practice-page :deep(.c-space__item) {
  min-width: 0;
}
</style>
```

## 实现与边界

页面的布局、字段、表格、卡片、弹层、反馈和分页全部使用 Cedar 自有组件。六类页面共享本地项目工作区；刷新保留本次浏览器会话的数据，归档可恢复，重置还原整个工作区。数据模型与行为在 `__demos__/shared/usePracticeData.js` 中，页面可按自身业务接入接口。

示例使用合成数据，不访问业务后端，不模拟服务端权限。CSV 导出只包含本地当前查询结果。

参考信息组织：[Ant Design 表单页面](https://ant.design/docs/spec/research-form/) · [Arco Design Pro](https://github.com/arco-design/arco-design-pro) · [TDesign Starter](https://tdesign.tencent.com/starter)。全部界面使用本库组件组合。

[最佳实践入口](llms/zh-CN/practices.md) · [特色与场景](llms/zh-CN/showcase.md)

---

Document: llms/zh-CN/practices/list.md

<!-- Source: docs/practices/list.md; locale: zh-CN; page: /practices/list/ -->

# 查询列表页

组合筛选、分页、编辑、交付、批量归档、恢复与 CSV 导出。

## 完整业务体验

按关键词、类型和状态组合查询；编辑项目后查看详情；归档所选项目，再勾选“查看已归档项目”并查询，恢复记录。导出的是当前筛选结果。

Example source: docs/practices/__demos__/list/basic.vue

```vue
<script setup>
import { computed, ref } from "vue";
import { usePracticeData, projectError } from "../shared/usePracticeData.js";
import { usePracticeNavigation } from "../shared/usePracticeNavigation.js";
const data = usePracticeData();
const {
  workspace,
  rows,
  projects,
  favorites,
  activity,
  savedDraft,
  latest,
  query,
  applied,
  current,
  selected,
  notice,
  statusOptions,
  categories,
  categoryOptions,
  priorities,
  filtered,
  pageRows,
  done,
  budget,
  overdue,
  active,
  detailOpen,
  createOpen,
  archiveOpen,
  editingKey,
  draft,
  fresh,
  search,
  clear,
  show,
  finish,
  finishSelected,
  startCreate,
  startEdit,
  create,
  requestArchive,
  confirmArchive,
  restore,
  favorite,
  reset,
  exportCsv,
} = data;
const { route, go, href } = usePracticeNavigation();
const required = [
  { required: true, whitespace: true, message: "此项不能为空" },
];
const money = (value) =>
  Number(value).toLocaleString("zh-CN", { maximumFractionDigits: 2 });
const columns = [
  { title: "项目 / 编号", slotName: "project" },
  { title: "负责人", dataIndex: "owner" },
  { title: "进度与状态", slotName: "state" },
  { title: "预算", slotName: "budget" },
  { title: "截止日期", dataIndex: "dueDate" },
  { title: "操作", slotName: "actions" },
];
</script>
<template>
  <c-space class="practice-page" direction="column" block size="lg"
    ><c-page-header
      title="项目管理"
      subtitle="统一查询、编辑、交付与归档的项目台账"
      :show-back="false"
      ><template #extra
        ><c-space wrap
          ><c-button @click="exportCsv">导出查询结果</c-button
          ><c-button @click="reset">重置工作区</c-button
          ><c-button status="primary" @click="startCreate"
            >快速新建</c-button
          ></c-space
        ></template
      ></c-page-header
    ><c-space wrap size="sm"
      ><c-button @click="go('dashboard')">工作台</c-button
      ><c-button @click="go('list')">项目列表</c-button
      ><c-button @click="go('card')">卡片视图</c-button
      ><c-button status="primary" @click="go('form')"
        >创建申请</c-button
      ></c-space
    ><c-typography-paragraph
      >本地演示工作区 ·
      各页面共享数据，刷新保留本次会话。归档可恢复，重置会还原整个工作区。</c-typography-paragraph
    ><c-grid :cols="{ xs: 2, md: 4 }" :col-gap="16" :row-gap="16"
      ><c-grid-item
        ><c-card
          ><c-statistic
            title="在管项目"
            :value="projects.length" /></c-card></c-grid-item
      ><c-grid-item
        ><c-card
          ><c-statistic title="已交付" :value="done" /></c-card></c-grid-item
      ><c-grid-item
        ><c-card
          ><c-statistic
            title="逾期待处理"
            :value="overdue" /></c-card></c-grid-item
      ><c-grid-item
        ><c-card
          ><c-statistic
            title="预算合计（元）"
            :value="budget"
            show-group-separator /></c-card></c-grid-item></c-grid
    ><c-card title="项目筛选"
      ><c-form :model="query" layout="vertical" @submit="search"
        ><c-grid :cols="{ xs: 1, md: 3 }" :col-gap="16" :row-gap="8"
          ><c-grid-item
            ><c-form-item label="关键词"
              ><c-input
                v-model="query.keyword"
                placeholder="项目、编号、负责人或类型"
                edit-mode="direct"
                clearable /></c-form-item></c-grid-item
          ><c-grid-item
            ><c-form-item label="项目状态"
              ><c-select
                v-model="query.status"
                :options="statusOptions"
                edit-mode="direct" /></c-form-item></c-grid-item
          ><c-grid-item
            ><c-form-item label="业务类型"
              ><c-select
                v-model="query.category"
                :options="categoryOptions"
                edit-mode="direct" /></c-form-item></c-grid-item></c-grid
        ><c-space wrap
          ><c-checkbox v-model="query.archived" edit-mode="direct"
            >查看已归档项目</c-checkbox
          ><c-checkbox v-model="query.favorites" edit-mode="direct"
            >仅看收藏</c-checkbox
          ><c-button html-type="submit" status="primary">查询项目</c-button
          ><c-button @click="clear">清空筛选</c-button></c-space
        ></c-form
      ></c-card
    ><c-card title="项目台账"
      ><template #title-action
        ><c-space wrap
          ><c-button
            :disabled="!selected.length || applied.archived"
            @click="finishSelected"
            >交付选中（{{ selected.length }}）</c-button
          ><c-button
            :disabled="!selected.length || applied.archived"
            @click="requestArchive([...selected])"
            >归档选中</c-button
          ></c-space
        ></template
      ><c-table
        :columns="columns"
        :data="pageRows"
        :pagination="false"
        row-key="key"
        v-model:selected-keys="selected"
        :row-selection="{ type: 'checkbox', showCheckedAll: true }"
        ><template #project="{ record }"
          ><c-space direction="column" size="xs"
            ><c-link
              :href="href('detail', { project: record.key })"
              @click.prevent="go('detail', { project: record.key })"
              >{{ record.name }}</c-link
            ><c-tag>{{ record.key }} · {{ record.category }}</c-tag></c-space
          ></template
        ><template #state="{ record }"
          ><c-space direction="column" block size="xs"
            ><c-tag
              :status="record.status === '已完成' ? 'success' : 'primary'"
              >{{ record.status }}</c-tag
            ><c-progress :percent="record.progress" /></c-space></template
        ><template #budget="{ record }">{{ money(record.budget) }} 元</template
        ><template #actions="{ record }"
          ><c-space wrap
            ><c-button size="sm" @click="go('detail', { project: record.key })"
              >详情</c-button
            ><c-button
              v-if="!record.archived"
              size="sm"
              @click="startEdit(record)"
              >编辑</c-button
            ><c-button
              v-if="!record.archived"
              size="sm"
              :disabled="record.status === '已完成'"
              @click="finish(record)"
              >交付</c-button
            ><c-button v-if="record.archived" size="sm" @click="restore(record)"
              >恢复</c-button
            ><c-button v-else size="sm" @click="requestArchive([record.key])"
              >归档</c-button
            ></c-space
          ></template
        ></c-table
      ><c-empty
        v-if="!filtered.length"
        description="没有匹配项目，清空筛选可恢复结果" /><template #footer
        ><c-pagination
          v-model="current"
          :total="filtered.length"
          :page-size="4" /></template></c-card
    ><c-typography-paragraph role="status" aria-live="polite">{{
      notice
    }}</c-typography-paragraph
    ><c-dialog
      v-model:open="createOpen"
      :title="editingKey ? '编辑项目资料' : '快速创建项目'"
      :footer="false"
      :unmount-on-close="true"
      ><c-form :model="draft" layout="vertical" @submit="create"
        ><c-grid :cols="{ xs: 1, md: 2 }" :col-gap="16" :row-gap="8"
          ><c-grid-item
            ><c-form-item
              label="项目名称"
              field="name"
              :rules="required"
              feedback
              ><c-input
                v-model="draft.name"
                edit-mode="direct"
                placeholder="项目名称" /></c-form-item></c-grid-item
          ><c-grid-item
            ><c-form-item
              label="负责人"
              field="owner"
              :rules="required"
              feedback
              ><c-input
                v-model="draft.owner"
                edit-mode="direct"
                placeholder="负责人" /></c-form-item></c-grid-item
          ><c-grid-item
            ><c-form-item label="业务类型" field="category"
              ><c-select
                v-model="draft.category"
                :options="categories"
                edit-mode="direct" /></c-form-item></c-grid-item
          ><c-grid-item
            ><c-form-item label="优先级" field="priority"
              ><c-select
                v-model="draft.priority"
                :options="priorities"
                edit-mode="direct" /></c-form-item></c-grid-item
          ><c-grid-item
            ><c-form-item label="开始日期" field="startDate"
              ><c-date
                v-model="draft.startDate"
                value-format="YYYY-MM-DD"
                edit-mode="direct" /></c-form-item></c-grid-item
          ><c-grid-item
            ><c-form-item label="截止日期" field="dueDate"
              ><c-date
                v-model="draft.dueDate"
                value-format="YYYY-MM-DD"
                edit-mode="direct" /></c-form-item></c-grid-item
          ><c-grid-item
            ><c-form-item label="项目预算（元）" field="budget"
              ><c-input-number
                v-model="draft.budget"
                :min="0"
                :precision="2"
                edit-mode="direct" /></c-form-item></c-grid-item></c-grid
        ><c-form-item label="项目说明" field="description"
          ><c-textarea
            v-model="draft.description"
            edit-mode="direct"
            placeholder="项目目标、交付物和验收要求" /></c-form-item
        ><c-space wrap
          ><c-button html-type="submit" status="primary">{{
            editingKey ? "保存项目" : "创建项目"
          }}</c-button
          ><c-button @click="createOpen = false">取消</c-button></c-space
        ><c-typography-paragraph role="status" aria-live="polite">{{
          notice
        }}</c-typography-paragraph></c-form
      ></c-dialog
    ><c-dialog v-model:open="archiveOpen" title="确认归档项目" :footer="false"
      ><c-space direction="column" block
        ><c-typography-paragraph
          >将归档所选项目。项目、任务和操作记录会保留，可在“已归档”筛选中恢复。</c-typography-paragraph
        ><c-space wrap
          ><c-button status="warning" @click="confirmArchive">确认归档</c-button
          ><c-button @click="archiveOpen = false">取消归档</c-button></c-space
        ></c-space
      ></c-dialog
    ></c-space
  >
</template>
<style scoped>
.practice-page {
  width: 100%;
  min-width: 0;
}
.practice-page :deep(.c-grid-item) {
  min-width: 0;
}
.practice-page :deep(.c-grid) {
  width: 100%;
}
.practice-page :deep(.c-space__item) {
  min-width: 0;
}
</style>
```

## 实现与边界

页面的布局、字段、表格、卡片、弹层、反馈和分页全部使用 Cedar 自有组件。六类页面共享本地项目工作区；刷新保留本次浏览器会话的数据，归档可恢复，重置还原整个工作区。数据模型与行为在 `__demos__/shared/usePracticeData.js` 中，页面可按自身业务接入接口。

示例使用合成数据，不访问业务后端，不模拟服务端权限。CSV 导出只包含本地当前查询结果。

参考信息组织：[Ant Design 表单页面](https://ant.design/docs/spec/research-form/) · [Arco Design Pro](https://github.com/arco-design/arco-design-pro) · [TDesign Starter](https://tdesign.tencent.com/starter)。全部界面使用本库组件组合。

[最佳实践入口](llms/zh-CN/practices.md) · [特色与场景](llms/zh-CN/showcase.md)

---

Document: llms/zh-CN/practices/result.md

<!-- Source: docs/practices/result.md; locale: zh-CN; page: /practices/result/ -->

# 结果与异常页

结合最新项目记录提供成功反馈、异常恢复与下一步。

## 完整业务体验

体验服务失败重试、空状态创建申请和项目详情返回；办理成功时可以打开最近创建的真实本地项目。结果类型只用于本地演示，不调用真实业务后端。

Example source: docs/practices/__demos__/result/basic.vue

```vue
<script setup>
import { computed, ref } from "vue";
import { usePracticeData, projectError } from "../shared/usePracticeData.js";
import { usePracticeNavigation } from "../shared/usePracticeNavigation.js";
const data = usePracticeData();
const {
  workspace,
  rows,
  projects,
  favorites,
  activity,
  savedDraft,
  latest,
  query,
  applied,
  current,
  selected,
  notice,
  statusOptions,
  categories,
  categoryOptions,
  priorities,
  filtered,
  pageRows,
  done,
  budget,
  overdue,
  active,
  detailOpen,
  createOpen,
  archiveOpen,
  editingKey,
  draft,
  fresh,
  search,
  clear,
  show,
  finish,
  finishSelected,
  startCreate,
  startEdit,
  create,
  requestArchive,
  confirmArchive,
  restore,
  favorite,
  reset,
  exportCsv,
} = data;
const { route, go, href } = usePracticeNavigation();
const required = [
  { required: true, whitespace: true, message: "此项不能为空" },
];
const money = (value) =>
  Number(value).toLocaleString("zh-CN", { maximumFractionDigits: 2 });
const state = ref(String(route.query.state || "success"));
const retries = ref(0);
const lastProject = computed(() =>
  rows.value.find((row) => row.key === (route.query.project || latest.value)),
);
const resultOptions = [
  { value: "success", label: "办理成功" },
  { value: "500", label: "服务异常" },
  { value: "403", label: "无权限访问" },
  { value: "404", label: "项目不存在" },
  { value: "empty", label: "暂无项目" },
];
const content = computed(
  () =>
    ({
      success: [
        "办理成功",
        lastProject.value
          ? `${lastProject.value.key} · ${lastProject.value.name}`
          : "可返回项目列表，或创建一份新申请。",
      ],
      500: ["保存暂时失败", "这是一种本地演示状态，重试恢复后可继续处理。"],
      403: ["暂时无法访问", "当前演示权限不足，请返回工作台。"],
      404: ["未找到项目", "请从项目列表重新选择，避免使用失效的项目编号。"],
      empty: ["尚未建立项目", "创建一份申请，建立完整的项目与任务清单。"],
    })[state.value] || ["结果类型无效", "请从下方选择一个演示状态。"],
);
function recover() {
  if (state.value === "500") {
    retries.value++;
    state.value = "success";
    notice.value = `重试成功（${retries.value} 次），可以继续处理。`;
  } else if (state.value === "empty") go("form");
  else go("list");
}
</script>
<template>
  <c-space class="practice-page" direction="column" block size="lg"
    ><c-page-header
      title="办理结果与异常恢复"
      subtitle="结合实际项目记录提供下一步操作"
      :show-back="false"
      ><template #extra><c-space wrap></c-space></template></c-page-header
    ><c-space wrap size="sm"
      ><c-button @click="go('dashboard')">工作台</c-button
      ><c-button @click="go('list')">项目列表</c-button
      ><c-button @click="go('card')">卡片视图</c-button
      ><c-button status="primary" @click="go('form')"
        >创建申请</c-button
      ></c-space
    ><c-card title="结果体验"
      ><c-form layout="vertical"
        ><c-form-item label="演示结果类型"
          ><c-select
            v-model="state"
            :options="resultOptions"
            edit-mode="direct" /></c-form-item></c-form></c-card
    ><c-card
      ><c-result
        :status="
          resultOptions.some((item) => item.value === state) ? state : 'warning'
        "
        :title="content[0]"
        :subtitle="content[1]"
        ><template #extra
          ><c-space wrap
            ><c-button status="primary" @click="recover">{{
              state === "500"
                ? "重试处理"
                : state === "empty"
                  ? "创建项目申请"
                  : "返回项目列表"
            }}</c-button
            ><c-button
              v-if="state === 'success' && lastProject"
              @click="go('detail', { project: lastProject.key })"
              >查看最新项目</c-button
            ><c-button @click="go('dashboard')">返回工作台</c-button></c-space
          ></template
        ></c-result
      ></c-card
    ><c-typography-paragraph role="status" aria-live="polite">{{
      notice
    }}</c-typography-paragraph></c-space
  >
</template>
<style scoped>
.practice-page {
  width: 100%;
  min-width: 0;
}
.practice-page :deep(.c-grid-item) {
  min-width: 0;
}
.practice-page :deep(.c-grid) {
  width: 100%;
}
.practice-page :deep(.c-space__item) {
  min-width: 0;
}
</style>
```

## 实现与边界

页面的布局、字段、表格、卡片、弹层、反馈和分页全部使用 Cedar 自有组件。六类页面共享本地项目工作区；刷新保留本次浏览器会话的数据，归档可恢复，重置还原整个工作区。数据模型与行为在 `__demos__/shared/usePracticeData.js` 中，页面可按自身业务接入接口。

示例使用合成数据，不访问业务后端，不模拟服务端权限。CSV 导出只包含本地当前查询结果。

参考信息组织：[Ant Design 表单页面](https://ant.design/docs/spec/research-form/) · [Arco Design Pro](https://github.com/arco-design/arco-design-pro) · [TDesign Starter](https://tdesign.tencent.com/starter)。全部界面使用本库组件组合。

[最佳实践入口](llms/zh-CN/practices.md) · [特色与场景](llms/zh-CN/showcase.md)

---

Document: llms/zh-CN/practices/utility-spec.md

<!-- Source: docs/practices/utility-spec.md; locale: zh-CN; page: /practices/utility-spec/ -->

# Utility 工具类规范（Cedar / Maple 共用）

两端 **语义与结构一致**，类名与变量均带库前缀，避免混用撞名：

| | Cedar | Maple |
|---|---|---|
| 类名前缀 | `c-`（如 `c-text-1`、`c-mt-16`） | `mp-`（如 `mp-text-1`、`mp-mt-16`） |
| CSS 变量 | `--c-*` | `--mp-*` |

**不做无前缀别名，不做向后兼容。**

## 交付方式

| | Cedar | Maple |
|---|---|---|
| 原子化 CSS preset | `@cedar-design/preset-unocss` / `@cedar-design/preset-tailwindcss` | `@maple-design/preset-unocss` / `@maple-design/preset-tailwindcss` |
| 暗色 | 只改 token，类名不变 | 同左 |

## 标准集合

下列以 Cedar（`c-`）举例；Maple 将前缀换成 `mp-` 即可。

### Color（语义）

| 类名 | 作用 |
|---|---|
| `c-text-1` … `c-text-4` | 文字层级 |
| `c-fill-1` … `c-fill-4` | 填充 |
| `c-color-border-1` … `c-color-border-4` | 边框色（与变量同名，避免和原子化 `c-border-*` 宽度类撞名） |
| `c-bg-0` / `c-bg-1` / `c-bg-2` | 背景层级 |

底层：`rgb(var(--{p}-primary-6))`、`var(--{p}-color-text-1)` 等。完整色阶原子不进默认工具包，见 Palette。

### Spacing / Size

间距与宽高仅由 Uno / Tailwind preset 按具体数值生成，不再提供语义档固定类。
`c-mt-16`（16px）、`c-h-10`（10px）、`c-w-full`（100%）；Maple 将前缀换成 `mp-`。
日常分类见 [常用写法](llms/zh-CN/components/style/atomic-usage.md)。

### 布局 / 圆角 / 阴影 / 海拔

- Flex / Display / Position：`c-flex`、`c-justify-*`、`c-relative` 等  
- Overflow：`c-overflow-hidden`、`c-truncate`、`c-line-clamp-2` 等，由原子化 preset 生成  
- Radius：`c-rounded-*`（含 `xl`）→ `--{p}-rounded-*`  
- Elevation：`c-elevation--0` … `--24`（Maple：`mp-elevation--*`，独立 CSS）

## 平台差异（侧栏目录一致）

| 项 | Cedar | Maple |
|---|---|---|
| Typography 工具包 | 有（PC） | 无；用 token / 原子化 |
| 原子化 CSS preset | `@cedar-design/preset-unocss` / `@cedar-design/preset-tailwindcss` | `@maple-design/preset-unocss` / `@maple-design/preset-tailwindcss` |

## 禁止

- 无前缀工具类（`text-1`、`mt-4`、`flex`）与无前缀变量（`--brand-6`）  
- 固定 Utilities 内重复实现间距原子  
- 默认包内完整色板原子类  
- Maple 再复制进全量组件 CSS（utilities 保持独立入口）

---

Document: llms/zh-CN/showcase.md

<!-- Source: docs/showcase/README.md; locale: zh-CN; page: /showcase/ -->

<ShowcaseOverview />

---

Document: llms/zh-CN/showcase/async-selection.md

<!-- Source: docs/showcase/async-selection.md; locale: zh-CN; page: /showcase/async-selection/ -->

# 异步数据选择

业务数据经常只保存 ID，而界面需要展示名称、搜索候选和处理加载状态。人员选择将候选 request 与已选人员 resolve 分开，让业务提供服务函数。

## 从 ID 到人员展示

下方初始模型为人员 ID。观察编辑字段和阅读字段中的人员名称，搜索 Alice 或 Bob 并切换人员，再点击阅读字段的操作按钮查看本地反馈。

示例使用本地人员数据；操作按钮只记录结果。业务接口、权限与聊天服务由应用接入。

Example source: src/people-select/__demos__/injected-services.vue

```vue
<script setup lang="ts">
import { onMounted, ref } from 'vue'
const personId = ref<string | null>('alice')
const log = ref('')
const people = [
 { value: 'alice', label: 'Alice', mobile: '13800000000', avatar: 'data:image/svg+xml,%3Csvg xmlns="http://www.w3.org/2000/svg" width="24" height="24"%3E%3Ccircle cx="12" cy="12" r="12" fill="%236579af"/%3E%3C/svg%3E' },
 { value: 'bob', label: 'Bob', mobile: '13900000000' },
]
const displayed = ref<Record<string, (typeof people)[number]>>({})
// 模拟详情请求：回显数据独立更新，不加入候选列表。
onMounted(() => { setTimeout(() => { displayed.value.alice = people[0] }, 600) })
const fallbackOption = (id: string) => displayed.value[id] ?? { value: id, label: id }
async function options(query: string, { signal }: { signal: AbortSignal }) {
 await new Promise(resolve => setTimeout(resolve, 200))
 if (signal.aborted) return []
 return people.filter(person => person.label.toLowerCase().includes(query.toLowerCase()))
}
async function call(person: { value: string; mobile?: string }) { log.value = `Call: ${person.mobile || person.value}` }
async function chat(person: { value: string }) { log.value = `Chat: ${person.value}` }
</script>
<template>
 <c-space direction="column">
  <c-people-select v-model="personId" :options="options" :fallback-option="fallbackOption" clearable :empty-value="null" />
  <c-people-select v-model="personId" :fallback-option="fallbackOption" show-phone show-chat :call="call" :chat="chat" read-pretty />
  <p role="status">{{ log }}</p>
 </c-space>
</template>
```

## 远程搜索

输入搜索词，观察候选和加载状态。展开源码，查看请求与字段值如何连接。

Example source: src/select/__demos__/search.vue

```vue
<template>
  <c-space direction="column" size="lg">
    <div>Show selections after search options</div>
    <c-select
      :style="{ width: '320px' }"
      :loading="loading"
      placeholder="Please select ..."
      multiple
      :filter-option="false"
      @search="handleSearch"
    >
      <c-option v-for="item of options" :key="item" :value="item">{{ item }}</c-option>
    </c-select>
    <div>Hide selections after search options</div>
    <c-select
      :options="options"
      :style="{ width: '320px' }"
      :loading="loading"
      placeholder="Please select ..."
      multiple
      :filter-option="false"
      :show-extr-options="false"
      @search="handleSearch" />
  </c-space>
</template>

<script lang="ts">
import { defineComponent, ref } from 'vue'
export default defineComponent({
  setup() {
    const options = ref(['Option1', 'Option2', 'Option3'])
    const loading = ref(false)

    const handleSearch = (value: any) => {
      if (value) {
        loading.value = true
        window.setTimeout(() => {
          options.value = [`${value}-Option1`, `${value}-Option2`, `${value}-Option3`]
          loading.value = false
        }, 2000)
      } else {
        options.value = []
      }
    }

    return {
      options,
      loading,
      handleSearch,
    }
  },
})
</script>
```

## 与其他实现对照什么

| 场景 | 核对结果 |
| --- | --- |
| 初始只有 ID | 是否能解析并展示已选项 |
| 连续快速输入 | 旧请求结果是否覆盖新的搜索结果 |
| 清空、只读、阅读态 | 是否仍发出不必要的候选请求 |
| 加载失败 | 是否有明确反馈和恢复入口 |
| 业务操作区 | 是否能组合权限与自定义操作 |

请求竞争与失败场景需使用可控延迟及错误数据单独验证，不能从正常搜索结果推断。

继续阅读：[PeopleSelect](llms/zh-CN/components/people-select.md) · [Select](llms/zh-CN/components/select.md) · [AutoComplete](llms/zh-CN/components/auto-complete.md)

## 复用业务数据服务

重新加载候选，观察加载状态和选中值；展开源码查看 useAsyncData 如何把数据请求与字段绑定分开。此例为本地固定数据，不模拟请求失败。

Example source: src/select/__demos__/async-source.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { useAsyncData } from '@cedar-design/use'
const value = ref('mengshuai')
// A shared business function can be imported and reused in other fields.
const loadPeople = async () => {
  await new Promise(resolve => setTimeout(resolve, 200))
  return [{ value: 'mengshuai', label: '孟帅' }, { value: 'wujiaming', label: '吴甲明' }]
}
const { data: options, loading, error, refresh } = useAsyncData(loadPeople, {
  initialData: [] as { value: string; label: string }[],
})
</script>
<template>
  <c-space direction="column">
    <c-select v-model="value" :options="options" :loading="loading" filterable />
    <p v-if="error" role="alert">加载失败，请重试。</p>
    <c-button @click="refresh()">重新加载</c-button>
  </c-space>
</template>
```

演示后返回[专栏总览](llms/zh-CN/showcase.md)继续下一站。

## 连续修改时的异步校验

输入错误用户名并触发校验，再改为 admin 再次校验。手动先返回最新结果、再返回最早结果，检查过期校验是否影响当前字段。此例的等待队列完全在本地，方便演示返回顺序。

Example source: src/form/__demos__/async-race.vue

```vue
<template>
  <section class="async-race-form-demo">
    <p>本地异步规则只接受 admin；手动返回最早或最新结果，不访问网络。</p>
    <c-form
      ref="formRef"
      :model="model"
      :disabled="disabled"
      :readonly="readonly"
    >
      <c-form-item
        v-if="mounted"
        field="name"
        label="用户名"
        :label-attrs="{ for: demoId }"
        :rules="rules"
        :validate-trigger="[]"
        feedback
      >
        <c-input :id="demoId" v-model="model.name" placeholder="请输入 admin" />
      </c-form-item>
    </c-form>
    <div class="async-race-controls">
      <c-checkbox v-model="disabled"> Disable async form</c-checkbox>
      <c-checkbox v-model="readonly"> Readonly async form</c-checkbox>
      <c-checkbox v-model="mounted"> Mount async field</c-checkbox>
    </div>
    <c-space wrap>
      <c-button :disabled="!mounted" @click="validate">校验字段</c-button>
      <c-button :disabled="!mounted" @click="validateAll">校验整表</c-button>
      <c-button :disabled="!pending.length" @click="complete(false)"
        >返回最早结果</c-button
      >
      <c-button :disabled="!pending.length" @click="complete(true)"
        >返回最新结果</c-button
      >
      <c-button :disabled="!mounted" @click="serverError"
        >写入服务端错误</c-button
      >
      <c-button @click="clear">清空校验</c-button>
      <c-button @click="reset">重置</c-button>
    </c-space>
    <p role="status">校验结果：{{ result }}；等待结果：{{ pending.length }}</p>
    <p>本次校验值：{{ checkedValue || "空" }}</p>
    <ModelOutput>{{ model }}</ModelOutput>
  </section>
</template>
<script setup lang="ts">
import ModelOutput from "../__demo-utils__/ModelOutput.vue";

import {
  onBeforeUnmount,
  onDeactivated,
  reactive,
  ref,
  shallowRef,
  useId,
} from "vue";
import type { FormInstance, FieldRule } from "@cedar-design/ui";

interface Pending {
  value: unknown;
  resolve: (result: true | string) => void;
}
const demoId = useId();
const disabled = ref(false);
const readonly = ref(false);
const mounted = ref(true);
const formRef = ref<FormInstance>();
const model = reactive({ name: "" });
const pending = shallowRef<Pending[]>([]);
const result = ref("尚未校验");
const checkedValue = ref("");
let run = 0;

function request(value: unknown) {
  return new Promise<true | string>((resolve) => {
    pending.value = [...pending.value, { value, resolve }];
  });
}
const rules: FieldRule[] = [
  {
    validator: async (value, callback) => {
      const answer = await request(value);
      if (answer !== true) callback(answer);
    },
  },
];

function validate() {
  return validateScope(false);
}
function validateAll() {
  return validateScope(true);
}
async function validateScope(all: boolean) {
  const current = ++run;
  checkedValue.value = model.name;
  result.value = "校验中";
  const errors = await (all
    ? formRef.value?.validate()
    : formRef.value?.validateField("name"));
  if (current === run) result.value = errors ? "未通过" : "通过";
}
function complete(latest: boolean) {
  const task = latest ? pending.value.at(-1) : pending.value[0];
  if (!task) return;
  pending.value = pending.value.filter((item) => item !== task);
  task.resolve(task.value === "admin" ? true : "用户名必须是 admin");
}
function clear() {
  run++;
  formRef.value?.clearValidate();
  result.value = "已清空";
}
function serverError() {
  run++;
  formRef.value?.setFields({
    name: { status: "error", message: "模拟服务端拒绝" },
  });
  result.value = "服务端错误";
}
function reset() {
  run++;
  formRef.value?.resetFields();
  checkedValue.value = "";
  result.value = "已重置";
}
function cleanup() {
  run++;
  result.value = "已取消";
  const tasks = pending.value;
  pending.value = [];
  tasks.forEach((task) => task.resolve(true));
}
onBeforeUnmount(cleanup);
onDeactivated(cleanup);
</script>

<style scoped>
.async-race-controls {
  display: flex;
  flex-wrap: wrap;
  gap: 12px;
}
.async-race-controls label {
  display: inline-flex;
  align-items: center;
  gap: 4px;
}
</style>
```

---

[返回总览，标记已体验](llms/zh-CN/showcase.md) · [下一站：任务数据工作台](llms/zh-CN/showcase/data-workbench.md)

---

Document: llms/zh-CN/showcase/components.md

<!-- Source: docs/showcase/components.md; locale: zh-CN; page: /showcase/components/ -->

# 逐组件对照

按开发任务归类组件：先认识基础与布局，再进入输入、选择、表单、数据管理和业务场景。每个组件都列出当前 Cedar 的展示重点、可操作示例，以及其他组件库的参考案例。

Vue 组件库用于比较使用与交互，React / Angular 组件库用于借鉴场景和示例组织。参考链接固定到工作区源码版本；“相关组合”表示职责相近的组合示例，不能据此认定对方缺少该能力。

<ComponentComparison />

## 功能点与增量

展开“相似功能点逐项对照”，可查看已有示例、文档依据和待核验增量；“值得补充的重要内容”按当前分类列出优先级、参考案例和验收重点。待核验表示尚未找到对应专题示例，不直接等同于缺少能力。

## 示例阅读顺序

基础用法 → 尺寸、变体与状态 → 常用交互 → 异步数据 → 插槽与业务组合 → 边界和生命周期。表单字段与独立面板分别归类，避免将两种接入方式混为同一功能。

## 怎么判断优势

对相同数据、容器和操作步骤，比较接入配置、额外业务代码及操作结果。当前索引提供源码与示例内容对照；性能、兼容性和失败恢复等结论需要同环境运行验证。

---

Document: llms/zh-CN/showcase/cross-platform.md

<!-- Source: docs/showcase/cross-platform.md; locale: zh-CN; page: /showcase/cross-platform/ -->

# 桌面与移动

使用相同的巡检任务、部门选项和业务模型，对照两端的编辑方式。Cedar 的选择与日期时间字段在当前位置展开面板；Maple 的这些字段明确使用 Popup，确认后提交，取消保留原值。任务名称在两端都直接输入。

## 同一个任务，两种交互

1. 在 Cedar 中选择“研发部”，观察已提交模型。
2. 在 Maple 手机预览中点击“负责部门”，在 Popup 内选择“研发部”；先不确认，观察已提交模型。
3. 点击右上角关闭（取消）后重新打开，核对仍为原来的值；再次选择并确认，核对模型更新。
4. 对日期和时间重复这组操作，比较面板形态与确认过程。

<PlatformComparison />

## 公共约定与平台差异

| 项目 | Cedar | Maple |
| --- | --- | --- |
| 业务数据 | 相同任务与部门 ID | 相同任务与部门 ID |
| 文本输入 | inline，直接输入 | inline，直接输入 |
| 本例选择、日期、时间 | inline，在字段附近操作 | popup，进入弹层编辑 |
| Popup 草稿 | 本例不使用 Popup 草稿 | 确认前不提交，取消保留原值 |
| 使用代码 | c- 前缀；字段的 edit-mode 为 direct | mp- 前缀；对应字段的 edit-mode 为 popup |

两端共用 API 语义，组件的交互方式按端侧场景选择。Maple 的选择和日期时间字段通常采用 Popup；文本输入仍可以保持直接编辑。

## 尺寸与外观

下面单独比较尺寸与变体；上方的业务示例负责展示交互差异。

Example source: src/field-decorator/__demos__/control-sizes.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
const sizes = ["xs", "sm", "md", "lg", "xl"] as const;
const variants = ["outline", "filled", "standard"] as const;
const size = ref<(typeof sizes)[number]>("md");
const variant = ref<(typeof variants)[number]>("outline");
const options = [
  { value: "beijing", label: "Beijing" },
  { value: "shanghai", label: "Shanghai" },
];
const cascaderOptions = [{ value: "china", label: "China", children: options }];

const inputValue = ref("Beijing");
const selectValue = ref("beijing");
const cascaderValue = ref("beijing");
const selectMultiple = ref(["beijing", "shanghai"]);
const cascaderMultiple = ref(["beijing", "shanghai"]);
const selectOverflow = ref(["long", "beijing", "shanghai"]);
const cascaderOverflow = ref(["long", "beijing", "shanghai"]);
const selectedOptions = [
  ...options,
  {
    value: "long",
    label:
      "A very long selected option label for overflow comparison — full text preview keeps the selected value unchanged.",
  },
];
const selectedCascaderOptions = [
  { value: "china", label: "China", children: selectedOptions },
];
function resetSelections() {
  inputValue.value = "Beijing";
  selectValue.value = "beijing";
  cascaderValue.value = "beijing";
  selectMultiple.value = ["beijing", "shanghai"];
  cascaderMultiple.value = ["beijing", "shanghai"];
  selectOverflow.value = ["long", "beijing", "shanghai"];
  cascaderOverflow.value = ["long", "beijing", "shanghai"];
}
</script>
<template>
  <section
    aria-label="Form control size comparison"
    class="control-size-comparison"
  >
    <c-space wrap :size="12">
      <c-radio-group v-model="size" aria-label="Comparison size">
        <c-radio v-for="item in sizes" :key="item" :value="item">{{
          item
        }}</c-radio>
      </c-radio-group>
      <c-radio-group v-model="variant" aria-label="Comparison variant">
        <c-radio v-for="item in variants" :key="item" :value="item">{{
          item
        }}</c-radio>
      </c-radio-group>
    </c-space>
    <div class="control-size-comparison__grid">
      <div data-control="Input">
        <p>Input</p>
        <c-input :size="size" :variant="variant" placeholder="Input" />
      </div>
      <div data-control="Button">
        <p>Button</p>
        <c-button :size="size" variant="outline">Button</c-button>
      </div>
      <div data-control="Select">
        <p>Select</p>
        <c-select
          :size="size"
          :variant="variant"
          :options="options"
          placeholder="Select"
        />
      </div>
      <div data-control="Date">
        <p>Date</p>
        <c-date :size="size" :variant="variant" placeholder="Date" />
      </div>
      <div data-control="Time">
        <p>Time</p>
        <c-time :size="size" :variant="variant" placeholder="Time" />
      </div>
      <div data-control="InputNumber">
        <p>InputNumber</p>
        <c-input-number :size="size" :variant="variant" placeholder="Number" />
      </div>
      <div data-control="AutoComplete">
        <p>AutoComplete</p>
        <c-auto-complete
          :size="size"
          :variant="variant"
          :options="options"
          placeholder="AutoComplete"
        />
      </div>
      <div data-control="Cascader">
        <p>Cascader</p>
        <c-cascader
          :size="size"
          :variant="variant"
          :options="cascaderOptions"
          placeholder="Cascader"
        />
      </div>
      <div data-control="DateRange">
        <p>DateRange</p>
        <c-date-range
          :size="size"
          :variant="variant"
          :placeholder="['Start', 'End']"
        />
      </div>
      <div data-control="TimeRange">
        <p>TimeRange</p>
        <c-time-range
          :size="size"
          :variant="variant"
          :placeholder="['Start', 'End']"
        />
      </div>
    </div>

    <section
      aria-label="Selected control size comparison"
      class="control-size-comparison__states"
    >
      <c-space wrap align="center" :size="12">
        <span>Selected / Clearable / Multiple — 有值、可清空与多选不换行</span>
        <span
          >Hover or focus truncated text; tap on touch screens /
          悬停或聚焦省略正文查看全文；触屏点按查看，点外部关闭</span
        >
        <c-button size="sm" variant="outline" @click="resetSelections"
          >Reset / 恢复选中值</c-button
        >
      </c-space>
      <div class="control-size-comparison__grid">
        <div data-control="InputValue">
          <p>Input · clearable</p>
          <c-input
            v-model="inputValue"
            :size="size"
            :variant="variant"
            clearable
            placeholder="Input value"
          />
        </div>
        <div data-control="ButtonReference">
          <p>Button · reference</p>
          <c-button :size="size" variant="outline">Button</c-button>
        </div>
        <div data-control="SelectValue">
          <p>Select · clearable</p>
          <c-select
            v-model="selectValue"
            :size="size"
            :variant="variant"
            :options="selectedOptions"
            clearable
            placeholder="Select value"
          />
        </div>
        <div data-control="CascaderValue">
          <p>Cascader · clearable</p>
          <c-cascader
            v-model="cascaderValue"
            :size="size"
            :variant="variant"
            :options="selectedCascaderOptions"
            clearable
            placeholder="Cascader value"
          />
        </div>
        <div data-control="SelectMultiple">
          <p>Select · multiple / nowrap</p>
          <c-select
            v-model="selectMultiple"
            :size="size"
            :variant="variant"
            :options="selectedOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Select multiple"
          />
        </div>
        <div data-control="CascaderMultiple">
          <p>Cascader · multiple / nowrap</p>
          <c-cascader
            v-model="cascaderMultiple"
            :size="size"
            :variant="variant"
            :options="selectedCascaderOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Cascader multiple"
          />
        </div>
        <div data-control="SelectOverflow">
          <p>Select · long values / nowrap</p>
          <c-select
            v-model="selectOverflow"
            edit-mode="direct"
            :size="size"
            :variant="variant"
            :options="selectedOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Select long values"
          />
        </div>
        <div data-control="CascaderOverflow">
          <p>Cascader · long values / nowrap</p>
          <c-cascader
            v-model="cascaderOverflow"
            edit-mode="direct"
            :size="size"
            :variant="variant"
            :options="selectedCascaderOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Cascader long values"
          />
        </div>
      </div>
    </section>
  </section>
</template>
<style scoped>
.control-size-comparison,
.control-size-comparison__states {
  display: grid;
  gap: 24px;
}
.control-size-comparison__grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
  align-items: start;
  gap: 24px 16px;
}
.control-size-comparison__grid > div {
  min-width: 0;
}
.control-size-comparison__grid p {
  margin: 0 0 12px;
  font-size: 14px;
  line-height: 20px;
}
.control-size-comparison__grid :deep(.c-input-number),
.control-size-comparison__grid :deep(.c-auto-complete) {
  width: 100%;
}
</style>
```

---

[返回总览，标记已体验](llms/zh-CN/showcase.md) · [下一站：完整业务表单](llms/zh-CN/showcase/forms.md)

---

Document: llms/zh-CN/showcase/data-workbench.md

<!-- Source: docs/showcase/data-workbench.md; locale: zh-CN; page: /showcase/data-workbench/ -->

# 数据工作台

数据页面通常需要筛选条件、结果表格和用户自定义列。Cedar 提供 FilterForm、Table 与独立的 TableColumnManager，应用按业务数据流组合它们。

## 同一份任务数据，筛选与统计联动

1. 查询“运营部”，结果从五条缩小到两条。
2. 完成“展厅设备巡检”，观察完成数量和行状态同步变化。
3. 状态选择“待处理”再查询，已完成的任务不再出现。
4. 输入不存在的关键词，体验空结果；清空筛选恢复全部，点击“恢复全部任务”重置业务数据。

Example source: src/table/__demos__/task-workbench.vue

```vue
<script setup>
import { computed, ref } from "vue";
const original = () => [
  { key: "01", name: "展厅设备巡检", department: "运营部", status: "待处理" },
  { key: "02", name: "网站交互验收", department: "研发部", status: "进行中" },
  { key: "03", name: "品牌物料审核", department: "设计部", status: "待处理" },
  { key: "04", name: "移动端体验走查", department: "研发部", status: "已完成" },
  { key: "05", name: "会议室设备维护", department: "运营部", status: "进行中" },
];
const rows = ref(original());
const keyword = ref("");
const status = ref("全部");
const applied = ref({ keyword: "", status: "全部" });
const message = ref("显示全部任务。输入条件后点击查询。");
const options = ["全部", "待处理", "进行中", "已完成"].map((value) => ({
  value,
  label: value,
}));
const filtered = computed(() =>
  rows.value.filter(
    (row) =>
      (!applied.value.keyword ||
        `${row.name} ${row.department}`.includes(applied.value.keyword)) &&
      (applied.value.status === "全部" || row.status === applied.value.status),
  ),
);
const completed = computed(
  () => rows.value.filter((row) => row.status === "已完成").length,
);
const columns = [
  { title: "任务", dataIndex: "name" },
  { title: "部门", dataIndex: "department" },
  { title: "状态", dataIndex: "status" },
  { title: "操作", slotName: "action" },
];
function search() {
  applied.value = { keyword: keyword.value.trim(), status: status.value };
  message.value = `查询完成，找到 ${filtered.value.length} 条任务。`;
}
function clear() {
  keyword.value = "";
  status.value = "全部";
  applied.value = { keyword: "", status: "全部" };
  message.value = "已清空筛选条件。";
}
function finish(row) {
  row.status = "已完成";
  message.value = `已完成“${row.name}”，统计与列表已同步。`;
}
function reset() {
  rows.value = original();
  clear();
  message.value = "任务和筛选已恢复，可以重新演示。";
}
</script>
<template>
  <section class="task-workbench" aria-label="巡检任务数据联动">
    <div class="task-workbench__metrics">
      <span
        >全部 <strong>{{ rows.length }}</strong></span
      ><span
        >已完成 <strong>{{ completed }}</strong></span
      ><span
        >当前结果 <strong>{{ filtered.length }}</strong></span
      >
    </div>
    <c-form :model="applied" layout="vertical" @submit="search">
      <c-form-item label="搜索任务或部门"
        ><c-input
          v-model="keyword"
          edit-mode="direct"
          placeholder="搜索任务或部门"
          clearable
      /></c-form-item>
      <c-form-item label="任务状态"
        ><c-select v-model="status" :options="options" edit-mode="direct"
      /></c-form-item>
      <c-space wrap
        ><c-button html-type="submit" status="primary">查询任务</c-button
        ><c-button @click="clear">清空筛选</c-button
        ><c-button @click="reset">恢复全部任务</c-button></c-space
      >
    </c-form>
    <p role="status" aria-live="polite">{{ message }}</p>
    <c-table :columns="columns" :data="filtered" :pagination="false"
      ><template #action="{ record }"
        ><c-button
          :disabled="record.status === '已完成'"
          :aria-label="`完成${record.name}`"
          @click="finish(record)"
          >完成</c-button
        ></template
      ></c-table
    >
    <p v-if="!filtered.length">
      没有匹配任务。修改关键词或点击“清空筛选”恢复结果。
    </p>
    <small
      >先查询“运营部”，完成一条任务，再用状态过滤；统计与结果来自同一份本地任务数据。</small
    >
  </section>
</template>
<style scoped>
.task-workbench {
  min-width: 0;
  width: 100%;
}
.task-workbench__metrics {
  display: flex;
  flex-wrap: wrap;
  gap: 12px;
  margin-bottom: 16px;
}
.task-workbench__metrics > span {
  padding: 12px 16px;
  background: var(--c-color-fill-1);
  border-radius: 8px;
}
.task-workbench__metrics strong {
  margin-left: 8px;
  color: var(--c-color-primary);
}
.task-workbench small {
  display: block;
  margin-top: 8px;
  color: var(--c-color-text-2);
}
</style>
```

筛选只有点击查询才生效；统计和列表都由同一份任务数据计算。以下列管理示例单独展示列配置流程。

## 管理表格列

打开列管理，尝试勾选、排序和冻结，确认后观察表格变化。取消时检查表格是否保持原配置。配置保存的位置由应用选择。

Example source: src/table-column-manager/__demos__/with-table-ungrouped.vue

```vue
<template>
  <c-space direction="column" size="md">
    <c-alert type="info" :show-icon="false">
      不分组列示例：目录就是普通数组。工号为必选左冻结列，备注和入职日期默认隐藏；支持搜索、显隐、拖拽排序、冻结、删除、重命名和列宽记忆。
    </c-alert>

    <div class="demo-toolbar">
      <c-button status="secondary" size="sm" @click="open">管理列</c-button>
      <c-link @click="resetToDefault">恢复默认</c-link>
      <span class="demo-summary"
        >已展示 {{ leafColumns.length }} /
        {{ columnDefinitions.length }} 列</span
      >
    </div>

    <c-table
      v-model:columns="columns"
      extra-column
      column-resizable
      :data="data"
      :pagination="false"
      :bordered="{ cell: true, headerCell: true }"
      size="xs"
      @column-resize="handleColumnResize"
    >
      <template #extra-column-header>
        <c-button variant="text" size="xs" aria-label="管理列" @click="open"
          ><c-icon-settings
        /></c-button>
      </template>
      <template #extra-column-cell />

      <template #header-cell-actions="{ column, dataIndex }">
        <HeaderAction :data-index="dataIndex" :column="column" />
      </template>

      <template #status="{ record }">
        <c-tag :color="record.status === '在职' ? 'green' : 'gray'" size="sm">{{
          record.status
        }}</c-tag>
      </template>
    </c-table>

    <c-table-column-manager v-bind="managerProps" />
  </c-space>
</template>

<script setup lang="ts">
import { ref } from "vue";
import { useTableColumnManager } from "@cedar-design/ui";
import type { ColumnDefinitions, ManagedTableColumn } from "@cedar-design/ui";

const defaultColumns: ManagedTableColumn[] = [
  {
    dataIndex: "employeeId",
    title: "工号",
    manager: { required: true },
    fixed: "left",
    width: 110,
  },
  { dataIndex: "name", title: "姓名", minWidth: 140 },
  { dataIndex: "department", title: "部门", width: 140 },
  { dataIndex: "position", title: "职位", minWidth: 160 },
  { dataIndex: "phone", title: "手机号", width: 150 },
  { dataIndex: "status", title: "状态", width: 100, slotName: "status" },
];

const columnDefinitions: ColumnDefinitions = [
  {
    dataIndex: "employeeId",
    title: "工号",
    tip: "必选规则来自 defaultColumns",
  },
  { dataIndex: "name", title: "姓名" },
  { dataIndex: "department", title: "部门" },
  { dataIndex: "position", title: "职位" },
  { dataIndex: "phone", title: "手机号" },
  { dataIndex: "status", title: "状态" },
  { dataIndex: "joinedAt", title: "入职日期" },
  { dataIndex: "remark", title: "备注", tip: "不在默认列中，可从弹窗添加" },
];

const {
  columns,
  managerProps,
  leafColumns,
  open,
  handleColumnResize,
  HeaderAction,
  resetToDefault,
} = useTableColumnManager({
  defaultColumns,
  columnDefinitions,
  columnDefaults: { width: 130, ellipsis: true },
  createColumn: (definition) =>
    definition.dataIndex === "remark"
      ? {
          dataIndex: definition.dataIndex,
          title: definition.title,
          minWidth: 220,
          width: undefined,
        }
      : { dataIndex: definition.dataIndex, title: definition.title },
});

const data = ref([
  {
    employeeId: "E-1001",
    name: "张三",
    department: "产品研发部",
    position: "前端工程师",
    phone: "138****1024",
    status: "在职",
    joinedAt: "2023-04-18",
    remark: "负责组件库和中后台基础设施",
  },
  {
    employeeId: "E-1002",
    name: "李四",
    department: "质量保障部",
    position: "测试工程师",
    phone: "139****3072",
    status: "在职",
    joinedAt: "2022-11-07",
    remark: "负责自动化测试平台",
  },
  {
    employeeId: "E-1003",
    name: "王五",
    department: "数据平台部",
    position: "数据分析师",
    phone: "136****8841",
    status: "离职",
    joinedAt: "2021-08-23",
    remark: "历史项目成员",
  },
]);
</script>

<style scoped>
.demo-toolbar {
  display: flex;
  align-items: center;
  gap: 12px;
}

.demo-summary {
  margin-left: auto;
  color: var(--c-color-text-3);
}
</style>
```

## 从结果管理延伸到文件输入

目录读取适合批量整理素材；剪贴板示例可以粘贴图片，或者用本地样例文件演示数量限制与重置。两者只读取本地文件，不发出上传请求。

Example source: src/upload/__demos__/directory.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
import type { UploadFileItem } from '@cedar-design/ui'
const files = ref<UploadFileItem[]>([])
</script>
<template>
  <c-space direction="column">
    <p>选择目录后查看文件列表；本例只读取本地文件，不发送请求。目录选择取决于浏览器与系统文件选择器，移动设备可使用普通多选入口。</p>
    <p>目录选择</p>
    <c-upload v-model="files" directory multiple />
    <p>普通文件多选</p>
    <c-upload multiple />
  </c-space>
</template>
```

Example source: src/upload/__demos__/clipboard.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { useUploader, type UploadFileItem } from '@cedar-design/ui'
const files = ref<UploadFileItem[]>([])
const message = ref('')
const rejectionMessages: Record<string, string> = { 'max-files': '最多接收 3 张图片', 'max-file-size': '单张图片不能超过 1 MiB', accept: '仅支持图片文件' }
const uploader = useUploader({
  modelValue: () => files.value,
  onUpdateModelValue: value => { files.value = value },
  accept: () => 'image/*',
  maxFiles: () => 3,
  maxFileSize: () => 1024 * 1024,
  autoUpload: () => false,
  onRejected: rejected => { message.value = rejected.map(item => rejectionMessages[item.reason] ?? '文件未能读取，请重新选择').join(', ') },
})
function paste(event: ClipboardEvent) {
  const incoming = Array.from(event.clipboardData?.files ?? [])
  if (!incoming.length) return
  event.preventDefault()
  message.value = ''
  uploader.addFiles(incoming)
}
function addExample() {
  message.value = ''
  uploader.addFiles([new File(['<svg xmlns="http://www.w3.org/2000/svg" width="8" height="8"/>'], 'local-example.svg', { type: 'image/svg+xml' })])
}
function reset() { uploader.reset(); message.value = '' }
</script>
<template>
  <c-space direction="column">
    <p>将剪贴板图片粘贴到输入区。最多 3 张，每张不超过 1 MiB；只读取文件，不上传。普通文本粘贴仍按原生输入处理。</p>
    <c-textarea placeholder="在这里粘贴图片或文本" @paste="paste" />
    <c-space wrap>
      <c-button @click="addExample">加入本地示例图片</c-button>
      <c-button @click="reset">清空列表</c-button>
    </c-space>
    <p role="status">已接收 {{ files.length }} 个文件。{{ message }}</p>
    <ul><li v-for="file in files" :key="file.uid">{{ file.name }}</li></ul>
  </c-space>
</template>
```

## 与其他实现对照什么

比较实现相同列管理流程所需的额外组件、状态同步与业务封装。TableColumnManager 与 Table 解耦，也可以放入自定义容器；持久化由业务使用 localStorage、Pinia 或服务端完成。

继续阅读：[FilterForm](llms/zh-CN/components/filter-form.md) · [Table](llms/zh-CN/components/table.md) · [TableColumnManager](llms/zh-CN/components/table-column-manager.md)

---

[返回总览，标记已体验](llms/zh-CN/showcase.md) · [下一站：资源排期](llms/zh-CN/showcase/scheduling.md)

---

Document: llms/zh-CN/showcase/forms.md

<!-- Source: docs/showcase/forms.md; locale: zh-CN; page: /showcase/forms/ -->

# 一致的表单体验

业务表单既要保持字段外观一致，也要处理阅读、编辑、校验和确认。Cedar 通过字段外壳与 Form 的展示约定组合这些能力。

## 先完成一张业务单

1. 保持任务名为空，点击“校验并预览”，观察必填提示。
2. 点击“填入演示数据”，进入预览；返回修改，再进入预览。
3. 勾选“模拟下一次保存失败”，确认提交。失败时草稿保留，已提交记录仍为空。
4. 点击“重试提交”，核对成功记录；继续编辑时核对上次记录没有被草稿覆盖。
5. 点击“重新演示”，恢复到初始状态。

Example source: src/form/__demos__/task-workflow.vue

```vue
<script setup>
import { computed, onBeforeUnmount, onDeactivated, ref } from "vue";
const fresh = () => ({ title: "", department: "ops", priority: "normal" });
const draft = ref(fresh());
const saved = ref(null);
const stage = ref("edit");
const message = ref("填写任务后进入确认；也可以直接提交空表单查看校验。");
const busy = ref(false);
const failNext = ref(false);
const formRef = ref();
const rules = [{ required: true, whitespace: true, message: "请输入任务名称" }];
const departments = [
  { value: "ops", label: "运营部" },
  { value: "dev", label: "研发部" },
  { value: "design", label: "设计部" },
];
const priorities = [
  { value: "normal", label: "普通" },
  { value: "urgent", label: "紧急" },
];
const departmentLabel = computed(
  () =>
    departments.find((item) => item.value === draft.value.department)?.label,
);
let timer;
let epoch = 0;
function cancelPending() {
  epoch++;
  clearTimeout(timer);
  busy.value = false;
}
onBeforeUnmount(cancelPending);
onDeactivated(cancelPending);
function review({ errors }) {
  if (errors) {
    message.value = "请补全必填项，任务尚未提交。";
    return;
  }
  stage.value = "review";
  message.value = "核对信息后确认提交；返回修改不会改变上次提交记录。";
}
function submit() {
  if (busy.value) return;
  const current = ++epoch;
  const snapshot = { ...draft.value };
  const shouldFail = failNext.value;
  failNext.value = false;
  busy.value = true;
  message.value = "正在本地模拟保存…";
  timer = setTimeout(() => {
    if (current !== epoch) return;
    busy.value = false;
    if (shouldFail) {
      message.value = "保存失败：草稿已保留，请点击“重试提交”。";
      return;
    }
    saved.value = snapshot;
    stage.value = "done";
    message.value = "提交成功，已生成任务记录。";
  }, 500);
}
function reset() {
  cancelPending();
  draft.value = fresh();
  saved.value = null;
  stage.value = "edit";
  failNext.value = false;
  message.value = "已重置，可以重新演示。";
  formRef.value?.clearValidate();
}
function fill() {
  draft.value = {
    title: "展厅设备巡检",
    department: "ops",
    priority: "urgent",
  };
  formRef.value?.clearValidate();
}
</script>
<template>
  <section class="workflow-demo" aria-label="巡检任务完整流程">
    <ol class="workflow-demo__steps" aria-label="任务流程">
      <li :aria-current="stage === 'edit' ? 'step' : undefined">
        01 填写与校验
      </li>
      <li :aria-current="stage === 'review' ? 'step' : undefined">
        02 核对与提交
      </li>
      <li :aria-current="stage === 'done' ? 'step' : undefined">
        03 结果与记录
      </li>
    </ol>
    <c-form
      v-if="stage === 'edit'"
      ref="formRef"
      :model="draft"
      layout="vertical"
      @submit="review"
    >
      <c-form-item label="任务名称" field="title" :rules="rules" feedback
        ><c-input
          v-model="draft.title"
          edit-mode="direct"
          placeholder="例如：展厅设备巡检"
      /></c-form-item>
      <c-form-item label="执行部门" field="department"
        ><c-select
          v-model="draft.department"
          :options="departments"
          edit-mode="direct"
      /></c-form-item>
      <c-form-item label="任务优先级" field="priority"
        ><c-select
          v-model="draft.priority"
          :options="priorities"
          edit-mode="direct"
      /></c-form-item>
      <c-space wrap
        ><c-button html-type="submit" status="primary">校验并预览</c-button
        ><c-button @click="fill">填入演示数据</c-button></c-space
      >
    </c-form>
    <div v-else-if="stage === 'review'">
      <h4>确认巡检任务</h4>
      <dl>
        <dt>任务</dt>
        <dd>{{ draft.title }}</dd>
        <dt>部门</dt>
        <dd>{{ departmentLabel }}</dd>
        <dt>优先级</dt>
        <dd>{{ draft.priority === "urgent" ? "紧急" : "普通" }}</dd>
      </dl>
      <c-checkbox v-model="failNext" :disabled="busy"
        >模拟下一次保存失败（本地）</c-checkbox
      >
      <c-space wrap
        ><c-button
          status="primary"
          :loading="busy"
          :disabled="busy"
          @click="submit"
          >{{
            message.includes("保存失败") ? "重试提交" : "确认提交"
          }}</c-button
        ><c-button :disabled="busy" @click="stage = 'edit'"
          >返回修改</c-button
        ></c-space
      >
    </div>
    <div v-else>
      <h4>任务已创建</h4>
      <p>
        {{ saved.title }} ·
        {{ saved.priority === "urgent" ? "紧急处理" : "普通处理" }}
      </p>
      <c-button @click="stage = 'edit'">继续编辑</c-button>
    </div>
    <p role="status" aria-live="polite">{{ message }}</p>
    <c-collapse>
      <c-collapse-item title="查看已提交记录" name="saved">
        <pre>{{
          saved
            ? JSON.stringify(saved, null, 2)
            : "尚无记录；校验失败、返回修改或保存失败都不会创建记录。"
        }}</pre>
      </c-collapse-item>
    </c-collapse>
    <c-button @click="reset">重新演示</c-button>
    <small
      >本例使用本地模拟保存，不访问业务服务。校验、确认、保存与失败恢复由业务流程组合。</small
    >
  </section>
</template>
<style scoped>
.workflow-demo {
  width: 100%;
  min-width: 0;
}
.workflow-demo__steps {
  display: flex;
  flex-wrap: wrap;
  gap: 12px;
  list-style: none;
  padding: 0;
}
.workflow-demo__steps li {
  padding: 8px 12px;
  border-radius: 8px;
  background: var(--c-color-fill-1);
}
.workflow-demo__steps [aria-current] {
  color: var(--c-color-primary);
  font-weight: 700;
}
.workflow-demo dl {
  display: grid;
  grid-template-columns: 80px 1fr;
  gap: 8px;
}
.workflow-demo dd {
  margin: 0;
  overflow-wrap: anywhere;
}
.workflow-demo pre {
  white-space: pre-wrap;
  overflow-wrap: anywhere;
}
.workflow-demo small {
  display: block;
  margin-top: 12px;
  color: var(--c-color-text-2);
}
</style>
```

这个例子组合组件能力实现业务流程；保存用本地延迟模拟，实际接口由应用接入。字段校验与服务端保存失败是两种不同结果。

## 一组字段，一起比较

切换五档尺寸和三种变体，观察 Input、Select、日期时间字段的高度、前后缀和长标签。多行内容按内容撑高。

Example source: src/field-decorator/__demos__/control-sizes.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
const sizes = ["xs", "sm", "md", "lg", "xl"] as const;
const variants = ["outline", "filled", "standard"] as const;
const size = ref<(typeof sizes)[number]>("md");
const variant = ref<(typeof variants)[number]>("outline");
const options = [
  { value: "beijing", label: "Beijing" },
  { value: "shanghai", label: "Shanghai" },
];
const cascaderOptions = [{ value: "china", label: "China", children: options }];

const inputValue = ref("Beijing");
const selectValue = ref("beijing");
const cascaderValue = ref("beijing");
const selectMultiple = ref(["beijing", "shanghai"]);
const cascaderMultiple = ref(["beijing", "shanghai"]);
const selectOverflow = ref(["long", "beijing", "shanghai"]);
const cascaderOverflow = ref(["long", "beijing", "shanghai"]);
const selectedOptions = [
  ...options,
  {
    value: "long",
    label:
      "A very long selected option label for overflow comparison — full text preview keeps the selected value unchanged.",
  },
];
const selectedCascaderOptions = [
  { value: "china", label: "China", children: selectedOptions },
];
function resetSelections() {
  inputValue.value = "Beijing";
  selectValue.value = "beijing";
  cascaderValue.value = "beijing";
  selectMultiple.value = ["beijing", "shanghai"];
  cascaderMultiple.value = ["beijing", "shanghai"];
  selectOverflow.value = ["long", "beijing", "shanghai"];
  cascaderOverflow.value = ["long", "beijing", "shanghai"];
}
</script>
<template>
  <section
    aria-label="Form control size comparison"
    class="control-size-comparison"
  >
    <c-space wrap :size="12">
      <c-radio-group v-model="size" aria-label="Comparison size">
        <c-radio v-for="item in sizes" :key="item" :value="item">{{
          item
        }}</c-radio>
      </c-radio-group>
      <c-radio-group v-model="variant" aria-label="Comparison variant">
        <c-radio v-for="item in variants" :key="item" :value="item">{{
          item
        }}</c-radio>
      </c-radio-group>
    </c-space>
    <div class="control-size-comparison__grid">
      <div data-control="Input">
        <p>Input</p>
        <c-input :size="size" :variant="variant" placeholder="Input" />
      </div>
      <div data-control="Button">
        <p>Button</p>
        <c-button :size="size" variant="outline">Button</c-button>
      </div>
      <div data-control="Select">
        <p>Select</p>
        <c-select
          :size="size"
          :variant="variant"
          :options="options"
          placeholder="Select"
        />
      </div>
      <div data-control="Date">
        <p>Date</p>
        <c-date :size="size" :variant="variant" placeholder="Date" />
      </div>
      <div data-control="Time">
        <p>Time</p>
        <c-time :size="size" :variant="variant" placeholder="Time" />
      </div>
      <div data-control="InputNumber">
        <p>InputNumber</p>
        <c-input-number :size="size" :variant="variant" placeholder="Number" />
      </div>
      <div data-control="AutoComplete">
        <p>AutoComplete</p>
        <c-auto-complete
          :size="size"
          :variant="variant"
          :options="options"
          placeholder="AutoComplete"
        />
      </div>
      <div data-control="Cascader">
        <p>Cascader</p>
        <c-cascader
          :size="size"
          :variant="variant"
          :options="cascaderOptions"
          placeholder="Cascader"
        />
      </div>
      <div data-control="DateRange">
        <p>DateRange</p>
        <c-date-range
          :size="size"
          :variant="variant"
          :placeholder="['Start', 'End']"
        />
      </div>
      <div data-control="TimeRange">
        <p>TimeRange</p>
        <c-time-range
          :size="size"
          :variant="variant"
          :placeholder="['Start', 'End']"
        />
      </div>
    </div>

    <section
      aria-label="Selected control size comparison"
      class="control-size-comparison__states"
    >
      <c-space wrap align="center" :size="12">
        <span>Selected / Clearable / Multiple — 有值、可清空与多选不换行</span>
        <span
          >Hover or focus truncated text; tap on touch screens /
          悬停或聚焦省略正文查看全文；触屏点按查看，点外部关闭</span
        >
        <c-button size="sm" variant="outline" @click="resetSelections"
          >Reset / 恢复选中值</c-button
        >
      </c-space>
      <div class="control-size-comparison__grid">
        <div data-control="InputValue">
          <p>Input · clearable</p>
          <c-input
            v-model="inputValue"
            :size="size"
            :variant="variant"
            clearable
            placeholder="Input value"
          />
        </div>
        <div data-control="ButtonReference">
          <p>Button · reference</p>
          <c-button :size="size" variant="outline">Button</c-button>
        </div>
        <div data-control="SelectValue">
          <p>Select · clearable</p>
          <c-select
            v-model="selectValue"
            :size="size"
            :variant="variant"
            :options="selectedOptions"
            clearable
            placeholder="Select value"
          />
        </div>
        <div data-control="CascaderValue">
          <p>Cascader · clearable</p>
          <c-cascader
            v-model="cascaderValue"
            :size="size"
            :variant="variant"
            :options="selectedCascaderOptions"
            clearable
            placeholder="Cascader value"
          />
        </div>
        <div data-control="SelectMultiple">
          <p>Select · multiple / nowrap</p>
          <c-select
            v-model="selectMultiple"
            :size="size"
            :variant="variant"
            :options="selectedOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Select multiple"
          />
        </div>
        <div data-control="CascaderMultiple">
          <p>Cascader · multiple / nowrap</p>
          <c-cascader
            v-model="cascaderMultiple"
            :size="size"
            :variant="variant"
            :options="selectedCascaderOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Cascader multiple"
          />
        </div>
        <div data-control="SelectOverflow">
          <p>Select · long values / nowrap</p>
          <c-select
            v-model="selectOverflow"
            edit-mode="direct"
            :size="size"
            :variant="variant"
            :options="selectedOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Select long values"
          />
        </div>
        <div data-control="CascaderOverflow">
          <p>Cascader · long values / nowrap</p>
          <c-cascader
            v-model="cascaderOverflow"
            edit-mode="direct"
            :size="size"
            :variant="variant"
            :options="selectedCascaderOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Cascader long values"
          />
        </div>
      </div>
    </section>
  </section>
</template>
<style scoped>
.control-size-comparison,
.control-size-comparison__states {
  display: grid;
  gap: 24px;
}
.control-size-comparison__grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
  align-items: start;
  gap: 24px 16px;
}
.control-size-comparison__grid > div {
  min-width: 0;
}
.control-size-comparison__grid p {
  margin: 0 0 12px;
  font-size: 14px;
  line-height: 20px;
}
.control-size-comparison__grid :deep(.c-input-number),
.control-size-comparison__grid :deep(.c-auto-complete) {
  width: 100%;
}
</style>
```

## 从阅读进入编辑

1. 在下方选择 click 或 dblclick，按对应方式进入字段编辑。
2. 修改内容后取消，核对已保存模型；再修改并确认，核对模型更新。
3. 切换纯阅读状态，观察普通字段与单项覆盖字段的表现。

Example source: src/form/__demos__/field-presentation.vue

```vue
<script setup>
import ModelOutput from "../__demo-utils__/ModelOutput.vue";

import { computed, ref } from "vue";

const editMode = ref("direct");
const readPretty = ref(false);

const options = ref([
  { value: 1, label: "研发设备" },
  { value: 2, label: "设计设备" },
  { value: 3, label: "运营设备" },
]);
const form = ref({
  name: "默认可直接编辑",
  deviceIds: [2],
  note: "此项始终直接编辑",
  summary: "只读展示",
});
const status = ref("");

const modeOptions = ["direct", "click", "dblclick"].map((value) => ({
  label: value,
  value,
}));
const committed = computed(() => JSON.stringify(form.value));
const presentationHint = computed(() =>
  readPretty.value
    ? "只展示已保存的值；下方“单项覆盖 direct”通过 readPretty=false 保持可编辑。"
    : editMode.value === "direct"
      ? "直接编辑，即时更新下方模型；选择设备无需额外确认。"
      : "按展示方式进入编辑；确认才更新下方模型，取消不保存本次修改。",
);
</script>
<template>
  <c-space direction="column" align="stretch" :size="16">
    <c-form-item layout="vertical" size="sm" label="Form 展示方式">
      <c-radio-group
        aria-label="Form 展示方式"
        v-model="editMode"
        :options="modeOptions"
        variant="button"
        size="sm"
      />
    </c-form-item>
    <c-space wrap>
      <c-checkbox v-model="readPretty">纯阅读 readPretty</c-checkbox>
    </c-space>
    <p>
      {{ presentationHint }}<br />设备 4 已停用，最多选择 3
      个设备；可切换本地搜索与模拟远程搜索。
    </p>
    <c-form
      :model="form"
      :edit-mode="editMode"
      :read-pretty="readPretty"
      @submit-success="status = '表单已提交'"
      @submit-failed="status = '请完成当前编辑或修正校验错误'"
    >
      <c-form-item
        field="name"
        label="名称"
        :rules="[{ required: true, message: '名称不能为空' }]"
      >
        <c-input v-model="form.name" placeholder="请输入名称" clearable />
      </c-form-item>
      <c-form-item
        field="deviceIds"
        label="设备"
        :rules="[{ type: 'array', required: true, message: '请选择设备' }]"
      >
        <c-select
          v-model="form.deviceIds"
          :options="options"
          multiple
          filterable
          :limit="3"
          placeholder="搜索设备"
        />
      </c-form-item>
      <c-form-item
        field="note"
        label="单项覆盖 direct"
        edit-mode="direct"
        :read-pretty="false"
      >
        <c-input v-model="form.note" />
      </c-form-item>
      <c-form-item field="summary" label="固定 readPretty" read-pretty>
        <c-input v-model="form.summary" />
      </c-form-item>
      <c-button html-type="submit">提交表单</c-button>
    </c-form>
    <ModelOutput role="status">当前模型：{{ committed }}</ModelOutput>
    <p v-if="status" role="status">{{ status }}</p>
  </c-space>
</template>
```

## 与其他实现对照什么

使用相同字段和校验规则，比较样式配置的重复程度、阅读态渲染方式、确认与取消的数据流，以及单字段覆盖是否需要额外封装。记录完成这个场景所需的业务代码与交互结果。

继续阅读：[Form](llms/zh-CN/components/form.md) · [Input](llms/zh-CN/components/input.md) · [Select](llms/zh-CN/components/select.md)

---

[返回总览，标记已体验](llms/zh-CN/showcase.md) · [下一站：主题与品牌](llms/zh-CN/showcase/themes.md)

---

Document: llms/zh-CN/showcase/loading.md

<!-- Source: docs/showcase/loading.md; locale: zh-CN; page: /showcase/loading/ -->

# 加载与等待

以活动报名为场景，集中观察各组件的加载位置、尺寸和布局变化。所有等待均使用本地计时，不请求业务接口；选择文件也不会发起上传。

1. 填写报名信息，或点击卡片上的「体验等待」，观察 2 秒后的恢复。
2. 开启「全部保持加载」比较各组件；「重置加载」停止等待，保留填写内容。
3. 单独切换「等待时禁止编辑」，对照 loading 与 disabled；再切换文本字段的默认指示器与底线。
4. 打开报名确认，观察 before-close 等待；关闭检查不通过时，弹层会保留。

Example source: docs/showcase/demos/loading-lab.vue

```vue
<script setup lang="ts">
import { computed, markRaw, onBeforeUnmount, reactive, ref } from 'vue'
import CButton from '../../../src/button'
import '../../../src/button/style'
import CSplitButton from '../../../src/split-button'
import '../../../src/split-button/style'
import CLink from '../../../src/link'
import '../../../src/link/style'
import CSwitch from '../../../src/switch'
import '../../../src/switch/style'
import CTag from '../../../src/tag'
import '../../../src/tag/style'
import CInput from '../../../src/input'
import '../../../src/input/style'
import CTextarea from '../../../src/textarea'
import '../../../src/textarea/style'
import CInputNumber from '../../../src/input-number'
import '../../../src/input-number/style'
import CSelect from '../../../src/select'
import '../../../src/select/style'
import CCascader from '../../../src/cascader'
import '../../../src/cascader/style'
import CAutoComplete from '../../../src/auto-complete'
import '../../../src/auto-complete/style'
import CDate from '../../../src/date'
import '../../../src/date/picker/style'
import CDateRange from '../../../src/date-range'
import CTime from '../../../src/time'
import '../../../src/time/picker/style'
import CTimeRange from '../../../src/time-range'
import CPeopleSelect from '../../../src/people-select'
import '../../../src/people-select/style'
import CSearch from '../../../src/search'
import '../../../src/search/style'
import CFieldDecorator from '../../../src/field-decorator'
import '../../../src/field-decorator/style'
import CTable from '../../../src/table'
import '../../../src/table/style'
import CList from '../../../src/list'
import '../../../src/list/style'
import CSkeleton from '../../../src/skeleton'
import '../../../src/skeleton/style'
import CLoading from '../../../src/loading'
import '../../../src/loading/style'
import CTreeSelect from '../../../src/tree-select'
import '../../../src/tree-select/style'
import CInputTag from '../../../src/input-tag'
import '../../../src/input-tag/style'
import CMention from '../../../src/mention'
import '../../../src/mention/style'
import CForm from '../../../src/form'
import '../../../src/form/style'
import { FormItem as CFormItem } from '../../../src/form'
import CDialog from '../../../src/dialog'
import '../../../src/dialog/style'
const cities = [{ label: '上海', value: 'shanghai' }, { label: '杭州', value: 'hangzhou' }]
const venues = [{ label: '上海', value: 'shanghai', children: [{ label: '设计中心', value: 'studio' }] }]
const fieldCards = [{ id: 'input', component: markRaw(CInput), title: '姓名', description: '查询报名信息', props: { defaultValue: '林小满', placeholder: '姓名' }, text: '', lockable: true },
{ id: 'textarea', component: markRaw(CTextarea), title: '备注', description: '保存报名备注', props: { defaultValue: '希望参加设计工作坊', placeholder: '备注' }, text: '', lockable: true },
{ id: 'input-number', component: markRaw(CInputNumber), title: '同行人数', description: '更新人数', props: { defaultValue: 2, min: 1 }, text: '', lockable: true },
{ id: 'select', component: markRaw(CSelect), title: '活动城市', description: '读取候选城市', props: { defaultValue: 'shanghai', options: cities, editMode: 'direct' }, text: '', lockable: true },
{ id: 'cascader', component: markRaw(CCascader), title: '活动场地', description: '读取级联场地', props: { options: venues, editMode: 'direct' }, text: '', lockable: true },
{ id: 'auto-complete', component: markRaw(CAutoComplete), title: '活动搜索', description: '查询匹配活动', props: { options: ['设计工作坊', '开发者交流'], placeholder: '搜索活动' }, text: '', lockable: true },
{ id: 'date', component: markRaw(CDate), title: '报名日期', description: '读取可选日期', props: { editMode: 'direct' }, text: '', lockable: true },
{ id: 'date-range', component: markRaw(CDateRange), title: '活动日期范围', description: '查询可用档期', props: { editMode: 'direct' }, text: '', lockable: true },
{ id: 'time', component: markRaw(CTime), title: '到场时间', description: '读取可用时间', props: { editMode: 'direct' }, text: '', lockable: true },
{ id: 'time-range', component: markRaw(CTimeRange), title: '参与时段', description: '查询可用时段', props: { editMode: 'direct' }, text: '', lockable: true },
{ id: 'people-select', component: markRaw(CPeopleSelect), title: '同行伙伴', description: '读取人员信息', props: { options: [{ label: '林小满', value: 'lin' }], editMode: 'direct' }, text: '', lockable: true },
{ id: 'search', component: markRaw(CSearch), title: '搜索报名', description: '查询报名记录', props: { placeholder: '输入姓名' }, text: '', lockable: true },
{ id: 'field-decorator', component: markRaw(CFieldDecorator), title: '通用字段容器', description: '观察容器的默认与底线反馈', props: {}, text: '容器内容', lockable: true },
{ id: 'tree-select', component: markRaw(CTreeSelect), title: '组织部门', description: '读取组织树', props: { options: [{ label: '设计部', value: 'design', children: [{ label: '体验组', value: 'ux' }] }], editMode: 'direct' }, text: '', lockable: true },
{ id: 'input-tag', component: markRaw(CInputTag), title: '活动标签', description: '保存标签', props: { defaultValue: ['设计', '交流'] }, text: '', lockable: true },
{ id: 'mention', component: markRaw(CMention), title: '邀请同伴', description: '查询提及候选', props: { options: [{ label: '林小满', value: 'lin' }] }, text: '', lockable: true }]
const actionCards = [{ id: 'button', component: markRaw(CButton), title: '提交报名', description: '业务控制按钮等待', props: {}, text: '提交报名', lockable: true },
{ id: 'split-button', component: markRaw(CSplitButton), title: '报名操作', description: '主按钮等待', props: {}, text: '保存报名', lockable: true },
{ id: 'link', component: markRaw(CLink), title: '查看报名详情', description: '链接等待', props: {}, text: '查看详情', lockable: true },
{ id: 'switch', component: markRaw(CSwitch), title: '接收短信', description: '开关保存', props: { defaultValue: true }, text: '', lockable: true },
{ id: 'tag', component: markRaw(CTag), title: '参与者身份', description: '标签状态更新', props: {}, text: '体验官', lockable: true }]
const groups = [{ title: '01 · 填写与数据选择', cards: fieldCards },
{ title: '02 · 提交与状态操作', cards: actionCards }]
const held = ref(false)
const lock = ref(false)
const line = ref(false)
const pending = reactive<Record<string, boolean>>({})
const completed = reactive<Record<string, boolean>>({})
const timers = new Map<string, ReturnType<typeof setTimeout>>()
const ids = [...fieldCards, ...actionCards].map(card => card.id).concat(['table', 'list', 'skeleton', 'loading'])

const busyCount = computed(() => ids.filter(id => isLoading(id)).length)
const status = ref('点击卡片上的「体验等待」，对照加载与恢复。')
function isLoading(id: string) { return held.value || Boolean(pending[id]) }
function run(id: string) {
  if (held.value || pending[id]) return
  pending[id] = true
  completed[id] = false
  status.value = `${id} 正在等待；2 秒后恢复。`
  timers.set(id, setTimeout(() => {
    pending[id] = false
    completed[id] = true
    timers.delete(id)
    status.value = `${id} 已完成，输入内容保留。`
  }, 2000))
}
function runAll() { held.value = false; ids.forEach(run) }
function reset() {
  held.value = false
  timers.forEach(timer => clearTimeout(timer))
  timers.clear()
  ids.forEach(id => { pending[id] = false; completed[id] = false })
  status.value = '已恢复全部加载状态，填写内容保留。'
}
const open = ref(false)
const allowClose = ref(true)
const guardStatus = ref('打开报名确认，关闭时等待 2 秒。')
const guardWaits = new Map<ReturnType<typeof setTimeout>, (allowed: boolean) => void>()
function beforeClose() {
  guardStatus.value = '正在检查报名状态…'
  return new Promise<boolean>(resolve => {
    const timer = setTimeout(() => {
      guardWaits.delete(timer)
      guardStatus.value = allowClose.value ? '检查通过，允许关闭。' : '本次未通过，弹层保留，可再次尝试。'
      resolve(allowClose.value)
    }, 2000)
    guardWaits.set(timer, resolve)
  })
}
onBeforeUnmount(() => { reset(); guardWaits.forEach((resolve, timer) => { clearTimeout(timer); resolve(false) }); guardWaits.clear() })
const columns = [{ title: '参与人', dataIndex: 'name' }, { title: '活动', dataIndex: 'event' }]
const rows = [{ key: '1', name: '林小满', event: '设计工作坊' }, { key: '2', name: '周青', event: '开发者交流' }]
</script>
<template>
  <div class="loading-lab">
    <header class="loading-lab__hero">
      <p class="loading-lab__eyebrow">LOADING / 活动报名工作台</p>
      <h2>让每一次等待都看得见</h2>
      <p>逐项填写报名信息，观察各组件如何表达等待；也可以保持全部加载，比较位置、尺寸与布局。</p>
      <CForm layout="vertical">
        <div class="loading-lab__controls">
          <CFormItem label="全部保持加载"><CSwitch v-model="held" aria-label="全部保持加载" /></CFormItem>
          <CFormItem label="等待时禁止编辑"><CSwitch v-model="lock" aria-label="等待时禁止编辑" /></CFormItem>
          <CFormItem label="文本字段使用底线"><CSwitch v-model="line" aria-label="文本字段使用底线" /></CFormItem>
        </div>
      </CForm>
      <div class="loading-lab__buttons"><CButton @click="runAll">全部等待 2 秒</CButton><CButton variant="outline" @click="reset">重置加载</CButton><span>{{ busyCount }} / {{ ids.length }} 项正在等待</span></div>
      <p role="status" aria-live="polite">{{ status }}</p>
      <small>所有等待均在本地模拟。loading 与 disabled 分别控制；切换底线只影响支持 loading-mode 的字段。</small>
    </header>
    <section v-for="group in groups" :key="group.title" class="loading-lab__section">
      <h3>{{ group.title }}</h3>
      <div class="loading-lab__grid">
        <article v-for="card in group.cards" :key="card.id" class="loading-lab__card" :data-loading-card="card.id">
          <div class="loading-lab__heading"><strong>{{ card.title }}</strong><code>{{ card.id }}</code></div>
          <p>{{ card.description }}</p>
          <div class="loading-lab__preview">
            <component v-if="card.text" :is="card.component" v-bind="card.id === 'split-button' ? { ...card.props, buttonProps: { loading: isLoading(card.id), disabled: lock && isLoading(card.id) } } : card.props" :loading="isLoading(card.id)" :disabled="lock && isLoading(card.id)" @change="run(card.id)">{{ card.text }}</component>
            <component v-else :is="card.component" v-bind="card.id === 'split-button' ? { ...card.props, buttonProps: { loading: isLoading(card.id), disabled: lock && isLoading(card.id) } } : card.props" :loading="isLoading(card.id)" :loading-mode="line ? 'line' : 'default'" :disabled="lock && isLoading(card.id)" @change="run(card.id)" />
          </div>
          <div class="loading-lab__footer"><CButton size="sm" variant="text" :disabled="isLoading(card.id)" @click="run(card.id)">体验等待</CButton><span>{{ isLoading(card.id) ? '等待中…' : completed[card.id] ? '已完成' : '就绪' }}</span></div>
        </article>
      </div>
    </section>
    <section class="loading-lab__section">
      <h3>03 · 内容区域</h3>
      <div class="loading-lab__grid">
        <article v-for="kind in ['table', 'list', 'skeleton', 'loading']" :key="kind" class="loading-lab__card" :data-loading-card="kind">
          <div class="loading-lab__heading"><strong>{{ {upload:'上传报名材料',table:'报名记录',list:'报名清单',skeleton:'初次读取占位',loading:'通用内容等待'}[kind] }}</strong><code>{{ kind }}</code></div>
          <div class="loading-lab__preview">
            
            <CTable v-if="kind === 'table'" :loading="isLoading(kind)" :columns="columns" :data="rows" :pagination="false" />
            <CList v-if="kind === 'list'" :loading="isLoading(kind)"><p>林小满 · 设计工作坊</p><p>周青 · 开发者交流</p></CList>
            <CSkeleton v-if="kind === 'skeleton'" :loading="isLoading(kind)"><p>报名信息已加载，可以继续填写。</p></CSkeleton>
            <CLoading v-if="kind === 'loading'" :loading="isLoading(kind)" tip="正在读取报名信息"><p class="loading-lab__placeholder">活动报名内容</p></CLoading>
          </div>
          <div class="loading-lab__footer"><CButton size="sm" variant="text" :disabled="isLoading(kind)" @click="run(kind)">体验等待</CButton><span>{{ isLoading(kind) ? '等待中…' : '就绪' }}</span></div>
        </article>
        
        
      </div>
    </section>
    <section class="loading-lab__section loading-lab__guard" data-loading-card="dialog">
      <h3>04 · 确认报名与关闭等待</h3>
      <p>关闭弹层时由 before-close 等待 2 秒。关闭检查不通过时保留弹层；可以切换后再次尝试。</p>
      <CForm layout="vertical"><CFormItem label="允许关闭"><CSwitch v-model="allowClose" aria-label="允许关闭" /></CFormItem></CForm>
      <CButton @click="open = true">打开报名确认</CButton>
      <CDialog v-model:open="open" title="确认报名" :before-close="beforeClose"><p>请确认活动报名信息。点击确认、取消或关闭，观察等待反馈。</p><CForm layout="vertical"><CFormItem label="允许关闭"><CSwitch v-model="allowClose" aria-label="弹层内允许关闭" /></CFormItem></CForm><p role="status">{{ guardStatus }}</p></CDialog>
      <p aria-live="polite">{{ guardStatus }}</p>
    </section>
  </div>
</template>
<style scoped>
.loading-lab { color: var(--c-sys-color-content-primary, inherit); min-width: 0; }
.loading-lab__hero, .loading-lab__guard { padding: 24px; border: 1px solid var(--c-sys-color-outline-default, #dce4e7); border-radius: 18px; background: var(--c-sys-color-surface-container, #f5f8f9); }
.loading-lab__eyebrow { letter-spacing: .12em; font-size: 12px; opacity: .7; }
.loading-lab__hero h2 { margin: 8px 0 12px; font-size: 28px; }
.loading-lab__controls { display: grid; grid-template-columns: repeat(auto-fit, minmax(180px, 1fr)); gap: 12px; }
.loading-lab__buttons, .loading-lab__footer { display: flex; align-items: center; flex-wrap: wrap; gap: 12px; }
.loading-lab__section { margin-block: 28px; }
.loading-lab__grid { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 16px; }
.loading-lab__card { min-width: 0; padding: 20px; border: 1px solid var(--c-sys-color-outline-default, #dce4e7); border-radius: 14px; }
.loading-lab__card--wide { grid-column: 1 / -1; }
.loading-lab__heading { display: flex; flex-wrap: wrap; align-items: center; justify-content: space-between; gap: 8px; }
.loading-lab__heading code { font-size: 12px; opacity: .65; }
.loading-lab__card p { font-size: 13px; opacity: .8; }
.loading-lab__preview { min-height: 72px; padding-block: 18px; min-width: 0; overflow-wrap: anywhere; }
.loading-lab__footer { justify-content: space-between; font-size: 12px; }
.loading-lab__placeholder, .loading-lab__popup { padding: 24px; }
.loading-lab__popup { min-width: 0; max-width: 90vw; }
@media (max-width: 600px) { .loading-lab__grid { grid-template-columns: minmax(0, 1fr); } .loading-lab__hero, .loading-lab__card, .loading-lab__guard { padding: 16px; } .loading-lab__hero h2 { font-size: 24px; } }
</style>
```

这里只展示有明确加载语义的输入、数据选择、操作与内容区域。普通事件不会自动收集 Promise。Upload 的文件进度与 before 等待在其专属案例中演示；Scheduler 的保存守卫放在 Scheduler 文档内说明。

## 更多 before 等待场景

### Drawer

Example source: src/drawer/__demos__/guard-protocol.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import type { DrawerBeforeClose } from "@cedar-design/ui";
const open = ref(false);
const mode = ref("promise");
const allowed = ref(true);
const status = ref("");
const check: DrawerBeforeClose = (payload, done, { signal }) => {
  status.value = `等待： ${payload.action}`;
  if (mode.value === "done") {
    setTimeout(() => {
      status.value = allowed.value ? "允许" : "阻止";
      done(!signal.aborted && allowed.value);
    }, 500);
    return;
  }
  return new Promise<boolean>((resolve) =>
    setTimeout(() => {
      status.value = allowed.value ? "允许" : "阻止";
      resolve(!signal.aborted && allowed.value);
    }, 500),
  );
};
</script>
<template>
  <c-space direction="column" align="stretch">
    <c-form-item layout="vertical" label="允许关闭"><c-switch v-model="allowed" aria-label="允许关闭" /></c-form-item>
    <c-form-item layout="vertical" size="sm" label="mode">
      <c-radio-group
        aria-label="mode"
        v-model="mode"
        :options="[
          { value: 'promise', label: 'Promise' },
          { value: 'done', label: 'done 回调' },
        ]"
        variant="button"
        size="sm"
      />
    </c-form-item>
    <c-button @click="open = true">打开</c-button>
    <c-drawer
      v-model:open="open"
      :before-close="check"
      @guard-error="status = 'Error'"
    >
      <p>关闭前等待片刻。可以关闭开关体验一次拦截，再在抽屉内重新允许关闭并重试。</p>
      <c-form-item layout="vertical" label="允许关闭"><c-switch v-model="allowed" aria-label="抽屉内允许关闭" /></c-form-item>
      <c-button @click="allowed = true; open = false">允许并关闭</c-button>
      <p role="status">{{ status }}</p>
    </c-drawer>
    <p role="status">{{ status }}</p>
  </c-space>
</template>
```

### Popconfirm

Example source: src/popconfirm/__demos__/guard-protocol.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import type { PopconfirmBeforeConfirm } from "@cedar-design/ui";
const open = ref(false);
const mode = ref("promise");
const allowed = ref(false);
const status = ref("");
const check: PopconfirmBeforeConfirm = (payload, done, { signal }) => {
  status.value = `等待： ${payload.action}`;
  if (mode.value === "done") {
    setTimeout(() => {
      status.value = allowed.value ? "允许" : "阻止";
      done(!signal.aborted && allowed.value);
    }, 500);
    return;
  }
  return new Promise<boolean>((resolve) =>
    setTimeout(() => {
      status.value = allowed.value ? "允许" : "阻止";
      resolve(!signal.aborted && allowed.value);
    }, 500),
  );
};
</script>
<template>
  <c-space direction="column" align="stretch">
    <c-switch v-model="allowed" />
    <c-form-item layout="vertical" size="sm" label="mode">
      <c-radio-group
        aria-label="mode"
        v-model="mode"
        :options="[
          { value: 'promise', label: 'Promise' },
          { value: 'done', label: 'done 回调' },
        ]"
        variant="button"
        size="sm"
      />
    </c-form-item>
    <c-button @click="open = true">打开</c-button>
    <c-popconfirm
      v-model:open="open"
      :before-confirm="check"
      @guard-error="status = 'Error'"
    >
      <template #default
        ><c-button v-if="true" @click="open = true">Confirm action</c-button
        ><span v-else>通过 beforeClose 关闭</span></template
      >
    </c-popconfirm>
    <p role="status">{{ status }}</p>
  </c-space>
</template>
```

---

Document: llms/zh-CN/showcase/scheduling.md

<!-- Source: docs/showcase/scheduling.md; locale: zh-CN; page: /showcase/scheduling/ -->

# 资源排期

Scheduler 用于日程展示与编辑，可关联人员、设备或会议室。先体验时间调整，再加入资源与容量约束。

## 拖动与调整时间

1. 拖动一条日程，观察落点预览和预计起止时间。
2. 调整日程上、下边缘，观察步长吸附。
3. 拖动时按 Esc 取消，核对下方已提交日程没有变化。

Example source: src/scheduler/__demos__/drag-feedback.vue

```vue
<template>
  <section class="scheduler-drag-demo">
    <p>
      拖动日程主体查看虚影和目标预览；拖上边缘调整开始，拖下边缘调整结束。按
      Escape 取消，松手才提交。
    </p>
    <c-scheduler
      v-model="events"
      default-date="2026-09-09"
      default-mode="resource-day"
      :resources="resources"
      resource-label="工作台"
      :start-hour="8"
      :end-hour="16"
      :step="15"
      :show-sidebar="false"
      style="--c-scheduler-max-height: 560px"
    >
      <template #event="{ event }">
        <strong>{{ event.title }}</strong
        ><br />
        <span>{{ event.description }}</span>
      </template>
    </c-scheduler>
    <c-button @click="events = createEvents()">重置日程</c-button>
    <ul aria-label="已提交日程">
      <li v-for="event in events" :key="event.id" :data-demo-event="event.id">
        {{ event.title }}：{{ event.start }} → {{ event.end }}；资源：{{
          event.resourceIds?.join(", ") || "无"
        }}
      </li>
    </ul>
  </section>
</template>
<script setup lang="ts">
import { ref } from "vue";
import type { SchedulerEvent, SchedulerResource } from "@cedar-design/ui";
const resources: SchedulerResource[] = [
  { id: "a", label: "工作台 A" },
  { id: "b", label: "工作台 B" },
];
function createEvents(): SchedulerEvent[] {
  return [
    {
      id: "design",
      title: "方案制作",
      description: "自定义卡片内容也会出现在虚影中",
      start: "2026-09-09T09:00:00",
      end: "2026-09-09T10:30:00",
      resourceIds: ["a"],
    },
    {
      id: "review",
      title: "验收检查",
      description: "试着拖动上边缘或下边缘",
      start: "2026-09-09T11:00:00",
      end: "2026-09-09T12:00:00",
      resourceIds: ["b"],
    },
  ];
}
const events = ref(createEvents());
</script>
```

## 人员与设备的共同资源模型

体验设备排期中的工单拖入、联合占用和维护时段。同一资源 API 可以表达人员与设备，业务字段通过 metadata 和插槽接入。

Example source: src/scheduler/__demos__/equipment.vue

```vue
<template>
  <p>
    设备共享使用时段：拖入左侧任务后确认排期；维护中的设备禁止新增分配，同一设备的时间冲突会阻止保存。
  </p>
  <c-scheduler
    v-model="events"
    :resources="devices"
    resource-label="设备"
    default-mode="resource-day"
    default-date="2026-09-09"
    :allow-overlap="false"
  >
    <template #sidebar-extra="{ startDrag, cancelDrag, disabled }">
      <strong>待安排工单</strong>
      <c-button
        v-for="task in tasks"
        :key="String(task.metadata?.taskId)"
        :draggable="!disabled"
        :disabled="disabled"
        @dragstart="startDrag(task, $event)"
        @dragend="cancelDrag"
      >
        {{ task.title }} · {{ task.duration }} 分钟
      </c-button>
    </template>
    <template #resource-header="{ resource, date }">
      <strong>{{ resource?.label ?? date.toLocaleDateString() }}</strong>
      <small v-if="resource">
        · {{ resource.disabled ? "维护中" : "可预约" }}</small
      >
    </template>
    <template #event="{ event }">
      <strong>{{ event.title }}</strong
      ><span v-if="event.metadata?.taskId">
        · {{ event.metadata?.taskId }}</span
      >
    </template>
  </c-scheduler>
</template>
<script setup lang="ts">
import { ref } from "vue";
import type {
  SchedulerEvent,
  SchedulerResource,
  SchedulerEventTemplate,
} from "@cedar-design/ui";
const devices: SchedulerResource[] = [
  { id: "laser-01", label: "激光切割机 01" },
  { id: "printer-02", label: "3D 打印机 02" },
  { id: "scanner-03", label: "扫描仪 03", disabled: true },
];
const tasks: SchedulerEventTemplate[] = [
  {
    title: "样件加工",
    duration: 90,
    metadata: { taskId: "JOB-201" },
    description: "安排加工设备并确认材料",
  },
  {
    title: "设备校准",
    duration: 30,
    metadata: { taskId: "JOB-202" },
    description: "校准完成后记录结果",
  },
];
const events = ref<SchedulerEvent[]>([
  {
    id: "run-1",
    title: "批次 A 加工",
    start: "2026-09-09T09:00:00",
    end: "2026-09-09T11:00:00",
    resourceIds: ["laser-01"],
    metadata: { taskId: "JOB-100" },
  },
  {
    id: "run-2",
    title: "联合验收（共用两台设备）",
    start: "2026-09-09T14:00:00",
    end: "2026-09-09T15:00:00",
    resourceIds: ["laser-01", "printer-02"],
    metadata: { taskId: "JOB-101" },
  },
  {
    id: "maintenance",
    title: "停机维护",
    start: "2026-09-09",
    end: "2026-09-10",
    allDay: true,
    resourceIds: ["scanner-03"],
    readonly: true,
  },
]);
</script>
```

## 与其他实现对照什么

在相同日程和资源数据下，比较视图切换、拖动预览、时间拉伸、冲突反馈及编辑器扩展。进一步检查异步保存失败是否保留原值、重试是否重复提交。对照排期产品时还应记录版本、授权范围和所用插件。

继续阅读：[Scheduler](llms/zh-CN/components/scheduler.md) · [任务日历工作台](llms/zh-CN/examples/task-calendar.md)

---

[返回总览，标记已体验](llms/zh-CN/showcase.md) · [下一站：逐组件对照](llms/zh-CN/showcase/components.md)

---

Document: llms/zh-CN/showcase/strengths.md

<!-- Source: docs/showcase/strengths.md; locale: zh-CN; page: /showcase/strengths/ -->

# 核心特点

Cedar 的特点既体现在单个组件，也体现在跨组件的约定和业务流程中。这里整理了 23 个有现有示例支撑的展示点，覆盖 体系级特点、场景组合能力、交互与数据特点、业务组件特点、工程保障。

## 演示时先讲什么

- **跨组件一致性**：一起切换输入、选择和日期字段的尺寸、变体，观察一组字段如何遵循共同约定。
- **阅读与编辑闭环**：修改、取消、确认及拒绝后重试，核对临时输入与已保存数据。
- **业务数据接入**：从 ID 回显、搜索候选到人员操作，展示字段如何连接业务模型与服务。
- **复杂业务组合**：操作列管理、上传准备与排期事务，观察保存、失败恢复和自定义接入。

以下属于本库的设计取向、已实现能力和工程保障。是否比某个参考库更省配置或体验更好，需要在逐组件页中按同一业务任务验证。

## 体系级特点

### 桌面与移动沿用同一套公共约定

公共尺寸、变体、值绑定与主题语言对齐，端侧密度和操作形态分别适配。

演示方法：使用同一巡检任务：Cedar 在字段附近操作；Maple 的选择与日期时间进入 Popup。先取消，再确认，对照已提交模型。

[打开对应示例](llms/zh-CN/components/form.md#桌面与移动的同场景展示) · 相关组件：[Button 按钮](llms/zh-CN/components/button.md)、[Input 输入框](llms/zh-CN/components/input.md)、[Select 下拉框](llms/zh-CN/components/select.md)、[Form 表单](llms/zh-CN/components/form.md)

### 主题从品牌延伸到组件与局部覆盖

品牌、语义颜色与组件变量分层，亮暗模式和局部覆盖可以组合使用。

演示方法：切换品牌和亮暗，再比较默认按钮与局部覆盖按钮，随后打开字段弹层。

[打开对应示例](llms/zh-CN/themes.md) · 相关组件：[ConfigProvider 全局配置](llms/zh-CN/components/config-provider.md)、[StyleProvider](llms/zh-CN/components/style-provider.md)、[Button 按钮](llms/zh-CN/components/button.md)、[FieldDecorator 字段外壳](llms/zh-CN/components/field-decorator.md)

### 跨控件保持字段外观与几何一致

Input、Select、日期时间字段通过共同外壳组织尺寸、变体、前后缀和清除区域。

演示方法：一次切换尺寸与变体，对照普通、有值、多选长标签和日期范围字段。

[打开对应示例](llms/zh-CN/components/field-decorator.md#表单控件尺寸对照) · 相关组件：[FieldDecorator 字段外壳](llms/zh-CN/components/field-decorator.md)、[Input 输入框](llms/zh-CN/components/input.md)、[Textarea 文本域](llms/zh-CN/components/textarea.md)、[Select 下拉框](llms/zh-CN/components/select.md)、[Cascader 级联选择](llms/zh-CN/components/cascader.md)、[Date 日期字段](llms/zh-CN/components/date.md)、[Time 时间字段](llms/zh-CN/components/time.md)、[Button 按钮](llms/zh-CN/components/button.md)

### 同一字段承接阅读与编辑

Form、FormItem 与字段可继承阅读展示和编辑方式，字段可以覆盖父级配置。

演示方法：切换阅读态、直接编辑和确认后提交，再查看单项覆盖。

[打开对应示例](llms/zh-CN/components/form.md#字段展示与确认提交) · 相关组件：[Form 表单](llms/zh-CN/components/form.md)、[Input 输入框](llms/zh-CN/components/input.md)、[Textarea 文本域](llms/zh-CN/components/textarea.md)、[InputNumber 数字输入框](llms/zh-CN/components/input-number.md)、[Select 下拉框](llms/zh-CN/components/select.md)、[PeopleSelect 人员选择](llms/zh-CN/components/people-select.md)、[Date 日期字段](llms/zh-CN/components/date.md)、[Time 时间字段](llms/zh-CN/components/time.md)、[Upload 上传](llms/zh-CN/components/upload.md)

### 日期时间字段和独立面板分别使用

带触发器的字段与可嵌入的面板分层，单值、范围和提交规则按公开契约接入。

演示方法：对照带输入框的字段与内嵌面板，检查手输、取消和确认后的值。

[打开对应示例](llms/zh-CN/components/date.md#字段视口与快捷项事件) · 相关组件：[Date 日期字段](llms/zh-CN/components/date.md)、[DateRange 日期范围字段](llms/zh-CN/components/date-range.md)、[Time 时间字段](llms/zh-CN/components/time.md)、[TimeRange 时间范围字段](llms/zh-CN/components/time-range.md)、[DatePicker 日期面板](llms/zh-CN/components/date-picker.md)、[TimePicker 时间面板](llms/zh-CN/components/time-picker.md)

## 场景组合能力

### 筛选、行操作和统计来自同一份业务数据

条件查询、状态变更、空结果与统计联动，桌面表格与移动表格使用同一任务场景。

演示方法：查询运营部 → 完成任务 → 按状态过滤 → 空结果 → 清空筛选并恢复任务。

[打开对应示例](llms/zh-CN/components/table.md#任务筛选与数据联动) · 相关组件：[Table 表格](llms/zh-CN/components/table.md)、[Input 输入框](llms/zh-CN/components/input.md)、[Select 下拉框](llms/zh-CN/components/select.md)

业务流程示例使用本地数据与模拟保存，不代表组件内置业务后端。

### 从字段校验走到确认、失败与恢复

把 Form 校验、预览和保存状态组合为业务流程，失败保留草稿，提交记录独立保存。

演示方法：空值校验 → 填入数据 → 返回修改 → 模拟失败 → 重试成功 → 查看提交记录。

[打开对应示例](llms/zh-CN/components/form.md#巡检任务完整流程) · 相关组件：[Form 表单](llms/zh-CN/components/form.md)、[Input 输入框](llms/zh-CN/components/input.md)、[Select 下拉框](llms/zh-CN/components/select.md)

业务流程示例使用本地数据与模拟保存，不代表组件内置业务后端。

## 交互与数据特点

### 编辑过程具有草稿、确认和失败恢复语义

编辑过程区分临时输入与已保存值，确认失败时可以保留内容供用户修正。

演示方法：修改后取消，再模拟拒绝确认并重试；观察最终模型和仍在编辑的内容。

[打开对应示例](llms/zh-CN/components/form.md#禁用、只读与异步确认) · 相关组件：[Form 表单](llms/zh-CN/components/form.md)、[Input 输入框](llms/zh-CN/components/input.md)、[Select 下拉框](llms/zh-CN/components/select.md)、[Date 日期字段](llms/zh-CN/components/date.md)、[Time 时间字段](llms/zh-CN/components/time.md)

Cedar 的 click/dblclick 原位编辑还包含字段切换与面板键盘优先级；Maple 按自身弹层交互演示。

### 候选高亮、搜索词、草稿与业务值分开

打开或搜索候选时不应意外提交表单，选择和确认按字段展示方式更新模型。

演示方法：先打开、搜索和移动候选，再选择与确认，对照更新次数与真实事件。

[打开对应示例](llms/zh-CN/components/select.md#候选高亮与表单数据流) · 相关组件：[Select 下拉框](llms/zh-CN/components/select.md)、[AutoComplete 自动补全](llms/zh-CN/components/auto-complete.md)、[PeopleSelect 人员选择](llms/zh-CN/components/people-select.md)、[Cascader 级联选择](llms/zh-CN/components/cascader.md)、[TreeSelect 树选择](llms/zh-CN/components/tree-select.md)、[Form 表单](llms/zh-CN/components/form.md)

### 远程搜索与已选 ID 回显分工

候选获取和已选内容解析分别接入业务服务，处理异步状态与过期结果。

演示方法：从仅有 ID 的模型开始，展示名称回显，再连续切换搜索词。

[打开对应示例](llms/zh-CN/components/people-select.md#完整业务示例) · 相关组件：[Select 下拉框](llms/zh-CN/components/select.md)、[PeopleSelect 人员选择](llms/zh-CN/components/people-select.md)、[AutoComplete 自动补全](llms/zh-CN/components/auto-complete.md)、[TreeSelect 树选择](llms/zh-CN/components/tree-select.md)

### 数值显示格式与业务数字分离

formatter / parser 处理展示与解析，精度、步长及边界共同约束最终数值。

演示方法：输入带格式的值，再尝试小数步长和边界，观察模型中保存的数字。

[打开对应示例](llms/zh-CN/components/input-number.md#小步长与范围边界) · 相关组件：[InputNumber 数字输入框](llms/zh-CN/components/input-number.md)、[Form 表单](llms/zh-CN/components/form.md)

模型仍为 JavaScript number；不将十进制计算等同于任意精度的大数存储。

### 上传准备与取消竞争有明确处理

异步准备、取消、重试和迟到请求句柄之间隔离失效结果，文件替换后重新检查限制。

演示方法：等待准备时取消并重新提交，再放行旧结果，核对有效请求与文件状态。

[打开对应示例](llms/zh-CN/components/upload.md#上传前准备与取消竞争) · 相关组件：[Upload 上传](llms/zh-CN/components/upload.md)

### 浮层开合、异步关闭和焦点按职责处理

弹层的展示控制、异步确认及焦点恢复与业务保存逻辑配合，嵌套时按当前层操作。

演示方法：在弹层内打开字段面板，尝试 Esc 和拒绝关闭，再核对焦点返回。

[打开对应示例](llms/zh-CN/components/dialog.md#高级属性) · 相关组件：[Dialog 对话框](llms/zh-CN/components/dialog.md)、[Drawer 抽屉](llms/zh-CN/components/drawer.md)、[Popover 气泡卡片](llms/zh-CN/components/popover.md)、[Trigger 浮层触发](llms/zh-CN/components/trigger.md)

## 业务组件特点

### 人员字段可以连接业务操作

人员显示与选择复用统一字段行为；头像与操作区由业务提供，不绑定聊天 SDK。

演示方法：同一人员 ID 在编辑字段和阅读字段中联动，并触发示例业务操作。

[打开对应示例](llms/zh-CN/components/people-select.md#完整业务示例) · 相关组件：[PeopleSelect 人员选择](llms/zh-CN/components/people-select.md)、[Form 表单](llms/zh-CN/components/form.md)

### 表格列管理是独立可组合能力

列显隐、重命名、顺序、冻结及宽度通过结构化状态回写；业务决定持久化位置。

演示方法：修改列后取消，再确认；恢复保存配置并核对必选列与冻结顺序。

[打开对应示例](llms/zh-CN/components/table-column-manager.md#与-table-组合-分组与持久化) · 相关组件：[Table 表格](llms/zh-CN/components/table.md)、[TableColumnManager 表格列管理](llms/zh-CN/components/table-column-manager.md)

### 表格配置能关联实际业务行类型

表格列配置与业务数据类型相连，配合虚拟列表、编辑和列管理扩展点使用。

演示方法：展开关联业务类型的示例源码，再对照相应表格配置。

[打开对应示例](llms/zh-CN/components/table.md#关联业务行与列类型) · 相关组件：[Table 表格](llms/zh-CN/components/table.md)

### 文件读取、准备、请求和展示可分别接入

不配置上传接口时可以只读取文件；请求、进度和自定义展示按业务需要组合。

演示方法：先选择本地文件，再展示手动提交、外部进度与独立 hook。

[打开对应示例](llms/zh-CN/components/upload.md#手动队列和可取消请求) · 相关组件：[Upload 上传](llms/zh-CN/components/upload.md)

### 排期包含资源、容量和可用时间

人员、设备、会议室复用资源模型，关联占用量、工作时间、维护与容量规则。

演示方法：调整资源容量，再将日程拖入冲突时段，观察拒绝与修正后的提交。

[打开对应示例](llms/zh-CN/components/scheduler.md#资源并发容量) · 相关组件：[Scheduler 日程调度](llms/zh-CN/components/scheduler.md)

### 排期支持批量事务与撤销重做

批量变更以最终状态校验，可结合异步保存、版本保护和撤销重做形成完整流程。

演示方法：交换两条排期或批量调整，先模拟失败，再修正重试并撤销。

[打开对应示例](llms/zh-CN/components/scheduler.md#原子事务交换) · 相关组件：[Scheduler 日程调度](llms/zh-CN/components/scheduler.md)

### 排期可表达依赖、里程碑和资源负载

依赖关系、零时长里程碑、时间线缩放和负载统计补充常规日历展示。

演示方法：缩放资源时间线，查看依赖与里程碑，再检查资源负载。

[打开对应示例](llms/zh-CN/components/scheduler.md#依赖、里程碑与时间线缩放) · 相关组件：[Scheduler 日程调度](llms/zh-CN/components/scheduler.md)

依赖校验不会自动重排其他任务；负载统计基于已加载数据。

### 排期可通过适配器连接外部日历语义

高级适配器提供 RRULE、时区转换、ICS 导入导出与打印；轻量核心继续独立使用。

演示方法：展示指定时区的重复规则，再查看日历交换示例与导出内容。

[打开对应示例](llms/zh-CN/components/scheduler.md#rrule、时区与夏令时) · 相关组件：[Scheduler 日程调度](llms/zh-CN/components/scheduler.md)

组件网格仍使用运行环境本地时间；模拟协同提供方不是已接入真实服务。

## 工程保障

### 部分稳定逻辑可以脱离默认界面复用

useUploader、列管理 hook 与 Scheduler 纯核心为自定义界面和业务适配提供入口。

演示方法：展开 hook 示例，识别业务模型、请求服务和默认展示之间的边界。

[打开对应示例](llms/zh-CN/components/upload.md#上传前准备与取消竞争) · 相关组件：[Upload 上传](llms/zh-CN/components/upload.md)、[TableColumnManager 表格列管理](llms/zh-CN/components/table-column-manager.md)、[Scheduler 日程调度](llms/zh-CN/components/scheduler.md)

### 复杂交互明确考虑停用、卸载与过期任务

对选择请求、计时、拖动和滚动等异步过程提供生命周期示例与相应检查。

演示方法：启动操作后改变状态或停用实例，再恢复并重新操作，观察旧任务是否干扰。

[打开对应示例](llms/zh-CN/components/select.md#交互调度生命周期) · 相关组件：[Select 下拉框](llms/zh-CN/components/select.md)、[Search 搜索框](llms/zh-CN/components/search.md)、[Upload 上传](llms/zh-CN/components/upload.md)、[Countdown 倒计时](llms/zh-CN/components/countdown.md)、[Scrollbar 滚动条](llms/zh-CN/components/scrollbar.md)

## 继续逐项比较

在[逐组件对照](llms/zh-CN/showcase/components.md)中查看其他组件库的相似示例、文档依据与待核验增量；每个特点的运行示例仍保存在对应组件目录中。

---

Document: llms/zh-CN/showcase/themes.md

<!-- Source: docs/showcase/themes.md; locale: zh-CN; page: /showcase/themes/ -->

# 主题与品牌

品牌定制要同时覆盖组件的背景、文字、边框、状态和弹层。Cedar 与 Maple 对齐主题语言，Cedar 内置默认与枫叶两套主题，并分别提供亮暗模式。

## 切换品牌与亮暗

依次切换四个主题，观察按钮、语义文字和背景。此示例会修改当前文档站的全局主题；演示后可点击“默认亮色”恢复。

Example source: src/themes/__demos__/toggle.vue

```vue
<template>
  <c-space direction="column" fill>
    <c-space wrap>
      <c-button status="primary" @click="apply(Themes.default.light)">默认亮色</c-button>
      <c-button status="primary" @click="apply(Themes.default.dark)">默认暗色</c-button>
      <c-button status="primary" @click="apply(Themes.maple.light)">枫叶亮色</c-button>
      <c-button status="primary" @click="apply(Themes.maple.dark)">枫叶暗色</c-button>
    </c-space>

    <div class="preview c-rounded-md c-p-16">
      <div class="c-text-1 c-mb-8">主题预览</div>
      <div class="c-text-3 c-mb-16">主色按钮与语义文字会随 StyleProvider / cedar-theme 变化。</div>
      <c-space>
        <c-button status="primary">Primary</c-button>
        <c-button>Default</c-button>
        <span class="semantic-primary">primary</span>
        <span class="semantic-success">success</span>
        <span class="semantic-warning">warning</span>
      </c-space>
    </div>
  </c-space>
</template>

<script lang="ts" setup>
import { StyleProvider, Themes, type StyleVars } from '@cedar-design/ui'

function apply(theme: StyleVars | null) {
  StyleProvider.setStyleVars(theme)
}
</script>

<style scoped>
.preview {
  background: var(--c-color-fill-2);
  border: 1px solid var(--c-color-border-2);
}

.semantic-primary {
  color: var(--c-color-primary);
}

.semantic-success {
  color: var(--c-color-success);
}

.semantic-warning {
  color: var(--c-color-warning);
}
</style>
```

## 检查弹层与输入状态

保持当前主题，打开下方选择面板，检查选中、搜索、禁用与只读的表现。品牌切换之后，再检查表面、边框和文字是否协调。

Example source: src/select/__demos__/state-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref("design");
const options = [
  { label: "研发", value: "dev" },
  { label: "设计", value: "design" },
  { label: "运营", value: "ops", disabled: true },
];
const __demoState = __demoReactive({
  disabled: false,
  readonly: false,
  error: false,
});
</script>
<template>
  <c-space direction="column" :size="16">
    <c-space wrap>
      <c-checkbox v-model="__demoState['disabled']">disabled</c-checkbox>
      <c-checkbox v-model="__demoState['readonly']">readonly</c-checkbox>
      <c-checkbox v-model="__demoState['error']">error</c-checkbox>
    </c-space>
    <c-select
      v-model="value"
      :options="options"
      clearable
      v-bind="__demoState"
    ></c-select>
  </c-space>
</template>
```

## 同一个页面中的局部主题

观察 StyleProvider 覆盖范围内与范围外的组件，展开源码确认主题变量如何局部传递。先修改局部，再切全局，检查两个层级的组合。

Example source: src/style-provider/__demos__/basic.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'

const active = ref(true)
</script>

<template>
  <div>
    <c-button variant="outline" @click="active = !active">切换局部变量 / Toggle local variables</c-button>
    <c-style-provider tag="section" :style-vars="active ? { '--c-demo-color': 'teal' } : null">
      <p style="color: var(--c-demo-color, currentColor)">局部颜色 / Local color</p>
      <c-style-provider :style-vars="{ '--c-demo-color': 'coral' }">
        <p style="color: var(--c-demo-color)">嵌套覆盖 / Nested override</p>
      </c-style-provider>
    </c-style-provider>
    <p>外部不受影响 / Outside remains unchanged</p>
  </div>
</template>
```

## 与其他实现对照什么

用相同品牌色和亮暗配置，比较全局主题、组件覆盖与局部覆盖的入口，以及弹层是否跟随主题。主题定制是比较维度，具体差异应通过同场景操作确认。

继续阅读：[主题定制](llms/zh-CN/themes.md) · [Token 分层](llms/zh-CN/guide/design-tokens.md) · [CSS 变量参考](llms/zh-CN/guide/design-token-reference.md)

---

[返回总览，标记已体验](llms/zh-CN/showcase.md) · [下一站：业务数据选择](llms/zh-CN/showcase/async-selection.md)

---

Document: llms/zh-CN/themes.md

<!-- Source: src/themes/README.md; locale: zh-CN; page: /themes/ -->

# 主题定制

### 介绍

Cedar 色板与 Maple 结构对齐：**RGB 通道色阶** + **语义色** + **组件 token**。

- 色阶：`--c-primary-6: r, g, b`，用法 `rgb(var(--c-primary-6))` / `rgba(var(--c-primary-6), 0.12)`
- 语义：`--c-color-text-1`、`--c-color-bg-*`、`--c-color-fill-*` 等
- 暗色：根节点属性 `cedar-theme="dark"` 整表覆盖（CSS `:root[cedar-theme=dark]`）
- 覆盖 / 多主题包：用 [StyleProvider](llms/zh-CN/components/style-provider.md) + `Themes`

设计 token：`style/theme/css-variables.less`、`style/color/css-variables.less`。

### 内置主题包

| 主题名称 | 主题包 | 说明 |
| --- | --- | --- |
| 默认 | `Themes.default.light` / `Themes.default.dark` | 青绿色品牌色阶，提供亮暗模式 |
| 枫叶 | `Themes.maple.light` / `Themes.maple.dark` | 枫叶红橙品牌色阶，提供亮暗模式 |

## 基础示例

### StyleProvider 切换

亮色对象会移除 `html[cedar-theme=dark]`，暗色对象会设置该属性。Cedar 与 Maple 使用相同的主题分组、颜色和值域。

```vue
<template>
  <c-space>
    <c-button status="primary" @click="StyleProvider.setStyleVars(Themes.default.light)">默认亮色</c-button>
    <c-button status="primary" @click="StyleProvider.setStyleVars(Themes.default.dark)">默认暗色</c-button>
    <c-button status="primary" @click="StyleProvider.setStyleVars(Themes.maple.light)">枫叶亮色</c-button>
    <c-button status="primary" @click="StyleProvider.setStyleVars(Themes.maple.dark)">枫叶暗色</c-button>
  </c-space>
</template>

<script setup>
import { StyleProvider, Themes } from '@cedar-design/ui'
</script>
```

Example source: src/themes/__demos__/toggle.vue

```vue
<template>
  <c-space direction="column" fill>
    <c-space wrap>
      <c-button status="primary" @click="apply(Themes.default.light)">默认亮色</c-button>
      <c-button status="primary" @click="apply(Themes.default.dark)">默认暗色</c-button>
      <c-button status="primary" @click="apply(Themes.maple.light)">枫叶亮色</c-button>
      <c-button status="primary" @click="apply(Themes.maple.dark)">枫叶暗色</c-button>
    </c-space>

    <div class="preview c-rounded-md c-p-16">
      <div class="c-text-1 c-mb-8">主题预览</div>
      <div class="c-text-3 c-mb-16">主色按钮与语义文字会随 StyleProvider / cedar-theme 变化。</div>
      <c-space>
        <c-button status="primary">Primary</c-button>
        <c-button>Default</c-button>
        <span class="semantic-primary">primary</span>
        <span class="semantic-success">success</span>
        <span class="semantic-warning">warning</span>
      </c-space>
    </div>
  </c-space>
</template>

<script lang="ts" setup>
import { StyleProvider, Themes, type StyleVars } from '@cedar-design/ui'

function apply(theme: StyleVars | null) {
  StyleProvider.setStyleVars(theme)
}
</script>

<style scoped>
.preview {
  background: var(--c-color-fill-2);
  border: 1px solid var(--c-color-border-2);
}

.semantic-primary {
  color: var(--c-color-primary);
}

.semantic-success {
  color: var(--c-color-success);
}

.semantic-warning {
  color: var(--c-color-warning);
}
</style>
```

### ConfigProvider 切换

```vue
<template>
  <c-config-provider :theme="theme">
    <App />
  </c-config-provider>
</template>

<script setup>
import { ref } from 'vue'

const theme = ref('light') // 'light' | 'dark'
</script>
```

`theme` 同步到根节点 `cedar-theme`（`light` 时移除）。取值可用 `cedarThemes`：`['light', 'dark']`。

### DOM 切换暗色

```ts
document.documentElement.setAttribute('cedar-theme', 'dark')
document.documentElement.removeAttribute('cedar-theme')
```

### 设置 body

```css
body {
  transition: background-color 0.25s, color 0.25s;
  color: var(--c-color-text);
  background-color: var(--c-color-body);
  color-scheme: var(--c-color-scheme);
}
```

### 主题定制

```ts
import { StyleProvider, Themes } from '@cedar-design/ui'

const customTheme = {
  ...Themes.maple.light,
  '--c-brand-6': '255, 0, 0',
}

StyleProvider.setStyleVars(customTheme)
```

### 与文档站同步

文档站监听 `html[data-theme]`，并映射到 `cedar-theme`，切换 VuePress 主题时组件预览会一并切换。

### 通用样式变量（节选）

| 变量名 | 说明 |
| --- | --- |
| `--c-primary-1` … `--c-primary-10` | 主色阶（映射 brand） |
| `--c-brand-1` … `--c-brand-10` | Brand 色阶 |
| `--c-success-*` / `--c-danger-*` / `--c-warning-*` / `--c-link-*` | 功能色阶 |
| `--c-gray-1` … `--c-gray-10` | 中性色阶 |
| `--c-color-text-1` … `--c-color-text-4` | 文本语义（`c-text-1` … `c-text-4`） |
| `--c-color-bg-1` … `--c-color-bg-5` | 背景语义 |
| `--c-color-fill-1` … `--c-color-fill-4` | 填充语义 |
| `--c-color-border-1` … `--c-color-border-4` | 边框语义 |
| `--c-color-scheme` / `--c-color-body` / `--c-color-text` | 主题切换 / body |

完整色阶见 [色板 Palette](llms/zh-CN/components/palette.md)，语义工具类见 [颜色 Color](llms/zh-CN/components/style/color.md)。

---

Document: llms/en-US/components/affix.md

<!-- Source: src/affix/README.en-US.md; locale: en-US; page: /en/components/affix/ -->

# Affix

The same scenarios, parameters and interactions as Cedar. Only component prefixes differ; themes and site shells remain independent.

## Basic examples

### Basic usage

Example source: src/affix/__demos__/basic.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const containerRef = ref<HTMLElement>()
</script>

<template>
  <p>Scroll inside the bordered area.</p>
  <div ref="containerRef" class="scroller">
    <div class="scroll-content">
      <c-affix :target="containerRef"><c-button status="primary">Basic usage</c-button></c-affix>
    </div>
  </div>
</template>

<style scoped>
.scroller {
  height: 200px;
  overflow: auto;
  border: 1px solid currentColor;
}
.scroll-content {
  min-height: 600px;
  padding: 16px;
}
</style>
```

## Layout and arrangement

### Affix direction, offset and container

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `target` | Scroller or selector; finds nearest scrolling ancestor when omitted, falling back to window | Affix direction, offset and container |
| `offset-top` | Distance from the scroll container top; accepts CSS lengths | Affix direction, offset and container |
| `offset-bottom` | Distance from the bottom; takes precedence over offset-top, including 0 | Affix direction, offset and container |
<!-- demo-config-notes:end -->


Scroll each bordered area separately to compare top/bottom affixing and offsets within an explicit scroll container.

Example source: src/affix/__demos__/offset-container-comparison.vue

```vue
<script setup lang="ts">
import { ref } from "vue"
import { proxyRefs as demoProxyRefs } from 'vue'

const scene1 = demoProxyRefs((() => {

const containerRef = ref<HTMLElement>()
return { containerRef }
})())

const scene2 = demoProxyRefs((() => {

const containerRef = ref<HTMLElement>()
return { containerRef }
})())

const scene3 = demoProxyRefs((() => {

const containerRef = ref<HTMLElement>()
return { containerRef }
})())
</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="top">
    <h4><span lang="zh-CN">顶部偏移</span><span lang="en-US">Top offset</span></h4>
    <p>Scroll inside the bordered area.</p>
      <div :ref="element => (scene1.containerRef = element)" class="scroller">
        <div class="scroll-content">
          <c-affix :target="scene1.containerRef" :offset-top="80"
            ><c-button status="primary">Top offset</c-button></c-affix
          >
        </div>
      </div>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="bottom">
    <h4><span lang="zh-CN">底部偏移</span><span lang="en-US">Bottom offset</span></h4>
    <p>Scroll inside the bordered area.</p>
      <div :ref="element => (scene2.containerRef = element)" class="scroller">
        <div class="scroll-content">
          <div style="height: 240px"></div>
          <c-affix :target="scene2.containerRef" :offset-bottom="20"
            ><c-button status="primary">Bottom offset</c-button></c-affix
          >
        </div>
      </div>
  </section>

  <section class="demo-comparison-case demo-comparison-case--3" data-comparison-scene="container">
    <h4><span lang="zh-CN">指定滚动容器</span><span lang="en-US">Scroll container</span></h4>
    <p>Scroll inside the bordered area.</p>
      <div :ref="element => (scene3.containerRef = element)" class="scroller">
        <div class="scroll-content">
          <div style="height: 40px"></div>
          <c-affix :target="scene3.containerRef" :offset-top="20"
            ><c-button status="primary">Scroll container</c-button></c-affix
          >
        </div>
      </div>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }
.demo-comparison-case--1 {

.scroller {
  height: 200px;
  overflow: auto;
  border: 1px solid currentColor;
}
.scroll-content {
  min-height: 600px;
  padding: 16px;
}

}
.demo-comparison-case--2 {

.scroller {
  height: 200px;
  overflow: auto;
  border: 1px solid currentColor;
}
.scroll-content {
  min-height: 600px;
  padding: 16px;
}

}
.demo-comparison-case--3 {

.scroller {
  height: 200px;
  overflow: auto;
  border: 1px solid currentColor;
}
.scroll-content {
  min-height: 600px;
  padding: 16px;
}

}
</style>
```

## Interaction and control

### Change event

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `target` | Scroller or selector; finds nearest scrolling ancestor when omitted, falling back to window | Change event, Disabled, CSS mode and manual update |
| `offset-top` | Distance from the scroll container top; accepts CSS lengths | Change event, Disabled, CSS mode and manual update |
| `disabled` | Disable affixing | Disabled, CSS mode and manual update |
| `css-mode` | Use native position: sticky, subject to ancestor overflow and container boundaries | Disabled, CSS mode and manual update |
| `z-index` | Stacking level | Disabled, CSS mode and manual update |
<!-- demo-config-notes:end -->


Example source: src/affix/__demos__/fix-change.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const containerRef = ref<HTMLElement>()
const fixed = ref(false)
</script>

<template>
  <p>Scroll inside the bordered area.</p>
  <div ref="containerRef" class="scroller">
    <div class="scroll-content">
      <div style="height: 40px"></div>
      <c-affix :target="containerRef" :offset-top="20" @change="fixed = $event"
        ><c-button status="primary">Change event</c-button></c-affix
      >
    </div>
  </div>
  <p role="status">Fixed: {{ fixed }}</p>
</template>

<style scoped>
.scroller {
  height: 200px;
  overflow: auto;
  border: 1px solid currentColor;
}
.scroll-content {
  min-height: 600px;
  padding: 16px;
}
</style>
```

### Disabled, CSS mode and manual update

Example source: src/affix/__demos__/controls.vue

```vue
<script setup lang="ts">
import { nextTick, ref } from "vue";
const containerRef = ref<HTMLElement>();
const affixRef = ref<{ updatePosition: () => Promise<void> }>();
const disabled = ref(false);
const cssMode = ref(false);
const spacerHeight = ref(40);
const updates = ref(0);
async function updateLayout() {
  spacerHeight.value = spacerHeight.value === 40 ? 100 : 40;
  await nextTick();
  await affixRef.value?.updatePosition();
  updates.value++;
}
</script>

<template>
  <c-space wrap size="12px" style="margin-bottom: 12px">
    <c-checkbox v-model="disabled"> Disabled</c-checkbox>
    <c-checkbox v-model="cssMode"> CSS sticky</c-checkbox>
    <c-button @click="updateLayout">Change layout and update position</c-button>
  </c-space>
  <p aria-live="polite">Position updates: {{ updates }}</p>
  <div ref="containerRef" class="scroller">
    <div class="scroll-content">
      <div :style="{ height: `${spacerHeight}px` }"></div>
      <c-affix
        ref="affixRef"
        :target="containerRef"
        :disabled="disabled"
        :css-mode="cssMode"
        :offset-top="12"
        :z-index="2"
      >
        <c-button status="primary">Scroll to pin</c-button>
      </c-affix>
    </div>
  </div>
</template>

<style scoped>
.scroller {
  height: 200px;
  overflow: auto;
  border: 1px solid currentColor;
}
.scroll-content {
  min-height: 600px;
  padding: 16px;
}
</style>
```

## API

<!-- same-source-api:start -->
### Props

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| offset-top | Distance from the scroll container top; accepts CSS lengths | `number / string` | `0` |
| offset-bottom | Distance from the bottom; takes precedence over offset-top, including 0 | `number / string` | `undefined` |
| target | Scroller or selector; finds nearest scrolling ancestor when omitted, falling back to window | `string / HTMLElement / Window` | `undefined` |
| target-container | Extra outer scroller to listen to; omitted means no extra listener, and it is not a clipping boundary | `string / HTMLElement / Window` | `undefined` |
| z-index | Stacking level | `number / string` | `10` |
| disabled | Disable affixing | `boolean` | `false` |
| css-mode | Use native position: sticky, subject to ancestor overflow and container boundaries | `boolean` | `false` |

### Events

| Event | Arguments and timing |
| --- | --- |
| change | `(fixed: boolean, offset: number)`, emitted when the fixed state changes. While fixed, offset is the affix threshold; otherwise it is the distance to the corresponding container edge. Disabling affixing reports 0. |

### Slots

| Slot | Description | Arguments |
| --- | --- | --- |
| default | Content to affix | — |

### Methods

| Method | Description | Arguments | Returns |
| --- | --- | --- | --- |
| updatePosition | Rebind scrollers and recalculate on the next animation frame | — | `Promise<void>` |

### Platform notes

Props, event arguments, slots and public methods match across platforms. CSS mode follows browser sticky rules; examples use independent scroll containers.
<!-- same-source-api:end -->

### Type definitions

The component exports the following types

```ts
import type { AffixInstance } from '@cedar-design/ui'
```

`change` reports state transitions, so remeasuring an already fixed item does not repeat `true`; disabling a fixed item reports `false, 0`. Viewport units are reevaluated during measurement. CSS mode passes valid lengths to native sticky positioning; JS mode resolves numbers, numeric strings, px, rem, vw, vh, vmin and vmax. The target controls observation and JS measurement; native sticky remains constrained by actual CSS ancestors. Pending `updatePosition()` work cannot rebind a deactivated or replaced activation generation.

---

Document: llms/en-US/components/alert.md

<!-- Source: src/alert/README.en-US.md; locale: en-US; page: /en/components/alert/ -->

# Alert

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

Example source: src/alert/__demos__/basic.vue

```vue
<template>
  <c-alert>This is an info alert.</c-alert>
</template>

<script lang="ts" setup>
</script>
```

## Appearance and states

### Appearance configuration comparison

Choose an axis to compare its available values with the same content and model. Other settings remain unchanged while comparing.

Example source: src/alert/__demos__/appearance-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";

const __demoAppearance = __demoReactive({
  variant: "tonal",
  status: "default",
});

import { computed as demoComputed, ref as demoRef } from 'vue'
const demoCompareFields = [{"name":"variant","values":["tonal","outline","standard"]},{"name":"status","values":["info","success","warning","danger","default"]}]
const demoCompareAxis = demoRef("variant")
const demoComparedOptions = demoComputed(() => demoCompareFields.find(field => field.name === demoCompareAxis.value)?.values ?? [])
</script>
<template>
  <c-space direction="column" :size="16">
    <c-form layout="vertical">
      <c-form-item layout="vertical" size="sm" label="variant">
        <c-radio-group
          v-model="__demoAppearance['variant']"
          aria-label="variant"
          :options="[
            { label: 'tonal', value: 'tonal' },
            { label: 'outline', value: 'outline' },
            { label: 'standard', value: 'standard' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
      <c-form-item layout="vertical" size="sm" label="status">
        <c-radio-group
          v-model="__demoAppearance['status']"
          aria-label="status"
          :options="[
            { label: 'info', value: 'info' },
            { label: 'success', value: 'success' },
            { label: 'warning', value: 'warning' },
            { label: 'danger', value: 'danger' },
            { label: 'default', value: 'default' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
    </c-form>
    <p class="demo-config-comparison-hint"><span lang="zh-CN">选择一个对比维度；其他配置和内容保持一致。输入类示例共享同一个值，便于比较外观。</span><span lang="en-US">Compare one dimension while keeping the other settings and content identical. Input specimens share the same value.</span></p>
<c-radio-group v-model="demoCompareAxis" aria-label="Compare configuration" :options="demoCompareFields.map(field => ({ label: field.name, value: field.name }))" />
<div class="demo-config-comparison">
<section v-for="sample in demoComparedOptions" :key="String(sample)">
<p><code>{{ demoCompareAxis }}={{ sample }}</code></p>
<c-alert v-bind="{ ...__demoAppearance, [demoCompareAxis]: sample }">This is an info alert.</c-alert>
</section>
</div>
  </c-space>
</template>

<style scoped>
.demo-config-comparison { display: grid; grid-template-columns: repeat(auto-fit, minmax(min(100%, 220px), 1fr)); gap: 20px; min-width: 0; max-width: 100%; }
.demo-config-comparison > section { min-width: 0; }
.demo-config-comparison p { margin: 0 0 8px; }
html:not([lang='en-US']) .demo-config-comparison-hint > [lang='en-US'],
html[lang='en-US'] .demo-config-comparison-hint > [lang='zh-CN'] { display: none; }
</style>
```

## Content and presentation

### Title, alignment and banners

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `title` | Alert title | Title, alignment and banners, Action |
| `status` | Alert status | Title, alignment and banners, Show Icon |
| `center` | Whether to center the content | Title, alignment and banners |
| `banner` | Whether to display a top banner without borders or rounded corners | Title, alignment and banners |
| `show-icon` | Whether to show an icon | Show Icon |
| `closable` | Whether to show the close button | Action |
<!-- demo-config-notes:end -->


Compare title hierarchy, centered content and page-wide banners. Actions and dismiss behavior have separate examples.

Example source: src/alert/__demos__/content-comparison.vue

```vue
<script setup lang="ts">


</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="title">
    <h4><span lang="zh-CN">提示标题</span><span lang="en-US">title</span></h4>
    <c-row :gutter="[40, 20]">
        <c-col :span="12">
          <c-alert title="Info">This is an info alert.</c-alert>
        </c-col>
        <c-col :span="12">
          <c-alert title="Success" status="success">This is an success alert.</c-alert>
        </c-col>
        <c-col :span="12">
          <c-alert status="warning">
            <template #title> Warning </template>
            This is an warning alert.
          </c-alert>
        </c-col>
        <c-col :span="12">
          <c-alert status="danger">
            <template #title> Error </template>
            This is a danger alert.
          </c-alert>
        </c-col>
      </c-row>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="center">
    <h4><span lang="zh-CN">居中</span><span lang="en-US">center</span></h4>
    <c-alert center>This is a centered alert.</c-alert>
  </section>

  <section class="demo-comparison-case demo-comparison-case--3" data-comparison-scene="banner">
    <h4><span lang="zh-CN">顶部公告</span><span lang="en-US">banner</span></h4>
    <c-alert banner>This is a banner alert.</c-alert>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

### Show Icon

- `status`: Selects the semantic state.

Example source: src/alert/__demos__/show-icon.vue

```vue
<template>
  <c-row :gutter="[40, 20]">
    <c-col :span="12">
      <c-alert :show-icon="false">This is an info alert.</c-alert>
    </c-col>
    <c-col :span="12">
      <c-alert status="success" :show-icon="false">This is an success alert.</c-alert>
    </c-col>
    <c-col :span="12">
      <c-alert status="warning" :show-icon="false">
        <template #title> Warning </template>
        This is an warning alert.
      </c-alert>
    </c-col>
    <c-col :span="12">
      <c-alert status="danger" :show-icon="false">
        <template #title> Error </template>
        This is a danger alert.
      </c-alert>
    </c-col>
  </c-row>
</template>

<script lang="ts" setup>
</script>
```

### Action

Example source: src/alert/__demos__/action.vue

```vue
<template>
  <c-space direction="column" size="lg" style="width: 100%">
    <c-alert closable>
      This is an info alert.
      <template #action>
        <c-button size="sm" status="primary">Detail</c-button>
      </template>
    </c-alert>
    <c-alert title="Example" closable>
      This is an info alert.
      <template #action>
        <c-button size="sm" status="primary">Detail</c-button>
      </template>
    </c-alert>
  </c-space>
</template>

<script lang="ts" setup>
</script>
```

## Customization and slots

### Custom Icon

- `status`: Selects the semantic state.

Example source: src/alert/__demos__/custom-icon.vue

```vue
<template>
  <c-space direction="column" size="lg" style="width: 100%">
    <c-alert>
      <template #icon>
        <c-icon-face-smile-fill />
      </template>
      This is an alert with a custom icon.
    </c-alert>
    <c-alert status="default">
      <template #icon>
        <c-icon-exclamation-circle-fill />
      </template>
      Default type can still show a custom icon via slot.
    </c-alert>
  </c-space>
</template>

<script lang="ts" setup>
</script>
```

## Interaction and control

### Dismiss controls and custom icons

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `closable` | Whether to show the close button | Dismiss controls and custom icons |
| `status` | Alert status | Dismiss controls and custom icons |
<!-- demo-config-notes:end -->


Operate the default and custom dismiss controls to compare the same dismissal behavior.

Example source: src/alert/__demos__/dismiss-comparison.vue

```vue
<script setup lang="ts">


</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="closable">
    <h4><span lang="zh-CN">可关闭</span><span lang="en-US">closable</span></h4>
    <c-row :gutter="[40, 20]">
        <c-col :span="12">
          <c-alert closable>This is an info alert.</c-alert>
        </c-col>
        <c-col :span="12">
          <c-alert status="success" closable>This is an success alert.</c-alert>
        </c-col>
        <c-col :span="12">
          <c-alert status="warning" closable>
            <template #title> Warning </template>
            This is an warning alert.
          </c-alert>
        </c-col>
        <c-col :span="12">
          <c-alert status="danger" closable>
            <template #title> Error </template>
            This is a danger alert.
          </c-alert>
        </c-col>
      </c-row>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="close-icon">
    <h4><span lang="zh-CN">自定义关闭图标</span><span lang="en-US">close icon</span></h4>
    <c-row :gutter="[40, 20]">
        <c-col :span="12">
          <c-alert closable>
            <template #close-icon>
              <c-icon-close-circle />
            </template>
            This is an info alert.
          </c-alert>
        </c-col>
        <c-col :span="12">
          <c-alert closable>
            <template #close-icon> Close </template>
            This is an info alert.
          </c-alert>
        </c-col>
      </c-row>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

## API

### `<Alert>` Props

| Prop | Description | Type | Default |
| --------- | --------------------------------------------------------------------- | --------------------------------------------------- | ------------ |
| status | Alert status | `'info' \| 'success' \| 'warning' \| 'danger' \| 'default'` | `'info'` |
| variant | Visual variant | `'standard' \| 'tonal' \| 'outline'` | `'standard'` |
| color | Custom background color; overrides the background derived from type | `string` | - |
| title | Alert title | `string` | - |
| message | Content text; the default slot can also supply it | `string` | - |
| show-icon | Whether to show an icon | `boolean` | `true` |
| closable | Whether to show the close button | `boolean` | `false` |
| banner | Whether to display a top banner without borders or rounded corners | `boolean` | `false` |
| center | Whether to center the content | `boolean` | `false` |
| elevation | Elevation: `true`, `false`, or a level from `0-24` | `boolean \| number` | `false` |

### `<Alert>` Events

| Event | Description | Arguments |
| ----------- | ------------------ | ----------------------------- |
| close | Triggered when the Close button is clicked and can only be used when the Close button is displayed | `(event: MouseEvent) => void` |
| closed | Emitted after close transition | - |

### `<Alert>` Slots

| Slot | Description | Arguments |
| ---------- | -------- | ---- |
| default | Content | - |
| icon | Icon | - |
| title | Title | - |
| action | Actions | - |
| close-icon | The close icon of alert | - |

### Type definitions

The component exports the following types:

```ts
import type {
  AlertInstance,
  AlertProps,
  AlertStatus,
  AlertVariant,
} from '@cedar-design/ui'
```

### Style variables

See `style/token.less`; all variables use the `--c-alert-` prefix. Example override:

```css
:root {
  --c-alert-padding-vertical: 12px;
  --c-alert-padding-horizontal: 20px;
}
```

## Migration notes (breaking changes)

| Previous API | Current API |
| -- | -- |
| `type="error"` | `type="danger"` |
| `type="normal"` | `type="default"` |
| `closeable` | `closable` |
| `#close-element` slot | `#close-icon` slot |

Added capabilities: `variant` / `color` / `elevation` / `default` status / `closed` event.

`type="default"` renders no built-in icon. Use `#icon` when an icon is needed.

## Shared implementation and platform boundaries

Each platform maintains a complete local implementation. They do not import a common core or share component instances or reactive state. Changes must update both implementations. Component bodies, props, key styles and paired tests have read-only source consistency checks; theme tokens and installation entries remain local to each library.

The close button supports keyboard activation. close fires once, and closed fires after the leave transition. Maple renamed its internal __close-icon class to __close-btn. Default icons are adapted locally in each library.

### Complete variable defaults

Colored titles, content, icons and outline borders use readable system content colors. standard and tonal share the same level-1 background; standard adds a subtle decorative border. Default titles use content-primary; body text and icons use content-secondary. The content variable also sets the root inherited color, used by close icons and actions without an explicit color. Maple dark mode inherits these colors while retaining its geometry overrides: 16px padding, 22px icons, 12px icon/close gaps and 1.5 body line height. color changes only the background; callers must also verify foreground contrast. The table lists :root defaults, not theme overrides.

| Variable | Default |
| --- | --- |
| `--c-alert-padding-vertical` | `var(--c-sys-space-4)` |
| `--c-alert-padding-horizontal` | `var(--c-sys-space-6)` |
| `--c-alert-padding-vertical-with-title` | `var(--c-sys-space-6)` |
| `--c-alert-padding-horizontal-with-title` | `var(--c-sys-space-6)` |
| `--c-alert-border-radius` | `var(--c-sys-radius-md)` |
| `--c-alert-border-width` | `1px` |
| `--c-alert-font-size-content` | `var(--c-sys-font-size-md)` |
| `--c-alert-font-size-title` | `var(--c-sys-font-size-lg)` |
| `--c-alert-font-weight-title` | `var(--c-sys-font-weight-medium)` |
| `--c-alert-line-height` | `1.5715` |
| `--c-alert-line-height-title` | `1.5` |
| `--c-alert-title-margin-bottom` | `var(--c-sys-space-2)` |
| `--c-alert-icon-size` | `16px` |
| `--c-alert-icon-margin-right` | `var(--c-sys-space-4)` |
| `--c-alert-action-margin-left` | `var(--c-sys-space-5)` |
| `--c-alert-close-margin-left` | `var(--c-sys-space-4)` |
| `--c-alert-standard-info-bg` | `rgb(var(--c-blue-1))` |
| `--c-alert-standard-info-border` | `rgb(var(--c-blue-3))` |
| `--c-alert-standard-info-title` | `var(--c-sys-color-content-info)` |
| `--c-alert-standard-info-content` | `var(--c-sys-color-content-info)` |
| `--c-alert-standard-info-icon` | `var(--c-sys-color-content-info)` |
| `--c-alert-standard-success-bg` | `rgb(var(--c-success-1))` |
| `--c-alert-standard-success-border` | `rgb(var(--c-success-3))` |
| `--c-alert-standard-success-title` | `var(--c-sys-color-content-success)` |
| `--c-alert-standard-success-content` | `var(--c-sys-color-content-success)` |
| `--c-alert-standard-success-icon` | `var(--c-sys-color-content-success)` |
| `--c-alert-standard-warning-bg` | `rgb(var(--c-warning-1))` |
| `--c-alert-standard-warning-border` | `rgb(var(--c-warning-3))` |
| `--c-alert-standard-warning-title` | `var(--c-sys-color-content-warning)` |
| `--c-alert-standard-warning-content` | `var(--c-sys-color-content-warning)` |
| `--c-alert-standard-warning-icon` | `var(--c-sys-color-content-warning)` |
| `--c-alert-standard-danger-bg` | `rgb(var(--c-danger-1))` |
| `--c-alert-standard-danger-border` | `rgb(var(--c-danger-3))` |
| `--c-alert-standard-danger-title` | `var(--c-sys-color-content-danger)` |
| `--c-alert-standard-danger-content` | `var(--c-sys-color-content-danger)` |
| `--c-alert-standard-danger-icon` | `var(--c-sys-color-content-danger)` |
| `--c-alert-standard-default-bg` | `var(--c-color-fill-2)` |
| `--c-alert-standard-default-border` | `var(--c-sys-color-border-default)` |
| `--c-alert-standard-default-title` | `var(--c-sys-color-content-primary)` |
| `--c-alert-standard-default-content` | `var(--c-sys-color-content-secondary)` |
| `--c-alert-standard-default-icon` | `var(--c-sys-color-content-secondary)` |
| `--c-alert-tonal-info-bg` | `rgb(var(--c-blue-1))` |
| `--c-alert-tonal-info-title` | `var(--c-sys-color-content-info)` |
| `--c-alert-tonal-info-content` | `var(--c-sys-color-content-info)` |
| `--c-alert-tonal-info-icon` | `var(--c-sys-color-content-info)` |
| `--c-alert-tonal-success-bg` | `rgb(var(--c-success-1))` |
| `--c-alert-tonal-success-title` | `var(--c-sys-color-content-success)` |
| `--c-alert-tonal-success-content` | `var(--c-sys-color-content-success)` |
| `--c-alert-tonal-success-icon` | `var(--c-sys-color-content-success)` |
| `--c-alert-tonal-warning-bg` | `rgb(var(--c-warning-1))` |
| `--c-alert-tonal-warning-title` | `var(--c-sys-color-content-warning)` |
| `--c-alert-tonal-warning-content` | `var(--c-sys-color-content-warning)` |
| `--c-alert-tonal-warning-icon` | `var(--c-sys-color-content-warning)` |
| `--c-alert-tonal-danger-bg` | `rgb(var(--c-danger-1))` |
| `--c-alert-tonal-danger-title` | `var(--c-sys-color-content-danger)` |
| `--c-alert-tonal-danger-content` | `var(--c-sys-color-content-danger)` |
| `--c-alert-tonal-danger-icon` | `var(--c-sys-color-content-danger)` |
| `--c-alert-tonal-default-bg` | `var(--c-color-fill-2)` |
| `--c-alert-tonal-default-title` | `var(--c-sys-color-content-primary)` |
| `--c-alert-tonal-default-content` | `var(--c-sys-color-content-secondary)` |
| `--c-alert-tonal-default-icon` | `var(--c-sys-color-content-secondary)` |
| `--c-alert-outline-info-border` | `var(--c-sys-color-content-info)` |
| `--c-alert-outline-info-title` | `var(--c-sys-color-content-info)` |
| `--c-alert-outline-info-content` | `var(--c-sys-color-content-info)` |
| `--c-alert-outline-info-icon` | `var(--c-sys-color-content-info)` |
| `--c-alert-outline-success-border` | `var(--c-sys-color-content-success)` |
| `--c-alert-outline-success-title` | `var(--c-sys-color-content-success)` |
| `--c-alert-outline-success-content` | `var(--c-sys-color-content-success)` |
| `--c-alert-outline-success-icon` | `var(--c-sys-color-content-success)` |
| `--c-alert-outline-warning-border` | `var(--c-sys-color-content-warning)` |
| `--c-alert-outline-warning-title` | `var(--c-sys-color-content-warning)` |
| `--c-alert-outline-warning-content` | `var(--c-sys-color-content-warning)` |
| `--c-alert-outline-warning-icon` | `var(--c-sys-color-content-warning)` |
| `--c-alert-outline-danger-border` | `var(--c-sys-color-content-danger)` |
| `--c-alert-outline-danger-title` | `var(--c-sys-color-content-danger)` |
| `--c-alert-outline-danger-content` | `var(--c-sys-color-content-danger)` |
| `--c-alert-outline-danger-icon` | `var(--c-sys-color-content-danger)` |
| `--c-alert-outline-default-border` | `var(--c-sys-color-border-default)` |
| `--c-alert-outline-default-title` | `var(--c-sys-color-content-primary)` |
| `--c-alert-outline-default-content` | `var(--c-sys-color-content-secondary)` |
| `--c-alert-outline-default-icon` | `var(--c-sys-color-content-secondary)` |

### Motion variables

Built-in motion follows `prefers-reduced-motion: reduce`. Reduced motion does not prevent loading-state or close-event updates.

| Token | Default |
| --- | --- |
| `--c-alert-close-duration` | `var(--c-sys-motion-duration-slow)` |

---

Document: llms/en-US/components/anchor.md

<!-- Source: src/anchor/README.en-US.md; locale: en-US; page: /en/components/anchor/ -->

# Anchor

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

- `show-background`: Whether to show the background

Example source: src/anchor/__demos__/basic.vue

```vue
<template>
  <c-anchor :show-background="false">
    <c-anchor-link href="#基础用法">基础用法</c-anchor-link>
    <c-anchor-link href="#无轴线模式">无轴线模式</c-anchor-link>
    <c-anchor-link href="#固钉位置">固钉位置
      Affix
      <template #sublist>
        <c-anchor-link href="#boundary"
          >Scroll Boundary
          <template #sublist>
            <c-anchor-link href="#boundary1">Scroll Boundary1</c-anchor-link>
            <c-anchor-link href="#hash1">Hash mode1</c-anchor-link>
          </template>
        </c-anchor-link>
        <c-anchor-link href="#是否改变hash">是否改变hash</c-anchor-link>
      </template>
    </c-anchor-link>
  </c-anchor>
</template>

<script lang="ts" setup></script>
```

## Layout and arrangement

### Affix

Preview configuration: `:offsetTop="80"`, `href="#basic"`, `href="#show-line"`, `href="#affix"`.

Example source: src/anchor/__demos__/affix.vue

```vue
<template>
  <c-affix :offsetTop="80">
    <c-anchor :style="{ backgroundColor: 'var(--color-bg-1)' }">
      <c-anchor-link href="#basic">Basic</c-anchor-link>
      <c-anchor-link href="#show-line">Show Rail</c-anchor-link>
      <c-anchor-link href="#affix">
        Affix
        <template #sublist>
          <c-anchor-link href="#boundary">Scroll Boundary</c-anchor-link>
          <c-anchor-link href="#hash">Hash mode</c-anchor-link>
        </template>
      </c-anchor-link>
    </c-anchor>
  </c-affix>
</template>
<script lang="ts" setup>
</script>
```

## Content and presentation

### Show Line

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `show-line` | Whether to show the left axis | Show Line |
| `change-hash` | Whether to change the hash. When set to `false`, clicking on the anchor will not change the hash of the page | Hash |
<!-- demo-config-notes:end -->


- `show-line`: Whether to show the left axis

Example source: src/anchor/__demos__/show-line.vue

```vue
<template>
  <c-anchor :show-line="false">
    <c-anchor-link href="#basic">Basic</c-anchor-link>
    <c-anchor-link href="#show-line">Show Rail</c-anchor-link>
    <c-anchor-link href="#affix">
      Affix
      <template #sublist>
        <c-anchor-link href="#boundary">Scroll Boundary</c-anchor-link>
        <c-anchor-link href="#hash">Hash mode</c-anchor-link>
      </template>
    </c-anchor-link>
  </c-anchor>
</template>

<script lang="ts" setup>
</script>
```

### Hash

- `change-hash`: Whether to change the hash. When set to `false`, clicking on the anchor will not change the hash of the page

Example source: src/anchor/__demos__/hash.vue

```vue
<template>
  <c-anchor :change-hash="false">
    <c-anchor-link href="#basic">Basic</c-anchor-link>
    <c-anchor-link href="#show-line">Show Line</c-anchor-link>
    <c-anchor-link href="#affix">
      Affix
      <template #sublist>
        <c-anchor-link href="#boundary">Scroll Boundary</c-anchor-link>
        <c-anchor-link href="#hash">Hash mode</c-anchor-link>
      </template>
    </c-anchor-link>
  </c-anchor>
</template>

<script lang="ts" setup>
</script>
```

## Lifecycle and edge cases

### Boundary

- `boundary`: Scrolling boundary value. After setting the value to a number, it will stop scrolling when the distance is `boundary` from the scrolling container.

Example source: src/anchor/__demos__/boundary.vue

```vue
<template>
  <c-anchor boundary="center">
    <c-anchor-link href="#basic">Basic</c-anchor-link>
    <c-anchor-link href="#show-line">Show Rail</c-anchor-link>
    <c-anchor-link href="#affix">
      Affix
      <template #sublist>
        <c-anchor-link href="#boundary">Scroll Boundary</c-anchor-link>
        <c-anchor-link href="#hash">Hash mode</c-anchor-link>
      </template>
    </c-anchor-link>
  </c-anchor>
</template>

<script lang="ts" setup>
</script>
```

### Scroll Lifecycle

Example source: src/anchor/__demos__/scroll-lifecycle.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import Anchor, { AnchorLink } from "../index";

const active = ref(true);
const mounted = ref(true);
const container = ref<HTMLElement>();
const changes = ref(0);
</script>

<template>
  <div>
    <c-button html-type="button" @click="active = !active"
      >切换 KeepAlive</c-button
    >
    <c-button html-type="button" @click="mounted = !mounted"
      >卸载／挂载</c-button
    >
    <p>
      切换链接后立即停用或卸载；激活后再次点击，检查旧滚动不会恢复。change
      通知：{{ changes }}
    </p>
    <KeepAlive v-if="mounted">
      <Anchor
        v-if="active"
        :scroll-container="container"
        :change-hash="false"
        @change="changes++"
      >
        <AnchorLink href="#anchor-lifecycle-first" title="第一段" />
        <AnchorLink href="#anchor-lifecycle-second" title="第二段" />
      </Anchor>
    </KeepAlive>
    <div ref="container" style="height: 180px; overflow: auto">
      <section id="anchor-lifecycle-first" style="min-height: 240px">
        第一段内容
      </section>
      <section id="anchor-lifecycle-second" style="min-height: 240px">
        第二段内容
      </section>
    </div>
  </div>
</template>
```

## Reading direction

The axis, highlight and indentation follow reading start. Vertical scrolling and anchor targets remain unchanged.

## API

### `<anchor>` Props

| Parameter | Description | Type | Default |
| ---------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------- | :-------: |
| boundary | Scrolling `boundary` value. After setting the value to a number, it will stop scrolling when the distance is `boundary` from the scrolling container. | `'start' \| 'end' \| 'center' \| 'nearest' \| number` | `'start'` |
| show-line | Whether to show the left axis | `boolean` | `true` |
| show-background | Whether to show the background | `boolean` | `true` |
| scroll-container | Scroll container | `string \| HTMLElement \| Window` | `-` |
| change-hash | Whether to change the hash. When set to `false`, clicking on the anchor will not change the hash of the page | `boolean` | `true` |

### `<anchor>` Events

| Event | Description | Arguments |
| ------ | ------------------ | ------------------------------------------------ |
| select | Emitted when the user clicks a link | hash: `string \| undefined`<br>preHash: `string` |
| change | Emitted when the active link changes | hash: `string` |

### `<anchor-link>` Props

| Parameter | Description | Type | Default |
| ------ | ------------------ | -------- | :----: |
| title | Anchor link text | `string` | `-` |
| href | Anchor link URL | `string` | `-` |

### Type definitions

The component exports the following types

```ts
import type { AnchorInstance } from '@cedar-design/ui'
```

---

Document: llms/en-US/components/auto-complete.md

<!-- Source: src/auto-complete/README.en-US.md; locale: en-US; page: /en/components/auto-complete/ -->

# AutoComplete

Text input with suggested completions. Suggestions are arrays; application code owns remote loading.

## Reading direction

The editor and suggestion popup inherit source dir, including in custom containers. Horizontal caret keys keep native editing behavior; vertical keys navigate candidates, Enter selects and Escape closes. Candidate updates preserve the native composition buffer until composition ends instead of repainting the previous model value.

## Search and visibility

case-sensitive replaces the removed strict prop. Default matching searches label and ignores case; use search-fields to include value. Custom filter-option callbacks own their case policy; filter-option=false bypasses local filtering for remote results. AutoComplete has no public open/defaultOpen/update:open API: focusing and typing determine suggestion visibility. trigger-props can customize placement but cannot force internal open state. A public v-model:open would require a separate API change.

## Basic examples

### Basic

Example source: src/auto-complete/__demos__/basic.vue

```vue
<template>
  <c-auto-complete
    v-model="value"
    :options="options"
    placeholder="输入或选择城市"
    clearable
    style="width: 100%; max-width: 320px"
  />
  <p>当前值：{{ value || '-' }}</p>
</template>

<script setup lang="ts">
import { ref } from 'vue'

const value = ref('')
const options = [
  'Beijing',
  { value: 310000, label: 'Shanghai' },
  { value: 'chengdu', label: 'Chengdu' },
  { value: 'wuhan', label: 'Wuhan', disabled: true },
]
</script>
```

### Interaction state comparison

Toggle disabled, read-only and error states, then interact with the same instance. Recovery controls remain outside the target; error appearance alone does not validate data.

<details>
<summary>Configuration details and limits</summary>

#### State Lab

## Appearance and states

### Appearance configuration comparison

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration | Purpose                                                                  | Related examples                    |
| ------------- | ------------------------------------------------------------------------ | ----------------------------------- |
| `options`     | Suggestions, including groups; unique values become strings on selection | Appearance configuration comparison |
| `clearable`   | Allow clearing a nonempty editable value                                 | Appearance configuration comparison |

<!-- demo-config-notes:end -->

Choose a dimension to compare all its values side by side while keeping other settings and content identical. Change the other settings to inspect combinations; input specimens share one model.

Example source: src/auto-complete/__demos__/appearance-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref("研发");
const options = [{ value: "研发" }, { value: "研发平台" }, { value: "设计" }];
const __demoAppearance = __demoReactive({ variant: "filled", size: "md" });

import { computed as demoComputed, ref as demoRef } from 'vue'
const demoCompareFields = [{"name":"variant","values":["filled","outline","standard"]},{"name":"size","values":["xs","sm","md","lg","xl"]}]
const demoCompareAxis = demoRef("variant")
const demoComparedOptions = demoComputed(() => demoCompareFields.find(field => field.name === demoCompareAxis.value)?.values ?? [])
</script>
<template>
  <c-space direction="column" :size="16">
    <c-form layout="vertical">
      <c-form-item layout="vertical" size="sm" label="variant">
        <c-radio-group
          v-model="__demoAppearance['variant']"
          aria-label="variant"
          :options="[
            { label: 'filled', value: 'filled' },
            { label: 'outline', value: 'outline' },
            { label: 'standard', value: 'standard' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
      <c-form-item layout="vertical" size="sm" label="size">
        <c-radio-group
          v-model="__demoAppearance['size']"
          aria-label="size"
          :options="[
            { label: 'xs', value: 'xs' },
            { label: 'sm', value: 'sm' },
            { label: 'md', value: 'md' },
            { label: 'lg', value: 'lg' },
            { label: 'xl', value: 'xl' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
    </c-form>
    <p class="demo-config-comparison-hint"><span lang="zh-CN">选择一个对比维度；其他配置和内容保持一致。输入类示例共享同一个值，便于比较外观。</span><span lang="en-US">Compare one dimension while keeping the other settings and content identical. Input specimens share the same value.</span></p>
<c-radio-group v-model="demoCompareAxis" aria-label="Compare configuration" :options="demoCompareFields.map(field => ({ label: field.name, value: field.name }))" />
<div class="demo-config-comparison">
<section v-for="sample in demoComparedOptions" :key="String(sample)">
<p><code>{{ demoCompareAxis }}={{ sample }}</code></p>
<c-auto-complete
      v-model="value"
      :options="options"
      clearable
      v-bind="{ ...__demoAppearance, [demoCompareAxis]: sample }"
    ></c-auto-complete>
</section>
</div>
  </c-space>
</template>

<style scoped>
.demo-config-comparison { display: grid; grid-template-columns: repeat(auto-fit, minmax(min(100%, 220px), 1fr)); gap: 20px; min-width: 0; max-width: 100%; }
.demo-config-comparison > section { min-width: 0; }
.demo-config-comparison p { margin: 0 0 8px; }
html:not([lang='en-US']) .demo-config-comparison-hint > [lang='en-US'],
html[lang='en-US'] .demo-config-comparison-hint > [lang='zh-CN'] { display: none; }
</style>
```

## Matching and suggestions

### Opening Policy

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration    | Purpose                                                                  | Related examples                              |
| ---------------- | ------------------------------------------------------------------------ | --------------------------------------------- |
| `options`        | Suggestions, including groups; unique values become strings on selection | Opening Policy, Case Sensitive, Group Spacing |
| `placeholder`    | Placeholder or floating hint text                                        | Opening Policy, Case Sensitive, Group Spacing |
| `should-open`    | Opening policy; does not filter candidates                               | Opening Policy, Group Spacing, Virtual List   |
| `filter-option`  | Filter by label; false for remote filtering                              | Opening Policy                                |
| `case-sensitive` | Case-sensitive built-in matching                                         | Case Sensitive                                |
| `trigger-props`  | Trigger configuration; cannot override owned opening and disabled state  | Group Spacing                                 |

<!-- demo-config-notes:end -->

Example source: src/auto-complete/__demos__/opening-policy.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
const value = ref("");
const allowEmpty = ref(false);
const filter = ref(true);
const shouldOpen = (text: string) => allowEmpty.value || text.length >= 2;
const options = ["Cedar", "Maple", "Vue"];
</script>
<template>
  <c-space direction="column" size="md">
    <c-checkbox v-model="allowEmpty"> 允许空输入展开</c-checkbox>
    <c-checkbox v-model="filter"> 按输入过滤候选</c-checkbox>
    <c-auto-complete
      v-model="value"
      :options="options"
      :filter-option="filter"
      :should-open="shouldOpen"
      placeholder="默认输入两个字符后展开"
    />
    <p>展开条件不负责过滤；即使允许展开，没有匹配候选也不显示菜单。</p>
  </c-space>
</template>
```

### Case Sensitive

Example source: src/auto-complete/__demos__/case-sensitive.vue

```vue
<template>
  <c-space direction="column" size="md">
    <c-auto-complete v-model="looseValue" :options="options" placeholder="默认：输入 ar" style="width: 100%; max-width: 320px" />
    <c-auto-complete v-model="caseSensitiveValue" :options="options" case-sensitive placeholder="区分大小写：输入 Ar" style="width: 100%; max-width: 320px" />
  </c-space>
</template>

<script setup lang="ts">
import { ref } from 'vue'

const options = ['Arco', 'Maple', 'Cedar']
const looseValue = ref('')
const caseSensitiveValue = ref('')
</script>
```

### Group Spacing

Example source: src/auto-complete/__demos__/group-spacing.vue

```vue
<script setup lang="ts">
const options = [
  {
    isGroup: true,
    label: "华北",
    options: [
      { value: "beijing", label: "北京" },
      { value: "tianjin", label: "天津" },
    ],
  },
  {
    isGroup: true,
    label: "华东",
    options: [
      { value: "shanghai", label: "上海" },
      { value: "hangzhou", label: "杭州" },
    ],
  },
];
</script>

<template>
  <c-space direction="column" size="md">
    <c-auto-complete
      :options="options"
      :should-open="() => true"
      placeholder="分组候选"
      :style="{ width: '280px' }"
    />
    <c-auto-complete
      :options="options"
      :should-open="() => true"
      placeholder="自定义缩进的分组候选"
      :style="{ width: '280px' }"
      :trigger-props="{ popupStyle: { '--c-auto-complete-option-padding-horizontal': '20px' } }"
    />
  </c-space>
</template>
```

### Virtual List

Example source: src/auto-complete/__demos__/virtual-list.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const value = ref('')
const options = Array.from({ length: 500 }, (_, index) => ({ value: `device-${index + 1}`, label: `Device ${index + 1}` }))
</script>
<template>
  <c-auto-complete v-model="value" :options="options" :should-open="() => true"
    :virtual-list-props="{ height: 180 }" placeholder="搜索 500 个设备" />
</template>
```

## Content and field customization

### Footer

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration | Purpose                                                                  | Related examples  |
| ------------- | ------------------------------------------------------------------------ | ----------------- |
| `options`     | Suggestions, including groups; unique values become strings on selection | Footer, Decorator |
| `placeholder` | Placeholder or floating hint text                                        | Footer, Decorator |
| `field-names` | Map value, label, disabled and other fields                              | Footer            |
| `variant`     | Input variant; inherits Group when unset                                 | Decorator         |
| `hint`        | Enable Input floating hint                                               | Decorator         |
| `clearable`   | Allow clearing a nonempty editable value                                 | Decorator         |

<!-- demo-config-notes:end -->

Example source: src/auto-complete/__demos__/footer.vue

```vue
<template>
  <c-auto-complete
    v-model="value"
    :options="options"
    :field-names="{ value: 'code', label: 'name', disabled: 'unavailable' }"
    placeholder="输入城市"
    style="width: 100%; max-width: 320px"
  >
    <template #option="{ data }">{{ data.label }} · {{ data.raw.country }}</template>
    <template #footer>
      <div style="padding: 6px 12px; color: var(--c-sys-color-content-tertiary)">选择候选或继续自由输入</div>
    </template>
  </c-auto-complete>
</template>

<script setup lang="ts">
import { ref } from 'vue'

const value = ref('')
const options = [
  { code: 'PEK', name: 'Beijing', country: 'CN' },
  { code: 'SHA', name: 'Shanghai', country: 'CN' },
  { code: 'NRT', name: 'Tokyo', country: 'JP', unavailable: true },
]
</script>
```

### Decorator

Example source: src/auto-complete/__demos__/decorator.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const value = ref('')
const options = ['Cedar', 'Maple']
</script>
<template>
  <c-space direction="column" size="md">
    <c-auto-complete v-for="variant in (['filled', 'outline', 'standard'] as const)" :key="variant"
      v-model="value" :options="options" :variant="variant" :placeholder="variant" hint clearable />
    <c-auto-complete v-model="value" :options="options" hint placeholder="自定义颜色"
      focus-color="#6750a4" text-color="#386a20" enterkeyhint="search">
      <template #prefix>@</template><template #suffix>.com</template>
    </c-auto-complete>
  </c-space>
</template>
```

## Interaction and keyboard

### Api Review

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration | Purpose                                                                  | Related examples          |
| ------------- | ------------------------------------------------------------------------ | ------------------------- |
| `options`     | Suggestions, including groups; unique values become strings on selection | Api Review, Accessibility |
| `clearable`   | Allow clearing a nonempty editable value                                 | Api Review                |
| `disabled`    | Disabled; inherited when unset, explicit false overrides                 | Api Review                |
| `readonly`    | Readonly; focus/copy allowed, suggestions stay closed                    | Api Review                |
| `error`       | Error state; inherits FormItem when unset                                | Api Review                |
| `input-attrs` | Native input attributes; combobox state is owned by the component        | Accessibility             |

<!-- demo-config-notes:end -->

</details>

Example source: src/auto-complete/__demos__/state-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref("研发");
const options = [{ value: "研发" }, { value: "研发平台" }, { value: "设计" }];
const __demoState = __demoReactive({
  disabled: false,
  readonly: false,
  error: false,
});
</script>
<template>
  <c-space direction="column" :size="16">
    <c-space wrap>
      <c-checkbox v-model="__demoState['disabled']">disabled</c-checkbox>
      <c-checkbox v-model="__demoState['readonly']">readonly</c-checkbox>
      <c-checkbox v-model="__demoState['error']">error</c-checkbox>
    </c-space>
    <c-auto-complete
      v-model="value"
      :options="options"
      clearable
      v-bind="__demoState"
    ></c-auto-complete>
  </c-space>
</template>
```

### Accessibility

Example source: src/auto-complete/__demos__/accessibility.vue

```vue
<template>
  <label :for="inputId">前端框架</label>
  <c-auto-complete
    v-model="value"
    :options="options"
    :input-attrs="{ id: inputId, 'aria-describedby': helpId }"
    style="width: 100%; max-width: 320px"
  />
  <p :id="helpId">使用方向键浏览建议，Enter 选择，Escape 关闭。</p>
</template>

<script setup lang="ts">
import { ref, useId } from 'vue'

const inputId = useId()
const helpId = useId()
const value = ref('')
const options = ['Vue', 'React', 'Angular']
</script>
```

## Async data and configuration

### Remote

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration   | Purpose                                                                  | Related examples            |
| --------------- | ------------------------------------------------------------------------ | --------------------------- |
| `options`       | Suggestions, including groups; unique values become strings on selection | Remote, Passthrough Options |
| `filter-option` | Filter by label; false for remote filtering                              | Remote                      |
| `placeholder`   | Placeholder or floating hint text                                        | Remote                      |
| `disabled`      | Disabled; inherited when unset, explicit false overrides                 | Passthrough Options         |
| `should-open`   | Opening policy; does not filter candidates                               | Passthrough Options         |
| `trigger-props` | Trigger configuration; cannot override owned opening and disabled state  | Passthrough Options         |

<!-- demo-config-notes:end -->

Example source: src/auto-complete/__demos__/remote.vue

```vue
<template>
  <c-auto-complete
    v-model="value"
    :options="options"
    :filter-option="false"
    placeholder="输入关键字获取远程建议"
    style="width: 100%; max-width: 320px"
    @search="handleSearch"
  />
</template>

<script setup lang="ts">
import { onBeforeUnmount, ref } from 'vue'

const value = ref('')
const options = ref<string[]>([])

let requestId = 0
onBeforeUnmount(() => requestId++)
const handleSearch = async (keyword: string) => {
  const current = ++requestId
  const result = await Promise.resolve(keyword ? Array.from({ length: 4 }, (_, index) => `${keyword}-${index + 1}`) : [])
  if (current === requestId) options.value = result
}
</script>
```

### Passthrough Options

Example source: src/auto-complete/__demos__/passthrough-options.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import type { AutoCompleteTriggerOptions } from "@cedar-design/ui";
const disabled = ref(false);
const triggerOptions: AutoCompleteTriggerOptions = {
  placement: "top-start",
  popupOffset: 8,
  popupContainer: false,
};
const options = [
  { value: "USER_A", label: "Apple" },
  { value: "USER_B", label: "Banana" },
];
</script>
<template>
  <c-space direction="column" fill>
    <c-button @click="disabled = !disabled">{{
      disabled ? "启用输入" : "禁用输入"
    }}</c-button>
    <c-auto-complete
      edit-mode="direct"
      :disabled="disabled"
      :should-open="() => true"
      :options="options"
      :trigger-props="triggerOptions"
      aria-label="透传配置示例"
    />
    <p role="status">
      顶层 disabled：{{ disabled }}；聚焦输入框查看向上展开的候选。
    </p>
  </c-space>
</template>
```

### Props

| Prop                 | Description                                                              | Type                                                                                     | Default                          |
| -------------------- | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- | -------------------------------- |
| `model-value`        | Controlled text                                                          | `string`                                                                                 | `—`                              |
| `default-value`      | Initial uncontrolled text                                                | `string`                                                                                 | `''`                             |
| `options`            | Suggestions, including groups; unique values become strings on selection | `(AutoCompleteOption \| SelectOptionGroup)[]` / `(query, { signal }) => Array / Promise` | `undefined`                      |
| `field-names`        | Map value, label, disabled and other fields                              | `AutoCompleteFieldNames`                                                                 | `—`                              |
| `should-open`        | Opening policy; does not filter candidates                               | `(value: string) => boolean`                                                             | `value.length > 0`               |
| `filter-option`      | Filter by label; false for remote filtering                              | `AutoCompleteFilterOption`                                                               | automatic: arrays on; loader off |
| `case-sensitive`     | Case-sensitive built-in matching                                         | `boolean`                                                                                | `false`                          |
| `popup-container`    | Popup container; same contract as Trigger                                | `PopupContainer`                                                                         | `—`                              |
| `trigger-props`      | Trigger configuration; cannot override owned opening and disabled state  | `TriggerProps`                                                                           | `—`                              |
| `virtual-list-props` | Enable and configure virtual scrolling                                   | `VirtualListProps`                                                                       | `—`                              |
| `size`               | Five sizes; inherit Group / Form / global configuration when unset       | `xs \| sm \| md \| lg \| xl`                                                             | `md`                             |
| `variant`            | Input variant; inherits Group when unset                                 | `filled \| outline \| standard`                                                          | `outline`                        |
| `disabled`           | Disabled; inherited when unset, explicit false overrides                 | `boolean`                                                                                | `undefined`                      |
| `readonly`           | Readonly; focus/copy allowed, suggestions stay closed                    | `boolean`                                                                                | `undefined`                      |
| `error`              | Error state; inherits FormItem when unset                                | `boolean`                                                                                | `undefined`                      |
| `clearable`          | Allow clearing a nonempty editable value                                 | `boolean`                                                                                | `false`                          |
| `placeholder`        | Placeholder or floating hint text                                        | `string`                                                                                 | `—`                              |
| `hint`               | Enable Input floating hint                                               | `boolean`                                                                                | `undefined`                      |
| `line`               | Show border or underline                                                 | `boolean`                                                                                | `true`                           |
| `text-color`         | Instance text color                                                      | `string`                                                                                 | `—`                              |
| `focus-color`        | Instance focus color                                                     | `string`                                                                                 | `—`                              |
| `blur-color`         | Instance unfocused hint color                                            | `string`                                                                                 | `—`                              |
| `enterkeyhint`       | Virtual keyboard action hint                                             | `InputHTMLAttributes['enterKeyHint']`                                                    | `—`                              |
| `aria-label`         | Accessible input name                                                    | `string`                                                                                 | `—`                              |
| `max-length`         | Same length normalization for typing and selecting                       | `number \| { length: number; errorOnly?: boolean }`                                      | `0`                              |
| `show-word-limit`    | Display word count                                                       | `boolean`                                                                                | `false`                          |
| `word-length`        | Custom length calculation                                                | `(value: string) => number`                                                              | `—`                              |
| `word-slice`         | Custom slicing                                                           | `(value: string, maxLength: number) => string`                                           | `—`                              |
| `input-attrs`        | Native input attributes; combobox state is owned by the component        | `Record<string, unknown>`                                                                | `—`                              |

### Events

| Event                                     | Arguments                                                     |
| ----------------------------------------- | ------------------------------------------------------------- |
| `update:model-value`                      | `value: string`                                               |
| `input / search / change`                 | `value: string, event: Event`                                 |
| `select`                                  | `value: string, option: AutoCompleteOptionInfo, event: Event` |
| `clear`                                   | `event: Event`                                                |
| `focus / blur`                            | `event: FocusEvent`                                           |
| `dropdown-scroll / dropdown-reach-bottom` | `event: Event`                                                |

### Slots

| Slot              | Description                        |
| ----------------- | ---------------------------------- |
| `option`          | `{ data: AutoCompleteOptionInfo }` |
| `footer`          | Menu footer                        |
| `prefix / suffix` | Input prefix / suffix              |
| `clear-icon`      | `{ clear }`                        |

### Shared field loading

`loading` displays the shared field indicator. `loading-mode` is `default` (indicator) or `line` (an indeterminate bottom line); it defaults to `default`. Rendering belongs to FieldDecorator. Loading does not implicitly disable editing or change readonly. Set those states separately.

## API details

| Token                                           | Default                                             |
| ----------------------------------------------- | --------------------------------------------------- |
| `--c-auto-complete-popup-max-height`            | `var(--c-select-popup-max-height)`                  |
| `--c-auto-complete-popup-bg`                    | `var(--c-select-popup-bg)`                          |
| `--c-auto-complete-popup-border-radius`         | `var(--c-select-popup-border-radius)`               |
| `--c-auto-complete-popup-padding-vertical`      | `var(--c-select-popup-padding-vertical)`            |
| `--c-auto-complete-popup-font-size`             | `var(--c-select-popup-font-size)`                   |
| `--c-auto-complete-popup-border-color`          | `var(--c-select-popup-border-color)`                |
| `--c-auto-complete-popup-box-shadow`            | `var(--c-select-popup-box-shadow)`                  |
| `--c-auto-complete-option-height`               | `var(--c-select-popup-option-height)`               |
| `--c-auto-complete-option-font-weight-selected` | `var(--c-select-popup-option-font-weight-selected)` |
| `--c-auto-complete-option-padding-horizontal`   | `var(--c-select-popup-option-padding-horizontal)`   |
| `--c-auto-complete-option-bg-default`           | `var(--c-select-popup-option-bg)`                   |
| `--c-auto-complete-option-bg-hover`             | `var(--c-select-popup-option-bg-hover)`             |
| `--c-auto-complete-option-bg-selected`          | `var(--c-select-popup-option-bg-selected)`          |
| `--c-auto-complete-option-bg-disabled`          | `var(--c-select-popup-option-bg-disabled)`          |
| `--c-auto-complete-option-text-color-default`   | `var(--c-select-popup-option-text-color)`           |
| `--c-auto-complete-option-text-color-hover`     | `var(--c-select-popup-option-text-color-hover)`     |
| `--c-auto-complete-option-text-color-selected`  | `var(--c-select-popup-option-text-color-selected)`  |
| `--c-auto-complete-option-text-color-disabled`  | `var(--c-select-popup-option-text-color-disabled)`  |

## API

### Empty values and reading placeholders

`empty-values` recognizes empty data; `empty-value` keeps existing clear output. `empty-text` defaults to `'-'` under `read-pretty`, with Field > FormItem > Form precedence and custom read slots first. With explicit empty-values, built-in required uses the policy; custom validators receive original data. See the [shared guide](llms/en-US/guide/empty-values.md).

| Prop         | Type               | Default and scope                                                           |
| ------------ | ------------------ | --------------------------------------------------------------------------- |
| empty-values | readonly unknown[] | Field > FormItem > Form > component-family default; replaces the whole list |
| empty-text   | string             | Field > FormItem > Form > '-'; explicit '' is valid                         |

These props belong to field presentation; pure panels do not gain reading mode. Form and FormItem provide inherited settings. The existing empty-value type and clear fallback remain component-specific.

### Props

| Prop                 | Description                                                              | Type                                                                                     | Default                                                      |
| -------------------- | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| `model-value`        | Controlled text                                                          | `string`                                                                                 | `—`                                                          |
| `default-value`      | Initial uncontrolled text                                                | `string`                                                                                 | `''`                                                         |
| `options`            | Suggestions, including groups; unique values become strings on selection | `(AutoCompleteOption \| SelectOptionGroup)[]` / `(query, { signal }) => Array / Promise` | `undefined`                                                  |
| `field-names`        | Map value, label, disabled and other fields                              | `AutoCompleteFieldNames`                                                                 | `—`                                                          |
| `should-open`        | Opening policy; does not filter candidates                               | `(value: string) => boolean`                                                             | `value.length > 0`                                           |
| `filter-option`      | Filter by label; false for remote filtering                              | `AutoCompleteFilterOption`                                                               | Automatic: enabled for arrays, disabled for loader functions |
| `case-sensitive`     | Case-sensitive built-in matching                                         | `boolean`                                                                                | `false`                                                      |
| `popup-container`    | Popup container; same contract as Trigger                                | `PopupContainer`                                                                         | `—`                                                          |
| `trigger-props`      | Trigger configuration; cannot override owned opening and disabled state  | `TriggerProps`                                                                           | `—`                                                          |
| `virtual-list-props` | Enable and configure virtual scrolling                                   | `VirtualListProps`                                                                       | `—`                                                          |
| `size`               | Five sizes; inherit Group / Form / global configuration when unset       | `xs \| sm \| md \| lg \| xl`                                                             | `md`                                                         |
| `variant`            | Input variant; inherits Group when unset                                 | `filled \| outline \| standard`                                                          | `outline`                                                    |
| `disabled`           | Disabled; inherited when unset, explicit false overrides                 | `boolean`                                                                                | `undefined`                                                  |
| `readonly`           | Readonly; focus/copy allowed, suggestions stay closed                    | `boolean`                                                                                | `undefined`                                                  |
| `error`              | Error state; inherits FormItem when unset                                | `boolean`                                                                                | `undefined`                                                  |
| `clearable`          | Allow clearing a nonempty editable value                                 | `boolean`                                                                                | `false`                                                      |
| `placeholder`        | Placeholder or floating hint text                                        | `string`                                                                                 | `—`                                                          |
| `hint`               | Enable Input floating hint                                               | `boolean`                                                                                | `undefined`                                                  |
| `line`               | Show border or underline                                                 | `boolean`                                                                                | `true`                                                       |
| `text-color`         | Instance text color                                                      | `string`                                                                                 | `—`                                                          |
| `focus-color`        | Instance focus color                                                     | `string`                                                                                 | `—`                                                          |
| `blur-color`         | Instance unfocused hint color                                            | `string`                                                                                 | `—`                                                          |
| `enterkeyhint`       | Virtual keyboard action hint                                             | `InputHTMLAttributes['enterKeyHint']`                                                    | `—`                                                          |
| `aria-label`         | Accessible input name                                                    | `string`                                                                                 | `—`                                                          |
| `max-length`         | Same length normalization for typing and selecting                       | `number \| { length: number; errorOnly?: boolean }`                                      | `0`                                                          |
| `show-word-limit`    | Display word count                                                       | `boolean`                                                                                | `false`                                                      |
| `word-length`        | Custom length calculation                                                | `(value: string) => number`                                                              | `—`                                                          |
| `word-slice`         | Custom slicing                                                           | `(value: string, maxLength: number) => string`                                           | `—`                                                          |
| `input-attrs`        | Native input attributes; combobox state is owned by the component        | `Record<string, unknown>`                                                                | `—`                                                          |

### Events

| Event                                     | Arguments                                                     |
| ----------------------------------------- | ------------------------------------------------------------- |
| `update:model-value`                      | `value: string`                                               |
| `input / search / change`                 | `value: string, event: Event`                                 |
| `select`                                  | `value: string, option: AutoCompleteOptionInfo, event: Event` |
| `clear`                                   | `event: Event`                                                |
| `focus / blur`                            | `event: FocusEvent`                                           |
| `dropdown-scroll / dropdown-reach-bottom` | `event: Event`                                                |

Typing: `input → update:modelValue → search`; selection: `update:modelValue → select → change`; clear: `clear → input → update:modelValue → change`. Selecting the same value emits only select. change is a commit on blur, Enter or selection. Input owns typing/focus/clear Form notifications; AutoComplete notifies Form once for suggestion commits. Selection applies maxLength; select.value is the committed string, while option.value retains the original suggestion. clear receives an event, not a string.

### Slots

| Slot              | Description                        |
| ----------------- | ---------------------------------- |
| `option`          | `{ data: AutoCompleteOptionInfo }` |
| `footer`          | Menu footer                        |
| `prefix / suffix` | Input prefix / suffix              |
| `clear-icon`      | `{ clear }`                        |

### Methods

`focus()` / `blur()`

label is text. Use the option slot or an option render function for complex candidates; function/VNode labels are not supported. Arrow keys browse, Enter selects, Escape closes, and Tab retains native focus navigation. Vue useId keeps SSR identifiers stable.

## Type definitions

```ts
import type {
  AutoCompleteProps,
  AutoCompleteInstance,
  AutoCompleteOption,
  AutoCompleteOptionData,
  AutoCompleteOptionInfo,
  AutoCompleteFieldNames,
  AutoCompleteFilterOption,
} from "@cedar-design/ui";
```

## Style variables

| Token                                           | Default                                             |
| ----------------------------------------------- | --------------------------------------------------- |
| `--c-auto-complete-popup-max-height`            | `var(--c-select-popup-max-height)`                  |
| `--c-auto-complete-popup-bg`                    | `var(--c-select-popup-bg)`                          |
| `--c-auto-complete-popup-border-radius`         | `var(--c-select-popup-border-radius)`               |
| `--c-auto-complete-popup-padding-vertical`      | `var(--c-select-popup-padding-vertical)`            |
| `--c-auto-complete-popup-font-size`             | `var(--c-select-popup-font-size)`                   |
| `--c-auto-complete-popup-border-color`          | `var(--c-select-popup-border-color)`                |
| `--c-auto-complete-popup-box-shadow`            | `var(--c-select-popup-box-shadow)`                  |
| `--c-auto-complete-option-height`               | `var(--c-select-popup-option-height)`               |
| `--c-auto-complete-option-font-weight-selected` | `var(--c-select-popup-option-font-weight-selected)` |
| `--c-auto-complete-option-padding-horizontal`   | `var(--c-select-popup-option-padding-horizontal)`   |
| `--c-auto-complete-option-bg-default`           | `var(--c-select-popup-option-bg)`                   |
| `--c-auto-complete-option-bg-hover`             | `var(--c-select-popup-option-bg-hover)`             |
| `--c-auto-complete-option-bg-selected`          | `var(--c-select-popup-option-bg-selected)`          |
| `--c-auto-complete-option-bg-disabled`          | `var(--c-select-popup-option-bg-disabled)`          |
| `--c-auto-complete-option-text-color-default`   | `var(--c-select-popup-option-text-color)`           |
| `--c-auto-complete-option-text-color-hover`     | `var(--c-select-popup-option-text-color-hover)`     |
| `--c-auto-complete-option-text-color-selected`  | `var(--c-select-popup-option-text-color-selected)`  |
| `--c-auto-complete-option-text-color-disabled`  | `var(--c-select-popup-option-text-color-disabled)`  |

Clearing does not emit search or reopen candidates, including when focus returns from a keyboard-focused clear button to the input. The parent controls the value: each rejected clear or selection still emits a change proposal; an accepted candidate selection notifies Form once.

### Form field presentation and confirmation

This component supports `edit-mode` with field > FormItem > Form precedence. When unset, it defaults to `direct` and preserves `direct` editing. Supported values: `direct / click / dblclick`. Non-`direct` modes open the editor through the field value trigger and keep one draft; v-model updates only after confirmation. Cancel, reset or enabling readPretty discards the draft.

Cedar uses edit-mode="click" / "dblclick" to open an editor popup near the field. Enter/F2 also opens it; cancel/Escape discards the draft, and confirmation commits it. readPretty is an independent reading setting, separate from readonly and disabled.

`before-commit(value, { previousValue, signal })` can reject an overlay save. FormItem validates the candidate first and keeps the editor open on failure. `open / default-open / update:open` control the editor. Use `#read="{ value, text }"` to customize display. See the full field comparison in Form.

`read-pretty` is an independent boolean alongside `readonly` and `disabled`. It inherits from field to FormItem to Form; explicit `false` overrides the parent. The default is `false`. Reading mode renders no editor.

Suggestions share Select’s list, group, selected and disabled styles. AutoComplete style variables follow the corresponding Select variables by default. In `inline` mode, the list opens below the input and follows scrolling; use `trigger-props` to explicitly change placement or enable automatic flipping. In `popup` mode, candidates use the same full editor surface as Select.

### Public type exports

Root and component entries export `AutoCompleteEmits`、`AutoCompleteSlots`、`AutoCompleteExpose` alongside Props and Instance. Emits are event argument tuples derived from the runtime validators; Expose contains focus/blur.

`case-sensitive` only makes built-in local filtering `case-sensitive`: `ap` matches `Apple` when false, but not when true. It does not require choosing an option or validate the value. A custom `filterOption` takes priority; `filterOption=false` disables local filtering and makes `case-sensitive` irrelevant.

### Migrating strict / Migration

The old `strict` prop is removed. Use `case-sensitive` (`caseSensitive` in TypeScript) instead; boolean meanings and the default false remain unchanged. This removal is marked for the next major release, without a compatibility alias.

### Built-in search fields

`searchFields` / `search-fields` is a readonly `('label' | 'value')[]`, defaulting to `['label']`. Multiple fields use OR matching, case-insensitive by default. `['value', 'label']` searches codes and names; fieldNames maps semantic fields to business fields. An empty array matches no items for a nonempty query. Values are compared as strings; object traversal, object values and pinyin matching require a custom callback. A custom callback takes precedence and decides case handling itself. Remote results use the existing protocol for disabling local filtering. Cascader retains path semantics and checks the configured fields on each path node.

## Configuring the cleared value

`empty-value` / `emptyValue` configures the model value produced by clearing. It accepts a value in the component model type, null, or a zero-argument factory. Omitting it preserves the existing default. Use `() => undefined` to distinguish omission from returning undefined. Arrays are shallow-copied on each clear; selected items that cannot be cleared remain. It does not redefine empty values, change Form reset defaults, or treat 0/false as universally empty.
Text and person-ID models remain strings; use an empty string or a business-defined string sentinel.

## Loading options through a function prop

Pass options(query, { signal }) directly; useAsyncData is unnecessary. options still accepts arrays, and an explicit array, including [], takes precedence. The component manages loading, stale-result isolation and cancellation. load-error reports failures, and the instance refresh() method retries. A business loader may accept only query and ignore the second argument.

filterable enables entering a search query. filterOption controls only local matching and never sends requests. With an options loader, remote results are not filtered again by default; with only an array, local matching is enabled by default. Most callers do not need filter-option.

```vue
<c-auto-complete v-model="text" :options="loadSuggestions" />
```

`empty-value` accepts explicit `null` (or `() => null`). Clearing publishes `null` unchanged; omitted values preserve the existing default. Editors render `null` as blank without converting ordinary empty-string input to `null`. In popup editing, clearing changes the draft; confirm commits it and cancel preserves the original model.

---

Document: llms/en-US/components/avatar.md

<!-- Source: src/avatar/README.en-US.md; locale: en-US; page: /en/components/avatar/ -->

# Avatar

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

- `color`: Overrides the color.

Example source: src/avatar/__demos__/basic.vue

```vue
<template>
  <c-space align="center" :size="16" wrap>
    <c-avatar>C</c-avatar>
    <c-avatar>CD</c-avatar>
    <c-avatar shape="square">Cedar</c-avatar>
    <c-avatar color="#00bebe">U</c-avatar>
    <c-avatar image-url="/cat.jpg" alt="一只猫" />
  </c-space>
</template>
```

## Appearance and states

### Size and shape comparison

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `shape` | Avatar shape | Size and shape comparison, Style, Hoverable |
| `image-url` | Image URL | Size and shape comparison, Hoverable |
| `alt` | Image alternative text | Size and shape comparison, Hoverable |
| `bordered` | Whether to show a border | Style, Hoverable |
| `size` | Avatar width and height; numbers are px, strings are CSS lengths | Size and shape comparison |
| `color` | Background color | Style |
<!-- demo-config-notes:end -->


Compare space used at each size, then round and square boundaries. Image fitting and fallback remain separate.

Example source: src/avatar/__demos__/shape-size-comparison.vue

```vue
<script setup lang="ts">
import { proxyRefs as demoProxyRefs } from 'vue'

const scene1 = demoProxyRefs((() => {

const numericSizes = [24, 32, 40, 48, 64] as const

const labels = { 24: 'A', 32: 'B', 40: 'C', 48: 'D', 64: 'E' } as const

const imageSizes = [28, 36, 48, 64, 78] as const

const cssSizes = ['3rem', '2.5em', '48px'] as const
return { numericSizes, labels, imageSizes, cssSizes }
})())
</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="size">
    <h4><span lang="zh-CN">尺寸</span><span lang="en-US">size</span></h4>
    <c-space direction="column" :size="20">
        <c-space align="flex-end" :size="16" wrap>
          <c-space v-for="size in scene1.numericSizes" :key="size" direction="column" align="center" :size="8">
            <c-avatar :size="size">{{ scene1.labels[size] }}</c-avatar>
            <span class="label">{{ size }}px</span>
          </c-space>
        </c-space>
    
        <c-space align="flex-end" :size="16" wrap>
          <c-space v-for="size in scene1.imageSizes" :key="size" direction="column" align="center" :size="8">
            <c-avatar image-url="/cat.jpg" :alt="`${size}px`" :size="size" />
            <span class="label">{{ size }}px</span>
          </c-space>
        </c-space>
    
        <c-space align="flex-end" :size="16" wrap>
          <c-space v-for="size in scene1.cssSizes" :key="size" direction="column" align="center" :size="8">
            <c-avatar :size="size">Aa</c-avatar>
            <span class="label">{{ size }}</span>
          </c-space>
        </c-space>
      </c-space>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="shape">
    <h4><span lang="zh-CN">形状</span><span lang="en-US">shape</span></h4>
    <c-space align="flex-end" :size="16" wrap>
        <c-space direction="column" align="center" :size="8">
          <c-avatar>圆</c-avatar>
          <span class="label">circle</span>
        </c-space>
        <c-space direction="column" align="center" :size="8">
          <c-avatar shape="square">方</c-avatar>
          <span class="label">square</span>
        </c-space>
        <c-space direction="column" align="center" :size="8">
          <c-avatar image-url="/cat.jpg" alt="圆形图片" />
          <span class="label">circle · 图片</span>
        </c-space>
        <c-space direction="column" align="center" :size="8">
          <c-avatar image-url="/cat.jpg" alt="方形图片" shape="square" />
          <span class="label">square · 图片</span>
        </c-space>
      </c-space>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }
.demo-comparison-case--1 {

.label {
  color: var(--c-color-text-3);
  font-size: var(--c-font-size-sm);
}

}
.demo-comparison-case--2 {

.label {
  color: var(--c-color-text-3);
  font-size: var(--c-font-size-sm);
}

}
</style>
```

### Style

- `color`: Overrides the color.

Example source: src/avatar/__demos__/style.vue

```vue
<template>
  <c-space align="center" :size="16" wrap>
    <c-avatar color="var(--c-color-warning)">火</c-avatar>
    <c-avatar color="var(--c-color-danger)">Cedar</c-avatar>
    <c-avatar color="#00bebe">CD</c-avatar>
    <c-avatar color="#7b61ff" shape="square">A</c-avatar>
    <c-avatar bordered>B</c-avatar>
    <c-avatar bordered border-color="#00bebe" color="#e6fffb">C</c-avatar>
  </c-space>
</template>
```

### Hoverable

Preview configuration: `hoverable`, `image-url="/cat.jpg"`, `alt="悬停放大"`, `shape="square"`.

Example source: src/avatar/__demos__/hoverable.vue

```vue
<template>
  <c-space direction="column" :size="24">
    <c-space align="center" :size="16" wrap>
      <c-avatar hoverable>H</c-avatar>
      <c-avatar hoverable image-url="/cat.jpg" alt="悬停放大" />
      <c-avatar hoverable shape="square">方</c-avatar>
    </c-space>
    <c-avatar-group>
      <c-avatar hoverable image-url="/cat.jpg" alt="用户一" bordered />
      <c-avatar hoverable image-url="/cat2.jpg" alt="用户二" bordered />
      <c-avatar hoverable image-url="/cat.jpg" alt="用户三" bordered />
      <c-avatar hoverable bordered>+2</c-avatar>
    </c-avatar-group>
  </c-space>
</template>
```

## Layout and arrangement

### Group direction and overflow

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `image-url` | Image URL | Group direction and overflow |
| `alt` | Image alternative text | Group direction and overflow |
| `bordered` | Whether to show a border | Group direction and overflow |
| `color` | Background color | Group direction and overflow |
<!-- demo-config-notes:end -->


Compare horizontal and vertical groups, maximum counts, stacking and overflow indicators.

Example source: src/avatar/__demos__/group-comparison.vue

```vue
<script setup lang="ts">


</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="group">
    <h4><span lang="zh-CN">头像组</span><span lang="en-US">group</span></h4>
    <c-space direction="column" :size="24">
        <c-space direction="column" :size="8">
          <span class="label">默认叠层</span>
          <c-avatar-group>
            <c-avatar image-url="/cat.jpg" alt="用户一" bordered />
            <c-avatar image-url="/cat2.jpg" alt="用户二" bordered />
            <c-avatar image-url="/cat.jpg" alt="用户三" bordered />
            <c-avatar bordered>+2</c-avatar>
          </c-avatar-group>
        </c-space>
    
        <c-space direction="column" :size="8">
          <span class="label">max-count + max-style</span>
          <c-avatar-group
            :max-count="3"
            :size="48"
            :max-style="{
      backgroundColor: '#1d2129',
      color: '#fff'
    }"
          >
            <c-avatar image-url="/cat.jpg" alt="用户一" />
            <c-avatar image-url="/cat2.jpg" alt="用户二" />
            <c-avatar color="#00bebe">A</c-avatar>
            <c-avatar color="#f59e0b">B</c-avatar>
            <c-avatar color="#ef4444">C</c-avatar>
          </c-avatar-group>
        </c-space>
    
        <c-space direction="column" :size="8">
          <span class="label">z-index-ascend</span>
          <c-avatar-group z-index-ascend>
            <c-avatar image-url="/cat.jpg" alt="用户一" />
            <c-avatar image-url="/cat2.jpg" alt="用户二" />
            <c-avatar color="#7b61ff">CD</c-avatar>
          </c-avatar-group>
        </c-space>
    
        <c-space direction="column" :size="8">
          <span class="label">shape="square" · offset="-16"</span>
          <c-avatar-group shape="square" :offset="-16" :size="40">
            <c-avatar image-url="/cat.jpg" alt="用户一" />
            <c-avatar image-url="/cat2.jpg" alt="用户二" />
            <c-avatar color="#00bebe">A</c-avatar>
            <c-avatar color="#7b61ff">B</c-avatar>
          </c-avatar-group>
        </c-space>
      </c-space>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="group-vertical">
    <h4><span lang="zh-CN">纵向头像组</span><span lang="en-US">group vertical</span></h4>
    <c-space align="flex-end" :size="32" wrap>
        <c-space direction="column" :size="8">
          <span class="label">offset = -12</span>
          <c-avatar-group vertical :offset="-12">
            <c-avatar image-url="/cat.jpg" alt="用户一" bordered />
            <c-avatar image-url="/cat2.jpg" alt="用户二" bordered />
            <c-avatar image-url="/cat.jpg" alt="用户三" bordered />
            <c-avatar bordered>+2</c-avatar>
          </c-avatar-group>
        </c-space>
        <c-space direction="column" :size="8">
          <span class="label">offset = -20</span>
          <c-avatar-group vertical :offset="-20" :size="48">
            <c-avatar image-url="/cat.jpg" alt="用户一" bordered />
            <c-avatar image-url="/cat2.jpg" alt="用户二" bordered />
            <c-avatar color="#00bebe">A</c-avatar>
          </c-avatar-group>
        </c-space>
      </c-space>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }
.demo-comparison-case--1 {

.label {
  color: var(--c-color-text-3);
  font-size: var(--c-font-size-sm);
}

}
.demo-comparison-case--2 {

.label {
  color: var(--c-color-text-3);
  font-size: var(--c-font-size-sm);
}

}
</style>
```

## Content and presentation

### Auto Fix

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `image-url` | Image URL | Image, Fit, Fallback |
| `alt` | Image alternative text | Image, Fit, Fallback |
| `size` | Avatar width and height; numbers are px, strings are CSS lengths | Image, Fit, Fallback |
| `shape` | Avatar shape | Auto Fix, Image |
| `auto-fix-font-size` | Whether to shrink long text automatically | Auto Fix |
| `object-fit` | Image fitting mode | Fit |
<!-- demo-config-notes:end -->


Preview configuration: `shape="square"`, `:auto-fix-font-size="false"`, `placeholder="输入更长的文字看缩放"`, `clearable`.

Example source: src/avatar/__demos__/auto-fix.vue

```vue
<template>
  <c-space direction="column" :size="16">
    <c-space align="center" :size="16" wrap>
      <c-space direction="column" align="center" :size="8">
        <c-avatar>{{ text }}</c-avatar>
        <span class="label">圆形 · 自适应</span>
      </c-space>
      <c-space direction="column" align="center" :size="8">
        <c-avatar shape="square">{{ text }}</c-avatar>
        <span class="label">方形 · 自适应</span>
      </c-space>
      <c-space direction="column" align="center" :size="8">
        <c-avatar :auto-fix-font-size="false">{{ text }}</c-avatar>
        <span class="label">关闭自适应</span>
      </c-space>
    </c-space>
    <c-input v-model="text" :style="{ width: '240px' }" placeholder="输入更长的文字看缩放" clearable />
  </c-space>
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const text = ref('Cedar')
</script>

<style scoped>
.label {
  color: var(--c-color-text-3);
  font-size: var(--c-font-size-sm);
}
</style>
```

### Image

- `size`: Controls the component size.

Example source: src/avatar/__demos__/image.vue

```vue
<template>
  <c-space align="center" :size="16" wrap>
    <c-space direction="column" align="center" :size="8">
      <c-avatar image-url="/cat.jpg" alt="一只猫" />
      <span class="label">image-url</span>
    </c-space>
    <c-space direction="column" align="center" :size="8">
      <c-avatar image-url="/cat2.jpg" alt="一只猫" :size="48" shape="square" />
      <span class="label">方形图片</span>
    </c-space>
    <c-space direction="column" align="center" :size="8">
      <c-avatar :size="48">
        <img src="/cat.jpg" alt="默认插槽中的图片" />
      </c-avatar>
      <span class="label">默认插槽 img</span>
    </c-space>
  </c-space>
</template>

<style scoped>
.label {
  color: var(--c-color-text-3);
  font-size: var(--c-font-size-sm);
}
</style>
```

### Fit

- `size`: Controls the component size.

Example source: src/avatar/__demos__/fit.vue

```vue
<template>
  <c-space align="flex-end" :size="24" wrap>
    <c-space v-for="fit in fits" :key="fit" direction="column" align="center" :size="8">
      <c-avatar image-url="/cat.jpg" :alt="fit" :object-fit="fit" :size="56" />
      <span class="label">{{ fit }}</span>
    </c-space>
  </c-space>
</template>

<script lang="ts" setup>
const fits = ['fill', 'contain', 'cover', 'none', 'scale-down'] as const
</script>

<style scoped>
.label {
  color: var(--c-color-text-3);
  font-size: var(--c-font-size-sm);
}
</style>
```

### Fallback

- `size`: Controls the component size.

Example source: src/avatar/__demos__/fallback.vue

```vue
<template>
  <c-space align="flex-end" :size="24" wrap>
    <c-space direction="column" align="center" :size="8">
      <c-avatar lazy image-url="/cat.jpg" loading="/cat2.jpg" alt="懒加载与占位图" :size="48" />
      <span class="label">lazy + loading</span>
    </c-space>
    <c-space direction="column" align="center" :size="8">
      <c-avatar image-url="data:image/png;base64,AA==" error="/cat.jpg" alt="失败时回退到占位图" :size="48" />
      <span class="label">error 图片</span>
    </c-space>
    <c-space direction="column" align="center" :size="8">
      <c-avatar image-url="data:image/png;base64,AA==" alt="失败插槽" :size="48">
        <template #error>NA</template>
      </c-avatar>
      <span class="label">error 插槽</span>
    </c-space>
  </c-space>
</template>

<style scoped>
.label {
  color: var(--c-color-text-3);
  font-size: var(--c-font-size-sm);
}
</style>
```

## Interaction and control

### Trigger

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `image-url` | Image URL | Trigger |
| `alt` | Image alternative text | Trigger |
| `size` | Avatar width and height; numbers are px, strings are CSS lengths | Trigger |
| `trigger-type` | How the action icon is shown | Trigger |
<!-- demo-config-notes:end -->


- `size`: Controls the component size.

Example source: src/avatar/__demos__/trigger.vue

```vue
<template>
  <c-space align="flex-end" :size="32" wrap>
    <c-space direction="column" align="center" :size="8">
      <c-avatar image-url="/cat.jpg" alt="编辑头像" :size="56" @click="onClick('button')">
        <template #trigger-icon>+</template>
      </c-avatar>
      <span class="label">{{ last === 'button' ? 'click · button' : 'trigger-type="button"' }}</span>
    </c-space>

    <c-space direction="column" align="center" :size="8">
      <c-avatar
        image-url="/cat2.jpg"
        alt="更换头像"
        :size="56"
        trigger-type="overlay"
        @click="onClick('overlay')"
      >
        <template #trigger-icon>+</template>
      </c-avatar>
      <span class="label">{{ last === 'overlay' ? 'click · overlay' : 'trigger-type="overlay"' }}</span>
    </c-space>
  </c-space>
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const last = ref('')

function onClick(type: string) {
  last.value = type
}
</script>

<style scoped>
.label {
  color: var(--c-color-text-3);
  font-size: var(--c-font-size-sm);
}
</style>
```

## API

<!-- same-source-api:start -->
### Props

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| shape | Avatar shape | `circle / square` | `circle` |
| image-url | Image URL | `string` | `-` |
| alt | Image alternative text | `string` | `''` |
| size | Avatar width and height; numbers are px, strings are CSS lengths | `number / string` | `-` |
| auto-fix-font-size | Whether to shrink long text automatically | `boolean` | `true` |
| trigger-type | How the action icon is shown | `button / overlay` | `button` |
| trigger-icon-style | Custom style for the action icon | `CSSProperties` | `-` |
| object-fit | Image fitting mode | `fill / contain / cover / none / scale-down` | `cover` |
| color | Background color | `string` | `-` |
| bordered | Whether to show a border | `boolean` | `false` |
| border-color | Border color | `string` | `-` |
| loading | Placeholder image while loading | `string` | `-` |
| error | Fallback image URL when image loading fails | `string` | `-` |
| lazy | Whether to lazy-load the image | `boolean` | `false` |
| hoverable | Whether to scale on hover | `boolean` | `false` |

### Events

| Event | Description | Arguments |
| --- | --- | --- |
| click | Emitted when the avatar is clicked | `(event: MouseEvent) => void` |
| load | Emitted when the image loads | `() => void` |
| error | Emitted when image loading fails | `() => void` |

### Slots

| Slot | Description |
| --- | --- |
| default | Text, icon, or loading content for an image |
| error | Fallback content when image loading fails |
| trigger-icon | Action icon on the avatar |

### Methods

No custom public methods.
<!-- same-source-api:end -->

### AvatarGroup Props

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| shape | Child avatar shape | `circle / square` | `circle` |
| size | Child avatar width and height; numbers are px, strings are CSS lengths | `number / string` | `-` |
| auto-fix-font-size | Whether to shrink child avatar text automatically | `boolean` | `true` |
| max-count | Maximum visible avatars; `0` means unlimited | `number` | `0` |
| z-index-ascend | Use ascending stacking order | `boolean` | `false` |
| max-style | Custom summary avatar style | `CSSProperties` | `-` |
| max-popover-props | Summary Popover props | `PopoverProps` | `-` |
| offset | Overlap offset | `number / string` | `-` |
| vertical | Stack avatars vertically | `boolean` | `false` |

### AvatarGroup Slots

| Slot | Description |
| --- | --- |
| default | Avatar list |

### Type definitions

```ts
import type {
  AvatarGroupInstance,
  AvatarGroupProps,
  AvatarInstance,
  AvatarProps,
  AvatarObjectFit,
  AvatarShape,
  AvatarTriggerType,
} from "@cedar-design/ui";
```

### Style variables

| Variable | Default |
| --- | --- |
| `--c-avatar-size-default` | `40px` |
| `--c-avatar-font-size-text` | `20px` |
| `--c-avatar-text-color` | `var(--c-sys-color-content-primary)` |
| `--c-avatar-text-padding-inline` | `4px` |
| `--c-avatar-bg` | `var(--c-color-fill-4)` |
| `--c-avatar-border-width` | `2px` |
| `--c-avatar-border-color` | `var(--c-sys-color-surface-default)` |
| `--c-avatar-group-item-border` | `var(--c-sys-color-surface-default)` |
| `--c-avatar-group-item-border-width` | `2px` |
| `--c-avatar-group-offset` | `-10px` |
| `--c-avatar-group-popover-item-spacing` | `8px` |
| `--c-avatar-font-weight-text` | `500` |
| `--c-avatar-circle-border-radius` | `50%` |
| `--c-avatar-square-border-radius` | `4px` |
| `--c-avatar-size-trigger-button` | `20px` |
| `--c-avatar-trigger-button-bg` | `var(--c-color-fill-2)` |
| `--c-avatar-trigger-button-bg-hover` | `var(--c-color-fill-3)` |
| `--c-avatar-trigger-overlay-icon` | `var(--c-sys-color-content-on-dark)` |
| `--c-avatar-trigger-overlay-bg` | `color-mix(in srgb, var(--c-color-black) 60%, transparent)` |
| `--c-avatar-trigger-icon-button` | `var(--c-sys-color-content-primary)` |
| `--c-avatar-spacing-trigger-button-right` | `4px` |
| `--c-avatar-spacing-trigger-button-bottom` | `4px` |
| `--c-avatar-size-trigger-icon` | `12px` |
| `--c-avatar-trigger-button-border-radius` | `50%` |
| `--c-avatar-font-size-max-count` | `20px` |
| `--c-avatar-max-count-text-color` | `var(--c-sys-color-content-primary)` |
| `--c-avatar-trigger-overlay-font-size` | `16px` |
| `--c-avatar-hover-transform` | `scale(1.1)` |
| `--c-avatar-motion-duration` | `0.2s` |
| `--c-avatar-z-index-trigger` | `1` |
| `--c-avatar-z-index-overlay` | `0` |
| `--c-avatar-z-index-overlay-hover` | `2` |

Text, summary counts and button trigger icons use the primary content `color` by default. Borders follow the container surface; only icons on dark interaction overlays use `content-on-dark`. The avatar `fill-4` background, button background/hover levels and translucent black overlay remain component visual values. When overriding the avatar background with `color`, also check text contrast and override `text-color` if needed.

### Reduced motion

Built-in CSS transitions follow `prefers-reduced-motion: reduce`. Removing transitions does not change final visibility, selected/expanded state or event semantics. Applications control custom animations inside slots.

---

Document: llms/en-US/components/back-top.md

<!-- Source: src/back-top/README.en-US.md; locale: en-US; page: /en/components/back-top/ -->

# BackTop

Visibility RAF and JS duration/easing interpolation have separate ownership. Old listeners/canceled or consumed frames cannot replay after target replacement/deactivation/disposal. Recheck after custom easing before writing; RAF/cancel/time origin use the target owner window. Retained inactive/disposed commands are inert, activation does not resume old animation. Scoped14/full30 per copy pass using controlled queues/iframe, not native browser/OS proof. Default200ms/API remain; no CSS token added.

A native button that scrolls the page or an explicit container to the top.

## Basic examples

### Basic usage

Example source: src/back-top/__demos__/basic.vue

```vue
<script setup lang="ts">
import { onMounted, ref } from 'vue'

const scroller = ref<HTMLElement>()
onMounted(() => {
  if (scroller.value) {
    scroller.value.scrollTop = 240
    scroller.value.dispatchEvent(new Event('scroll'))
  }
})
</script>

<template>
  <div class="back-top-demo">
    <p>在面板内滚动，超过 120px 时显示按钮。</p>
    <div class="back-top-demo__frame">
      <div ref="scroller" class="back-top-demo__scroll">
        <p v-for="row in 30" :key="row">A · 滚动内容 {{ row }}</p>
      </div>
      <c-back-top
        :target-container="() => scroller"
        :popup-container="false"
        :visible-height="120"
        :right="16"
        :bottom="16"
        aria-label="回到顶部"
      />
    </div>
  </div>
</template>

<style scoped>
.back-top-demo { display: flex; flex-direction: column; gap: 12px; }
.back-top-demo > p { margin: 0; }
.back-top-demo__frame { position: relative; display: flex; gap: 12px; }
.back-top-demo__scroll { flex: 1; min-width: 0; height: 240px; overflow: auto; border: 1px solid #ddd; border-radius: 8px; }
.back-top-demo__scroll p { padding: 8px 12px; margin: 0; }
</style>
```

## Customization and slots

### Custom position

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `target-container` | Scroll target; omitted means page | Custom position |
| `popup-container` | Render target; false renders locally | Custom position |
| `visible-height` | Inclusive scroll threshold in px, numeric strings accepted | Custom position |
| `right` | Right offset; number in px, string accepts CSS units | Custom position |
| `bottom` | Bottom offset; number in px, string accepts CSS units | Custom position |
| `aria-label` | Accessible name | Custom position |
<!-- demo-config-notes:end -->


Example source: src/back-top/__demos__/custom-position.vue

```vue
<script setup lang="ts">
import { onMounted, ref } from 'vue'

const scroller = ref<HTMLElement>()
onMounted(() => {
  if (scroller.value) {
    scroller.value.scrollTop = 240
    scroller.value.dispatchEvent(new Event('scroll'))
  }
})
</script>

<template>
  <div class="back-top-demo">
    <p>在面板内滚动，超过 120px 时显示按钮。</p>
    <div class="back-top-demo__frame">
      <div ref="scroller" class="back-top-demo__scroll">
        <p v-for="row in 30" :key="row">A · 滚动内容 {{ row }}</p>
      </div>
      <c-back-top
        :target-container="() => scroller"
        :popup-container="false"
        :visible-height="120"
        :right="64"
        :bottom="32"
        aria-label="回到顶部"
      />
    </div>
  </div>
</template>

<style scoped>
.back-top-demo { display: flex; flex-direction: column; gap: 12px; }
.back-top-demo > p { margin: 0; }
.back-top-demo__frame { position: relative; display: flex; gap: 12px; }
.back-top-demo__scroll { flex: 1; min-width: 0; height: 240px; overflow: auto; border: 1px solid #ddd; border-radius: 8px; }
.back-top-demo__scroll p { padding: 8px 12px; margin: 0; }
</style>
```

## Interaction and control

### Switch scroll container

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `target-container` | Scroll target; omitted means page | Switch scroll container, Content and events |
| `popup-container` | Render target; false renders locally | Switch scroll container, Content and events |
| `visible-height` | Inclusive scroll threshold in px, numeric strings accepted | Switch scroll container, Content and events |
| `right` | Right offset; number in px, string accepts CSS units | Switch scroll container, Content and events |
| `bottom` | Bottom offset; number in px, string accepts CSS units | Switch scroll container, Content and events |
| `aria-label` | Accessible name | Switch scroll container, Content and events |
<!-- demo-config-notes:end -->


Example source: src/back-top/__demos__/container.vue

```vue
<script setup lang="ts">
import { onMounted, ref } from 'vue'

const scroller = ref<HTMLElement>()
const second = ref<HTMLElement>()
const useSecond = ref(false)
onMounted(() => {
  if (scroller.value) {
    scroller.value.scrollTop = 240
    scroller.value.dispatchEvent(new Event('scroll'))
  }
})
</script>

<template>
  <div class="back-top-demo">
    <p>在面板内滚动，超过 120px 时显示按钮。</p>
    <c-button @click="useSecond = !useSecond">切换滚动目标 {{ useSecond ? 'B' : 'A' }}</c-button>
    <div class="back-top-demo__frame">
      <div ref="scroller" class="back-top-demo__scroll">
        <p v-for="row in 30" :key="row">A · 滚动内容 {{ row }}</p>
      </div>
      <div ref="second" class="back-top-demo__scroll">
        <p v-for="row in 30" :key="row">B · 滚动内容 {{ row }}</p>
      </div>
      <c-back-top
        :target-container="() => useSecond ? second : scroller"
        :popup-container="false"
        :visible-height="120"
        :right="16"
        :bottom="16"
        aria-label="回到顶部"
      />
    </div>
  </div>
</template>

<style scoped>
.back-top-demo { display: flex; flex-direction: column; gap: 12px; }
.back-top-demo > p { margin: 0; }
.back-top-demo__frame { position: relative; display: flex; gap: 12px; }
.back-top-demo__scroll { flex: 1; min-width: 0; height: 240px; overflow: auto; border: 1px solid #ddd; border-radius: 8px; }
.back-top-demo__scroll p { padding: 8px 12px; margin: 0; }
</style>
```

### Content and events

Example source: src/back-top/__demos__/custom.vue

```vue
<script setup lang="ts">
import { onMounted, ref } from 'vue'

const scroller = ref<HTMLElement>()
const clicks = ref(0)
onMounted(() => {
  if (scroller.value) {
    scroller.value.scrollTop = 240
    scroller.value.dispatchEvent(new Event('scroll'))
  }
})
</script>

<template>
  <div class="back-top-demo">
    <p>在面板内滚动，超过 120px 时显示按钮。 {{ '点击次数：' }}{{ clicks }}</p>
    <div class="back-top-demo__frame">
      <div ref="scroller" class="back-top-demo__scroll">
        <p v-for="row in 30" :key="row">A · 滚动内容 {{ row }}</p>
      </div>
      <c-back-top
        :target-container="() => scroller"
        :popup-container="false"
        :visible-height="120"
        :right="16"
        :bottom="16"
        @click="clicks++"
        aria-label="回到顶部"
      >TOP</c-back-top>
    </div>
  </div>
</template>

<style scoped>
.back-top-demo { display: flex; flex-direction: column; gap: 12px; }
.back-top-demo > p { margin: 0; }
.back-top-demo__frame { position: relative; display: flex; gap: 12px; }
.back-top-demo__scroll { flex: 1; min-width: 0; height: 240px; overflow: auto; border: 1px solid #ddd; border-radius: 8px; }
.back-top-demo__scroll p { padding: 8px 12px; margin: 0; }
</style>
```

The examples use isolated local containers. Omit `target-container` to listen to the page, not the nearest scrollable ancestor. A selector that is invalid or missing hides the button; use a reactive getter for a container mounted asynchronously. `popup-container` controls where the button renders, not what scrolls.

## Lifecycle and edge cases

### Scheduling Lifecycle

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `target-container` | Scroll target; omitted means page | Scheduling Lifecycle |
| `popup-container` | Render target; false renders locally | Scheduling Lifecycle |
| `duration` | Animation duration in ms; 0 is immediate | Scheduling Lifecycle |
| `easing` | Built-in curve or normalized progress function | Scheduling Lifecycle |
<!-- demo-config-notes:end -->


Example source: src/back-top/__demos__/scheduler-lifecycle.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import type { BackTopInstance } from "@cedar-design/ui";
const first = ref<HTMLElement>();
const second = ref<HTMLElement>();
const active = ref(true);
const alternate = ref(false);
let retained: BackTopInstance | undefined;
const capture = (instance: BackTopInstance | null) => {
  if (instance) retained = instance;
};
const lower = () => {
  if (first.value) first.value.scrollTop = 300;
  if (second.value) second.value.scrollTop = 300;
};
</script>
<template>
  <div style="position: relative">
    <c-button @click="lower">Scroll down / 滚动到底部</c-button>
    <c-button @click="alternate = !alternate"
      >Switch target / 切换目标</c-button
    >
    <c-button @click="active = !active">Activate / 停用与激活</c-button>
    <c-button @click="retained?.scrollToTop()"
      >Retained command / 保留命令</c-button
    >
    <p>
      Start an animation, switch or deactivate before completion. Old work must
      not resume.
    </p>
    <div ref="first" style="height: 100px; overflow: auto">
      <div style="height: 500px">Target A</div>
    </div>
    <div ref="second" style="height: 100px; overflow: auto">
      <div style="height: 500px">Target B</div>
    </div>
    <KeepAlive>
      <c-back-top
        v-if="active"
        :ref="capture"
        :target-container="() => (alternate ? second : first)"
        :popup-container="false"
        :duration="1000"
        easing="linear"
      />
    </KeepAlive>
  </div>
</template>
```

## API

### Props

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| `target-container` | Scroll target; omitted means page | `string \| HTMLElement \| (() => HTMLElement \| null \| undefined)` | `—` |
| `popup-container` | Render target; false renders locally | `string \| HTMLElement \| false` | `body` |
| `visible-height` | Inclusive scroll threshold in px, numeric strings accepted | `number \| string` | `200` |
| `duration` | Animation duration in ms; 0 is immediate | `number` | `200` |
| `easing` | Built-in curve or normalized progress function | `'linear' \| 'quartOut' \| 'easeInOutCubic' \| ((progress: number) => number)` | `'quartOut'` |
| `right` | Right offset; number in px, string accepts CSS units | `number \| string` | `—` |
| `bottom` | Bottom offset; number in px, string accepts CSS units | `number \| string` | `—` |
| `elevation` | Shadow level; true uses level 2 | `boolean \| number` | `true` |
| `aria-label` | Accessible name | `string` | `'Back to top'` |

When `popup-container=false`, the button is positioned absolutely; give its containing block `position: relative`. Repeated clicks replace the previous animation; changing target, deactivation and unmount cancel queued work. Reduced-motion preference skips animation. Horizontal scroll position is preserved.

### Events / slots / methods

- `click(event: MouseEvent)`: emitted once per activation.
- Default slot: noninteractive text or icons. The root is already a native button; do not nest another Button or link.
- `scrollToTop()`: scrolls the current target without emitting an additional click.
- Keyboard: Tab focuses the visible button; Enter / Space activates it. Hidden buttons are not focusable.

### Types

```ts
import type { BackTopProps, BackTopInstance, BackTopTarget, BackTopEasing } from '@cedar-design/ui'
```

### Style variables

| Token | Default |
| --- | --- |
| `--c-back-top-right` | `40px` |
| `--c-back-top-bottom` | `40px` |
| `--c-back-top-button-size` | `var(--c-sys-control-touch-target)` |
| `--c-back-top-button-border-radius` | `50%` |
| `--c-back-top-font-size` | `var(--c-sys-font-size-md)` |
| `--c-back-top-icon-size` | `20px` |
| `--c-back-top-background` | `var(--c-sys-color-surface-raised)` |
| `--c-back-top-text-color` | `var(--c-sys-color-content-brand)` |
| `--c-back-top-hover-background` | `var(--c-sys-color-state-hover)` |
| `--c-back-top-focus-color` | `var(--c-sys-color-content-brand)` |
| `--c-back-top-focus-width` | `2px` |
| `--c-back-top-focus-offset` | `2px` |
| `--c-back-top-z-index` | `var(--c-z-index-local-sticky)` |

Pre-release migration: Cedar `margin-right/bottom` → `right/bottom`, `button-size-width` → `button-size`, `button-size-font/icon` → `font-size/icon-size`, `button-bg/bg-hover/text-color` → `background/hover-background/text-color` (all with the component prefix). Maple duration is now 200ms; default target is the page. Legacy arbitrary BTween curve names are replaced with the documented presets or a function. No aliases remain.

---

Document: llms/en-US/components/badge.md

<!-- Source: src/badge/README.en-US.md; locale: en-US; page: /en/components/badge/ -->

# Badge

The same scenarios, parameters and interactions as Cedar. Only component prefixes differ; themes and site shells remain independent.

## Basic examples

### Basic usage

Badges use a red background and white text by default.

Example source: src/badge/__demos__/basic.vue

```vue
<template>
  <c-space wrap :size="24"
    ><c-badge :content="9"
      ><span style="display: inline-block; padding: 12px; border: 1px solid currentColor; border-radius: 4px"
        >Inbox</span
      ></c-badge
    ><c-badge :content="9" dot
      ><span style="display: inline-block; padding: 12px; border: 1px solid currentColor; border-radius: 4px"
        >Inbox</span
      ></c-badge
    ><c-badge
      ><template #content><span aria-label="New activity">!</span></template
      ><span style="display: inline-block; padding: 12px; border: 1px solid currentColor; border-radius: 4px"
        >Inbox</span
      ></c-badge
    ></c-space
  >
</template>
```

## Appearance and states

### Statuses and colors

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `content` | Badge content | Statuses and colors, Appearance configuration comparison |
| `status` | Semantic status | Statuses and colors |
| `mode` | Layout mode | Statuses and colors |
| `description` | Fallback description text | Statuses and colors |
| `color` | Custom color; outline uses it for border and text | Statuses and colors |
| `text-color` | Content text color | Statuses and colors |
<!-- demo-config-notes:end -->


Example source: src/badge/__demos__/color.vue

```vue
<script setup lang="ts">
const statuses = [
  'default',
  'primary',
  'secondary',
  'tertiary',
  'info',
  'success',
  'warning',
  'danger',
] as const
</script>

<template>
  <c-space direction="column">
    <c-space wrap
      ><c-badge
        v-for="status in statuses"
        :key="status"
        :status="status"
        mode="inline"
        :description="status"
        :content="1"
    /></c-space>
    <c-space wrap
      ><c-badge v-for="status in statuses" :key="status" :status="status" :content="status"
    /></c-space>
    <c-space wrap
      ><c-badge color="#7816ff" text-color="#ffffff" content="Purple" /><c-badge
        color="#005f73"
        text-color="#ffffff"
        content="Teal"
    /></c-space>
  </c-space>
</template>
```

### Appearance configuration comparison

Choose a dimension to compare all its values side by side while keeping other settings and content identical. Change the other settings to inspect combinations; input specimens share one model.

Example source: src/badge/__demos__/appearance-lab.vue

```vue
<script setup lang="ts">
import { reactive as __demoReactive } from "vue";

const __demoAppearance = __demoReactive({
  variant: "default",
  status: "default",
  size: "md",
});

import { computed as demoComputed, ref as demoRef } from 'vue'
const demoCompareFields = [{"name":"variant","values":["default","outline"]},{"name":"status","values":["default","primary","secondary","tertiary","info","success","warning","danger"]},{"name":"size","values":["xs","sm","md","lg","xl"]}]
const demoCompareAxis = demoRef("variant")
const demoComparedOptions = demoComputed(() => demoCompareFields.find(field => field.name === demoCompareAxis.value)?.values ?? [])
</script>
<template>
  <c-space direction="column" :size="16">
    <c-form layout="vertical">
      <c-form-item layout="vertical" size="sm" label="variant">
        <c-radio-group
          v-model="__demoAppearance['variant']"
          aria-label="variant"
          :options="[
            { label: 'default', value: 'default' },
            { label: 'outline', value: 'outline' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
      <c-form-item layout="vertical" size="sm" label="status">
        <c-select
          v-model="__demoAppearance['status']"
          :clearable="false"
          :options="[
            { label: 'default', value: 'default' },
            { label: 'primary', value: 'primary' },
            { label: 'secondary', value: 'secondary' },
            { label: 'tertiary', value: 'tertiary' },
            { label: 'info', value: 'info' },
            { label: 'success', value: 'success' },
            { label: 'warning', value: 'warning' },
            { label: 'danger', value: 'danger' },
          ]"
          aria-label="status"
        />
      </c-form-item>
      <c-form-item layout="vertical" size="sm" label="size">
        <c-radio-group
          v-model="__demoAppearance['size']"
          aria-label="size"
          :options="[
            { label: 'xs', value: 'xs' },
            { label: 'sm', value: 'sm' },
            { label: 'md', value: 'md' },
            { label: 'lg', value: 'lg' },
            { label: 'xl', value: 'xl' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
    </c-form>
    <p class="demo-config-comparison-hint"><span lang="zh-CN">选择一个对比维度；其他配置和内容保持一致。输入类示例共享同一个值，便于比较外观。</span><span lang="en-US">Compare one dimension while keeping the other settings and content identical. Input specimens share the same value.</span></p>
<c-radio-group v-model="demoCompareAxis" aria-label="Compare configuration" :options="demoCompareFields.map(field => ({ label: field.name, value: field.name }))" />
<div class="demo-config-comparison">
<section v-for="sample in demoComparedOptions" :key="String(sample)">
<p><code>{{ demoCompareAxis }}={{ sample }}</code></p>
<c-badge :content="1000" v-bind="{ ...__demoAppearance, [demoCompareAxis]: sample }" />
</section>
</div>
  </c-space>
</template>

<style scoped>
.demo-config-comparison { display: grid; grid-template-columns: repeat(auto-fit, minmax(min(100%, 220px), 1fr)); gap: 20px; min-width: 0; max-width: 100%; }
.demo-config-comparison > section { min-width: 0; }
.demo-config-comparison p { margin: 0 0 8px; }
html:not([lang='en-US']) .demo-config-comparison-hint > [lang='en-US'],
html[lang='en-US'] .demo-config-comparison-hint > [lang='zh-CN'] { display: none; }
</style>
```

## Layout and arrangement

### Positions and offsets

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `position` | Physical corner or left/right midpoint inside the host box, default top-right. Only used in floating mode; RTL does not mirror it | Positions and offsets |
| `content` | Badge content | Positions and offsets |
| `dot` | Display a dot | Positions and offsets |
| `offset-x` | Horizontal offset; ignored in inline mode | Positions and offsets |
| `offset-y` | Vertical offset | Positions and offsets |
| `mode` | Layout mode | Positions and offsets |
<!-- demo-config-notes:end -->


Example source: src/badge/__demos__/position.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const offset = ref(0)
const dot = ref(false)
const positions = ['top-right', 'top-left', 'bottom-right', 'bottom-left', 'left', 'right'] as const
const inlinePositions = ['start', 'end'] as const
</script>

<template>
  <c-space direction="column" :size="24">
    <c-space wrap
      ><c-button @click="offset++">Offset +1</c-button><c-button @click="offset--">Offset -1</c-button
      ><c-button @click="offset = 0">Reset</c-button><c-switch v-model="dot" aria-label="Toggle dot"
    /></c-space>
    <output aria-live="polite">Offset: {{ offset }}px</output>
    <c-space wrap :size="32"
      ><c-badge
        v-for="position in positions"
        :key="position"
        :position="position"
        :content="100"
        :dot="dot"
        :offset-x="offset"
        :offset-y="offset"
        ><span style="display: inline-block; padding: 12px; border: 1px solid currentColor">{{
          position
        }}</span></c-badge
      ></c-space
    >
    <c-space wrap :size="24"
      ><c-badge
        v-for="position in inlinePositions"
        :key="position"
        mode="inline"
        :inline-position="position"
        :content="9"
        :dot="dot"
        :offset-y="offset"
        :description="position"
    /></c-space>
  </c-space>
</template>
```

## Content and presentation

### Inline and standalone

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `content` | Badge content | Inline and standalone, Dot badges, Maximum and zero |
| `dot` | Display a dot | Inline and standalone, Dot badges, Show and hide |
| `description` | Fallback description text | Inline and standalone, Show and hide |
| `show-zero` | Show numeric zero | Maximum and zero, Show and hide |
| `mode` | Layout mode | Inline and standalone |
| `inline-position` | Inline badge at the logical start or end of the host content, default end. Only used in inline mode | Inline and standalone |
<!-- demo-config-notes:end -->


Example source: src/badge/__demos__/inline.vue

```vue
<script setup lang="ts">
const positions = ['start', 'end'] as const
</script>

<template>
  <c-space direction="column" :size="16">
    <c-space wrap><c-badge :content="1000" /><c-badge :content="1000" dot /></c-space>
    <c-space v-for="position in positions" :key="position" wrap>
      <c-badge mode="inline" :inline-position="position" :content="9" description="Messages" />
      <c-badge mode="inline" :inline-position="position" dot :content="9" description="Messages" />
    </c-space>
  </c-space>
</template>
```

### Dot badges

Example source: src/badge/__demos__/dot.vue

```vue
<template>
  <c-space wrap :size="24"
    ><c-badge dot :content="1"
      ><span
        style="
          display: inline-block;
          padding: 12px;
          border: 1px solid currentColor;
          border-radius: 4px;
        "
        >Inbox</span
      ></c-badge
    ><c-badge dot :content="1" :offset-x="6" :offset-y="-2"
      ><c-link href="#" @click.prevent>Messages</c-link></c-badge
    ></c-space
  >
</template>
```

### Maximum and zero

Example source: src/badge/__demos__/max.vue

```vue
<template>
  <c-space wrap :size="24"
    ><c-badge :content="0"
      ><span style="display: inline-block; padding: 12px; border: 1px solid currentColor; border-radius: 4px"
        >Inbox</span
      ></c-badge
    ><c-badge :content="0" show-zero
      ><span style="display: inline-block; padding: 12px; border: 1px solid currentColor; border-radius: 4px"
        >Inbox</span
      ></c-badge
    ><c-badge :content="100" :max="10"
      ><span style="display: inline-block; padding: 12px; border: 1px solid currentColor; border-radius: 4px"
        >Inbox</span
      ></c-badge
    ><c-badge :content="100"
      ><span style="display: inline-block; padding: 12px; border: 1px solid currentColor; border-radius: 4px"
        >Inbox</span
      ></c-badge
    ><c-badge :content="1000" :max="999"
      ><span style="display: inline-block; padding: 12px; border: 1px solid currentColor; border-radius: 4px"
        >Inbox</span
      ></c-badge
    ></c-space
  >
</template>
```

### Show and hide

Example source: src/badge/__demos__/show.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const show = ref(true)
const content = ref(1)
</script>

<template>
  <c-space direction="column">
    <c-space wrap
      ><c-switch v-model="show" aria-label="Show badge" /><c-button @click="content++">Add</c-button
      ><c-button @click="content = Math.max(0, content - 1)">Subtract</c-button></c-space
    >
    <c-badge :content="0" :show="show" show-zero description="show-zero true" />
    <c-badge :content="0" :show="show" :show-zero="false" description="show-zero false" />
    <c-badge :content="content" :show="show" description="Messages" />
    <c-badge :content="content" :show="show" dot description="Activity" />
  </c-space>
</template>
```

## Customization and slots

### Custom content

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `content` | Badge content | Custom content |
| `mode` | Layout mode | Custom content |
| `inline-position` | Inline badge at the logical start or end of the host content, default end. Only used in inline mode | Custom content |
<!-- demo-config-notes:end -->


Example source: src/badge/__demos__/content.vue

```vue
<template>
  <c-space wrap :size="24"
    ><c-badge content="NEW"
      ><span style="display: inline-block; padding: 12px; border: 1px solid currentColor; border-radius: 4px"
        >Inbox</span
      ></c-badge
    ><c-badge content="HOT" mode="inline" inline-position="start"
      ><span style="display: inline-block; padding: 12px; border: 1px solid currentColor; border-radius: 4px"
        >Inbox</span
      ></c-badge
    ><c-badge content="HOT" mode="inline" inline-position="end"
      ><span style="display: inline-block; padding: 12px; border: 1px solid currentColor; border-radius: 4px"
        >Inbox</span
      ></c-badge
    ></c-space
  >
</template>
```

## API

<!-- same-source-api:start -->
### Props

| Parameter | Description | Type | Default |
| --------------- | ---------------------------------------------------------------------------------- | -------------------------------------------------------------- | :---------: |
| description | Fallback description text | `string` | `-` |
| content | Badge content | `number \| string` | `-` |
| max | Maximum displayed numeric badge value. Numeric content above this value is shown as `${max}+`. | `number` | `99` |
| dot | Display a dot | `boolean` | `false` |
| offset-x | Horizontal offset; ignored in inline mode | `number` | `0` |
| offset-y | Vertical offset | `number` | `0` |
| color | Custom color; outline uses it for border and text | `string` | `-` |
| text-color | Content text color | `string` | `-` |
| mode | Layout mode | `'floating' \| 'inline'` | `floating` |
| position | Physical corner or left/right midpoint inside the host box, default top-right. Only used in floating mode; RTL does not mirror it | `'top-right' \| 'top-left' \| 'bottom-right' \| 'bottom-left' \| 'left' \| 'right'` | `top-right` |
| inline-position | Inline badge at the logical start or end of the host content, default end. Only used in inline mode | `'start' \| 'end'` | `end` |
| size | Size | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | `md` |
| status | Semantic status | `SemanticStatus` | `danger` |
| show | Show the badge | `boolean` | `true` |
| show-zero | Show numeric zero | `boolean` | `false` |
| variant | Appearance | `'outline' \| 'default'` | `default` |

### Events

No component-specific events.

### Slots

| Slot | Description | Arguments |
| ------- | ---------------- | ---- |
| default | Fallback description text | - |
| content | Content displayed inside the badge | - |

### Methods

No public methods.

### Platform notes

Props and slots match across platforms. Without a default slot and with an empty description, the badge renders independently inline. Omitting content displays a dot. Each library reads text direction from its own configuration and supplies its own theme colors and CSS prefix.
<!-- same-source-api:end -->

### Style variables

The following CSS variables support customization with [StyleProvider](#/en-US/style-provider).

| Variable | Default |
| --- | --- |
| `--c-badge-font-weight` | `var(--c-sys-font-weight-medium)` |
| `--c-badge-description-size-xs-font-size` | `var(--c-sys-font-size-xs)` |
| `--c-badge-description-size-sm-font-size` | `var(--c-sys-font-size-xs)` |
| `--c-badge-description-size-md-font-size` | `var(--c-sys-font-size-md)` |
| `--c-badge-description-size-lg-font-size` | `var(--c-sys-font-size-lg)` |
| `--c-badge-description-size-xl-font-size` | `var(--c-sys-font-size-xl)` |
| `--c-badge-description-text-color` | `var(--c-sys-color-content-primary)` |
| `--c-badge-size-xs-font-size` | `var(--c-sys-font-size-xs)` |
| `--c-badge-size-sm-font-size` | `var(--c-sys-font-size-xs)` |
| `--c-badge-size-md-font-size` | `var(--c-sys-font-size-xs)` |
| `--c-badge-size-lg-font-size` | `var(--c-sys-font-size-md)` |
| `--c-badge-size-xl-font-size` | `var(--c-sys-font-size-lg)` |
| `--c-badge-size-xs-scale` | `0.6667` |
| `--c-badge-size-sm-scale` | `0.8333` |
| `--c-badge-size-md-scale` | `1` |
| `--c-badge-size-lg-scale` | `1` |
| `--c-badge-size-xl-scale` | `1` |
| `--c-badge-size-xs-dot-width` | `4px` |
| `--c-badge-size-sm-dot-width` | `5px` |
| `--c-badge-size-md-dot-width` | `6px` |
| `--c-badge-size-lg-dot-width` | `7px` |
| `--c-badge-size-xl-dot-width` | `8px` |
| `--c-badge-size-xs-dot-height` | `4px` |
| `--c-badge-size-sm-dot-height` | `5px` |
| `--c-badge-size-md-dot-height` | `6px` |
| `--c-badge-size-lg-dot-height` | `7px` |
| `--c-badge-size-xl-dot-height` | `8px` |
| `--c-badge-size-xs-space` | `0px` |
| `--c-badge-size-sm-space` | `var(--c-sys-space-1)` |
| `--c-badge-size-md-space` | `var(--c-sys-space-3)` |
| `--c-badge-size-lg-space` | `var(--c-sys-space-3)` |
| `--c-badge-size-xl-space` | `var(--c-sys-space-4)` |
| `--c-badge-size-xs-padding` | `0 var(--c-sys-space-3)` |
| `--c-badge-size-sm-padding` | `0 var(--c-sys-space-3)` |
| `--c-badge-size-md-padding` | `0 var(--c-sys-space-4)` |
| `--c-badge-size-lg-padding` | `0 var(--c-sys-space-4)` |
| `--c-badge-size-xl-padding` | `0 10px` |
| `--c-badge-size-xs-height` | `20px` |
| `--c-badge-size-sm-height` | `20px` |
| `--c-badge-size-md-height` | `24px` |
| `--c-badge-size-lg-height` | `28px` |
| `--c-badge-size-xl-height` | `32px` |
| `--c-badge-size-xs-border-radius` | `20px` |
| `--c-badge-size-sm-border-radius` | `20px` |
| `--c-badge-size-md-border-radius` | `24px` |
| `--c-badge-size-lg-border-radius` | `28px` |
| `--c-badge-size-xl-border-radius` | `32px` |
| `--c-badge-bg-color` | `rgb(var(--c-danger-7))` |
| `--c-badge-text-color` | `var(--c-sys-color-content-on-dark)` |
| `--c-badge-status-default-bg-color` | `#e0e0e0` |
| `--c-badge-status-default-text-color` | `var(--c-sys-color-content-on-bright)` |
| `--c-badge-status-info-bg-color` | `var(--c-sys-color-status-info)` |
| `--c-badge-status-info-text-color` | `var(--c-sys-color-content-on-dark)` |
| `--c-badge-status-success-bg-color` | `var(--c-sys-color-status-success)` |
| `--c-badge-status-success-text-color` | `var(--c-sys-color-content-on-dark)` |
| `--c-badge-status-warning-bg-color` | `var(--c-sys-color-status-warning)` |
| `--c-badge-status-warning-text-color` | `var(--c-sys-color-content-on-dark)` |
| `--c-badge-status-danger-bg-color` | `rgb(var(--c-danger-7))` |
| `--c-badge-status-danger-text-color` | `var(--c-sys-color-content-on-dark)` |
| `--c-badge-status-primary-bg-color` | `var(--c-sys-color-action-primary)` |
| `--c-badge-status-primary-text-color` | `var(--c-sys-color-content-on-dark)` |
| `--c-badge-status-secondary-bg-color` | `rgb(var(--c-gray-6))` |
| `--c-badge-status-secondary-text-color` | `var(--c-sys-color-content-on-dark)` |
| `--c-badge-status-tertiary-bg-color` | `rgb(var(--c-gray-7))` |
| `--c-badge-status-tertiary-text-color` | `var(--c-sys-color-content-on-dark)` |
| `--c-badge-variant-outline-bg-color` | `transparent` |
| `--c-badge-variant-outline-text-color` | `var(--c-sys-color-content-danger)` |
| `--c-badge-variant-outline-status-info-text-color` | `var(--c-sys-color-content-info)` |
| `--c-badge-variant-outline-status-success-text-color` | `var(--c-sys-color-content-success)` |
| `--c-badge-variant-outline-status-warning-text-color` | `var(--c-sys-color-content-warning)` |
| `--c-badge-variant-outline-status-danger-text-color` | `var(--c-sys-color-content-danger)` |
| `--c-badge-variant-outline-status-primary-text-color` | `var(--c-sys-color-content-brand)` |
| `--c-badge-variant-outline-status-default-text-color` | `var(--c-sys-color-content-primary)` |
| `--c-badge-variant-outline-status-secondary-text-color` | `var(--c-sys-color-content-secondary)` |
| `--c-badge-variant-outline-status-tertiary-text-color` | `var(--c-sys-color-content-secondary)` |
| `--c-badge-border-color` | `var(--c-sys-color-surface-default)` |
| `--c-badge-offset` | `2px` |
| `--c-badge-ring-width` | `2px` |

Filled badge text follows Button: primary, info, success, warning, danger and secondary use `content-on-dark`; tertiary uses `content-on-dark` in light mode and `content-on-bright` in dark mode. Default notification badges use red backgrounds and white text; the neutral background remains `#e0e0e0`.

Colored outline text and borders follow Button, using the matching `content-brand`, `content-info`, `content-success`, `content-warning` and `content-danger` semantic roles; secondary and tertiary outlines use `content-secondary` for readability. `variant-outline-bg-color` works for every status and defaults to transparent. The `color` prop overrides outline text and border; `text-color` overrides text further. Both preserve control through the background variable. Recheck contrast after customizing foreground or background.

### Type definitions

The component exports the following types

```ts
import type { BadgeInstance } from '@cedar-design/ui'
```

### Color override boundaries

The bg-color fallback and danger fill use red backgrounds with white text: danger level 7 in light mode and level 4 in dark mode. Fixed neutral light gray and secondary/tertiary gray levels are intentional component colors. Override the border-color isolation ring to match the host surface. Callers must ensure contrast for custom color/text-color values.

---

Document: llms/en-US/components/breadcrumb.md

<!-- Source: src/breadcrumb/README.en-US.md; locale: en-US; page: /en/components/breadcrumb/ -->

# Breadcrumb

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

Example source: src/breadcrumb/__demos__/basic.vue

```vue
<template>
  <c-breadcrumb>
    <c-breadcrumb-item>Home</c-breadcrumb-item>
    <c-breadcrumb-item>Channel</c-breadcrumb-item>
    <c-breadcrumb-item>News</c-breadcrumb-item>
  </c-breadcrumb>
</template>

<script lang="ts">
</script>
```

## Content and presentation

### Routes

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `routes` | Route list | Routes, Droplist, Max Count |
| `max-count` | Maximum ordinary breadcrumb items, excluding the overflow item; 0 means unlimited | Max Count |
<!-- demo-config-notes:end -->


Preview configuration: `:routes="routes"`, `:href="paths.join('/')"`.

Example source: src/breadcrumb/__demos__/routes.vue

```vue
<template>
  <c-space direction="column">
    <c-breadcrumb :routes="routes" @click.prevent />
    <c-breadcrumb :routes="routes">
      <template #item-render="{ route, routes, paths }">
        <span v-if="route === routes[routes.length - 1]">{{ route.label }}</span>
        <c-link v-else :href="paths.join('/')" @click.prevent>
          {{ route.label }}
        </c-link>
      </template>
    </c-breadcrumb>
    <c-breadcrumb :routes="routes">
      <template #item-render="{ route, routes }">
        <span v-if="route === routes[routes.length - 1]">{{ route.label }}</span>
        <RouterLink v-else :to="route.to">
          {{ route.label }}
        </RouterLink>
      </template>
    </c-breadcrumb>
  </c-space>
</template>

<script lang="ts">
import { RouterLink } from 'vue-router'

export default {
  components: { RouterLink },
  setup() {
    const routes = [
      {
        path: '/',
        to: { query: { breadcrumb: 'home' } },
        label: 'Home',
      },
      {
        path: '/channel',
        to: { query: { breadcrumb: 'channel' } },
        label: 'Channel',
      },
      {
        path: '/news',
        to: { query: { breadcrumb: 'news' } },
        label: 'News',
      },
    ]
    return { routes }
  },
}
</script>
```

### Droplist

Preview configuration: `:routes="routes"`, `:droplist="droplist"`.

Example source: src/breadcrumb/__demos__/droplist.vue

```vue
<template>
  <c-space direction="column">
    <c-breadcrumb :routes="routes" @click.prevent />
    <c-breadcrumb>
      <c-breadcrumb-item>Home</c-breadcrumb-item>
      <c-breadcrumb-item :droplist="droplist"> Channel </c-breadcrumb-item>
      <c-breadcrumb-item>News</c-breadcrumb-item>
    </c-breadcrumb>
    <c-breadcrumb>
      <c-breadcrumb-item>Home</c-breadcrumb-item>
      <c-breadcrumb-item>
        <template #droplist>
          <c-menu-option>Option 1</c-menu-option>
          <c-menu-option>Option 2</c-menu-option>
          <c-menu-option>Option 3</c-menu-option>
        </template>
        Channel
      </c-breadcrumb-item>
      <c-breadcrumb-item>News</c-breadcrumb-item>
    </c-breadcrumb>
  </c-space>
</template>

<script lang="ts">
export default {
  setup() {
    const routes = [
      {
        path: '/',
        label: 'Home',
      },
      {
        path: '/channel',
        label: 'Channel',
        children: [
          { path: '/goods', label: 'Goods' },
          { path: '/wallet', label: 'Wallet' },
        ],
      },
      {
        path: '/news',
        label: 'News',
      },
    ]
    const droplist = [
      {
        path: '/goods',
        label: 'Goods',
      },
      {
        path: '/wallet',
        label: 'Wallet',
      },
    ]
    return { routes, droplist }
  },
}
</script>
```

### Max Count

Preview configuration: `:max-count="3"`, `:routes="maxRoutes"`, `:trigger="['hover', 'focus', 'click']"`, `:content="omittedItems.map((item) => item.label).join(' / ')"`.

Example source: src/breadcrumb/__demos__/max-count.vue

```vue
<template>
  <c-space direction="column">
    <c-breadcrumb :max-count="3">
      <c-breadcrumb-item>Home</c-breadcrumb-item>
      <c-breadcrumb-item>Sub Home</c-breadcrumb-item>
      <c-breadcrumb-item>All Channel</c-breadcrumb-item>
      <c-breadcrumb-item>Channel</c-breadcrumb-item>
      <c-breadcrumb-item>News</c-breadcrumb-item>
      <c-breadcrumb-item>Post</c-breadcrumb-item>
    </c-breadcrumb>
    <c-breadcrumb :routes="maxRoutes" :max-count="3" @click.prevent>
      <template #more-icon="{ omittedItems }">
        <c-tooltip :trigger="['hover', 'focus', 'click']" :content="omittedItems.map((item) => item.label).join(' / ')">
          <c-icon-more />
        </c-tooltip>
      </template>
    </c-breadcrumb>
  </c-space>
</template>

<script lang="ts">
export default {
  setup() {
    const maxRoutes = [
      { path: '/', label: 'Home' },
      { path: '/sub-home', label: 'Sub Home' },
      { path: '/all-channel', label: 'All Channel' },
      { path: '/channel', label: 'Channel' },
      { path: '/news', label: 'News' },
      { path: '/post', label: 'Post' },
    ]
    return { maxRoutes }
  },
}
</script>
```

### Link

Preview configuration: `href="#/home"`, `href="#/channel"`.

Example source: src/breadcrumb/__demos__/link.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'

const lastAction = ref('尚未操作')
const record = (label: string) => { lastAction.value = `已选择 ${label}` }
</script>

<template>
  <c-space direction="column">
    <div>纯文本：仅展示路径</div>
    <c-breadcrumb>
      <c-breadcrumb-item>Home</c-breadcrumb-item>
      <c-breadcrumb-item>Channel</c-breadcrumb-item>
      <c-breadcrumb-item>News</c-breadcrumb-item>
    </c-breadcrumb>
    <div>链接：悬停或聚焦查看反馈</div>
    <c-breadcrumb>
      <c-breadcrumb-item href="#/home" @click.prevent="record('Home')">Home</c-breadcrumb-item>
      <c-breadcrumb-item href="#/channel" @click.prevent="record('Channel')">Channel</c-breadcrumb-item>
      <c-breadcrumb-item>News</c-breadcrumb-item>
    </c-breadcrumb>
    <div>点击操作：支持 Enter / 空格</div>
    <c-breadcrumb>
      <c-breadcrumb-item @click="record('Home')">Home</c-breadcrumb-item>
      <c-breadcrumb-item @click="record('Channel')">Channel</c-breadcrumb-item>
      <c-breadcrumb-item>News</c-breadcrumb-item>
    </c-breadcrumb>
    <span role="status">{{ lastAction }}</span>
  </c-space>
</template>
```

## Customization and slots

### Custom Split

Preview configuration: `separator="~"`, `separator="->"`.

Example source: src/breadcrumb/__demos__/custom-split.vue

```vue
<template>
  <c-space direction="column">
    <c-breadcrumb>
      <template #separator>
        <c-icon-oblique-line />
      </template>
      <c-breadcrumb-item>Home</c-breadcrumb-item>
      <c-breadcrumb-item>Channel</c-breadcrumb-item>
      <c-breadcrumb-item>News</c-breadcrumb-item>
    </c-breadcrumb>
    <c-breadcrumb separator="~">
      <c-breadcrumb-item>Home</c-breadcrumb-item>
      <c-breadcrumb-item>Channel</c-breadcrumb-item>
      <c-breadcrumb-item>News</c-breadcrumb-item>
    </c-breadcrumb>
    <c-breadcrumb>
      <template #separator>
        <c-icon-oblique-line />
      </template>
      <c-breadcrumb-item separator="->">Home</c-breadcrumb-item>
      <c-breadcrumb-item>Channel</c-breadcrumb-item>
      <c-breadcrumb-item>News</c-breadcrumb-item>
    </c-breadcrumb>
  </c-space>
</template>

<script lang="ts">
</script>
```

### Custom Icon

Example source: src/breadcrumb/__demos__/custom-icon.vue

```vue
<template>
  <c-space direction="column">
    <c-breadcrumb>
      <c-breadcrumb-item>
        <c-icon-home />
      </c-breadcrumb-item>
      <c-breadcrumb-item>Channel</c-breadcrumb-item>
      <c-breadcrumb-item>News</c-breadcrumb-item>
    </c-breadcrumb>
    <c-breadcrumb>
      <c-breadcrumb-item>
        <c-icon-home />
      </c-breadcrumb-item>
      <c-breadcrumb-item>
        <c-icon-link />
        Channel
      </c-breadcrumb-item>
      <c-breadcrumb-item>News</c-breadcrumb-item>
    </c-breadcrumb>
  </c-space>
</template>

<script lang="ts">
</script>
```

## API

### Breadcrumb Props

| Prop | Description | Type | Default |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ------ |
| max-count | Maximum ordinary breadcrumb items, excluding the overflow item; 0 means unlimited | `number` | `0` |
| routes | Route list | `BreadcrumbRoute[]` | `-` |
| separator | Separator text | `string \| number` | `/` |

### Breadcrumb Slots

| Slot | Description | Arguments |
| ----------- | ---------------------------------- | --------------------------------------------------------------------------- |
| more-icon | Custom overflow icon | `omittedItems` `count` `start` `end` |
| item-render | Custom breadcrumb rendering when routes is provided | `route:BreadcrumbRoute`<br/>`routes:BreadcrumbRoute[]`<br/>`paths:string[]` |
| separator | Custom separator | `-` |

### BreadcrumbItem Props

| Prop | Description | Type | Default |
| -------------- | ------------ | ----------------------------- | ------ |
| separator | Separator text | `string \| number` | `-` |
| href | Link URL | `string` | `-` |
| droplist | Dropdown menu content | `BreadcrumbRoute['children']` | `-` |
| dropdown-props | Props passed to Menu | `MenuProps` | `-` |

### BreadcrumbItem Events

| Event | Description | Arguments |
| ------ | -------- | -------------- |
| click | Click event; omitted items do not emit it | `event: MouseEvent` |
| select | Fired when a built-in dropdown item is selected | `route: BreadcrumbRoute, event?: Event` |

### BreadcrumbItem Slots

| Slot | Description | Arguments |
| --------- | -------------- | ---- |
| droplist | Custom dropdown menu | `-` |
| separator | Custom separator | `-` |

### BreadcrumbRoute

| Parameter | Description | Type | Default |
| -------- | ------------------------- | ------------------------------ | ------ |
| label | Breadcrumb label | `string` | `-` |
| path | Navigation path (`href` on the `a` element) | `string` |
| children | Dropdown menu items | `{label:string,path:string}[]` | `-` |

## Type definitions

The component exports the following types

```ts
import type { BreadcrumbProps, BreadcrumbItemProps, BreadcrumbRoute } from '@cedar-design/ui'
```

## Shared implementation and platform boundaries

Breadcrumb and BreadcrumbItem are maintained as local copies in Cedar / Maple. Component bodies, props, context, types, key styles and paired tests are checked by `design-ui/bin/copied-components-check.mjs`. Each library supplies its own icons, installation entry, menu implementation and theme tokens.

- A nonempty `routes` array takes precedence over the default slot; an empty array falls back to the slot. Default route rendering links all items except the last, which has `aria-current="page"`. `item-render` controls links itself.
- Separator precedence: child slot → child prop → parent slot → parent prop. `0` and an empty string are supported.
- `max-count` preserves the existing boundary: collapsing occurs only when the total exceeds `max-count + 1`. It keeps the first and trailing items. The overflow position does not trigger omitted items’ clicks, links or dropdowns.
- Built-in dropdown selection emits `select(route, event)`. Indices and separators update with dynamic insertion, removal, reordering and SSR.
- Cedar adds a `__content` wrapper for item content; attributes fall through to it. Maple retains its existing theme variables through token mappings.

---

Document: llms/en-US/components/button.md

<!-- Source: src/button/README.en-US.md; locale: en-US; page: /en/components/button/ -->

# Button

Both libraries use the same implementation and examples; package prefixes, themes and registration stay local.

## Basic examples

### Eight statuses

Example source: src/button/__demos__/basic.vue

```vue
<script setup lang="ts">
const statuses = [
  "default",
  "primary",
  "secondary",
  "tertiary",
  "info",
  "success",
  "warning",
  "danger",
] as const;
</script>
<template>
  <c-space wrap size="12px">
    <c-button v-for="status in statuses" :key="status" :status="status">{{
      status
    }}</c-button>
  </c-space>
</template>
```

## Appearance and states

### Four variants

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `variant` | Appearance; inherits group, otherwise default | Four variants, Colors, ripple and elevation |
| `size` | Size; inherits group, otherwise md | Four variants, Five sizes |
| `status` | Semantic color; inherits group, otherwise default | Four variants |
| `disabled` | Disabled; inherits group, explicit false overrides | Disabled buttons and links |
| `component` | Root tag; link attributes fall through | Disabled buttons and links |
| `loading` | Loading; blocks activation and navigation | Disabled buttons and links |
<!-- demo-config-notes:end -->


The `default` variant uses white text for primary, info, success, warning, danger and secondary solid fills.

Example source: src/button/__demos__/variants.vue

```vue
<script setup lang="ts">
import { computed, ref } from "vue";

const variant = ref("default");
const size = ref("md");
const background = ref("navy");
const variants = ["default", "text", "outline", "tonal"];
const sizes = ["xs", "sm", "md", "lg", "xl"];
const statuses = [
  "default",
  "primary",
  "secondary",
  "tertiary",
  "info",
  "success",
  "warning",
  "danger",
];
const backgrounds = [
  { label: "Navy / 深蓝", value: "navy", color: "#17224B" },
  { label: "White / 白色", value: "light", color: "#FFFFFF" },
  { label: "Light gray / 浅灰", value: "muted", color: "#F5F5F5" },
  { label: "Dark gray / 深灰", value: "dark", color: "#252525" },
];
const cardBackground = computed(
  () => backgrounds.find((item) => item.value === background.value)?.color,
);
</script>
<template>
  <c-space direction="column" block align="stretch" :size="16">
    <c-form layout="vertical" size="sm">
      <c-form-item label="Variant" field="variant">
        <c-radio-group
          v-model="variant"
          :options="variants"
          aria-label="Button variant"
          variant="button"
        />
      </c-form-item>
      <c-form-item label="Size" field="size">
        <c-radio-group
          v-model="size"
          :options="sizes"
          aria-label="Button size"
          variant="button"
        />
      </c-form-item>
      <c-form-item label="Background" field="background">
        <c-radio-group
          v-model="background"
          :options="backgrounds"
          aria-label="Button background"
          variant="button"
        />
      </c-form-item>
    </c-form>
    <c-card
      class="button-variant-card"
      :data-background="background"
      :elevation="false"
      :style="{ '--c-card-background': cardBackground }"
    >
      <c-space wrap>
        <c-button
          v-for="status in statuses"
          :key="status"
          :status="status"
          :variant="variant"
          :size="size"
          >{{ status }}</c-button
        >
      </c-space>
    </c-card>
  </c-space>
</template>
```

### Five sizes

Horizontal buttons and inputs of the same size share the default height and font size within each platform. Cedar heights are 24/28/32/36/44px; Maple heights are 32/40/48/56/64px. Horizontal button padding is 8/12/16/20/24px per side, with a 6px icon-label gap. Stacked buttons keep their separate content-based height. Component-level overrides remain independent.

Example source: src/button/__demos__/size.vue

```vue
<script setup lang="ts">
const sizes = ["xs", "sm", "md", "lg", "xl"] as const;
</script>
<template>
  <c-space direction="column" :size="16">
    <c-space v-for="size in sizes" :key="size" align="center" wrap :size="12">
      <span>{{ size }}</span>
      <c-input
        :size="size"
        :aria-label="`Input ${size}`"
        placeholder="Input"
        style="width: 140px"
      />
      <c-button :size="size">Button</c-button>
      <c-button :size="size"
        ><template #icon><c-icon-search /></template>Search</c-button
      >
    </c-space>
  </c-space>
</template>
```

### Disabled buttons and links

Example source: src/button/__demos__/disabled.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
const clicks = ref(0);
</script>
<template>
  <c-space wrap size="12px">
    <c-button disabled @click="clicks++">Disabled button</c-button>
    <c-button
      component="a"
      href="#blocked-button-link"
      disabled
      @click="clicks++"
      >Disabled link</c-button
    >
    <c-button
      component="a"
      href="#blocked-button-link"
      loading
      @click="clicks++"
      >Loading link</c-button
    >
  </c-space>
  <p aria-live="polite">Blocked clicks: {{ clicks }}</p>
</template>
```

### Colors, ripple and elevation

Example source: src/button/__demos__/custom-color.vue

```vue
<template>
  <c-space wrap size="12px">
    <c-button color="#6750a4" text-color="white">Custom filled</c-button>
    <c-button
      color="linear-gradient(to bottom right, #6750a4, #d0bcff)"
      text-color="white"
      >Gradient</c-button
    >
    <c-button color="#6750a4" variant="text">Custom text</c-button>
    <c-button color="#6750a4" variant="outline">Custom outline</c-button>
    <c-button color="#6750a4" variant="tonal">Custom tonal</c-button>
  </c-space>
</template>
```

## Icons and layout

### Icons and label layouts

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `status` | Semantic color; inherits group, otherwise default | Icons and label layouts |
| `variant` | Appearance; inherits group, otherwise default | Icons and label layouts |
| `size` | Size; inherits group, otherwise md | Icons and label layouts |
| `stacked` | Stack icon and text; inherits group when omitted | Icons and label layouts |
| `round` | Round button | Icons and label layouts |
| `block` | Full available width | Block buttons |
<!-- demo-config-notes:end -->


Use built-in icons to compare icon-only, inline and stacked labels across four variants and five sizes. Stacked buttons grow with content and keep at least 8px of top and bottom padding. Omit the default slot for icon-only buttons; round controls shape and stacked controls label layout.

Example source: src/button/__demos__/icons.vue

```vue
<script setup lang="ts">
import { ref } from "vue";

const sizes = ["xs", "sm", "md", "lg", "xl"] as const;
const variants = ["default", "text", "outline", "tonal"] as const;
const layouts = ["icon", "inline", "stacked"] as const;
const size = ref<(typeof sizes)[number]>("md");
const variant = ref<(typeof variants)[number]>("tonal");
const items = [
  { status: "default", icon: "plus", label: "Add" },
  { status: "primary", icon: "reply", label: "Reply" },
  { status: "info", icon: "info-circle", label: "Info" },
  { status: "success", icon: "check", label: "Confirm" },
  { status: "warning", icon: "delete", label: "Delete" },
  { status: "danger", icon: "close", label: "Close" },
] as const;
</script>
<template>
  <c-space direction="column" :size="16">
    <c-form layout="vertical" size="sm">
      <c-form-item label="Variant" field="variant">
        <c-radio-group
          v-model="variant"
          :options="variants"
          aria-label="Icon button variant"
          variant="button"
        />
      </c-form-item>
      <c-form-item label="Size" field="size">
        <c-radio-group
          v-model="size"
          :options="sizes"
          aria-label="Icon button size"
          variant="button"
        />
      </c-form-item>
    </c-form>
    <c-space
      v-for="layout in layouts"
      :key="layout"
      direction="column"
      :size="8"
    >
      <span>{{
        layout === "icon"
          ? "Icon only / 纯图标"
          : layout === "inline"
            ? "Icon and text / 横排图文"
            : "Stacked / 上下堆叠"
      }}</span>
      <c-space wrap>
        <c-button
          v-for="item in items"
          :key="item.label"
          :status="item.status"
          :variant="variant"
          :size="size"
          :stacked="layout === 'stacked'"
          :round="layout === 'icon'"
          :aria-label="item.label"
        >
          <template #icon>
            <c-icon-plus v-if="item.icon === 'plus'" />
            <c-icon-reply v-else-if="item.icon === 'reply'" />
            <c-icon-info-circle v-else-if="item.icon === 'info-circle'" />
            <c-icon-check v-else-if="item.icon === 'check'" />
            <c-icon-delete v-else-if="item.icon === 'delete'" />
            <c-icon-close v-else-if="item.icon === 'close'" />
          </template>
          <template v-if="layout !== 'icon'" #default>{{
            item.label
          }}</template>
        </c-button>
      </c-space>
    </c-space>
  </c-space>
</template>
```

### Block buttons

Example source: src/button/__demos__/block.vue

```vue
<template>
  <c-button block>Full width</c-button>
</template>
```

## Button groups

### Group inheritance and overrides

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `status` | Semantic color; inherits group, otherwise default | Group inheritance and overrides |
| `disabled` | Disabled; inherits group, explicit false overrides | Group inheritance and overrides |
| `loading` | Loading; blocks activation and navigation | Button Group Content |
<!-- demo-config-notes:end -->


Example source: src/button/__demos__/button-group.vue

```vue
<script setup lang="ts">
import { ref } from "vue";

const size = ref("md");
const disabled = ref(false);
</script>
<template>
  <c-space direction="column" :size="16" class="button-group-demo">
    <c-form layout="vertical" size="sm">
      <c-form-item label="Size" field="size">
        <c-radio-group
          v-model="size"
          aria-label="Button group size"
          :options="['xs', 'sm', 'md', 'lg', 'xl']"
          variant="button"
        />
      </c-form-item>
      <c-form-item label="State" field="disabled"
        ><c-checkbox v-model="disabled">Disable group</c-checkbox></c-form-item
      >
    </c-form>
    <div class="button-group-demo__scroll">
      <c-button-group aria-label="Document actions" status="primary" :size="size" :disabled="disabled">
        <c-button>Inherited</c-button>
        <c-button status="success">Status override</c-button>
        <c-button :disabled="false">Enabled override</c-button>
      </c-button-group>
    </div>
  </c-space>
</template>
<style scoped>
.button-group-demo {
  width: 100%;
}
.button-group-demo__scroll {
  max-width: 100%;
  overflow-x: auto;
}
</style>
```

### Button Group Layout

Example source: src/button/__demos__/button-group-layout.vue

```vue
<script setup lang="ts">
import { ref } from "vue";

const mixed = ref(false)
const variant = ref("default");
const size = ref("md");
</script>
<template>
  <c-space direction="column" :size="16">
    <c-form layout="vertical" size="sm">
      <c-form-item label="Variant" field="variant">
        <c-radio-group
          v-model="variant"
          aria-label="Button group variant"
          :options="['default', 'text', 'outline', 'tonal']"
          variant="button"
        />
      </c-form-item>
      <c-form-item label="Size" field="size">
        <c-radio-group
          v-model="size"
          aria-label="Button group size"
          :options="['xs', 'sm', 'md', 'lg', 'xl']"
          variant="button"
        />
      </c-form-item>
      <c-form-item label="Mixed variants"><c-checkbox v-model="mixed">Text override in middle</c-checkbox></c-form-item>
    </c-form>
    <c-space wrap align="flex-start" :size="24">
      <c-button-group
        v-for="vertical in [false, true]"
        :key="String(vertical)"
        :aria-label="vertical ? 'Vertical page actions' : 'Horizontal page actions'"
        :vertical="vertical"
        :variant="variant"
        :size="size"
        status="primary"
      >
        <c-button>Prev</c-button><c-button :variant="mixed ? 'text' : undefined">Info</c-button><c-button>Next</c-button>
      </c-button-group>
    </c-space>
  </c-space>
</template>
```

### Button Group Content

Example source: src/button/__demos__/button-group-content.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
const stacked = ref(false);
const vertical = ref(false);
const loading = ref(false);
</script>
<template>
  <c-space direction="column" :size="16">
    <c-space wrap>
      <c-checkbox v-model="stacked">Stacked labels</c-checkbox>
      <c-checkbox v-model="vertical">Vertical group</c-checkbox>
      <c-checkbox v-model="loading">Load first action</c-checkbox>
    </c-space>
    <c-button-group aria-label="Save or cancel" status="primary" :stacked="stacked" :vertical="vertical">
      <c-button :loading="loading"
        ><template #icon><c-icon-check /></template>Save</c-button
      >
      <c-button
        ><template #icon><c-icon-close /></template>Cancel</c-button
      >
    </c-button-group>
  </c-space>
</template>
```

## Forms and events

### Control Sizes

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `size` | Size; inherits group, otherwise md | Control Sizes |
| `variant` | Appearance; inherits group, otherwise default | Control Sizes |
| `html-type` | Native button type | Native form, focus and touch events |
| `focusable` | Allow sequential Tab focus; does not prevent programmatic focus | Native form, focus and touch events |
<!-- demo-config-notes:end -->


- `size`: Controls the component size.
- `variant`: Selects the visual variant.

Example source: src/field-decorator/__demos__/control-sizes.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
const sizes = ["xs", "sm", "md", "lg", "xl"] as const;
const variants = ["outline", "filled", "standard"] as const;
const size = ref<(typeof sizes)[number]>("md");
const variant = ref<(typeof variants)[number]>("outline");
const options = [
  { value: "beijing", label: "Beijing" },
  { value: "shanghai", label: "Shanghai" },
];
const cascaderOptions = [{ value: "china", label: "China", children: options }];

const inputValue = ref("Beijing");
const selectValue = ref("beijing");
const cascaderValue = ref("beijing");
const selectMultiple = ref(["beijing", "shanghai"]);
const cascaderMultiple = ref(["beijing", "shanghai"]);
const selectOverflow = ref(["long", "beijing", "shanghai"]);
const cascaderOverflow = ref(["long", "beijing", "shanghai"]);
const selectedOptions = [
  ...options,
  {
    value: "long",
    label:
      "A very long selected option label for overflow comparison — full text preview keeps the selected value unchanged.",
  },
];
const selectedCascaderOptions = [
  { value: "china", label: "China", children: selectedOptions },
];
function resetSelections() {
  inputValue.value = "Beijing";
  selectValue.value = "beijing";
  cascaderValue.value = "beijing";
  selectMultiple.value = ["beijing", "shanghai"];
  cascaderMultiple.value = ["beijing", "shanghai"];
  selectOverflow.value = ["long", "beijing", "shanghai"];
  cascaderOverflow.value = ["long", "beijing", "shanghai"];
}
</script>
<template>
  <section
    aria-label="Form control size comparison"
    class="control-size-comparison"
  >
    <c-space wrap :size="12">
      <c-radio-group v-model="size" aria-label="Comparison size">
        <c-radio v-for="item in sizes" :key="item" :value="item">{{
          item
        }}</c-radio>
      </c-radio-group>
      <c-radio-group v-model="variant" aria-label="Comparison variant">
        <c-radio v-for="item in variants" :key="item" :value="item">{{
          item
        }}</c-radio>
      </c-radio-group>
    </c-space>
    <div class="control-size-comparison__grid">
      <div data-control="Input">
        <p>Input</p>
        <c-input :size="size" :variant="variant" placeholder="Input" />
      </div>
      <div data-control="Button">
        <p>Button</p>
        <c-button :size="size" variant="outline">Button</c-button>
      </div>
      <div data-control="Select">
        <p>Select</p>
        <c-select
          :size="size"
          :variant="variant"
          :options="options"
          placeholder="Select"
        />
      </div>
      <div data-control="Date">
        <p>Date</p>
        <c-date :size="size" :variant="variant" placeholder="Date" />
      </div>
      <div data-control="Time">
        <p>Time</p>
        <c-time :size="size" :variant="variant" placeholder="Time" />
      </div>
      <div data-control="InputNumber">
        <p>InputNumber</p>
        <c-input-number :size="size" :variant="variant" placeholder="Number" />
      </div>
      <div data-control="AutoComplete">
        <p>AutoComplete</p>
        <c-auto-complete
          :size="size"
          :variant="variant"
          :options="options"
          placeholder="AutoComplete"
        />
      </div>
      <div data-control="Cascader">
        <p>Cascader</p>
        <c-cascader
          :size="size"
          :variant="variant"
          :options="cascaderOptions"
          placeholder="Cascader"
        />
      </div>
      <div data-control="DateRange">
        <p>DateRange</p>
        <c-date-range
          :size="size"
          :variant="variant"
          :placeholder="['Start', 'End']"
        />
      </div>
      <div data-control="TimeRange">
        <p>TimeRange</p>
        <c-time-range
          :size="size"
          :variant="variant"
          :placeholder="['Start', 'End']"
        />
      </div>
    </div>

    <section
      aria-label="Selected control size comparison"
      class="control-size-comparison__states"
    >
      <c-space wrap align="center" :size="12">
        <span>Selected / Clearable / Multiple — 有值、可清空与多选不换行</span>
        <span
          >Hover or focus truncated text; tap on touch screens /
          悬停或聚焦省略正文查看全文；触屏点按查看，点外部关闭</span
        >
        <c-button size="sm" variant="outline" @click="resetSelections"
          >Reset / 恢复选中值</c-button
        >
      </c-space>
      <div class="control-size-comparison__grid">
        <div data-control="InputValue">
          <p>Input · clearable</p>
          <c-input
            v-model="inputValue"
            :size="size"
            :variant="variant"
            clearable
            placeholder="Input value"
          />
        </div>
        <div data-control="ButtonReference">
          <p>Button · reference</p>
          <c-button :size="size" variant="outline">Button</c-button>
        </div>
        <div data-control="SelectValue">
          <p>Select · clearable</p>
          <c-select
            v-model="selectValue"
            :size="size"
            :variant="variant"
            :options="selectedOptions"
            clearable
            placeholder="Select value"
          />
        </div>
        <div data-control="CascaderValue">
          <p>Cascader · clearable</p>
          <c-cascader
            v-model="cascaderValue"
            :size="size"
            :variant="variant"
            :options="selectedCascaderOptions"
            clearable
            placeholder="Cascader value"
          />
        </div>
        <div data-control="SelectMultiple">
          <p>Select · multiple / nowrap</p>
          <c-select
            v-model="selectMultiple"
            :size="size"
            :variant="variant"
            :options="selectedOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Select multiple"
          />
        </div>
        <div data-control="CascaderMultiple">
          <p>Cascader · multiple / nowrap</p>
          <c-cascader
            v-model="cascaderMultiple"
            :size="size"
            :variant="variant"
            :options="selectedCascaderOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Cascader multiple"
          />
        </div>
        <div data-control="SelectOverflow">
          <p>Select · long values / nowrap</p>
          <c-select
            v-model="selectOverflow"
            edit-mode="direct"
            :size="size"
            :variant="variant"
            :options="selectedOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Select long values"
          />
        </div>
        <div data-control="CascaderOverflow">
          <p>Cascader · long values / nowrap</p>
          <c-cascader
            v-model="cascaderOverflow"
            edit-mode="direct"
            :size="size"
            :variant="variant"
            :options="selectedCascaderOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Cascader long values"
          />
        </div>
      </div>
    </section>
  </section>
</template>
<style scoped>
.control-size-comparison,
.control-size-comparison__states {
  display: grid;
  gap: 24px;
}
.control-size-comparison__grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
  align-items: start;
  gap: 24px 16px;
}
.control-size-comparison__grid > div {
  min-width: 0;
}
.control-size-comparison__grid p {
  margin: 0 0 12px;
  font-size: 14px;
  line-height: 20px;
}
.control-size-comparison__grid :deep(.c-input-number),
.control-size-comparison__grid :deep(.c-auto-complete) {
  width: 100%;
}
</style>
```

### Native form, focus and touch events


Example source: src/button/__demos__/native-events.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const value = ref('Editable')
const submissions = ref(0)
const event = ref('Use Tab, Enter or touch')
</script>
<template>
  <c-form @submit="submissions++" @reset="value = 'Editable'" style="display: flex; flex-wrap: wrap; gap: 12px">
    <c-input v-model="value" aria-label="Example field" placeholder="Example field" style="width: 100%; max-width: 280px" />
    <c-button html-type="submit">Submit</c-button>
    <c-button html-type="reset">Reset</c-button>
    <c-button :focusable="false">Skip Tab</c-button>
    <c-button @touchstart="event = 'touchstart'" @focus="event = 'focus'" @blur="event = 'blur'" @click="event = 'click'">Event target</c-button>
  </c-form>
  <p aria-live="polite">Submissions: {{ submissions }}; {{ event }}</p>
</template>
```

## Loading and action feedback

### Loading layouts and animations

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `loading` | Loading; blocks activation and navigation | Loading layouts and animations, Loading Appearance |
| `loading-size` | Indicator size; xs/sm/md/lg/xl map to 12/14/16/18/20px; numbers are px; follows button size when omitted; not used in line mode | Loading layouts and animations, Loading Appearance |
| `loading-type` | Spinner animation; same as Loading.type; not used in line mode | Loading layouts and animations |
| `loading-mode` | Inline, covering, or bottom progress line; line only uses loading-color | Loading layouts and animations |
| `loading-color` | Loading indicator color | Loading Appearance |
| `ripple` | Click ripple | Feedback |
<!-- demo-config-notes:end -->


Example source: src/button/__demos__/loading.vue

```vue
<script setup lang="ts">
import { ref } from "vue";

const stacked = ref(false)
const mode = ref("default");
const size = ref("md");
const modes = ["default", "fill", "line"];
const sizes = ["xs", "sm", "md", "lg", "xl"];
const types = ["circle", "wave", "cube", "rect", "disappear"];
</script>
<template>
  <c-space direction="column" :size="16">
    <c-form layout="vertical" size="sm">
      <c-form-item label="Layout" field="mode">
        <c-radio-group
          v-model="mode"
          :options="modes"
          aria-label="Loading mode"
          variant="button"
        />
      </c-form-item>
      <c-form-item label="Size" field="size">
        <c-radio-group
          v-model="size"
          :disabled="mode === 'line'"
          :options="sizes"
          aria-label="Loading size"
          variant="button"
        />
      </c-form-item>
    </c-form>
    <label><input v-model="stacked" type="checkbox" />图文堆叠（stacked）</label>
    <p v-if="mode === 'line'">
      line 使用底部进度线，loading-type 和 loading-size 不适用；可通过
      loading-color 调整颜色。
    </p>
    <c-space wrap
      ><c-button
        v-for="type in mode === 'line' ? ['line'] : types"
        :key="type"
        loading
        :stacked="stacked"
        :loading-type="mode === 'line' ? 'circle' : type"
        :loading-mode="mode"
        :loading-size="size"
        ><template #icon><svg width="16" height="16" viewBox="0 0 16 16" aria-hidden="true"><path d="M8 1v14M1 8h14" stroke="currentColor" /></svg></template>{{ type }}</c-button
      ></c-space
    >
  </c-space>
</template>
```

### Loading Appearance

Example source: src/button/__demos__/loading-appearance.vue

```vue
<template>
  <c-space wrap
    ><c-button loading loading-color="#e05279">Custom color</c-button
    ><c-button loading :loading-size="16">Custom size</c-button></c-space
  >
</template>
```

### Feedback

- `elevation`: Controls the shadow intensity.

Example source: src/button/__demos__/feedback.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
const ripple = ref(true);
const elevation = ref(2);
</script>
<template>
  <c-space direction="column" :size="16">
    <c-space wrap>
      <c-checkbox v-model="ripple">Ripple</c-checkbox>
      <label
        >Elevation<c-input-number
          v-model="elevation"
          :min="0"
          :max="24"
          aria-label="Button elevation"
      /></label>
    </c-space>
    <c-button :ripple="ripple" :elevation="elevation"
      >Click to compare feedback</c-button
    >
  </c-space>
</template>
```

### Sync, async and rejection recovery

Example source: src/button/__demos__/controlled-loading.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const saving = ref(false)
const failing = ref(false)
const message = ref('点击保存，观察业务控制的 loading / Click Save to start')
const delay = () => new Promise(resolve => setTimeout(resolve, 800))
async function save() {
  if (saving.value) return
  saving.value = true
  try { await delay(); message.value = '保存完成 / Saved' }
  finally { saving.value = false }
}
async function recover() {
  if (failing.value) return
  failing.value = true
  try { await delay(); throw new Error('模拟请求失败 / Simulated failure') }
  catch (error) { message.value = (error as Error).message }
  finally { failing.value = false }
}
</script>
<template>
  <c-space direction="column" :size="12">
    <p>click 支持 async 回调；业务通过 loading 展示等待，在 finally 中恢复。Async click handlers own their loading state.</p>
    <c-space wrap :size="12">
      <c-button :loading="saving" @click="save">保存 / Save</c-button>
      <c-button :loading="failing" @click="recover">失败与恢复 / Failure recovery</c-button>
    </c-space>
    <p aria-live="polite">{{ message }}</p>
  </c-space>
</template>
```

## Reading direction

Inherits the nearest `dir="ltr|rtl"`, including runtime changes and local overrides. Icons and content follow reading order; stacked content stays top to bottom and slot graphics are not mirrored. ButtonGroup owns horizontal joining edges and outer corners even when a child has a different text direction. A single child keeps all corners; vertical groups preserve top-to-bottom order. Native Tab, Enter and Space remain available; ordinary groups do not intercept horizontal arrows. Disabled and loading behavior stays unchanged.

## API

<!-- same-source-api:start -->

### Props

| Prop | Description | Type | Default |
| ------------- | ------------------------------------------------------------------------------------------------ | ----------------------------------------- | -------------- |
| status | Semantic color; inherits group, otherwise default | `SemanticStatus` | `undefined` |
| variant | Appearance; inherits group, otherwise default | `default / text / outline / tonal` | `undefined` |
| size | Size; inherits group, otherwise md | `xs / sm / md / lg / xl` | `undefined` |
| html-type | Native button type | `button / submit / reset` | `button` |
| component | Root tag; link attributes fall through | `button / a` | `button` |
| round | Round button | `boolean` | `false` |
| block | Full available width | `boolean` | `false` |
| loading | Loading; blocks activation and navigation | `boolean` | `false` |
| loading-type | Spinner animation; same as Loading.type; not used in line mode | `circle / wave / cube / rect / disappear` | `circle` |
| loading-mode | Inline, covering, or bottom progress line; line only uses loading-color | `default / fill / line` | `default` |
| loading-size | Indicator size; xs/sm/md/lg/xl map to 12/14/16/18/20px; numbers are px; follows button size when omitted; not used in line mode | `ComponentSize / number` | `undefined` |
| loading-color | Loading indicator color | `string` | `currentColor` |
| disabled | Disabled; inherits group, explicit false overrides | `boolean` | `undefined` |
| ripple | Click ripple | `boolean` | `true` |
| focusable | Allow sequential Tab focus; does not prevent programmatic focus | `boolean` | `true` |
| autofocus | Native autofocus | `boolean` | `false` |
| text-color | Custom text color | `string` | `undefined` |
| color | Custom background or variant base color | `string` | `undefined` |
| elevation | Default variant shadow; true=2, false=off, rounded/clamped 0–24; group owns grouped elevation | `boolean / number` | `true` |
| stacked | Stack icon and text; inherits group when omitted | `boolean` | `undefined` |

### Events

| Event | Arguments and behavior |
| ---------- | ------------------------------------------- |
| click | `(event: MouseEvent) => void` |
| touchstart | `(event: TouchEvent) => void` |

click is a normal emitted event and supports async handlers. Business state controls loading; restore it in finally. Listener Promises do not automatically drive loading. Disabled/loading links have no effective href.

### Slots

| Slot | Description | Arguments |
| ------- | -------------------------------- | ---- |
| default | Button label; retained while loading | — |
| icon | Leading icon; above label when stacked | — |

### Methods

No custom public methods.
<!-- same-source-api:end -->

## ButtonGroup

### ButtonGroup Props

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| status | Default semantic status; a child may override it | SemanticStatus | default |
| size | Default button size; a child may override it | xs / sm / md / lg / xl | md |
| variant | Default appearance; adjacent effective variants determine joining, including mixed variants | default / text / outline / tonal | default |
| color | Default custom color; a child may override it | string | undefined |
| text-color | Default text color; a child may override it | string | undefined |
| disabled | Default disabled state; an explicit child false overrides group true | boolean | false |
| stacked | Default vertical icon/text layout; a child may explicitly override with false | boolean | false |
| vertical | Vertical group layout, independent of button content stacking | boolean | false |
| elevation | Group shadow; true means 2, numbers normalize to 0–24; applies only to an enabled default-variant group | boolean / number | true |

The root defaults to `role="group"`. Supply `aria-label` or `aria-labelledby` when the action group needs a name. Native attributes can override role. Ordinary groups retain native Tab / Enter / Space handling without arrow-key focus management.

**Inheritance:** explicit child values win for status, size, variant, color, text-color, disabled and stacked. Elevation belongs to the group; a child's own elevation does not apply. Nested groups use their nearest group's settings and defaults rather than combining outer disabled states.

### ButtonGroup Events

No custom events. `@click` falls through to the root DOM element and can receive descendant bubbling; listen to each Button for its action. The group does not collect listener Promises or own a task or selection model.

### ButtonGroup Slots

| Slot | Description | Arguments |
| --- | --- | --- |
| default | Joined styling supports directly adjacent Button DOM nodes under the group root | — |

**Composition:** extra DOM wrappers, prefix/suffix text and arbitrary controls are outside the joined-styling contract. Wrapped buttons may still inherit configuration without sharing the same joined edges. The group owns outer corners and does not preserve an individual round button's circular shape. Use Space for separated or arbitrary content. For narrow containers, the application chooses scrolling, shorter labels or vertical layout; groups do not wrap automatically.

### ButtonGroup Expose

| Name | Description |
| --- | --- |
| buttonGroupProvider | Reactive group configuration with readonly ComputedRef fields; elevation is boolean / number and other fields match the Props |

There are no additional group action methods.

## Types

ButtonProps、ButtonVariant、ButtonLoadingMode、ButtonInstance、ButtonGroupProps、ButtonGroupInstance。

## CSS variable responsibilities and complete defaults

Button exposes 58 appearance tokens. `{status}-color` controls the solid background, `{status}-foreground-color` controls text/outline/tonal foreground, and `{status}-tonal-color` controls soft backgrounds. `solid-text-color` and `solid-state-layer-color` are shared by semantic statuses; default/tertiary foregrounds and primary/tertiary state layers retain theme-specific roles.

Sizes use xs/sm/md/lg/xl. Font sizes, transition duration, focus width/offset and stacked-height increments reuse system variables. Button groups and stacked buttons share border-radius. Four state opacity variables preserve hover/active differences. loading-duration controls only the bottom progress line; Loading controls other loading animations. Internal variables and fixed animation geometry are not public customization points.

| Variable | Default |
| --------------------------------------- | ----------------------------------------- |
| `--c-button-border-radius` | `var(--c-sys-radius-md)` |
| `--c-button-content-gap` | `var(--c-sys-space-3)` |
| `--c-button-danger-color` | `var(--c-sys-color-status-danger)` |
| `--c-button-danger-disabled-color` | `rgb(var(--c-danger-3))` |
| `--c-button-danger-foreground-color` | `var(--c-sys-color-content-danger)` |
| `--c-button-danger-tonal-color` | `rgb(var(--c-danger-1))` |
| `--c-button-default-color` | `var(--c-sys-color-surface-default)` |
| `--c-button-default-foreground-color` | `var(--c-sys-color-content-primary)` |
| `--c-button-default-tonal-color` | `var(--c-sys-color-surface-muted)` |
| `--c-button-disabled-color` | `var(--c-color-fill-2)` |
| `--c-button-disabled-solid-text-color` | `var(--c-sys-color-content-on-dark)` |
| `--c-button-disabled-text-color` | `var(--c-sys-color-content-disabled)` |
| `--c-button-focus-color` | `var(--c-sys-color-content-brand)` |
| `--c-button-info-color` | `var(--c-sys-color-status-info)` |
| `--c-button-info-disabled-color` | `rgb(var(--c-blue-3))` |
| `--c-button-info-foreground-color` | `var(--c-sys-color-content-info)` |
| `--c-button-info-tonal-color` | `rgb(var(--c-blue-1))` |
| `--c-button-lg-height` | `36px` |
| `--c-button-lg-padding` | `0 var(--c-sys-space-7)` |
| `--c-button-loading-duration` | `1s` |
| `--c-button-loading-line-height` | `3px` |
| `--c-button-md-height` | `32px` |
| `--c-button-md-padding` | `0 var(--c-sys-space-6)` |
| `--c-button-plain-state-opacity-active` | `1` |
| `--c-button-plain-state-opacity-hover` | `0.5` |
| `--c-button-primary-color` | `var(--c-sys-color-action-primary)` |
| `--c-button-primary-disabled-color` | `rgb(var(--c-primary-3))` |
| `--c-button-primary-foreground-color` | `var(--c-sys-color-content-brand)` |
| `--c-button-primary-state-layer-color` | `var(--c-button-solid-state-layer-color)` |
| `--c-button-primary-tonal-color` | `rgb(var(--c-primary-1))` |
| `--c-button-secondary-color` | `rgb(var(--c-gray-6))` |
| `--c-button-secondary-foreground-color` | `var(--c-sys-color-content-secondary)` |
| `--c-button-secondary-tonal-color` | `rgb(var(--c-gray-2))` |
| `--c-button-sm-height` | `28px` |
| `--c-button-sm-padding` | `0 var(--c-sys-space-5)` |
| `--c-button-solid-state-layer-color` | `var(--c-sys-color-content-on-dark)` |
| `--c-button-solid-text-color` | `var(--c-sys-color-content-on-dark)` |
| `--c-button-stacked-gap` | `var(--c-sys-space-2)` |
| `--c-button-state-layer-color` | `var(--c-sys-color-surface-page)` |
| `--c-button-state-opacity-active` | `0.12` |
| `--c-button-state-opacity-hover` | `0.08` |
| `--c-button-success-color` | `var(--c-sys-color-status-success)` |
| `--c-button-success-disabled-color` | `rgb(var(--c-success-3))` |
| `--c-button-success-foreground-color` | `var(--c-sys-color-content-success)` |
| `--c-button-success-tonal-color` | `rgb(var(--c-success-1))` |
| `--c-button-tertiary-color` | `rgb(var(--c-gray-7))` |
| `--c-button-tertiary-foreground-color` | `var(--c-sys-color-content-secondary)` |
| `--c-button-tertiary-state-layer-color` | `var(--c-sys-color-content-on-bright)` |
| `--c-button-tertiary-text-color` | `var(--c-sys-color-content-on-dark)` |
| `--c-button-tertiary-tonal-color` | `rgb(var(--c-gray-1))` |
| `--c-button-warning-color` | `var(--c-sys-color-status-warning)` |
| `--c-button-warning-disabled-color` | `rgb(var(--c-warning-3))` |
| `--c-button-warning-foreground-color` | `var(--c-sys-color-content-warning)` |
| `--c-button-warning-tonal-color` | `rgb(var(--c-warning-1))` |
| `--c-button-xl-height` | `44px` |
| `--c-button-xl-padding` | `0 var(--c-sys-space-8)` |
| `--c-button-xs-height` | `24px` |
| `--c-button-xs-padding` | `0 var(--c-sys-space-4)` |

---

Document: llms/en-US/components/calendar.md

<!-- Source: src/calendar/README.en-US.md; locale: en-US; page: /en/components/calendar/ -->

# Calendar

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

Example source: src/calendar/__demos__/basic.vue

```vue
<template>
  <c-calendar v-model="value" />
  <p class="demo-result">当前选择：{{ format(value) }}</p>
</template>

<script lang="ts" setup>
import { ref } from "vue";

const value = ref(new Date());
const format = (value: Date) =>
  value.toLocaleDateString("zh-CN", {
    year: "numeric",
    month: "long",
    day: "numeric",
    weekday: "long",
  });
</script>

<style scoped>
.demo-result {
  margin: 12px 0 0;
  color: var(--c-color-text-2);
}
</style>
```

## Views and date presentation

### Modes

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `mode` | Mode | Modes |
| `modes` | Displayed mode | Modes |
| `day-start-of-week` | First day of the week | Week Options |
| `is-week` | Whether to show week numbers | Week Options |
<!-- demo-config-notes:end -->


- `mode`: Mode
- `modes`: Displayed mode

Example source: src/calendar/__demos__/modes.vue

```vue
<template>
  <c-space wrap>
    <c-button
      :status="mode === 'month' ? 'primary' : 'default'"
      @click="mode = 'month'"
      >月视图</c-button
    >
    <c-button
      :status="mode === 'year' ? 'primary' : 'default'"
      @click="mode = 'year'"
      >年视图</c-button
    >
  </c-space>
  <c-calendar
    v-model="value"
    class="calendar-demo"
    :mode="mode"
    :modes="['month', 'year']"
  />
</template>

<script lang="ts" setup>
import { ref } from "vue";

const value = ref(new Date());
const mode = ref<"month" | "year">("month");
</script>

<style scoped>
.calendar-demo {
  margin-top: 12px;
}
</style>
```

### Week Options

Preview configuration: `:day-start-of-week="mondayFirst ? 1 : 0"`, `:is-week="showWeek"`.

Example source: src/calendar/__demos__/week-options.vue

```vue
<template>
  <c-space wrap>
    <c-checkbox v-model="mondayFirst">周一作为一周开始</c-checkbox>
    <c-checkbox v-model="showWeek">显示周序号</c-checkbox>
  </c-space>
  <c-calendar
    v-model="value"
    class="calendar-demo"
    :day-start-of-week="mondayFirst ? 1 : 0"
    :is-week="showWeek"
  />
</template>

<script lang="ts" setup>
import { ref } from "vue";

const value = ref(new Date());
const mondayFirst = ref(true);
const showWeek = ref(false);
</script>

<style scoped>
.calendar-demo {
  margin-top: 12px;
}
</style>
```

## Interaction and customization

### Controlled

Example source: src/calendar/__demos__/controlled.vue

```vue
<template>
  <c-space wrap>
    <c-button @click="selectToday">选择今天</c-button>
    <c-button @click="selectTomorrow">选择明天</c-button>
  </c-space>
  <c-calendar
    v-model="value"
    class="calendar-demo"
    @change="lastAction = `选择了 ${format($event)}`"
    @panel-change="lastAction = `面板切换到 ${formatMonth($event)}`"
  />
  <c-alert status="info">{{ lastAction }}</c-alert>
</template>

<script lang="ts" setup>
import { ref } from "vue";

const value = ref(new Date());
const lastAction = ref("可点击日期或切换月份");
const format = (date: Date) => date.toLocaleDateString("zh-CN");
const formatMonth = (date: Date) =>
  date.toLocaleDateString("zh-CN", { year: "numeric", month: "long" });
function selectToday() {
  value.value = new Date();
  lastAction.value = `外部设置为 ${format(value.value)}`;
}
function selectTomorrow() {
  const tomorrow = new Date();
  tomorrow.setDate(tomorrow.getDate() + 1);
  value.value = tomorrow;
  lastAction.value = `外部设置为 ${format(value.value)}`;
}
</script>

<style scoped>
.calendar-demo {
  margin: 12px 0;
}
</style>
```

### Custom Cell

Example source: src/calendar/__demos__/custom-cell.vue

```vue
<template>
  <c-calendar v-model="value">
    <template #default="{ year, month, date }">
      <div v-if="items[key(year, month, date)]" class="cell-items">
        <span
          v-for="item in items[key(year, month, date)]"
          :key="item.label"
          class="cell-item"
          :style="{ '--item-color': item.color }"
          >{{ item.label }}</span
        >
      </div>
    </template>
  </c-calendar>
</template>

<script lang="ts" setup>
import { ref } from "vue";

const value = ref(new Date());
const today = new Date();
const key = (year: number, month: number, date: number) =>
  `${year}-${month}-${date}`;
const relativeKey = (offset: number) => {
  const date = new Date(today);
  date.setDate(date.getDate() + offset);
  return key(date.getFullYear(), date.getMonth() + 1, date.getDate());
};
const items: Record<string, Array<{ label: string; color: string }>> = {
  [relativeKey(0)]: [
    { label: "产品评审", color: "rgb(var(--c-primary-6))" },
    { label: "版本发布", color: "rgb(var(--c-success-6))" },
  ],
  [relativeKey(2)]: [{ label: "客户回访", color: "rgb(var(--c-warning-6))" }],
  [relativeKey(5)]: [{ label: "团队周会", color: "rgb(var(--c-purple-6))" }],
};
</script>

<style scoped>
.cell-items {
  display: flex;
  flex-direction: column;
  gap: 4px;
  margin-top: 6px;
}
.cell-item {
  overflow: hidden;
  color: var(--c-color-text-2);
  font-size: 12px;
  line-height: 20px;
  text-overflow: ellipsis;
  white-space: nowrap;
}
.cell-item::before {
  display: inline-block;
  width: 6px;
  height: 6px;
  margin-right: 6px;
  background: var(--item-color);
  border-radius: 50%;
  content: "";
}
</style>
```

### Custom Header

Example source: src/calendar/__demos__/custom-header.vue

```vue
<template>
  <c-calendar v-model="value">
    <template #header="{ year, month }">
      <span class="custom-title">{{ year }} 年 {{ month }} 月工作日历</span>
    </template>
  </c-calendar>
</template>

<script lang="ts" setup>
import { ref } from "vue";

const value = ref(new Date());
</script>

<style scoped>
.custom-title {
  margin: 0 8px;
  color: var(--c-color-text-1);
  font-weight: 600;
}
</style>
```

## API

### `<calendar>` Props

| Parameter | Description | Type | Default |
| ------------------------- | -------------------- | ----------------------- | :-----------------: |
| model-value **(v-model)** | Bound value | `date` | `-` |
| default-value | Default value (uncontrolled state) | `date` | `-` |
| mode | Mode | `'month' \| 'year'` | `-` |
| default-mode | Default Mode | `'month' \| 'year'` | `'month'` |
| modes | Displayed mode | `('month' \| 'year')[]` | `['month', 'year']` |
| day-start-of-week | First day of the week | `0 \| 1` | `0` |
| is-week | Whether to show week numbers | `boolean` | `false` |

### `<calendar>` Events

| Event | Description | Arguments |
| ------------ | -------------------- | ------------ |
| change | Emitted when the selected date changes | date: `Date` |
| panel-change | Emitted when the displayed date panel changes | date: `Date` |

### `<calendar>` Slots

| Slot | Description | Arguments | Version |
| ------- | :--------------: | --------------------------------------------------- | :----- |
| header | Custom header content | year: `number`<br>month: `number` | 2.53.0 |
| default | Custom cell content | year: `number`<br>month: `number`<br>date: `number` | 2.53.0 |

### Type definitions

The component exports the following types

```ts
import type { CalendarInstance } from "@cedar-design/ui";
```

---

Document: llms/en-US/components/card.md

<!-- Source: src/card/README.en-US.md; locale: en-US; page: /en/components/card/ -->

# Card

Source changes synchronously invalidate render generations. Close, row direction, newer work, deactivation or disposal prevent old nextTick/timer/double-frame continuations from changing newer phases. Render/timer deliveries consume once. Recheck lifecycle/request/node after geometry hooks to reject reentrant disposal. Suspension cancels both timers and retained close/click input is inert; activation starts a fresh phase from current props without replay, and initial KeepAlive activation does not duplicate the wait.

## Basic examples

### Basic usage and subtitle

Example source: src/card/__demos__/basic.vue

```vue
<template>
  <c-space direction="column" style="width: 100%">
    <c-card title="Project overview" description="Keep the team informed." />
    <c-card
      title="Project overview"
      subtitle="Updated today"
      description="Keep the team informed."
      top-divider
      bottom-divider
    >
      Release checklist and project updates.
      <template #title-action><c-button size="sm">More</c-button></template>
      <template #footer><c-button status="primary">View details</c-button></template>
    </c-card>
  </c-space>
</template>
```

## Appearance and states

### Appearance configuration comparison

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `title` | Title | Appearance configuration comparison, Hover style |
| `description` | Description | Appearance configuration comparison |
| `hoverable` | Hover style | Hover style |
<!-- demo-config-notes:end -->


Choose a dimension to compare all its values side by side while keeping other settings and content identical. Change the other settings to inspect combinations; input specimens share one model.

Example source: src/card/__demos__/appearance-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";

const __demoAppearance = __demoReactive({ variant: "default", size: "md" });

import { computed as demoComputed, ref as demoRef } from 'vue'
const demoCompareFields = [{"name":"variant","values":["default","outline","tonal"]},{"name":"size","values":["sm","md"]}]
const demoCompareAxis = demoRef("variant")
const demoComparedOptions = demoComputed(() => demoCompareFields.find(field => field.name === demoCompareAxis.value)?.values ?? [])

__demoAppearance['elevation'] = 2
demoCompareFields.push({ name: 'elevation', values: [0, 2, 6] })
</script>
<template>
  <c-space direction="column" :size="16">
    <c-form layout="vertical">
      <c-form-item layout="vertical" size="sm" label="variant">
        <c-radio-group
          v-model="__demoAppearance['variant']"
          aria-label="variant"
          :options="[
            { label: 'default', value: 'default' },
            { label: 'outline', value: 'outline' },
            { label: 'tonal', value: 'tonal' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
      <c-form-item layout="vertical" size="sm" label="size">
        <c-radio-group
          v-model="__demoAppearance['size']"
          aria-label="size"
          :options="[
            { label: 'sm', value: 'sm' },
            { label: 'md', value: 'md' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
    <c-form-item label="elevation"><c-radio-group v-model="__demoAppearance['elevation']" aria-label="elevation" :options="[{ label: '0', value: 0 }, { label: '2', value: 2 }, { label: '6', value: 6 }]" /></c-form-item>
</c-form>
    <p class="demo-config-comparison-hint"><span lang="zh-CN">选择一个对比维度；其他配置和内容保持一致。输入类示例共享同一个值，便于比较外观。</span><span lang="en-US">Compare one dimension while keeping the other settings and content identical. Input specimens share the same value.</span></p>
<c-radio-group v-model="demoCompareAxis" aria-label="Compare configuration" :options="demoCompareFields.map(field => ({ label: field.name, value: field.name }))" />
<div class="demo-config-comparison">
<section v-for="sample in demoComparedOptions" :key="String(sample)">
<p><code>{{ demoCompareAxis }}={{ sample }}</code></p>
<c-card
      title="Project overview"
      description="Keep the team informed."
      v-bind="{ ...__demoAppearance, [demoCompareAxis]: sample }"
    />
</section>
</div>
  </c-space>
</template>

<style scoped>
.demo-config-comparison { display: grid; grid-template-columns: repeat(auto-fit, minmax(min(100%, 220px), 1fr)); gap: 20px; min-width: 0; max-width: 100%; }
.demo-config-comparison > section { min-width: 0; }
.demo-config-comparison p { margin: 0 0 8px; }
html:not([lang='en-US']) .demo-config-comparison-hint > [lang='en-US'],
html[lang='en-US'] .demo-config-comparison-hint > [lang='zh-CN'] { display: none; }
</style>
```

### Hover style

Example source: src/card/__demos__/hoverable.vue

```vue
<template>
  <c-card hoverable title="Hover over this card" style="width: 100%; max-width: 360px"
    >Hover feedback on pointer devices.</c-card
  >
</template>
```

## Layout and arrangement

### Images and directions

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `direction` | Order of cover and body, default column; supports row, column and row-reverse. Does not position the card itself | Images and directions |
| `title` | Title | Images and directions |
| `src` | Cover image URL; cover slot takes precedence | Images and directions |
| `alt` | Image alternative text | Images and directions |
| `image-height` | Image height; numbers use px | Images and directions |
| `image-width` | Image width; numbers use px | Images and directions |
<!-- demo-config-notes:end -->


Example source: src/card/__demos__/image.vue

```vue
<script setup lang="ts">
const imageSrc = `${import.meta.env.BASE_URL}cat.jpg`
const directions = ['column', 'row', 'row-reverse'] as const
</script>

<template>
  <c-space direction="column" style="width: 100%">
    <c-card
      v-for="direction in directions"
      :key="direction"
      :direction="direction"
      :title="direction"
      :src="imageSrc"
      alt="Cat"
      :image-height="120"
      :image-width="direction === 'column' ? '100%' : 100"
      fit="cover"
      >Card content</c-card
    >
    <c-card title="Custom cover"
      ><template #cover
        ><img :src="imageSrc" alt="Cat" style="width: 100%; height: 120px; object-fit: cover" /></template
      >Cover slot overrides the image.</c-card
    >
  </c-space>
</template>
```

## Content and presentation

### Long title and tooltip

Example source: src/card/__demos__/tooltip.vue

```vue
<script setup lang="ts">
const title = 'Project overview with a long title that does not fit on one line'
</script>

<template>
  <c-card style="width: 100%; max-width: 280px">
    <template #title
      ><span class="long-title" :title="title">{{ title }}</span></template
    >
    <template #description
      ><span class="long-title" :title="title">{{ title }}</span></template
    >
    Native title tooltip on pointer devices; the full text remains in the DOM.
  </c-card>
</template>

<style scoped>
.long-title {
  display: block;
  overflow: hidden;
  white-space: nowrap;
  text-overflow: ellipsis;
}
</style>
```

## Customization and slots

### Custom header

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `title` | Title | Custom header |
| `top-divider` | Top divider | Content slots |
| `bottom-divider` | Bottom divider | Content slots |
<!-- demo-config-notes:end -->


Example source: src/card/__demos__/no-padding.vue

```vue
<template>
  <c-card title="Fallback title">
    <template #header
      ><header style="padding: 16px">
        <strong>Custom header</strong>
        <p>Replaces the title and subtitle region.</p>
      </header></template
    >
    Card content
  </c-card>
</template>
```

### Content slots

Example source: src/card/__demos__/slots.vue

```vue
<template>
  <c-card top-divider bottom-divider>
    <template #cover><div style="padding: 16px">Custom cover</div></template>
    <template #title="{ slotClass }"><strong :class="slotClass">Custom title</strong></template>
    <template #title-action><c-button size="sm">More</c-button></template>
    <template #subtitle="{ slotClass }"><span :class="slotClass">Custom subtitle</span></template>
    <template #description="{ slotClass }"><p :class="slotClass">Custom description</p></template>
    Default content
    <template #footer><c-button status="primary">Confirm</c-button></template>
  </c-card>
</template>
```

## Interaction and control

### Ripple and click

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `title` | Title | Ripple and click, Floating and close |
| `ripple` | Click ripple | Ripple and click |
| `floating` | Fullscreen state; supports v-model:floating | Floating and close |
| `floating-duration` | Fullscreen transition duration in ms | Floating and close |
<!-- demo-config-notes:end -->


Example source: src/card/__demos__/ripple.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const clicks = ref(0)
</script>

<template>
  <c-card ripple title="Click this card" @click="clicks++"
    >Clicks: <output aria-live="polite">{{ clicks }}</output></c-card
  >
</template>
```

### Floating and close

Example source: src/card/__demos__/floating.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const floating = ref(false)
</script>

<template>
  <c-card v-model:floating="floating" title="Project overview" :floating-duration="250">
    Summary content
    <template #footer><c-button status="primary" @click="floating = true">Expand</c-button></template>
    <template #floating-content><p style="padding: 16px">Expanded project details.</p></template>
    <template #close-button
      ><c-button aria-label="Close expanded card" @click.stop="floating = false">Close</c-button></template
    >
  </c-card>
</template>
```

## Lifecycle and edge cases

### Floating scheduler lifecycle

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `floating` | Fullscreen state; supports v-model:floating | Floating scheduler lifecycle |
| `ripple` | Click ripple | Floating scheduler lifecycle |
| `floating-duration` | Fullscreen transition duration in ms | Floating scheduler lifecycle |
| `title` | Title | Floating scheduler lifecycle |
<!-- demo-config-notes:end -->


500ms ripple wait is interaction policy; floating-duration defaults to250ms for collapse and transition. DoubleRaf settles layout; cancellation rejects stale continuation writes, not underlying frames. Public API and CSS variables are unchanged. Full Card Cedar21/Maple44 and scoped15 each are controlled tests, not native browser/OS certification.

Example source: src/card/__demos__/scheduler-lifecycle.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const active = ref(true)
const mounted = ref(true)
const floating = ref(false)
const ripple = ref(true)
const duration = ref(250)
</script>
<template>
  <div>
    <c-button @click="floating = !floating">Float / 浮起与回落</c-button>
    <c-button @click="active = !active">Activate / 停用与激活</c-button>
    <c-button @click="mounted = !mounted">Mount / 卸载与挂载</c-button>
    <c-button @click="ripple = !ripple">Ripple wait / 涟漪等待</c-button>
    <c-button @click="duration = duration ? 0 : 250">Duration / 零与默认时长</c-button>
    <p>Toggle floating rapidly, suspend during500ms ripple wait or layout settlement, then activate. Old tasks must not reset a newer phase. Underlying doubleRaf frames are not physically canceled.</p>
    <KeepAlive v-if="mounted">
      <c-card v-if="active" v-model:floating="floating" :ripple="ripple" :floating-duration="duration" title="Floating lifecycle / 浮起生命周期">
        Card content / 卡片内容
        <template #floating-content>
          <c-button @click.stop="floating = false">Collapse / 回落</c-button>
          <c-button @click.stop="active = false">Deactivate / 停用</c-button>
          <c-button @click.stop="mounted = false">Unmount / 卸载</c-button>
        </template>
      </c-card>
    </KeepAlive>
  </div>
</template>
```

The same scenarios, parameters and interactions as Cedar. Only component prefixes differ; themes and site shells remain independent.

## Reading direction

Headings, content and actions follow reading order. Default floating actions sit at reading end without mirroring images or custom slots.

## API

<!-- same-source-api:start -->
### Props

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| variant | Appearance | `default / outline / tonal` | `default` |
| size | Density; omitted value follows platform rules below | `sm / md` | `undefined` |
| direction | Order of cover and body, default column; supports row, column and row-reverse. Does not position the card itself | `row / column / row-reverse` | `column` |
| hoverable | Hover styling | `boolean` | `false` |
| title-style | Title row styles | `CSSProperties` | `undefined` |
| title | Title | `string` | `undefined` |
| subtitle | Subtitle | `string` | `undefined` |
| description | Description | `string` | `undefined` |
| top-divider | Top divider | `boolean` | `false` |
| bottom-divider | Bottom divider | `boolean` | `false` |
| src | Cover image URL; cover slot takes precedence | `string` | `undefined` |
| fit | Cover image fit | `fill / contain / cover / none / scale-down` | `cover` |
| image-height | Image height; numbers use px | `string / number` | `undefined` |
| image-width | Image width; numbers use px | `string / number` | `undefined` |
| alt | Image alternative text | `string` | `undefined` |
| elevation | Shadow for default variant; true means level 1, false disables it, numeric levels 0–24 | `boolean / number` | `true` |
| ripple | Click ripple | `boolean` | `false` |
| floating | Fullscreen state; supports v-model:floating | `boolean` | `false` |
| floating-duration | Fullscreen transition duration in ms | `number` | `250` |

### Events

| Event | Arguments and timing |
| --- | --- |
| click | `(event: Event)`, emitted when the card is clicked |
| update:floating | `(value: boolean)`, emits false when the built-in close button requests closing; expansion is controlled by the parent |

### Slots

| Slot | Description | Arguments |
| --- | --- | --- |
| default | Body | — |
| cover | Cover; overrides src | — |
| header | Entire header; overrides title, title-action and subtitle | — |
| title | Title | `{ slotClass: string }` |
| title-action | Title action | — |
| subtitle | Subtitle | `{ slotClass: string }` |
| description | Description | `{ slotClass: string }` |
| footer | Footer actions | — |
| floating-content | Expanded content; column layout only | — |
| close-button | Custom close button; update floating yourself | — |

### Methods

No public methods.

### Platform notes

Props, event arguments and slots match. Cedar inherits the global size when size is omitted: xs/sm map to sm, all others to md. Maple falls back to md. Pass size explicitly for identical density. Themes and CSS prefixes remain platform-specific.
Card no longer has a loading prop. Compose a loading overlay with the Loading directive.
<!-- same-source-api:end -->

### `<Card>` CSS variables

| Variable | Default |
| --- | --- |
| `--c-card-hover-shadow` | `0 4px 12px rgb(0 0 0 / 12%)` |
| `--c-card-size-sm-title-font-size` | `16px` |
| `--c-card-size-sm-section-margin` | `8px 0 0` |
| `--c-card-size-sm-section-padding` | `0 12px` |
| `--c-card-padding` | `0 0 15px 0` |
| `--c-card-background` | `var(--c-sys-color-surface-default)` |
| `--c-card-filled-background` | `var(--c-sys-color-surface-muted)` |
| `--c-card-outline-color` | `var(--c-sys-color-border-default)` |
| `--c-card-border-radius` | `4px` |
| `--c-card-image-width` | `100%` |
| `--c-card-row-image-width` | `140px` |
| `--c-card-image-height` | `200px` |
| `--c-card-row-height` | `140px` |
| `--c-card-title-color` | `var(--c-sys-color-content-primary)` |
| `--c-card-title-font-size` | `20px` |
| `--c-card-title-padding` | `0 12px` |
| `--c-card-title-margin` | `15px 0 0 0` |
| `--c-card-title-row-margin` | `12px 0` |
| `--c-card-content-padding` | `0 16px` |
| `--c-card-content-margin` | `16px 0 0 0` |
| `--c-card-content-color` | `var(--c-sys-color-content-tertiary)` |
| `--c-card-content-font-size` | `14px` |
| `--c-card-content-row-margin` | `16px 0 0 0` |
| `--c-card-subtitle-color` | `var(--c-sys-color-content-secondary)` |
| `--c-card-subtitle-font-size` | `14px` |
| `--c-card-subtitle-padding` | `0 12px` |
| `--c-card-subtitle-margin` | `10px 0 0 0` |
| `--c-card-subtitle-row-margin` | `-8px 0 0 0` |
| `--c-card-description-color` | `var(--c-sys-color-content-secondary)` |
| `--c-card-description-font-size` | `14px` |
| `--c-card-description-margin` | `20px 0 0 0` |
| `--c-card-description-padding` | `0 13px` |
| `--c-card-footer-padding` | `0 12px` |
| `--c-card-footer-right` | `13px` |
| `--c-card-footer-bottom` | `9px` |
| `--c-card-footer-margin` | `30px 0 0 0` |
| `--c-card-line-height` | `22px` |
| `--c-card-row-line-height` | `1.5` |
| `--c-card-floating-buttons-bottom` | `16px` |
| `--c-card-floating-buttons-right` | `16px` |
| `--c-card-floating-buttons-color` | `var(--c-sys-color-content-primary)` |
| `--c-card-close-button-icon-size` | `24px` |
| `--c-card-close-button-size` | `56px` |
| `--c-card-close-button-background` | `#212121` |
| `--c-card-close-button-text-color` | `var(--c-sys-color-content-on-dark)` |
| `--c-card-close-button-border-radius` | `50%` |

Card colors follow system semantics: regular/filled backgrounds and borders use `surface-default`, `surface-muted` and `border-default`. Titles, body text and secondary text use `content-primary`, `content-tertiary` and `content-secondary`. Expanded floating-button containers sit on the card surface and use `content-primary`; text/icons on dark close buttons use `content-on-dark`. The `#212121` close-button background is Card-specific, not the global primary-action color. See the Design Token specification for old variable mappings.

### Type definitions

The component exports the following types

```ts
import type { CardProps } from '@cedar-design/ui'
```

See `API-MIGRATION.md` at the repository root for size and cross-platform migration rules. Only the documented sizes are supported, not every ComponentSize.

### Variable consumption rules

Row content consumes `--c-card-content-row-margin`, independently from the title margin. Card intentionally exposes only sm/md density, not all five control sizes. Motion uses `--c-card-animation-duration` (`var(--c-sys-motion-duration-slow)`) and `--c-card-animation-easing` (`var(--c-sys-motion-easing-standard)`). Reduced motion disables transitions on every animated Card section.

---

Document: llms/en-US/components/carousel.md

<!-- Source: src/carousel/README.en-US.md; locale: en-US; page: /en/components/carousel/ -->

# Carousel

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

Example source: src/carousel/__demos__/basic.vue

```vue
<template>
  <c-carousel :style="{ width: '600px', height: '240px' }" >
    <c-carousel-item>
      <img src="/cat.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none">
    </c-carousel-item>
    <c-carousel-item>
      <img src="/cat2.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none">
    </c-carousel-item>
    <c-carousel-item>
      <img src="/cat3.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none">
    </c-carousel-item>
  </c-carousel>
</template>
```

## Direction and layout

### Vertical

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `slides-per-view` | Visible count; auto uses item size | Multi Slides, Centered Slides, Auto Sized |
| `space-between` | Item gap; numbers/numeric strings are px | Multi Slides, Centered Slides, Auto Sized |
| `draggable` | Mouse dragging, independent of touch | Multi Slides, Auto Sized |
| `centered-slides` | Center active slide | centered-slides、auto-sized |
| `orientation` | Horizontal/vertical axis of carousel sliding, default horizontal; does not determine indicator position | Vertical |
| `model-value` | Controlled one-based slide number | Multi Slides |
<!-- demo-config-notes:end -->


- `orientation`: Controls the content direction.

Example source: src/carousel/__demos__/vertical.vue

```vue
<template>
  <c-carousel orientation="vertical" :style="{ width: '600px', height: '300px' }">
    <c-carousel-item>
      <img src="/cat.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none">
    </c-carousel-item>
    <c-carousel-item>
      <img src="/cat2.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none">
    </c-carousel-item>
    <c-carousel-item>
      <img src="/cat3.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none">
    </c-carousel-item>
  </c-carousel>
</template>
```

### Multi Slides

Preview configuration: `:slides-per-view="2.5"`, `:space-between="10"`, `:model-value="current"`, `:loop="loop"`.

Example source: src/carousel/__demos__/multi-slides.vue

```vue
<script setup>
import { ref } from "vue";
const current = ref(1);
const proposal = ref(1);
const changes = ref(0);
const accept = ref(true);
const loop = ref(true);
function update(value) {
  proposal.value = value;
  if (accept.value) current.value = value;
}
</script>

<template>
  <section class="multi-slides-demo">
    <c-checkbox v-model="accept"> Accept changes / 接受切换</c-checkbox>
    <c-checkbox v-model="loop"> Loop / 循环</c-checkbox>
    <p role="status">
      Current: {{ current }} · Proposal: {{ proposal }} · Changes: {{ changes }}
    </p>
    <c-carousel
      :slides-per-view="2.5"
      :space-between="10"
      :style="{ width: '600px', height: '200px' }"
      :model-value="current"
      :loop="loop"
      draggable
      keyboard
      @update:modelValue="update"
      @change="changes++"
    >
      <c-carousel-item v-for="i in 6" :key="i">
        <div
          style="
            width: 100%;
            height: 100%;
            display: flex;
            align-items: center;
            justify-content: center;
            background: #4a90d9;
            color: #fff;
            font-size: 24px;
            font-weight: bold;
          "
        >
          {{ i }}
        </div>
      </c-carousel-item>
    </c-carousel>
  </section>
</template>
```

### Centered Slides

Preview configuration: `:slides-per-view="1.5"`, `:space-between="10"`, `centered-slides`.

Example source: src/carousel/__demos__/centered-slides.vue

```vue
<script setup></script>

<template>
  <c-carousel class="carousel" :slides-per-view="1.5" :space-between="10" centered-slides>
    <c-carousel-item v-for="i in 5" :key="i">
      <div class="carousel-custom-slide">{{ i }}</div>
    </c-carousel-item>
  </c-carousel>
</template>

<style lang="less" scoped>
.carousel {
  height: 160px;
}

.carousel-example {
  height: 160px;
}

.carousel-item {
  width: 100%;
  height: 100%;
  object-fit: cover;
  pointer-events: none;
}

.carousel-custom-slide {
  width: 100%;
  height: 100%;
  display: flex;
  align-items: center;
  justify-content: center;
  background: #4a90d9;
  color: #fff;
  font-size: 24px;
  font-weight: bold;
}

.carousel-custom-indicators {
  position: absolute;
  bottom: 10px;
  left: 50%;
  transform: translateX(-50%);
  display: flex;
  gap: 4px;
}

.carousel-custom-indicator {
  width: 20px;
  height: 20px;
  display: flex;
  align-items: center;
  justify-content: center;
  background: rgba(0, 0, 0, 0.3);
  color: #fff;
  font-size: 12px;
  border-radius: 50%;
}

.carousel-custom--active {
  background: #4a90d9;
}

.space {
  height: 20px;
}
</style>
```

### Auto Sized

- `height`: Constrains the component height.

Example source: src/carousel/__demos__/auto-sized.vue

```vue
<script setup>
import { computed, ref } from "vue";
const current = ref(1);
const changes = ref(0);
const wider = ref(false);
const compact = ref(false);
const extra = ref(false);
const empty = ref(false);
const reversed = ref(false);
const widths = computed(() => {
  const items = empty.value
    ? []
    : [140, 220, 180, 260, ...(extra.value ? [200] : [])];
  return (reversed.value ? items.reverse() : items).map(
    (width) => width + (wider.value ? 80 : 0),
  );
});
</script>

<template>
  <section class="auto-sized-demo">
    <c-checkbox v-model="wider"> Wider cards / 加宽卡片</c-checkbox>
    <c-checkbox v-model="compact"> 300px viewport / 窄容器</c-checkbox>
    <c-checkbox v-model="extra"> Extra card / 增加末项</c-checkbox>
    <c-checkbox v-model="empty"> Empty / 清空项目</c-checkbox>
    <c-checkbox v-model="reversed"> Reverse cards / 反转顺序</c-checkbox>
    <p role="status">Current: {{ current }} · Changes: {{ changes }}</p>
    <c-carousel
      v-model="current"
      slides-per-view="auto"
      :space-between="12"
      :style="{ width: compact ? '300px' : '100%' }"
      height="180px"
      centered-slides
      draggable
      @change="changes++"
    >
      <c-carousel-item
        v-for="width in widths"
        :key="width"
        :style="{ width: width + 'px' }"
      >
        <div class="carousel-demo-panel">{{ width }}px</div>
      </c-carousel-item>
    </c-carousel>
  </section>
</template>
<style scoped>
.carousel-demo-panel {
  display: grid;
  place-items: center;
  height: 100%;
  background: #e0e7ff;
  color: #312e81;
}
</style>
```

## Navigation and effects

### Navigation

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `show-arrow` | Arrow visibility | Navigation |
| `indicator-type` | Indicator appearance | Indicator style and position |
| `indicator-position` | Indicator edge or outer region of the carousel container, default bottom. Not a trigger-relative popup placement | Indicator style and position |
| `effect` | Effect; all supported by both libraries | Transition effects |
<!-- demo-config-notes:end -->


Preview configuration: `show-arrow="always"`, `show-arrow="hover"`.

Example source: src/carousel/__demos__/navigation.vue

```vue
<template>
  <div>
    <h4 style="margin:0 0 8px">Always</h4>
    <c-carousel show-arrow="always" :style="{width:'600px',height:'200px',marginBottom:'20px'}">
      <c-carousel-item><img src="/cat.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none"></c-carousel-item>
      <c-carousel-item><img src="/cat2.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none"></c-carousel-item>
      <c-carousel-item><img src="/cat3.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none"></c-carousel-item>
    </c-carousel>
    <h4 style="margin:0 0 8px">Hover</h4>
    <c-carousel show-arrow="hover" :style="{width:'600px',height:'200px'}">
      <c-carousel-item><img src="/cat.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none"></c-carousel-item>
      <c-carousel-item><img src="/cat2.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none"></c-carousel-item>
      <c-carousel-item><img src="/cat3.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none"></c-carousel-item>
    </c-carousel>
  </div>
</template>
```

### Indicator style and position

All indicator presets use the same three local slides and active-slide model. Click an indicator or a navigation arrow in any specimen: every specimen changes to the same slide. The first group compares dot, line and slider; the second compares top and outer positions. The grid stacks on narrow screens.

Example source: src/carousel/__demos__/indicator-comparison.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const current = ref(1)
const groups = [{"name":"indicator-type","zh":"指示器样式","en":"Indicator types","values":[{"label":"dot","type":"dot","position":"bottom"},{"label":"line","type":"line","position":"bottom"},{"label":"slider","type":"slider","position":"bottom"}]},{"name":"indicator-position","zh":"指示器位置","en":"Indicator positions","values":[{"label":"top","type":"dot","position":"top"},{"label":"outer","type":"dot","position":"outer"}]}] as const
const slides = ["data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20width%3D%22640%22%20height%3D%22240%22%3E%3Crect%20width%3D%22640%22%20height%3D%22240%22%20fill%3D%22%23286b72%22%2F%3E%3Ctext%20x%3D%22320%22%20y%3D%22130%22%20text-anchor%3D%22middle%22%20fill%3D%22white%22%20font-size%3D%2236%22%3ESlide%201%3C%2Ftext%3E%3C%2Fsvg%3E","data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20width%3D%22640%22%20height%3D%22240%22%3E%3Crect%20width%3D%22640%22%20height%3D%22240%22%20fill%3D%22%234b5694%22%2F%3E%3Ctext%20x%3D%22320%22%20y%3D%22130%22%20text-anchor%3D%22middle%22%20fill%3D%22white%22%20font-size%3D%2236%22%3ESlide%202%3C%2Ftext%3E%3C%2Fsvg%3E","data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20width%3D%22640%22%20height%3D%22240%22%3E%3Crect%20width%3D%22640%22%20height%3D%22240%22%20fill%3D%22%23965734%22%2F%3E%3Ctext%20x%3D%22320%22%20y%3D%22130%22%20text-anchor%3D%22middle%22%20fill%3D%22white%22%20font-size%3D%2236%22%3ESlide%203%3C%2Ftext%3E%3C%2Fsvg%3E"]
</script>
<template>
<div class="indicator-comparison">
<p role="status">Slide: {{ current }}</p>
<section v-for="group in groups" :key="group.name" :data-comparison-scene="group.name">
<h4><span lang="zh-CN">{{ group.zh }}</span><span lang="en-US">{{ group.en }}</span></h4>
<div class="indicator-comparison-grid">
<div v-for="preset in group.values" :key="preset.label">
<p><code>{{ preset.label }}</code></p>
<c-carousel v-model="current" :indicator-type="preset.type" :indicator-position="preset.position" style="height: 150px">
<c-carousel-item v-for="(src, index) in slides" :key="src"><img :src="src" :alt="'Slide ' + (index + 1)" /></c-carousel-item>
</c-carousel>
</div>
</div>
</section>
</div>
</template>
<style scoped>
.indicator-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.indicator-comparison-grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(min(100%, 240px), 1fr)); gap: 16px; }
.indicator-comparison > section, .indicator-comparison-grid, .indicator-comparison-grid > div { min-width: 0; max-width: 100%; }
p, h4 { margin: 0 0 8px; }
img { width: 100%; height: 100%; object-fit: cover; pointer-events: none; }
html:not([lang='en-US']) h4 > [lang='en-US'], html[lang='en-US'] h4 > [lang='zh-CN'] { display: none; }
</style>
```

### Transition effects

Change adjacent slides to compare fade, card and slide effects independently of autoplay and input methods.

Example source: src/carousel/__demos__/effect-comparison.vue

```vue
<script setup lang="ts">


</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="effect-fade">
    <h4><span lang="zh-CN">effect-fade</span><span lang="en-US">effect fade</span></h4>
    <c-carousel class="carousel" effect="fade">
        <c-carousel-item>
          <img class="carousel-item" :src="'/cat.jpg'" alt="" />
        </c-carousel-item>
        <c-carousel-item>
          <img class="carousel-item" :src="'/cat2.jpg'" alt="" />
        </c-carousel-item>
        <c-carousel-item>
          <img class="carousel-item" :src="'/cat3.jpg'" alt="" />
        </c-carousel-item>
      </c-carousel>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="effect-card">
    <h4><span lang="zh-CN">effect-card</span><span lang="en-US">effect card</span></h4>
    <c-carousel class="carousel" effect="card">
        <c-carousel-item>
          <img class="carousel-item" :src="'/cat.jpg'" alt="" />
        </c-carousel-item>
        <c-carousel-item>
          <img class="carousel-item" :src="'/cat2.jpg'" alt="" />
        </c-carousel-item>
        <c-carousel-item>
          <img class="carousel-item" :src="'/cat3.jpg'" alt="" />
        </c-carousel-item>
      </c-carousel>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }
.demo-comparison-case--1 {

.carousel {
  height: 160px;
}

.carousel-example {
  height: 160px;
}

.carousel-item {
  width: 100%;
  height: 100%;
  object-fit: cover;
  pointer-events: none;
}

.carousel-custom-slide {
  width: 100%;
  height: 100%;
  display: flex;
  align-items: center;
  justify-content: center;
  background: #4a90d9;
  color: #fff;
  font-size: 24px;
  font-weight: bold;
}

.carousel-custom-indicators {
  position: absolute;
  bottom: 10px;
  left: 50%;
  transform: translateX(-50%);
  display: flex;
  gap: 4px;
}

.carousel-custom-indicator {
  width: 20px;
  height: 20px;
  display: flex;
  align-items: center;
  justify-content: center;
  background: rgba(0, 0, 0, 0.3);
  color: #fff;
  font-size: 12px;
  border-radius: 50%;
}

.carousel-custom--active {
  background: #4a90d9;
}

.space {
  height: 20px;
}

}
.demo-comparison-case--2 {

.carousel {
  height: 160px;
}

.carousel-example {
  height: 160px;
}

.carousel-item {
  width: 100%;
  height: 100%;
  object-fit: cover;
  pointer-events: none;
}

.carousel-custom-slide {
  width: 100%;
  height: 100%;
  display: flex;
  align-items: center;
  justify-content: center;
  background: #4a90d9;
  color: #fff;
  font-size: 24px;
  font-weight: bold;
}

.carousel-custom-indicators {
  position: absolute;
  bottom: 10px;
  left: 50%;
  transform: translateX(-50%);
  display: flex;
  gap: 4px;
}

.carousel-custom-indicator {
  width: 20px;
  height: 20px;
  display: flex;
  align-items: center;
  justify-content: center;
  background: rgba(0, 0, 0, 0.3);
  color: #fff;
  font-size: 12px;
  border-radius: 50%;
}

.carousel-custom--active {
  background: #4a90d9;
}

.space {
  height: 20px;
}

}
</style>
```

### Custom Indicator

Example source: src/carousel/__demos__/custom-indicator.vue

```vue
<template>
  <c-carousel :style="{ width: '600px', height: '240px' }">
    <c-carousel-item
      ><img
        src="/cat.jpg"
        style="
          width: 100%;
          height: 100%;
          object-fit: cover;
          pointer-events: none;
        "
    /></c-carousel-item>
    <c-carousel-item
      ><img
        src="/cat2.jpg"
        style="
          width: 100%;
          height: 100%;
          object-fit: cover;
          pointer-events: none;
        "
    /></c-carousel-item>
    <c-carousel-item
      ><img
        src="/cat3.jpg"
        style="
          width: 100%;
          height: 100%;
          object-fit: cover;
          pointer-events: none;
        "
    /></c-carousel-item>
    <template #indicator="{ slideNumber, length, to }">
      <div
        style="
          position: absolute;
          bottom: 10px;
          left: 50%;
          transform: translateX(-50%);
          display: flex;
          gap: 4px;
        "
      >
        <c-button
          v-for="i in length"
          :key="i"
          size="xs"
          round
          :variant="i === slideNumber ? 'default' : 'tonal'"
          :status="i === slideNumber ? 'primary' : 'default'"
          :aria-label="`跳转至第 ${i} 页`"
          @click="to(i)"
          >{{ i }}</c-button
        >
      </div>
    </template>
  </c-carousel>
</template>
```

## Playback and interaction

### Forbid Loop

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `height` | Container height; numbers are px | Autoplay, Controlled, Interactive Content |
| `keyboard` | Scoped arrow/Home/End navigation | Keyboard, Controlled, Interactive Content |
| `auto-play` | Autoplay configuration | Autoplay, Auto Play Hover |
| `draggable` | Mouse dragging, independent of touch | controlled、interactive-content |
| `loop` | Loop without duplicating instances | Forbid Loop |
| `trigger` | Indicator trigger | Trigger |
<!-- demo-config-notes:end -->


Preview configuration: `:loop="false"`.

Example source: src/carousel/__demos__/forbid-loop.vue

```vue
<template>
  <c-carousel :style="{ width: '600px', height: '240px' }" :loop="false">
    <c-carousel-item>
      <img src="/cat.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none">
    </c-carousel-item>
    <c-carousel-item>
      <img src="/cat2.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none">
    </c-carousel-item>
    <c-carousel-item>
      <img src="/cat3.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none">
    </c-carousel-item>
  </c-carousel>
</template>
```

### Autoplay

- `height`: Constrains the component height.

Example source: src/carousel/__demos__/autoplay.vue

```vue
<script setup>
import { ref } from "vue";
const current = ref(1);
const playing = ref(true);
const changes = ref(0);
const sources = ["/cat.jpg", "/cat2.jpg", "/cat3.jpg"];
</script>

<template>
  <section class="carousel-autoplay-demo">
    <c-checkbox v-model="playing"> 自动播放</c-checkbox>
    <p role="status">当前页：{{ current + 1 }}；切换次数：{{ changes }}</p>
    <c-carousel
      v-model="current"
      height="180px"
      :auto-play="playing ? 2000 : false"
      @change="changes += 1"
    >
      <c-carousel-item v-for="(source, index) in sources" :key="source">
        <img
          class="carousel-autoplay-demo__image"
          :src="source"
          :alt="'示例图片 ' + (index + 1)"
        />
      </c-carousel-item>
    </c-carousel>
  </section>
</template>

<style scoped>
.carousel-autoplay-demo__image {
  width: 100%;
  height: 100%;
  object-fit: cover;
  pointer-events: none;
}
</style>
```

### Auto Play Hover

Preview configuration: `:auto-play="{ interval: 2000, hoverToPause: true }"`.

Example source: src/carousel/__demos__/auto-play-hover.vue

```vue
<template>
  <c-carousel :style="{ width: '600px', height: '240px' }" :auto-play="{ interval: 2000, hoverToPause: true }">
    <c-carousel-item>
      <img src="/cat.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none">
    </c-carousel-item>
    <c-carousel-item>
      <img src="/cat2.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none">
    </c-carousel-item>
    <c-carousel-item>
      <img src="/cat3.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none">
    </c-carousel-item>
  </c-carousel>
</template>
```

### Trigger

Preview configuration: `trigger="hover"`.

Example source: src/carousel/__demos__/trigger.vue

```vue
<template>
  <c-carousel :style="{ width: '600px', height: '240px' }" trigger="hover">
    <c-carousel-item>
      <img src="/cat.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none">
    </c-carousel-item>
    <c-carousel-item>
      <img src="/cat2.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none">
    </c-carousel-item>
    <c-carousel-item>
      <img src="/cat3.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none">
    </c-carousel-item>
  </c-carousel>
</template>
```

### Mousewheel

Preview configuration: `mousewheel`.

Example source: src/carousel/__demos__/mousewheel.vue

```vue
<template>
  <c-carousel :style="{ width: '600px', height: '240px' }" mousewheel>
    <c-carousel-item>
      <img src="/cat.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none">
    </c-carousel-item>
    <c-carousel-item>
      <img src="/cat2.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none">
    </c-carousel-item>
    <c-carousel-item>
      <img src="/cat3.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none">
    </c-carousel-item>
  </c-carousel>
</template>
```

### Keyboard

Preview configuration: `keyboard`.

Example source: src/carousel/__demos__/keyboard.vue

```vue
<template>
  <c-carousel :style="{ width: '600px', height: '240px' }" keyboard>
    <c-carousel-item>
      <img src="/cat.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none">
    </c-carousel-item>
    <c-carousel-item>
      <img src="/cat2.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none">
    </c-carousel-item>
    <c-carousel-item>
      <img src="/cat3.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none">
    </c-carousel-item>
  </c-carousel>
</template>
```

### Change Event

Example source: src/carousel/__demos__/change-event.vue

```vue
<template>
  <c-carousel :style="{ width: '600px', height: '240px' }" @change="handleChange">
    <c-carousel-item>
      <img src="/cat.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none">
    </c-carousel-item>
    <c-carousel-item>
      <img src="/cat2.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none">
    </c-carousel-item>
    <c-carousel-item>
      <img src="/cat3.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none">
    </c-carousel-item>
  </c-carousel>
</template>

<script setup>
const handleChange = (slideNumber) => {
  console.log('slide:', slideNumber)
}
</script>
```

### Controlled

- `height`: Constrains the component height.

Example source: src/carousel/__demos__/controlled.vue

```vue
<script setup>
import { ref } from "vue";
const current = ref(1);
const accept = ref(true);
const proposal = ref(1);
function update(value) {
  proposal.value = value;
  if (accept.value) current.value = value;
}
</script>
<template>
  <c-checkbox v-model="accept"> Accept changes / 接受切换</c-checkbox>
  <p>Current: {{ current }} · Proposal: {{ proposal }}</p>
  <c-carousel
    :model-value="current"
    height="180px"
    keyboard
    draggable
    @update:modelValue="update"
  >
    <c-carousel-item v-for="item in 4" :key="item"
      ><div class="carousel-demo-panel">Slide {{ item }}</div></c-carousel-item
    >
  </c-carousel>
</template>
<style scoped>
.carousel-demo-panel {
  display: grid;
  place-items: center;
  height: 100%;
  background: #dbeafe;
  color: #1e3a8a;
}
</style>
```

### Interactive Content

- `height`: Constrains the component height.

Example source: src/carousel/__demos__/interactive-content.vue

```vue
<script setup>
import { ref } from "vue";

const current = ref(1);
const changes = ref(0);
</script>

<template>
  <p>
    Drag the background; inputs retain normal editing. /
    拖动背景切换，输入框保留原生编辑。
  </p>
  <p role="status">Current: {{ current }} · Changes: {{ changes }}</p>
  <c-carousel
    v-model="current"
    class="carousel-interactive-demo"
    height="180px"
    draggable
    touchable
    keyboard
    @change="changes++"
  >
    <c-carousel-item v-for="item in 3" :key="item">
      <div class="carousel-demo-panel">
        <label
          >Slide {{ item }}
          <c-input :aria-label="'Slide ' + item" placeholder="Type here"
        /></label>
      </div>
    </c-carousel-item>
  </c-carousel>
</template>
<style scoped>
.carousel-demo-panel {
  display: grid;
  place-items: center;
  height: 100%;
  background: #dcfce7;
  color: #14532d;
}
input {
  max-width: 150px;
}
</style>
```

## Lifecycle

### Scheduler Lifecycle

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `auto-play` | Autoplay configuration | Scheduler Lifecycle |
| `move-speed` | Explicit duration in milliseconds | Scheduler Lifecycle |
| `height` | Container height; numbers are px | Scheduler Lifecycle |
| `keyboard` | Scoped arrow/Home/End navigation | Scheduler Lifecycle |
| `mousewheel` | Wheel navigation | Scheduler Lifecycle |
<!-- demo-config-notes:end -->


- `height`: Constrains the component height.

Example source: src/carousel/__demos__/scheduler-lifecycle.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const active = ref(true)
const mounted = ref(true)
const current = ref(1)
const playing = ref(false)
const moves = ref(0)
</script>
<template>
  <div>
    <c-button @click="playing = !playing">Autoplay / 自动播放</c-button>
    <c-button @click="active = !active">Activate / 停用与激活</c-button>
    <c-button @click="mounted = !mounted">Mount / 卸载与挂载</c-button>
    <p>Current / 当前: {{ current }}; changes / 通知: {{ moves }}. Suspend during autoplay or loop settlement, then activate. Old work must not replay.</p>
    <KeepAlive v-if="mounted">
      <c-carousel v-if="active" v-model="current" :auto-play="playing ? { interval: 1000 } : false" :move-speed="600" :height="180" keyboard mousewheel @change="moves++">
        <c-carousel-item v-for="item in 3" :key="item">Slide / 幻灯片 {{ item }}</c-carousel-item>
      </c-carousel>
    </KeepAlive>
  </div>
</template>
```

## API

### Value and default value

Use ordinary `v-model`. `modelValue` is the current slide number, starting at 1. `defaultValue` initializes uncontrolled state only on creation; later changes do not reset it. An explicit bound value takes precedence. Initialization does not emit `update:modelValue`.

### Carousel Props

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| `model-value` | Controlled one-based slide number | `number` | `undefined` |
| `default-value` | Uncontrolled initial index | `number` | `1` |
| `loop` | Loop without duplicating instances | `boolean` | `true` |
| `auto-play` | Autoplay configuration | `boolean \| number \| CarouselAutoPlayConfig` | `false` |
| `move-speed` | Explicit duration in milliseconds | `number` | `undefined (token)` |
| `trigger` | Indicator trigger | `click \| hover` | `click` |
| `orientation` | Horizontal/vertical axis of carousel sliding, default horizontal; does not determine indicator position | `horizontal \| vertical` | `horizontal` |
| `show-arrow` | Arrow visibility | `always \| hover \| never` | `always` |
| `arrow-class` | Additional arrow class | `string` | `undefined` |
| `indicator` | Show indicators | `boolean` | `true` |
| `indicator-type` | Indicator appearance | `dot \| line \| slider` | `dot` |
| `indicator-position` | Indicator edge or outer region of the carousel container, default bottom. Not a trigger-relative popup placement | `bottom \| top \| left \| right \| outer` | `bottom` |
| `indicator-class` | Additional indicator class | `string` | `undefined` |
| `indicator-color` | Custom indicator background | `string` | `undefined` |
| `height` | Container height; numbers are px | `number \| string` | `undefined` |
| `transition-timing-function` | Explicit timing function | `string` | `undefined (token)` |
| `touchable` | Touch dragging | `boolean` | `true` |
| `draggable` | Mouse dragging, independent of touch | `boolean` | `false` |
| `mousewheel` | Wheel navigation | `boolean` | `false` |
| `keyboard` | Scoped arrow/Home/End navigation | `boolean` | `false` |
| `slides-per-view` | Visible count; auto uses item size | `number \| auto` | `1` |
| `space-between` | Item gap; numbers/numeric strings are px | `number \| string` | `0` |
| `effect` | Effect; all supported by both libraries | `slide \| fade \| card` | `slide` |
| `centered-slides` | Center active slide | `boolean` | `false` |
| `aria-label` | Carousel accessible name | `string` | Locale |
| `previous-button-aria-label` | Previous button accessible name | `string` | Locale |
| `next-button-aria-label` | Next button accessible name | `string` | Locale |

### Model and interaction
Public slide numbers start at 1. Controlled actions emit update:model-value, then change(slideNumber, previousSlideNumber, isManual), and do not move until the parent accepts current. External assignments do not emit change. Method option event:false suppresses only change, not the model proposal. isManual is true for user actions and false for autoplay.

loop moves existing children across boundaries without cloning component instances. Without looping or centering, the final viewport is clamped to avoid empty space; selection can move within the final visible group without moving the track. Partly visible slides remain accessible; fully offscreen slides are inert. fade displays one slide. auto uses explicit CarouselItem width horizontally or height vertically; vertical mode requires a container height. Only CarouselItem children, including those inside Vue Fragments, count as slides; comments and ordinary elements do not.

auto-play=true uses 3000ms and pauses on hover; a number sets milliseconds without hover pausing; an object configures interval/hoverToPause. Focus within, dragging, hidden documents/ancestors and KeepAlive deactivation always pause playback. Reduced-motion preferences are respected. Interactive children such as inputs/buttons keep native behavior; mark custom interactive areas with data-carousel-no-drag. show-arrow=hover also shows arrows on keyboard focus.

### Events
| Event | Arguments |
| --- | --- |
| update:model-value | slideNumber: number |
| change | slideNumber: number, previousSlideNumber: number, isManual: boolean |

### Slots
| Slot | Arguments |
| --- | --- |
| default | CarouselItem |
| prev / next / indicator | { slideNumber, length, hovering, prev, next, to, resize } |

### Methods
| Method | Signature |
| --- | --- |
| prev / next | (options?: CarouselToOptions) => void |
| to | (slideNumber: number, options?: CarouselToOptions) => void |
| resize | () => void |

CarouselItem has no own props, events or methods. Its default slot supplies slide content.

### Types
CarouselProps, CarouselItemProps, CarouselInstance, CarouselItemInstance, CarouselEmits, CarouselSlots, CarouselItemSlots, CarouselExpose, CarouselSlotScope, CarouselToOptions, CarouselChangeData, CarouselOrientation, CarouselEffect, CarouselAutoPlayConfig, CarouselArrowType, CarouselIndicatorType, CarouselIndicatorPosition, CarouselTriggerEvent.

### Style variables

| Token | Default |
| --- | --- |
| `--c-carousel-indicator-dot-size` | `8px` |
| `--c-carousel-indicator-position` | `var(--c-sys-space-4)` |
| `--c-carousel-indicator-gap` | `var(--c-sys-space-3)` |
| `--c-carousel-indicator-color-default` | `rgb(255 255 255 / 35%)` |
| `--c-carousel-indicator-color-active` | `var(--c-sys-color-content-on-dark)` |
| `--c-carousel-indicator-outer-margin-bottom` | `var(--c-sys-space-8)` |
| `--c-carousel-indicator-line-width` | `20px` |
| `--c-carousel-indicator-line-height` | `3px` |
| `--c-carousel-indicator-line-border-radius` | `var(--c-sys-radius-sm)` |
| `--c-carousel-arrow-size` | `var(--c-sys-control-height-md)` |
| `--c-carousel-arrow-font-size` | `var(--c-sys-font-size-xl)` |
| `--c-carousel-arrow-margin` | `var(--c-sys-space-4)` |
| `--c-carousel-arrow-color` | `var(--c-sys-color-content-on-dark)` |
| `--c-carousel-arrow-background` | `rgb(0 0 0 / 35%)` |
| `--c-carousel-arrow-background-hover` | `rgb(0 0 0 / 55%)` |
| `--c-carousel-arrow-disabled-opacity` | `0.4` |
| `--c-carousel-navigation-z-index` | `10` |
| `--c-carousel-transition-duration` | `var(--c-sys-motion-duration-standard)` |
| `--c-carousel-transition-timing-function` | `ease` |
| `--c-carousel-fade-duration` | `var(--c-sys-motion-duration-standard)` |
| `--c-carousel-card-duration` | `var(--c-sys-motion-duration-standard)` |
| `--c-carousel-card-scale` | `0.85` |
| `--c-carousel-card-opacity` | `0.6` |
| `--c-carousel-focus-width` | `2px` |
| `--c-carousel-focus-offset` | `2px` |
| `--c-carousel-focus-color` | `var(--c-sys-color-content-brand)` |

### Loop transition boundaries

Each slide always has one component instance. Ordinary previous/next navigation recycles positions after the departing slide exits. Multi-slide or centered jumps that would require one slide in two positions settle immediately without animation, cloning interactive content or queuing unlimited transitions. Fewer items than visible slides are not cloned to fill space. Accessible names follow global Locale; explicit label props take precedence.

Native root listeners such as `keydown`, `mouseenter`, `mouseleave`, `focusin` and `focusout` run alongside internal navigation and autoplay pause handling. Native `.once` listeners fire once for the root element lifetime.

---

Document: llms/en-US/components/cascader.md

<!-- Source: src/cascader/README.en-US.md; locale: en-US; page: /en/components/cascader/ -->

# Cascader

Hierarchical option selection with single, multiple and path models.

```ts
import type { CascaderProps, CascaderInstance } from "@cedar-design/ui";
```

`empty-value` accepts explicit `null` (or `() => null`). Clearing publishes null unchanged; omitted values preserve the existing default. Editors render null as blank without converting ordinary empty-string input to null. In popup editing, clearing changes the draft; confirm commits it and cancel preserves the original model.

The candidate `options` prop accepts an array or `(query, { signal }) => array/Promise`. Components own loading, cancellation and stale results, and emit load-error on failure. Choice groups initialize with an empty query; searchable fields load when queries change. Root tree loaders remain independent of existing load-more child loading.

## Reading direction

Inherits source dir. Child columns, expansion icons and separators follow reading direction. Horizontal keys enter loaded children or return to the parent in the visible direction, skipping disabled children; vertical keys retain logical order. Search preserves native horizontal caret editing. Path and multiple-value arrays are not reversed. Clearing the last value while closed resets navigation before reopening.

## Basic examples

### Basic usage

Example source: src/cascader/__demos__/basic.vue

```vue
<template>
  <c-space direction="column" size="lg">
    <c-cascader v-model="value" :options="options" placeholder="请选择地区" />
    <p role="status">当前值：{{ value ?? '未选择' }}</p>
  </c-space>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import type { CascaderProps } from '@cedar-design/ui'

const value = ref<CascaderProps['modelValue']>()

const options = [
  {
    value: 'beijing',
    label: 'Beijing',
    children: [
      {
        value: 'chaoyang',
        label: 'ChaoYang',
        children: [
          {
            value: 'datunli',
            label: 'Datunli',
          },
        ],
      },
      {
        value: 'haidian',
        label: 'Haidian',
      },
      {
        value: 'dongcheng',
        label: 'Dongcheng',
      },
      {
        value: 'xicheng',
        label: 'Xicheng',
        children: [
          {
            value: 'jinrongjie',
            label: 'Jinrongjie',
          },
          {
            value: 'tianqiao',
            label: 'Tianqiao',
          },
        ],
      },
    ],
  },
  {
    value: 'shanghai',
    label: 'Shanghai',
    children: [
      {
        value: 'huangpu',
        label: 'Huangpu',
      },
    ],
  },
]
</script>
```

## Appearance and states

### Appearance configuration comparison

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration | Purpose                                                                             | Related examples                                   |
| ------------- | ----------------------------------------------------------------------------------- | -------------------------------------------------- |
| `options`     | Tree options; leaf values must be unique in scalar mode; paths distinguish branches | Appearance configuration comparison, Control Sizes |
| `clearable`   | Allow clearing; preserve disabled selections                                        | Appearance configuration comparison, Control Sizes |
| `size`        | Supports all five sizes; inherits group/form settings                               | Control Sizes                                      |
| `variant`     | filled, outline, standard; inherits InputGroup                                      | Control Sizes                                      |
| `placeholder` | Placeholder                                                                         | Control Sizes                                      |
| `multiple`    | Multiple selection; enables search by default                                       | Control Sizes                                      |

<!-- demo-config-notes:end -->

Choose an axis to compare its available values with the same content and model. Other settings remain unchanged while comparing.

Example source: src/cascader/__demos__/appearance-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref("shanghai");
const options = [
  {
    label: "华东",
    value: "east",
    children: [
      { label: "上海", value: "shanghai" },
      { label: "杭州", value: "hangzhou" },
    ],
  },
];
const __demoAppearance = __demoReactive({ variant: "filled", size: "md" });

import { computed as demoComputed, ref as demoRef } from 'vue'
const demoCompareFields = [{"name":"variant","values":["filled","outline","standard"]},{"name":"size","values":["xs","sm","md","lg","xl"]}]
const demoCompareAxis = demoRef("variant")
const demoComparedOptions = demoComputed(() => demoCompareFields.find(field => field.name === demoCompareAxis.value)?.values ?? [])
</script>
<template>
  <c-space direction="column" :size="16">
    <c-form layout="vertical">
      <c-form-item layout="vertical" size="sm" label="variant">
        <c-radio-group
          v-model="__demoAppearance['variant']"
          aria-label="variant"
          :options="[
            { label: 'filled', value: 'filled' },
            { label: 'outline', value: 'outline' },
            { label: 'standard', value: 'standard' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
      <c-form-item layout="vertical" size="sm" label="size">
        <c-radio-group
          v-model="__demoAppearance['size']"
          aria-label="size"
          :options="[
            { label: 'xs', value: 'xs' },
            { label: 'sm', value: 'sm' },
            { label: 'md', value: 'md' },
            { label: 'lg', value: 'lg' },
            { label: 'xl', value: 'xl' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
    </c-form>
    <p class="demo-config-comparison-hint"><span lang="zh-CN">选择一个对比维度；其他配置和内容保持一致。输入类示例共享同一个值，便于比较外观。</span><span lang="en-US">Compare one dimension while keeping the other settings and content identical. Input specimens share the same value.</span></p>
<c-radio-group v-model="demoCompareAxis" aria-label="Compare configuration" :options="demoCompareFields.map(field => ({ label: field.name, value: field.name }))" />
<div class="demo-config-comparison">
<section v-for="sample in demoComparedOptions" :key="String(sample)">
<p><code>{{ demoCompareAxis }}={{ sample }}</code></p>
<c-cascader
      v-model="value"
      :options="options"
      clearable
      v-bind="{ ...__demoAppearance, [demoCompareAxis]: sample }"
    ></c-cascader>
</section>
</div>
  </c-space>
</template>

<style scoped>
.demo-config-comparison { display: grid; grid-template-columns: repeat(auto-fit, minmax(min(100%, 220px), 1fr)); gap: 20px; min-width: 0; max-width: 100%; }
.demo-config-comparison > section { min-width: 0; }
.demo-config-comparison p { margin: 0 0 8px; }
html:not([lang='en-US']) .demo-config-comparison-hint > [lang='en-US'],
html[lang='en-US'] .demo-config-comparison-hint > [lang='zh-CN'] { display: none; }
</style>
```

### Control Sizes

- `size`: The size of the select
- `variant`: Selects the visual variant.
- `options`: Options for cascader
- `placeholder`: Placeholder

Example source: src/field-decorator/__demos__/control-sizes.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
const sizes = ["xs", "sm", "md", "lg", "xl"] as const;
const variants = ["outline", "filled", "standard"] as const;
const size = ref<(typeof sizes)[number]>("md");
const variant = ref<(typeof variants)[number]>("outline");
const options = [
  { value: "beijing", label: "Beijing" },
  { value: "shanghai", label: "Shanghai" },
];
const cascaderOptions = [{ value: "china", label: "China", children: options }];

const inputValue = ref("Beijing");
const selectValue = ref("beijing");
const cascaderValue = ref("beijing");
const selectMultiple = ref(["beijing", "shanghai"]);
const cascaderMultiple = ref(["beijing", "shanghai"]);
const selectOverflow = ref(["long", "beijing", "shanghai"]);
const cascaderOverflow = ref(["long", "beijing", "shanghai"]);
const selectedOptions = [
  ...options,
  {
    value: "long",
    label:
      "A very long selected option label for overflow comparison — full text preview keeps the selected value unchanged.",
  },
];
const selectedCascaderOptions = [
  { value: "china", label: "China", children: selectedOptions },
];
function resetSelections() {
  inputValue.value = "Beijing";
  selectValue.value = "beijing";
  cascaderValue.value = "beijing";
  selectMultiple.value = ["beijing", "shanghai"];
  cascaderMultiple.value = ["beijing", "shanghai"];
  selectOverflow.value = ["long", "beijing", "shanghai"];
  cascaderOverflow.value = ["long", "beijing", "shanghai"];
}
</script>
<template>
  <section
    aria-label="Form control size comparison"
    class="control-size-comparison"
  >
    <c-space wrap :size="12">
      <c-radio-group v-model="size" aria-label="Comparison size">
        <c-radio v-for="item in sizes" :key="item" :value="item">{{
          item
        }}</c-radio>
      </c-radio-group>
      <c-radio-group v-model="variant" aria-label="Comparison variant">
        <c-radio v-for="item in variants" :key="item" :value="item">{{
          item
        }}</c-radio>
      </c-radio-group>
    </c-space>
    <div class="control-size-comparison__grid">
      <div data-control="Input">
        <p>Input</p>
        <c-input :size="size" :variant="variant" placeholder="Input" />
      </div>
      <div data-control="Button">
        <p>Button</p>
        <c-button :size="size" variant="outline">Button</c-button>
      </div>
      <div data-control="Select">
        <p>Select</p>
        <c-select
          :size="size"
          :variant="variant"
          :options="options"
          placeholder="Select"
        />
      </div>
      <div data-control="Date">
        <p>Date</p>
        <c-date :size="size" :variant="variant" placeholder="Date" />
      </div>
      <div data-control="Time">
        <p>Time</p>
        <c-time :size="size" :variant="variant" placeholder="Time" />
      </div>
      <div data-control="InputNumber">
        <p>InputNumber</p>
        <c-input-number :size="size" :variant="variant" placeholder="Number" />
      </div>
      <div data-control="AutoComplete">
        <p>AutoComplete</p>
        <c-auto-complete
          :size="size"
          :variant="variant"
          :options="options"
          placeholder="AutoComplete"
        />
      </div>
      <div data-control="Cascader">
        <p>Cascader</p>
        <c-cascader
          :size="size"
          :variant="variant"
          :options="cascaderOptions"
          placeholder="Cascader"
        />
      </div>
      <div data-control="DateRange">
        <p>DateRange</p>
        <c-date-range
          :size="size"
          :variant="variant"
          :placeholder="['Start', 'End']"
        />
      </div>
      <div data-control="TimeRange">
        <p>TimeRange</p>
        <c-time-range
          :size="size"
          :variant="variant"
          :placeholder="['Start', 'End']"
        />
      </div>
    </div>

    <section
      aria-label="Selected control size comparison"
      class="control-size-comparison__states"
    >
      <c-space wrap align="center" :size="12">
        <span>Selected / Clearable / Multiple — 有值、可清空与多选不换行</span>
        <span
          >Hover or focus truncated text; tap on touch screens /
          悬停或聚焦省略正文查看全文；触屏点按查看，点外部关闭</span
        >
        <c-button size="sm" variant="outline" @click="resetSelections"
          >Reset / 恢复选中值</c-button
        >
      </c-space>
      <div class="control-size-comparison__grid">
        <div data-control="InputValue">
          <p>Input · clearable</p>
          <c-input
            v-model="inputValue"
            :size="size"
            :variant="variant"
            clearable
            placeholder="Input value"
          />
        </div>
        <div data-control="ButtonReference">
          <p>Button · reference</p>
          <c-button :size="size" variant="outline">Button</c-button>
        </div>
        <div data-control="SelectValue">
          <p>Select · clearable</p>
          <c-select
            v-model="selectValue"
            :size="size"
            :variant="variant"
            :options="selectedOptions"
            clearable
            placeholder="Select value"
          />
        </div>
        <div data-control="CascaderValue">
          <p>Cascader · clearable</p>
          <c-cascader
            v-model="cascaderValue"
            :size="size"
            :variant="variant"
            :options="selectedCascaderOptions"
            clearable
            placeholder="Cascader value"
          />
        </div>
        <div data-control="SelectMultiple">
          <p>Select · multiple / nowrap</p>
          <c-select
            v-model="selectMultiple"
            :size="size"
            :variant="variant"
            :options="selectedOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Select multiple"
          />
        </div>
        <div data-control="CascaderMultiple">
          <p>Cascader · multiple / nowrap</p>
          <c-cascader
            v-model="cascaderMultiple"
            :size="size"
            :variant="variant"
            :options="selectedCascaderOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Cascader multiple"
          />
        </div>
        <div data-control="SelectOverflow">
          <p>Select · long values / nowrap</p>
          <c-select
            v-model="selectOverflow"
            edit-mode="direct"
            :size="size"
            :variant="variant"
            :options="selectedOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Select long values"
          />
        </div>
        <div data-control="CascaderOverflow">
          <p>Cascader · long values / nowrap</p>
          <c-cascader
            v-model="cascaderOverflow"
            edit-mode="direct"
            :size="size"
            :variant="variant"
            :options="selectedCascaderOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Cascader long values"
          />
        </div>
      </div>
    </section>
  </section>
</template>
<style scoped>
.control-size-comparison,
.control-size-comparison__states {
  display: grid;
  gap: 24px;
}
.control-size-comparison__grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
  align-items: start;
  gap: 24px 16px;
}
.control-size-comparison__grid > div {
  min-width: 0;
}
.control-size-comparison__grid p {
  margin: 0 0 12px;
  font-size: 14px;
  line-height: 20px;
}
.control-size-comparison__grid :deep(.c-input-number),
.control-size-comparison__grid :deep(.c-auto-complete) {
  width: 100%;
}
</style>
```

## Selection modes and paths

### Multiple

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration    | Purpose                                                                             | Related examples                    |
| ---------------- | ----------------------------------------------------------------------------------- | ----------------------------------- |
| `options`        | Tree options; leaf values must be unique in scalar mode; paths distinguish branches | Multiple, Check Strictly, Path Mode |
| `placeholder`    | Placeholder                                                                         | Multiple, Check Strictly, Path Mode |
| `multiple`       | Multiple selection; enables search by default                                       | Multiple, Check Strictly            |
| `default-value`  | Default value (uncontrolled state)                                                  | Check Strictly, Path Mode           |
| `expand-trigger` | Menu / List expansion: click or hover                                               | Check Strictly, Path Mode           |
| `check-strictly` | Allow parent selection; unlink parent/child checks                                  | Check Strictly                      |

<!-- demo-config-notes:end -->

- `options`: Options for cascader
- `placeholder`: Placeholder
- `multiple`: Whether it is a multi-selection state (The search is turned on by default in the multi-select mode)

Example source: src/cascader/__demos__/multiple.vue

```vue
<template>
  <c-space direction="column" size="lg">
    <c-cascader :options="options" :style="{ width: '320px' }" placeholder="Please select ..." multiple />
  </c-space>
</template>

<script lang="ts">
import { defineComponent } from 'vue'
export default defineComponent({
  setup() {
    const options = [
      {
        value: 'beijing',
        label: 'Beijing',
        children: [
          {
            value: 'chaoyang',
            label: 'ChaoYang',
          },
          {
            value: 'haidian',
            label: 'Haidian',
            isLeaf: true,
          },
          {
            value: 'dongcheng',
            label: 'Dongcheng',
            isLeaf: true,
          },
          {
            value: 'xicheng',
            label: 'Xicheng',
          },
        ],
      },
      {
        value: 'shanghai',
        label: 'Shanghai',
        children: [
          {
            value: 'huangpu',
            label: 'Huangpu',
            isLeaf: true,
          },
        ],
      },
    ]
    return {
      options,
    }
  },
})
</script>
```

### Check Strictly

- `options`: Options for cascader
- `placeholder`: Placeholder
- `check-strictly`: Whether to enable strict selection mode
- `default-value`: Default value (uncontrolled state)

Example source: src/cascader/__demos__/check-strictly.vue

```vue
<template>
  <c-space direction="column" size="lg">
    <c-cascader :options="options" :style="{ width: '320px' }" placeholder="Please select ..." check-strictly />
    <c-cascader
      :options="options"
      default-value="datunli"
      expand-trigger="hover"
      :style="{ width: '320px' }"
      placeholder="Please select ..."
      multiple
      check-strictly />
  </c-space>
</template>

<script lang="ts">
import { defineComponent } from 'vue'
export default defineComponent({
  setup() {
    const options = [
      {
        value: 'beijing',
        label: 'Beijing',
        children: [
          {
            value: 'chaoyang',
            label: 'ChaoYang',
            children: [
              {
                value: 'datunli',
                label: 'Datunli',
              },
            ],
          },
          {
            value: 'haidian',
            label: 'Haidian',
          },
          {
            value: 'dongcheng',
            label: 'Dongcheng',
          },
          {
            value: 'xicheng',
            label: 'Xicheng',
            children: [
              {
                value: 'jinrongjie',
                label: 'Jinrongjie',
              },
              {
                value: 'tianqiao',
                label: 'Tianqiao',
              },
            ],
          },
        ],
      },
      {
        value: 'shanghai',
        label: 'Shanghai',
        children: [
          {
            value: 'huangpu',
            label: 'Huangpu',
          },
        ],
      },
    ]
    return {
      options,
    }
  },
})
</script>
```

### Path Mode

- `options`: Options for cascader
- `placeholder`: Placeholder
- `path-mode`: Whether the value is a path
- `default-value`: Default value (uncontrolled state)

Example source: src/cascader/__demos__/path-mode.vue

```vue
<template>
  <c-space direction="column" size="lg">
    <c-cascader
      :options="options"
      :style="{ width: '320px' }"
      placeholder="Please select ..."
      path-mode
      @change="handleChange" />
    <c-cascader
      :options="options"
      default-value="datunli"
      expand-trigger="hover"
      :style="{ width: '320px' }"
      placeholder="Please select ..."
      path-mode
      @change="handleChange" />
  </c-space>
</template>

<script lang="ts">
import { defineComponent } from 'vue'
export default defineComponent({
  setup() {
    const handleChange = (path: any) => {
      console.log(path)
    }
    const options = [
      {
        value: 'beijing',
        label: 'Beijing',
        children: [
          {
            value: 'chaoyang',
            label: 'ChaoYang',
            children: [
              {
                value: 'datunli',
                label: 'Datunli',
              },
            ],
          },
          {
            value: 'haidian',
            label: 'Haidian',
          },
          {
            value: 'dongcheng',
            label: 'Dongcheng',
          },
          {
            value: 'xicheng',
            label: 'Xicheng',
            children: [
              {
                value: 'jinrongjie',
                label: 'Jinrongjie',
              },
              {
                value: 'tianqiao',
                label: 'Tianqiao',
              },
            ],
          },
        ],
      },
      {
        value: 'shanghai',
        label: 'Shanghai',
        children: [
          {
            value: 'huangpu',
            label: 'Huangpu',
          },
        ],
      },
    ]
    return {
      options,
      handleChange,
    }
  },
})
</script>
```

### Clearable

- `options`: Options for cascader
- `placeholder`: Placeholder
- `clearable`: Whether to allow clear

Example source: src/cascader/__demos__/clearable.vue

```vue
<template>
  <c-cascader :options="options" v-model="value" placeholder="Please select ..." clearable />
</template>

<script lang="ts">
import { ref, defineComponent } from 'vue'
export default defineComponent({
  setup() {
    const value = ref('datunli')

    const options = [
      {
        value: 'beijing',
        label: 'Beijing',
        children: [
          {
            value: 'chaoyang',
            label: 'ChaoYang',
            children: [
              {
                value: 'datunli',
                label: 'Datunli',
              },
            ],
          },
          {
            value: 'haidian',
            label: 'Haidian',
          },
          {
            value: 'dongcheng',
            label: 'Dongcheng',
          },
          {
            value: 'xicheng',
            label: 'Xicheng',
            children: [
              {
                value: 'jinrongjie',
                label: 'Jinrongjie',
              },
              {
                value: 'tianqiao',
                label: 'Tianqiao',
              },
            ],
          },
        ],
      },
      {
        value: 'shanghai',
        label: 'Shanghai',
        children: [
          {
            value: 'huangpu',
            label: 'Huangpu',
          },
        ],
      },
    ]
    return {
      value,
      options,
    }
  },
})
</script>
```

## Search and presentation

### Filterable

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration    | Purpose                                                                             | Related examples                         |
| ---------------- | ----------------------------------------------------------------------------------- | ---------------------------------------- |
| `options`        | Tree options; leaf values must be unique in scalar mode; paths distinguish branches | Filterable, Case Sensitive, Format Label |
| `placeholder`    | Placeholder                                                                         | Filterable, Case Sensitive, Format Label |
| `filterable`     | Enable search                                                                       | Filterable, Case Sensitive               |
| `case-sensitive` | Case-sensitive built-in filtering; custom filters take priority                     | Case Sensitive                           |
| `format-label`   | Format selected labels; use label slot for VNodes                                   | Format Label                             |

<!-- demo-config-notes:end -->

- `options`: Options for cascader
- `placeholder`: Placeholder
- `filterable`: Whether to allow searching

Example source: src/cascader/__demos__/filterable.vue

```vue
<template>
  <c-space direction="column" size="lg">
    <c-cascader :options="options" placeholder="Please select ..." filterable />
  </c-space>
</template>

<script lang="ts">
import { defineComponent } from 'vue'
export default defineComponent({
  setup() {
    const options = [
      {
        value: 'beijing',
        label: 'Beijing',
        children: [
          {
            value: 'chaoyang',
            label: 'ChaoYang',
            children: [
              {
                value: 'datunli',
                label: 'Datunli',
              },
            ],
          },
          {
            value: 'haidian',
            label: 'Haidian',
          },
          {
            value: 'dongcheng',
            label: 'Dongcheng',
          },
          {
            value: 'xicheng',
            label: 'Xicheng',
            children: [
              {
                value: 'jinrongjie',
                label: 'Jinrongjie',
              },
              {
                value: 'tianqiao',
                label: 'Tianqiao',
              },
            ],
          },
        ],
      },
      {
        value: 'shanghai',
        label: 'Shanghai',
        children: [
          {
            value: 'huangpu',
            label: 'Huangpu',
          },
        ],
      },
    ]
    return {
      options,
    }
  },
})
</script>
```

### Case Sensitive

- `options`: Options for cascader
- `filterable`: Whether to allow searching
- `placeholder`: Placeholder

Example source: src/cascader/__demos__/case-sensitive.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const value = ref<string[]>([])
const caseSensitive = ref(false)
const options = [{ value: 'fruit', label: 'Fruit', children: [{ value: 'apple', label: 'Apple' }] }]
</script>
<template>
  <c-space direction="column" fill>
    <c-space><c-switch v-model="caseSensitive" /><span>区分大小写</span></c-space>
    <c-cascader v-model="value" :options="options" :case-sensitive="caseSensitive" filterable placeholder="输入 fruit、Fruit、apple 或 Apple" />
    <p>保留原有路径标签匹配。启用区分大小写后，输入 fruit 不匹配 Fruit。</p>
  </c-space>
</template>
```

### Format Label

- `options`: Options for cascader
- `placeholder`: Placeholder
- `format-label`: Format display content

Example source: src/cascader/__demos__/format-label.vue

```vue
<template>
  <c-space direction="column" size="lg">
    <c-cascader :options="options" :style="{ width: '320px' }" placeholder="Please select ..." :format-label="format" />
  </c-space>
</template>

<script lang="ts">
import { defineComponent } from 'vue'
export default defineComponent({
  setup() {
    const options = [
      {
        value: 'beijing',
        label: 'Beijing',
        children: [
          {
            value: 'chaoyang',
            label: 'ChaoYang',
            children: [
              {
                value: 'datunli',
                label: 'Datunli',
              },
            ],
          },
          {
            value: 'haidian',
            label: 'Haidian',
          },
          {
            value: 'dongcheng',
            label: 'Dongcheng',
          },
          {
            value: 'xicheng',
            label: 'Xicheng',
            children: [
              {
                value: 'jinrongjie',
                label: 'Jinrongjie',
              },
              {
                value: 'tianqiao',
                label: 'Tianqiao',
              },
            ],
          },
        ],
      },
      {
        value: 'shanghai',
        label: 'Shanghai',
        children: [
          {
            value: 'huangpu',
            label: 'Huangpu',
          },
        ],
      },
    ]
    interface Option {
      value: string
      label: string
    }

    const format = (options: Option[]) => {
      const labels = options.map((option) => option.label)
      return labels.join('-')
    }
    return {
      options,
      format,
    }
  },
})
</script>
```

## Interaction and control

### Interaction state comparison

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration | Purpose                                                                             | Related examples             |
| ------------- | ----------------------------------------------------------------------------------- | ---------------------------- |
| `options`     | Tree options; leaf values must be unique in scalar mode; paths distinguish branches | Interaction state comparison |
| `clearable`   | Allow clearing; preserve disabled selections                                        | Interaction state comparison |
| `disabled`    | Whether disabled                                                                    | Interaction state comparison |

<!-- demo-config-notes:end -->

Toggle the state, interact with the component, and restore editing using the controls outside the specimen. Error appearance alone does not run validation.

Example source: src/cascader/__demos__/state-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref("shanghai");
const options = [
  {
    label: "华东",
    value: "east",
    children: [
      { label: "上海", value: "shanghai" },
      { label: "杭州", value: "hangzhou" },
    ],
  },
];
const __demoState = __demoReactive({
  disabled: false,
  readonly: false,
  error: false,
});
</script>
<template>
  <c-space direction="column" :size="16">
    <c-space wrap>
      <c-checkbox v-model="__demoState['disabled']">disabled</c-checkbox>
      <c-checkbox v-model="__demoState['readonly']">readonly</c-checkbox>
      <c-checkbox v-model="__demoState['error']">error</c-checkbox>
    </c-space>
    <c-cascader
      v-model="value"
      :options="options"
      clearable
      v-bind="__demoState"
    ></c-cascader>
  </c-space>
</template>
```

## Configuration and composition

### Passthrough Options

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration         | Purpose                                                                                                                          | Related examples                         |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
| `edit-mode`           | Presentation                                                                                                                     | Passthrough Options, Copying and editing |
| `options`             | Tree options; leaf values must be unique in scalar mode; paths distinguish branches                                              | Passthrough Options, Copying and editing |
| `trigger-props`       | Menu Trigger props; field owns open state                                                                                        | Passthrough Options                      |
| `open-trigger-target` | Pointer opening target: the whole field or only the suffix icon. Explicit keyboard opening and controlled open remain available. | Copying and editing                      |
| `filterable`          | Enable search                                                                                                                    | Copying and editing                      |

<!-- demo-config-notes:end -->

- `open`: Whether to show the dropdown
- `options`: Options for cascader
- `trigger-props`: Trigger props of the drop-down menu

Example source: src/cascader/__demos__/passthrough-options.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import type { CascaderTriggerOptions } from "@cedar-design/ui";
const open = ref(false);
const triggerOptions: CascaderTriggerOptions = {
  placement: "top-start",
  popupOffset: 8,
  popupContainer: false,
};
const options = [
  {
    value: "fruit",
    label: "水果",
    children: [{ value: "apple", label: "Apple" }],
  },
];
</script>
<template>
  <c-space direction="column" fill>
    <c-button @click="open = !open">{{
      open ? "关闭面板" : "打开面板"
    }}</c-button>
    <c-cascader
      edit-mode="direct"
      v-model:open="open"
      :options="options"
      :trigger-props="triggerOptions"
      aria-label="透传配置示例"
    />
    <p role="status">顶层 open：{{ open }}；嵌套配置：向上展开并调整偏移。</p>
  </c-space>
</template>
```

### Copying and editing

With open-trigger-target="icon", use the input area to edit or copy and the suffix button to open. Existing text remains copyable when editing or search is disabled.

Example source: src/cascader/__demos__/open-trigger-target.en-US.vue

```vue
<template>
  <c-space direction="column">
    <c-radio-group
      v-model="target"
      :options="[
        { label: 'Whole field', value: 'field' },
        { label: 'Suffix icon only', value: 'icon' },
      ]"
    />
    <label><c-switch v-model="editable" /> Allow editing / search</label>
    <c-cascader
      v-model="value"
      edit-mode="direct"
      :open-trigger-target="target"
      :filterable="editable"
      :options="[
        { value: 'a', label: 'Alpha' },
        { value: 'b', label: 'Beta' },
      ]"
    />
    <p>
      Disable editing to copy existing text. In icon mode, editing does not open
      the panel.
    </p>
  </c-space>
</template>
<script setup lang="ts">
import { ref } from "vue";
const target = ref<"field" | "icon">("icon");
const editable = ref(true);
const value = ref("a");
</script>
```

## Async loading and value resolution

### Loading

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration | Purpose                                                                             | Related examples                  |
| ------------- | ----------------------------------------------------------------------------------- | --------------------------------- |
| `options`     | Tree options; leaf values must be unique in scalar mode; paths distinguish branches | Loading, Load More, Async Devices |
| `placeholder` | Placeholder                                                                         | Loading, Load More, Async Devices |
| `loading`     | Loading state; blocks selection and confirmation                                    | Loading, Async Devices            |
| `load-more`   | Load children asynchronously; call done(children), or done() to allow retry         | Load More                         |
| `path-mode`   | Return a complete path instead of a node value                                      | Async Devices                     |
| `filterable`  | Enable search                                                                       | Async Devices                     |

<!-- demo-config-notes:end -->

- `options`: Options for cascader
- `placeholder`: Placeholder
- `loading`: Whether it is loading state

Example source: src/cascader/__demos__/loading.vue

```vue
<template>
  <c-space direction="column" size="lg">
    <c-cascader :options="[]" :style="{ width: '320px' }" placeholder="Please select ..." loading />
  </c-space>
</template>

<script lang="ts">
import { defineComponent } from 'vue'
export default defineComponent({
  })
</script>
```

### Load More

- `options`: Options for cascader
- `placeholder`: Placeholder
- `load-more`: Data lazy loading function, open the lazy loading function when it is passed in

Example source: src/cascader/__demos__/load-more.vue

```vue
<template>
  <c-space direction="column" size="lg">
    <c-cascader :options="options" :style="{ width: '320px' }" placeholder="Please select ..." :load-more="loadMore" />
  </c-space>
</template>

<script lang="ts">
import { defineComponent } from 'vue'
export default defineComponent({
  setup() {
    const options = [
      {
        value: 'beijing',
        label: 'Beijing',
        children: [
          {
            value: 'chaoyang',
            label: 'ChaoYang',
          },
          {
            value: 'haidian',
            label: 'Haidian',
            isLeaf: true,
          },
          {
            value: 'dongcheng',
            label: 'Dongcheng',
            isLeaf: true,
          },
          {
            value: 'xicheng',
            label: 'Xicheng',
          },
        ],
      },
      {
        value: 'shanghai',
        label: 'Shanghai',
        children: [
          {
            value: 'huangpu',
            label: 'Huangpu',
            isLeaf: true,
          },
        ],
      },
    ]
    const loadMore = (option: any, done: any) => {
      window.setTimeout(() => {
        const nodes = [
          {
            value: `${option.value}-option1`,
            label: `${option.label}-Option1`,
            isLeaf: true,
          },
          {
            value: `${option.value}-option2`,
            label: `${option.label}-Option2`,
            isLeaf: true,
          },
        ]
        done(nodes)
      }, 2000)
    }

    return {
      options,
      loadMore,
    }
  },
})
</script>
```

### Async Devices

- `options`: Options for cascader
- `loading`: Whether it is loading state
- `path-mode`: Whether the value is a path
- `filterable`: Whether to allow searching

Example source: src/cascader/__demos__/async-devices.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const value = ref(['factory', 'device-2'])
const options = ref<Record<string, unknown>[]>([])
const loading = ref(false)
async function load() {
  loading.value = true
  try {
    options.value = await Promise.resolve([
      { id: 'factory', name: '工厂', nodes: [
        { id: 'device-1', name: '设备一' },
        { id: 'device-2', name: '设备二' },
        { id: 'device-3', name: '检修设备', disabled: true },
      ] },
    ])
  } finally { loading.value = false }
}
</script>
<template>
  <c-space direction="column" :size="16">
    <c-button @click="load">加载设备树</c-button>
    <c-cascader v-model="value" :options="options" :loading="loading" path-mode filterable clearable
      :field-names="{ label: 'name', value: 'id', children: 'nodes' }" placeholder="选择设备路径" />
    <p>已提交路径：{{ value }}。标签与 ID 分离，异步加载后自动回显。</p>
  </c-space>
</template>
```

### Shared field loading

`loading` displays the shared field indicator. `loading-mode` is `default` (indicator) or `line` (an indeterminate bottom line); it defaults to `default`. Rendering belongs to FieldDecorator. Loading does not implicitly disable editing or change readonly. Set those states separately.

## API

### Empty values and reading placeholders

`empty-values` recognizes empty data; `empty-value` keeps existing clear output. `empty-text` defaults to `'-'` under `read-pretty`, with Field > FormItem > Form precedence and custom read slots first. With explicit empty-values, built-in required uses the policy; custom validators receive original data. See the [shared guide](llms/en-US/guide/empty-values.md).

| Prop         | Type               | Default and scope                                                           |
| ------------ | ------------------ | --------------------------------------------------------------------------- |
| empty-values | readonly unknown[] | Field > FormItem > Form > component-family default; replaces the whole list |
| empty-text   | string             | Field > FormItem > Form > '-'; explicit '' is valid                         |

These props belong to field presentation; pure panels do not gain reading mode. Form and FormItem provide inherited settings. The existing empty-value type and clear fallback remain component-specific.

### Cascader props

Use `v-model`, `v-model:open` and `v-model:input-value` for controlled state. Clear values are `''` for single selection and `[]` for multiple selection. Select uses `undefined` when an actual empty-string option exists.

| Prop                                    | Description                                                                                                                                      | Type                                                          | Default                         |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------- | ------------------------------- |
| `open-trigger-target`                   | Pointer opening target: the whole field or only the suffix icon. Explicit keyboard opening and controlled open remain available.                 | `'field' \| 'icon'`                                           | `'field'`                       |
| `model-value / default-value`           | Controlled value / uncontrolled initial value                                                                                                    | `Value`                                                       | `Single: ''; multiple: []`      |
| `open / default-open`                   | Controlled / initial open state                                                                                                                  | `boolean`                                                     | `undefined / false`             |
| `input-value / default-input-value`     | Search text, independent of selected values                                                                                                      | `string`                                                      | `undefined / ''`                |
| `multiple`                              | Multiple selection; enables search by default                                                                                                    | `boolean`                                                     | `false`                         |
| `size`                                  | Supports all five sizes; inherits group/form settings                                                                                            | `ComponentSize`                                               | `md`                            |
| `variant`                               | filled, outline, standard; inherits InputGroup                                                                                                   | `FormControlVariant`                                          | `filled`                        |
| `disabled / readonly / error`           | Inherits form state unless explicitly overridden                                                                                                 | `boolean`                                                     | `undefined`                     |
| `placeholder`                           | Placeholder                                                                                                                                      | `string`                                                      | `—`                             |
| `hint / line`                           | Floating hint / standard variant underline                                                                                                       | `boolean`                                                     | `true`                          |
| `text-color / focus-color / blur-color` | Field colors                                                                                                                                     | `string`                                                      | `—`                             |
| `loading`                               | Loading state; blocks selection and confirmation                                                                                                 | `boolean`                                                     | `false`                         |
| `show-tags`                             | Show tags; false displays separated text                                                                                                         | `boolean`                                                     | `true`                          |
| `separator`                             | Separator when show-tags=false                                                                                                                   | `string`                                                      | `,`                             |
| `text-align`                            | Text alignment: left / center / right. Inherits FormItem content-align when unset; standalone fields default to inline start                             | `'left' \| 'center' \| 'right'`                               | `-`                             |
| `max-tag-count`                         | Maximum visible tags; 0 means unlimited                                                                                                          | `number`                                                      | `0`                             |
| `tag-nowrap`                            | Keep tags on one line with ellipsis and preserved removal icons; overflow scrolls horizontally; hover, focus or tap truncated text to preview it | `boolean`                                                     | `false`                         |
| `popup-container`                       | Selector, element, element resolver, or false for inline rendering                                                                               | `PopupContainer`                                              | `—`                             |
| `trigger-props`                         | Menu Trigger props; field owns open state                                                                                                        | `TriggerProps`                                                | `—`                             |
| `virtual-list-props`                    | Pass the virtual list attribute, pass in this parameter to turn on virtual scrolling [VirtualListProps](#VirtualListProps)                       | `VirtualListProps`                                            | `—`                             |
| `search-delay`                          | Search debounce delay in ms                                                                                                                      | `number`                                                      | `500`                           |
| `format-label`                          | Format selected labels; use label slot for VNodes                                                                                                | `function`                                                    | `—`                             |
| `clearable`                             | Allow clearing; preserve disabled selections                                                                                                     | `boolean`                                                     | `false`                         |
| `options`                               | Tree options; leaf values must be unique in scalar mode; paths distinguish branches                                                              | `CascaderOption[]` / `(query, { signal }) => Array / Promise` | `undefined`                     |
| `field-names`                           | Map value, label, disabled, children, isLeaf, tagProps, render                                                                                   | `CascaderFieldNames`                                          | `—`                             |
| `path-mode`                             | Return a complete path instead of a node value                                                                                                   | `boolean`                                                     | `false`                         |
| `check-strictly`                        | Allow parent selection; unlink parent/child checks                                                                                               | `boolean`                                                     | `false`                         |
| `filterable`                            | Enable search                                                                                                                                    | `boolean`                                                     | `Single: false; multiple: true` |
| case-sensitive                          | Case-sensitive built-in filtering; custom filters take priority                                                                                  | boolean                                                       | false                           |
| `filter-option`                         | Receives query and raw node                                                                                                                      | `(input, option) => boolean`                                  | `—`                             |
| `expand-trigger`                        | Menu / List expansion: click or hover                                                                                                            | `string`                                                      | `click`                         |
| `expand-child`                          | Expand to first child                                                                                                                            | `boolean`                                                     | `false`                         |
| `load-more`                             | Load children asynchronously; call done(children), or done() to allow retry                                                                      | `(option, done) => void`                                      | `—`                             |
| `fallback-option`                       | Display unresolved values                                                                                                                        | `boolean or (value) => string`                                | `true`                          |
| `search-option-only-label`              | Show node label only in search results                                                                                                           | `boolean`                                                     | `false`                         |
| `auto-fit-popup-width`                  | Match Menu width to field                                                                                                                        | `boolean`                                                     | `false`                         |
| `edit-mode`                             | Presentation                                                                                                                                     | `menu`                                                        | `menu`                          |

### Events and methods

- `update:modelValue`, `change(value)`: emitted on commit, not while editing a draft.
- `update:open`, `open-change(open)`: request an expanded-state change.
- `update:inputValue`, `input-value-change(text)`, `search(text)`: search state.
- `focus(event)`, `blur(event)`, `clear(event)`: native field events; only the field owner notifies Form.
- Methods: `focus()`, `blur()`.

### Slots and option data

Use `label({ data })` for custom `selected` labels; `selected` replaces the whole selection area. Also supports `prefix`, `suffix`, `clear-icon({ clear })`, `arrow-icon`, `loading-icon`, `search-icon`, `empty`, and `option({ data })`.

Option `label` is searchable plain text. Use `render` or the `option` slot for custom `option` content, and `format-label` or `label` slot for selected content. Values identify selections; labels never do. `disabled` blocks selection/removal, and `tagProps` customizes selected tags.

### `<CascaderPanel>` Props

| Parameter                 | Description                                                                                                      | Type                                                                                                                                                               |         Default         |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :---------------------: |
| path-mode                 | Return a complete path instead of a node value                                                                   | `boolean`                                                                                                                                                          |         `false`         |
| multiple                  | Multiple selection; enables search by default                                                                    | `boolean`                                                                                                                                                          |         `false`         |
| model-value **(v-model)** | Bound value                                                                                                      | `string\| number\| Record<string, any>\| (    \| string    \| number    \| Record<string, any>    \| (string \| number \| Record<string, any>)[]  )[]\| undefined` |           `-`           |
| default-value             | Default value (uncontrolled state)                                                                               | `string\| number\| Record<string, any>\| (    \| string    \| number    \| Record<string, any>    \| (string \| number \| Record<string, any>)[]  )[]\| undefined` | `'' \| undefined \| []` |
| options                   | Tree options; leaf values must be unique in scalar mode; paths distinguish branches                              | `CascaderOption[]` / `(query, { signal }) => Array / Promise`                                                                                                      |       `undefined`       |
| expand-trigger            | Menu / List expansion: click or hover                                                                            | `string`                                                                                                                                                           |        `'click'`        |
| check-strictly            | Allow parent selection; unlink parent/child checks                                                               | `boolean`                                                                                                                                                          |         `false`         |
| load-more                 | Load children asynchronously; call done(children), or done() to allow retry                                      | `(  option: CascaderOption,  done: (children?: CascaderOption[]) => void) => void`                                                                                 |           `-`           |
| field-names               | Customize fields in `CascaderOption`; when option `value` is an object, `value` is also used as the key property | `CascaderFieldNames`                                                                                                                                               |           `-`           |
| expand-child              | Expand to first child                                                                                            | `boolean`                                                                                                                                                          |         `false`         |

### `<CascaderPanel>` Events

| Event  | Description                             | Arguments                                                                              |
| ------ | --------------------------------------- | -------------------------------------------------------------------------------------- |
| change | Emitted when the selected value changes | value: `string \| number \| (string \| number \| (string \| number)[])[] \| undefined` |

### `<CascaderPanel>` Slots

| Slot  |                   Description                   | Arguments |
| ----- | :---------------------------------------------: | --------- |
| empty | Content displayed when no options are available | -         |

### CascaderOption

| Parameter | Description                           | Type                                      | Default |
| --------- | ------------------------------------- | ----------------------------------------- | :-----: |
| value     | Option value                          | `string \| number \| Record<string, any>` |   `-`   |
| label     | Option text                           | `string`                                  |   `-`   |
| render    | Custom render function                | `RenderFunction`                          |   `-`   |
| disabled  | Whether disabled                      | `boolean`                                 | `false` |
| tagProps  | Property used for the displayed label | `TagProps`                                |   `-`   |
| children  | Child options                         | `CascaderOption[]`                        |   `-`   |
| isLeaf    | Whether this is a leaf node           | `boolean`                                 | `false` |

## Type definitions

The component exports the following types

```ts
import type { CascaderProps } from "@cedar-design/ui";
```

### Form field presentation and confirmation

This component supports `edit-mode` with field > FormItem > Form precedence. When unset, it defaults to `direct` and preserves `direct` editing. Supported values: `direct / click / dblclick`. Non-`direct` modes open the editor through the field value trigger and keep one draft; v-model updates only after confirmation. Cancel, reset or enabling readPretty discards the draft.

Cedar uses edit-mode="click" / "dblclick" to open an editor popup near the field. Enter/F2 also opens it; cancel/Escape discards the draft, and confirmation commits it. readPretty is an independent reading setting, separate from readonly and disabled.

`before-commit(value, { previousValue, signal })` can reject an overlay save. FormItem validates the candidate first and keeps the editor open on failure. `open / default-open / update:open` control the editor. Use `#read="{ value, text }"` to customize display. See the full field comparison in Form.

Field editing uses edit-mode: Cedar supports direct/click/dblclick, and Maple supports direct/popup. The old menu/list/picker editing values are not retained. Popup editors reuse the existing option index, search, asynchronous loading and virtual-list algorithms.

`read-pretty` is an independent boolean alongside `readonly` and `disabled`. It inherits from field to FormItem to Form; explicit `false` overrides the parent. The default is `false`. Reading mode renders no editor.

### Single-selection checkmark variables

| Variable                        | Default                             |
| ------------------------------- | ----------------------------------- |
| `--c-cascader-item-check-color` | `var(--c-sys-color-action-primary)` |
| `--c-cascader-item-check-size`  | `var(--c-sys-font-size-md)`         |

### Built-in search fields

`searchFields` / `search-fields` is a readonly `('label' | 'value')[]`, defaulting to `['label']`. Multiple fields use OR matching, case-insensitive by default. `['value', 'label']` searches codes and names; fieldNames maps semantic fields to business fields. An empty array matches no items for a nonempty query. Values are compared as strings; object traversal, object values and pinyin matching require a custom callback. A custom callback takes precedence and decides case handling itself. Remote results use the existing protocol for disabling local filtering. Cascader retains path semantics and checks the configured fields on each path node.

## Configuring the cleared value

`empty-value` / `emptyValue` sets the model value produced by clearing. It accepts a value in the component model type or a zero-argument factory. Omission preserves the existing default; use `() => undefined` to distinguish omission from returning undefined. Arrays are shallow-copied on every clear; selected items that cannot be cleared remain. It does not redefine emptiness, alter Form reset defaults or treat 0/false as universally empty.

`empty-value` accepts explicit `null` (or `() => null`). Clearing publishes `null` unchanged; omitted values preserve the existing default. Editors render `null` as blank without converting ordinary empty-string input to `null`. In popup editing, clearing changes the draft; confirm commits it and cancel preserves the original model.

The `options` prop accepts an array or `(query, { signal }) => array/Promise`. The component manages loading, cancellation and stale-result isolation; failures emit load-error. Single/multiple groups initialize with an empty-string query, searchable fields reload when the query changes, and root loading for tree fields remains independent of existing load-more child loading.

---

Document: llms/en-US/components/checkbox.md

<!-- Source: src/checkbox/README.en-US.md; locale: en-US; page: /en/components/checkbox/ -->

# Checkbox

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Reading direction

Checkbox labels and groups follow source dir without reversing value arrays. Space keeps its toggle meaning; disabled and readonly behavior remains effective. Changing direction does not select or clear options.

## Basic examples

### Basic usage

Preview configuration: `value="1"`.

Example source: src/checkbox/__demos__/basic.vue

```vue
<template>
  <c-checkbox value="1">Option 1</c-checkbox>
</template>
<script lang="ts">
import { defineComponent } from 'vue'
export default defineComponent({
  })
</script>
```

## Groups and layout

### Option declaration comparison

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration | Purpose                                                   | Related examples                    |
| ------------- | --------------------------------------------------------- | ----------------------------------- |
| `value`       | Option identifier in array/group mode                     | Option declaration comparison, Grid |
| `disabled`    | Disabled state; inherits from the form/group when omitted | Grid                                |

<!-- demo-config-notes:end -->

Compare child-component declarations with options data. Both use a group model; field mapping and asynchronous data are separate.

Example source: src/checkbox/__demos__/group-declaration-comparison.vue

```vue
<script setup lang="ts">
import { ref } from "vue"
import { proxyRefs as demoProxyRefs } from 'vue'

const scene2 = demoProxyRefs((() => {


    const value1 = ref(['Plain 1'])


    const plainOptions = ['Plain 1', 'Plain 2', 'Plain 3']



    const value2 = ref(['1'])


    const options = [
      { label: 'Option 1', value: '1' },
      { label: 'Option 2', value: '2' },
      { label: 'Option 3', value: '3', disabled: true },
    ]
return { value1, plainOptions, value2, options }
})())
</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="checkbox-group">
    <h4><span lang="zh-CN">复选框组</span><span lang="en-US">checkbox group</span></h4>
    <c-space direction="column" size="lg">
        <c-checkbox-group :default-value="['1']">
          <c-checkbox value="1">Option 1</c-checkbox>
          <c-checkbox value="2">Option 2</c-checkbox>
          <c-checkbox value="3">Option 3</c-checkbox>
        </c-checkbox-group>
        <c-checkbox-group orientation="vertical">
          <c-checkbox value="1">Option 1</c-checkbox>
          <c-checkbox value="2">Option 2</c-checkbox>
          <c-checkbox value="3">Option 3</c-checkbox>
        </c-checkbox-group>
      </c-space>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="checkbox-group-options">
    <h4><span lang="zh-CN">复选框组选项</span><span lang="en-US">checkbox group options</span></h4>
    <c-space direction="column" size="lg">
        <c-checkbox-group v-model="scene2.value1" :options="scene2.plainOptions"> </c-checkbox-group>
        <c-checkbox-group v-model="scene2.value2" :options="scene2.options"> </c-checkbox-group>
        <c-checkbox-group v-model="scene2.value2" :options="scene2.options">
          <template #label="{ data }">
            <c-tag>{{ data.label }}</c-tag>
          </template>
        </c-checkbox-group>
      </c-space>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

### Grid

- `disabled`: Prevents user interaction.

Example source: src/checkbox/__demos__/grid.vue

```vue
<template>
  <c-checkbox-group v-model="checkedValue">
    <c-grid :cols="3" :colGap="24" :rowGap="16">
      <c-grid-item>
        <c-checkbox value="1">Option 1</c-checkbox>
      </c-grid-item>
      <c-grid-item>
        <c-checkbox value="2" disabled>Option 2</c-checkbox>
      </c-grid-item>
      <c-grid-item>
        <c-checkbox value="3">Option 3</c-checkbox>
      </c-grid-item>
      <c-grid-item>
        <c-checkbox value="4">Option 4</c-checkbox>
      </c-grid-item>
      <c-grid-item>
        <c-checkbox value="5">Option 5</c-checkbox>
      </c-grid-item>
    </c-grid>
  </c-checkbox-group>
</template>
<script lang="ts">
import { defineComponent, ref } from 'vue'
export default defineComponent({
  setup() {
    const checkedValue = ref(['1', '2'])

    return {
      checkedValue,
    }
  },
})
</script>
```

### Group State

Preview configuration: `:default-value="['a']"`, `:options="options"`, `:readonly="readonly"`, `:model-value="[]"`.

Example source: src/checkbox/__demos__/group-state.vue

```vue
<script setup>
import { ref } from 'vue'

const accepted = ref(['a'])
const proposed = ref([])
const readonly = ref(false)
const options = [{ label: '设备 A', value: 'a' }, { label: '设备 B', value: 'b' }]
</script>

<template>
  <c-space direction="column">
    <div>
      <p>非受控：default-value 只用于初始值</p>
      <c-checkbox-group :default-value="['a']" :options="options" />
    </div>
    <div>
      <p>受控：父级接受更新 {{ accepted }}</p>
      <c-checkbox-group v-model="accepted" :options="options" :readonly="readonly" />
      <c-button size="sm" @click="readonly = !readonly">{{ readonly ? '解除只读' : '设为只读' }}</c-button>
    </div>
    <div>
      <p>父级拒绝更新：仅记录提议 {{ proposed }}</p>
      <c-checkbox-group :model-value="[]" :options="options" @update:model-value="proposed = $event" />
    </div>
  </c-space>
</template>
```

## Options and value model

### Control Value

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration   | Purpose                                                   | Related examples               |
| --------------- | --------------------------------------------------------- | ------------------------------ |
| `default-value` | Initial uncontrolled value                                | Control Value, Controlled Mode |
| `value`         | Option identifier in array/group mode                     | Control Value                  |
| `readonly`      | Readonly state; inherits from the form/group when omitted | Control Value                  |
| `disabled`      | Disabled state; inherits from the form/group when omitted | Control Value                  |

<!-- demo-config-notes:end -->

- `readonly`: Displays the current value without allowing edits.
- `disabled`: Prevents user interaction.

Example source: src/checkbox/__demos__/control-value.vue

```vue
<script setup>
import { ref } from 'vue'
const control = ref()
const value = ref(false)
const selected = ref([0])
</script>
<template>
  <c-space direction="column">
    <p>布尔模型始终返回布尔值；数组模型用 value 标识选项。 当前值：{{ value }}</p>
    <c-checkbox ref="control" v-model="value">启用通知</c-checkbox>
    <c-space wrap>
      <c-button size="sm" @click="control?.toggle()">切换选择</c-button>
      <c-button size="sm" @click="control?.focus()">聚焦</c-button>
      <c-button size="sm" @click="value = false">重置</c-button>
    </c-space>
    <p>数组模型：{{ selected }}</p>
    <c-checkbox v-model="selected" :value="0">数值 0</c-checkbox>
    <c-checkbox v-model="selected" :value="false">布尔 false</c-checkbox>
    <p>只读允许聚焦，禁用不允许操作；Enter/空格只影响当前控件。</p>
    <c-checkbox :default-value="true" readonly>只读</c-checkbox>
    <c-checkbox :default-value="true" disabled>禁用</c-checkbox>
  </c-space>
</template>
```

### Option Data

Preview configuration: `:options="options"`, `:field-names="fields"`, `orientation="vertical"`, `:options="renderOptions"`.

Example source: src/checkbox/__demos__/option-data.vue

```vue
<script setup lang="ts">
import { h, ref } from 'vue'

const value = ref<Array<string | number | boolean>>(['locked'])
const fields = { value: 'id', label: 'name', disabled: 'unavailable', readonly: 'locked' }
const options = ref([
  { id: false, name: '布尔 false' },
  { id: 0, name: '数字 0' },
  { id: '', name: '空字符串' },
  { id: 'locked', name: '只读选项', locked: true },
  { id: 'disabled', name: '禁用选项', unavailable: true },
])
const renderOptions = [
  { value: 'render', label: (_data: unknown, checked: boolean) => h('strong', checked ? '已选择' : '渲染函数标签') },
]
</script>

<template>
  <section class="option-demo">
    <p>字段映射与标签插槽；只读可聚焦，禁用不可操作。</p>
    <c-checkbox-group v-model="value" :options="options" :field-names="fields" orientation="vertical">
      <template #label="{ data, checked }">{{ data.label }} {{ checked ? '✓' : '' }}</template>
    </c-checkbox-group>
    <p>当前值：{{ JSON.stringify(value) }}</p>
    <c-button @click="value = []">清空</c-button>
    <p>标签也支持渲染函数；不传 options 时使用默认插槽，传入 [] 时保持空组。</p>
    <c-checkbox-group :options="renderOptions" />
  </section>
</template>

<style scoped>
.option-demo { display: flex; flex-direction: column; gap: 12px; }
.option-demo p { margin: 0; }
</style>
```

### Controlled Mode

Preview configuration: `:model-value="true"`, `:model-value="checked2"`, `:default-value="true"`.

Example source: src/checkbox/__demos__/controlled-mode.vue

```vue
<template>
  <c-space wrap size="lg">
    <c-checkbox v-model="checked1">v-model</c-checkbox>
    <c-checkbox :model-value="true">binding value</c-checkbox>
    <c-checkbox :model-value="checked2">binding value2</c-checkbox>
    <c-checkbox :default-value="true">uncontrolled state</c-checkbox>
  </c-space>
  <div :style="{ marginTop: '20px' }">
    <c-button status="primary" @click="handleSetCheck">
      {{ checked2 ? "uncheck" : "check" }} value2
    </c-button>
  </div>
</template>
<script lang="ts">
import { defineComponent, ref } from "vue";
export default defineComponent({
  setup() {
    const checked1 = ref(false);
    const checked2 = ref(false);

    const handleSetCheck = () => {
      checked2.value = !checked2.value;
    };

    return {
      checked1,
      checked2,
      handleSetCheck,
    };
  },
});
</script>
```

## Selection and bulk actions

### Max Checked

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration   | Purpose                                                   | Related examples                          |
| --------------- | --------------------------------------------------------- | ----------------------------------------- |
| `value`         | Option identifier in array/group mode                     | Max Checked, Checked All Indeterminate    |
| `disabled`      | Disabled state; inherits from the form/group when omitted | Max Checked, Interaction state comparison |
| `indeterminate` | Whether to display an indeterminate state                 | Checked All Indeterminate                 |
| `readonly`      | Readonly state; inherits from the form/group when omitted | Interaction state comparison              |
| `error`         | Error state; inherits from the form/group when omitted    | Interaction state comparison              |

<!-- demo-config-notes:end -->

- `disabled`: Prevents user interaction.

Example source: src/checkbox/__demos__/max-checked.vue

```vue
<template>
  <c-space direction="column" size="lg">
    <c-checkbox-group :max="2" v-model="value1" :options="plainOptions" />
    <c-checkbox-group :max="2" :default-value="['1']">
      <c-checkbox value="1" disabled>Option 1</c-checkbox>
      <c-checkbox value="2">Option 2</c-checkbox>
      <c-checkbox value="3">Option 3</c-checkbox>
      <c-checkbox value="4">Option 4</c-checkbox>
    </c-checkbox-group>
  </c-space>
</template>
<script lang="ts">
import { defineComponent, ref } from 'vue'
export default defineComponent({
  setup() {
    const value1 = ref(['Plain 1'])
    const plainOptions = ['Plain 1', 'Plain 2', 'Plain 3', 'Plain 4']

    return {
      plainOptions,
      value1,
    }
  },
})
</script>
```

### Checked All Indeterminate

Preview configuration: `:model-value="checkedAll"`, `:indeterminate="indeterminate"`, `value="1"`, `value="2"`.

Example source: src/checkbox/__demos__/checked-all-indeterminate.vue

```vue
<template>
  <c-space direction="column">
    <c-checkbox :model-value="checkedAll" :indeterminate="indeterminate" @change="handleChangeAll">Check All </c-checkbox>
    <c-checkbox-group v-model="data" @change="handleChange">
      <c-checkbox value="1">Option 1</c-checkbox>
      <c-checkbox value="2">Option 2</c-checkbox>
      <c-checkbox value="3">Option 3</c-checkbox>
    </c-checkbox-group>
  </c-space>
</template>
<script lang="ts">
import { defineComponent, ref } from 'vue'
export default defineComponent({
  setup() {
    const indeterminate = ref(false)
    const checkedAll = ref(false)
    const data = ref<string[]>([])

    const handleChangeAll = (value) => {
      indeterminate.value = false
      if (value) {
        checkedAll.value = true
        data.value = ['1', '2', '3']
      } else {
        checkedAll.value = false
        data.value = []
      }
    }

    const handleChange = (values) => {
      if (values.length === 3) {
        checkedAll.value = true
        indeterminate.value = false
      } else if (values.length === 0) {
        checkedAll.value = false
        indeterminate.value = false
      } else {
        checkedAll.value = false
        indeterminate.value = true
      }
    }

    return {
      indeterminate,
      checkedAll,
      data,
      handleChangeAll,
      handleChange,
    }
  },
})
</script>
```

### Group Methods

Preview configuration: `:options="reverse ? [...options].reverse() : options"`, `:max="4"`, `orientation="vertical"`.

Example source: src/checkbox/__demos__/group-methods.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
import type { CheckboxGroupInstance } from '@cedar-design/ui'

const group = ref<CheckboxGroupInstance>()
const value = ref<Array<string | number | boolean>>(['remote', 'locked', 'a'])
const reverse = ref(false)
const proposal = ref<Array<string | number | boolean>>([])
const options = [
  { value: 'a', label: '任务 A' },
  { value: 'b', label: '任务 B' },
  { value: 'c', label: '任务 C' },
  { value: 'locked', label: '只读，保留选择', readonly: true },
  { value: 'disabled', label: '禁用，不参与操作', disabled: true },
]
</script>

<template>
  <section class="group-methods-demo">
    <p>最多选择 4 项（包含未加载的 remote）。全选/反选保留只读和未加载的已选值。</p>
    <c-checkbox-group ref="group" v-model="value" :options="reverse ? [...options].reverse() : options" :max="4" orientation="vertical" />
    <c-space wrap>
      <c-button @click="proposal = group?.checkAll() ?? []">全选</c-button>
      <c-button @click="proposal = group?.inverseAll() ?? []">反选</c-button>
      <c-button @click="reverse = !reverse">调整选项顺序</c-button>
    </c-space>
    <p>当前值：{{ JSON.stringify(value) }}</p>
    <p>方法返回值：{{ JSON.stringify(proposal) }}</p>
  </section>
</template>

<style scoped>
.group-methods-demo { display: flex; flex-direction: column; gap: 12px; }
.group-methods-demo p { margin: 0; }
</style>
```

### Interaction state comparison

Toggle the state, interact with the component, and restore editing using the controls outside the specimen. Error appearance alone does not run validation.

Example source: src/checkbox/__demos__/state-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref(false);
const __demoState = __demoReactive({
  disabled: false,
  readonly: false,
  error: false,
});
</script>
<template>
  <c-space direction="column" :size="16">
    <c-space wrap>
      <c-checkbox v-model="__demoState['disabled']">disabled</c-checkbox>
      <c-checkbox v-model="__demoState['readonly']">readonly</c-checkbox>
      <c-checkbox v-model="__demoState['error']">error</c-checkbox>
    </c-space>
    <c-checkbox v-model="value" v-bind="__demoState">同意条款</c-checkbox>
  </c-space>
</template>
```

## Control and slot customization

### Native Control

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration   | Purpose                                                   | Related examples |
| --------------- | --------------------------------------------------------- | ---------------- |
| `name`          | Native field name; inherits from Group when omitted       | Native Control   |
| `indeterminate` | Whether to display an indeterminate state                 | Native Control   |
| `aria-label`    | Accessible name when no visible label exists              | Native Control   |
| `default-value` | Initial uncontrolled value                                | Native Control   |
| `readonly`      | Readonly state; inherits from the form/group when omitted | Native Control   |
| `disabled`      | Disabled state; inherits from the form/group when omitted | Native Control   |

<!-- demo-config-notes:end -->

- `readonly`: Displays the current value without allowing edits.
- `disabled`: Prevents user interaction.

Example source: src/checkbox/__demos__/native-control.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const value = ref(false)
const choices = ref(['read'])
</script>
<template>
  <div class="checkbox-native-demo">
    <p>按 Tab 聚焦，按空格或 Enter 切换。禁用项跳过，只读项可聚焦。</p>
    <c-checkbox v-model="value" name="agreement">接受协议：{{ value ? '已接受' : '未接受' }}</c-checkbox>
    <c-checkbox indeterminate aria-label="部分选中" />
    <c-checkbox :default-value="true" readonly>只读已选</c-checkbox>
    <c-checkbox disabled>禁用</c-checkbox>
    <c-checkbox error>错误状态</c-checkbox>
    <c-checkbox-group v-model="choices" name="permissions" aria-label="权限" :max="2" :options="[{ label: '读取', value: 'read' }, { label: '编辑', value: 'edit' }, { label: '管理', value: 'admin' }]" />
    <p>最多选择两项：{{ choices.join(', ') }}</p>
  </div>
</template>
<style scoped>
.checkbox-native-demo { display: flex; flex-direction: column; align-items: flex-start; gap: 12px; }
.checkbox-native-demo p { margin: 0; }
</style>
```

### Checked Custom

Preview configuration: `:default-value="['1']"`, `value="1"`, `:model-value="checked"`, `value="2"`.

Example source: src/checkbox/__demos__/checked-custom.vue

```vue
<template>
  <c-checkbox-group :default-value="['1']">
    <c-checkbox value="1">
      <template #checkbox="{ checked }">
        <c-tag :model-value="checked">This is a tag checkbox 1</c-tag>
      </template>
    </c-checkbox>
    <c-checkbox value="2">
      <template #checkbox="{ checked }">
        <c-tag :model-value="checked">This is a tag checkbox 2</c-tag>
      </template>
    </c-checkbox>
    <c-checkbox value="3">
      <template #checkbox="{ checked }">
        <c-tag :model-value="checked">This is a tag checkbox 3</c-tag>
      </template>
    </c-checkbox>
  </c-checkbox-group>

  <div :style="{ marginTop: '20px' }">
    <c-checkbox-group :default-value="[1]">
      <template v-for="item in 2" :key="item">
        <c-checkbox :value="item">
          <template #checkbox="{ checked }">
            <c-space wrap align="flex-start" class="custom-checkbox-card" :class="{ 'custom-checkbox-card-checked': checked }">
              <div class="custom-checkbox-card-mask">
                <div class="custom-checkbox-card-mask-dot" />
              </div>
              <div>
                <div class="custom-checkbox-card-title">Checkbox Card {{ item }}</div>
                <span>this is a text</span>
              </div>
            </c-space>
          </template>
        </c-checkbox>
      </template>
    </c-checkbox-group>
  </div>
</template>
<script lang="ts">
import { defineComponent } from 'vue'
export default defineComponent({
  })
</script>

<style scoped>
.custom-checkbox-card {
  padding: 10px 16px;
  border: 1px solid var(--color-border-2);
  border-radius: 4px;
  width: 250px;
  box-sizing: border-box;
}

.custom-checkbox-card-mask {
  height: 14px;
  width: 14px;
  display: inline-flex;
  align-items: center;
  justify-content: center;
  border-radius: 2px;
  border: 1px solid var(--color-border-2);
  box-sizing: border-box;
}

.custom-checkbox-card-mask-dot {
  width: 8px;
  height: 8px;
  border-radius: 2px;
}

.custom-checkbox-card-title {
  color: var(--color-text-1);
  font-size: 14px;
  font-weight: bold;
  margin-bottom: 8px;
}

.custom-checkbox-card:hover,
.custom-checkbox-card-checked,
.custom-checkbox-card:hover .custom-checkbox-card-mask,
.custom-checkbox-card-checked .custom-checkbox-card-mask {
  border-color: rgb(var(--primary-6));
}

.custom-checkbox-card-checked {
  background-color: var(--color-primary-light-1);
}

.custom-checkbox-card:hover .custom-checkbox-card-title,
.custom-checkbox-card-checked .custom-checkbox-card-title {
  color: rgb(var(--primary-6));
}

.custom-checkbox-card-checked .custom-checkbox-card-mask-dot {
  background-color: rgb(var(--primary-6));
}
</style>
```

### Custom Control

Preview configuration: `:icon-size="28"`, `checked-color="#137547"`, `unchecked-color="#656565"`, `icon-size="1.5rem"`.

Example source: src/checkbox/__demos__/custom-control.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const checked = ref(true)
</script>
<template>
  <div class="checkbox-custom-demo">
    <c-checkbox v-model="checked" :icon-size="28" checked-color="#137547" unchecked-color="#656565">数字尺寸（px）与实例颜色</c-checkbox>
    <c-checkbox icon-size="1.5rem" :ripple="false">CSS 长度尺寸，无波纹</c-checkbox>
    <c-checkbox v-model="checked">
      <template #checked-icon><span class="checkbox-custom-icon" aria-hidden="true">✓</span></template>
      <template #unchecked-icon><span class="checkbox-custom-icon" aria-hidden="true">○</span></template>
      自定义图标，仍保留原生键盘与无障碍语义
    </c-checkbox>
    <c-checkbox-group :default-value="['a']" :options="[{ label: '方案 A', value: 'a' }, { label: '方案 B', value: 'b' }]">
      <template #checkbox="{ checked: selected }"><span class="checkbox-custom-icon">{{ selected ? '✓' : '○' }}</span></template>
    </c-checkbox-group>
  </div>
</template>
<style scoped>
.checkbox-custom-demo { display: flex; flex-direction: column; align-items: flex-start; gap: 12px; }
.checkbox-custom-icon { display: inline-flex; justify-content: center; align-items: center; width: 28px; height: 28px; border: 1px solid currentColor; border-radius: 4px; }
</style>
```

## Async options

### Async Options

Preview configuration: `edit-mode="direct"`, `:options="options"`, `:max="2"`.

Example source: src/checkbox/__demos__/async-options.vue

```vue
<script setup>
import { onDeactivated, onUnmounted, ref, shallowRef } from "vue";

const value = ref(["remote"]);
const options = ref([]);
const loading = ref(false);
let pendingTimer;
const manual = ref(false);
const waiting = shallowRef([]);
const applied = ref(0);
const ignored = ref(0);
const changeCount = ref(0);
let version = 0;
let sequence = 0;

function cancelPending() {
  version++;
  if (pendingTimer !== undefined) {
    clearTimeout(pendingTimer);
  }
  pendingTimer = undefined;
  loading.value = false;
}

function load() {
  cancelPending();
  loading.value = true;
  const ticket = version;
  const id = ++sequence;
  const complete = () => {
    if (ticket !== version) {
      ignored.value++;
      return;
    }
    applied.value = id;
    options.value = [
      { label: "异步设备", value: "remote" },
      { label: "设备 A", value: "a" },
      { label: "设备 B", value: "b" },
      { label: "停用设备", value: "locked", disabled: true },
    ];
    pendingTimer = undefined;
    loading.value = false;
  };
  if (manual.value) {
    new Promise((resolve) => {
      waiting.value = [...waiting.value, { id, resolve }];
    }).then(complete);
  } else {
    pendingTimer = setTimeout(complete, 800);
  }
}

function settle(latest) {
  const jobs = [...waiting.value];
  const job = latest ? jobs.pop() : jobs.shift();
  waiting.value = jobs;
  job?.resolve();
}

function cleanup() {
  cancelPending();
  const jobs = waiting.value;
  waiting.value = [];
  jobs.forEach((job) => job.resolve());
}

function remove() {
  cancelPending();
  options.value = [];
}

onDeactivated(cleanup);
onUnmounted(cleanup);
</script>

<template>
  <c-space class="checkbox-async-demo" direction="column">
    <p>业务值独立于当前选项，加载或移除选项不会清空已选值：{{ value }}</p>
    <c-checkbox v-model="manual" edit-mode="direct" @change="remove"
      >Manual responses / 手动返回</c-checkbox
    >
    <c-space wrap>
      <c-button size="sm" @click="load">加载选项</c-button>
      <c-button size="sm" @click="remove">移除选项</c-button>
      <c-button
        size="sm"
        :disabled="waiting.length === 0"
        @click="settle(false)"
        >返回最早加载</c-button
      >
      <c-button size="sm" :disabled="waiting.length === 0" @click="settle(true)"
        >返回最新加载</c-button
      >
    </c-space>
    <p aria-live="polite">
      {{
        loading
          ? "加载中，可在完成前移除选项以取消本次加载。"
          : "加载完成后保留当前选值和键盘焦点。"
      }}
    </p>
    <c-checkbox-group
      v-model="value"
      edit-mode="direct"
      :options="options"
      :max="2"
      @change="changeCount++"
    />
    <p>用户变更次数：{{ changeCount }}</p>
    <p role="status">
      Applied: {{ applied }} · Ignored: {{ ignored }} · Pending:
      {{ waiting.length }}
    </p>
  </c-space>
</template>
```

## API

### Empty values and reading placeholders

`empty-values` recognizes empty data; `empty-value` keeps existing clear output. `empty-text` defaults to `'-'` under `read-pretty`, with Field > FormItem > Form precedence and custom read slots first. With explicit empty-values, built-in required uses the policy; custom validators receive original data. See the [shared guide](llms/en-US/guide/empty-values.md).

| Prop         | Type               | Default and scope                                                           |
| ------------ | ------------------ | --------------------------------------------------------------------------- |
| empty-values | readonly unknown[] | Field > FormItem > Form > component-family default; replaces the whole list |
| empty-text   | string             | Field > FormItem > Form > '-'; explicit '' is valid                         |

These props belong to field presentation; pure panels do not gain reading mode. Form and FormItem provide inherited settings. The existing empty-value type and clear fallback remain component-specific.

`ChoiceValue = string | number | boolean`；`CheckboxModel = boolean | ChoiceValue[]`；`RadioModel = ChoiceValue | null`。

### Checkbox Props

| Prop                   | Description                                                     | Type                     | Default   |
| ---------------------- | --------------------------------------------------------------- | ------------------------ | --------- |
| model-value (v-model)  | Controlled value                                                | boolean \| ChoiceValue[] | undefined |
| default-value          | Initial uncontrolled value                                      | boolean \| ChoiceValue[] | false     |
| value                  | Option identifier in array/group mode                           | string\|number\|boolean  | true      |
| disabled               | Disabled state; inherits from the form/group when omitted       | boolean                  | undefined |
| readonly               | Readonly state; inherits from the form/group when omitted       | boolean                  | undefined |
| error                  | Error state; inherits from the form/group when omitted          | boolean                  | undefined |
| indeterminate          | Whether to display an indeterminate state                       | boolean                  | false     |
| checked-color          | Instance checked color; error/disabled states take precedence   | string                   | undefined |
| unchecked-color        | Instance unchecked color; error/disabled states take precedence | string                   | undefined |
| icon-size              | Numbers are px; strings are CSS lengths                         | number \| string         | undefined |
| ripple                 | Whether to enable ripple feedback                               | boolean                  | true      |
| uninject-group-context | Ignore surrounding CheckboxGroup; form state still applies      | boolean                  | false     |
| name                   | Native field name; inherits from Group when omitted             | string                   | undefined |
| aria-label             | Accessible name when no visible label exists                    | string                   | undefined |

### Checkbox Events

| Event              | Description                       | Arguments                           |
| ------------------ | --------------------------------- | ----------------------------------- |
| update:model-value | Proposes a new value              | value: CheckboxModel                |
| change             | Value change                      | value: CheckboxModel, event?: Event |
| click              | Click; not emitted while disabled | event: MouseEvent                   |
| focus              | Focus                             | event: FocusEvent                   |
| blur               | Blur                              | event: FocusEvent                   |

### Checkbox Methods

| Method | Arguments              | Returns |
| ------ | ---------------------- | ------- |
| toggle | checked?: boolean      | void    |
| focus  | options?: FocusOptions | void    |
| blur   | -                      | void    |

### Checkbox Slots

| Slot               | Description                               | Arguments                                                   |
| ------------------ | ----------------------------------------- | ----------------------------------------------------------- |
| checkbox           | Customize the complete control appearance | checked: boolean, disabled: boolean, indeterminate: boolean |
| checked-icon       | Checked icon                              | -                                                           |
| unchecked-icon     | Unchecked icon                            | -                                                           |
| indeterminate-icon | Half icon                                 | -                                                           |
| default            | Label                                     | checked: boolean                                            |

### CheckboxGroup Props

| Prop                  | Description                                                                                               | Type                                                                                                       | Default      |
| --------------------- | --------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ------------ |
| model-value (v-model) | Controlled value                                                                                          | ChoiceValue[]                                                                                              | undefined    |
| default-value         | Initial uncontrolled value                                                                                | ChoiceValue[]                                                                                              | []           |
| max                   | Maximum selection count                                                                                   | number                                                                                                     | undefined    |
| options               | Options; replaces default slot when supplied                                                              | Array<ChoiceValue \| CheckboxOption \| Record<string, unknown>> / `(query, { signal }) => Array / Promise` | `undefined`  |
| orientation           | Horizontal/vertical arrangement of checkbox-group options, default horizontal; not text reading direction | Orientation                                                                                                | 'horizontal' |
| disabled              | Disabled state; inherits from the form/group when omitted                                                 | boolean                                                                                                    | undefined    |
| readonly              | Readonly state; inherits from the form/group when omitted                                                 | boolean                                                                                                    | undefined    |
| error                 | Error state; inherits from the form/group when omitted                                                    | boolean                                                                                                    | undefined    |
| field-names           | Option field mapping                                                                                      | ChoiceFieldNames                                                                                           | undefined    |
| name                  | Native input name within the group                                                                        | string                                                                                                     | undefined    |
| aria-label            | Accessible group name                                                                                     | string                                                                                                     | undefined    |

### CheckboxGroup Methods

| Method     | Arguments | Returns       |
| ---------- | --------- | ------------- |
| checkAll   | -         | ChoiceValue[] |
| inverseAll | -         | ChoiceValue[] |

### CheckboxGroup Events

| Event              | Description                          | Arguments                                          |
| ------------------ | ------------------------------------ | -------------------------------------------------- |
| update:model-value | Proposes a new value                 | value: (string \| number \| boolean)[]             |
| change             | Value change; notified once by Group | value: (string \| number \| boolean)[], ev?: Event |

### CheckboxGroup Slots

| Slot     | Description            | Arguments                              |
| -------- | ---------------------- | -------------------------------------- |
| checkbox | Custom checkbox        | checked: boolean<br/>disabled: boolean |
| label    | Checkbox label content | data: CheckboxOption, checked: boolean |

### CheckboxOption

| Field         | Description                      | Type                                                                 |
| ------------- | -------------------------------- | -------------------------------------------------------------------- |
| value         | Option identity                  | ChoiceValue                                                          |
| label         | Label or render function         | VNodeChild \| (data: CheckboxOption, checked: boolean) => VNodeChild |
| disabled      | Disable interaction              | boolean                                                              |
| readonly      | Read-only interaction            | boolean                                                              |
| indeterminate | Display-only indeterminate state | boolean                                                              |

## Type definitions

The component exports the following types

```ts
import type { CheckboxProps } from "@cedar-design/ui";
```

### ChoiceFieldNames

`{ label?: string; value?: string; disabled?: string; readonly?: string; indeterminate?: string }`

Exported types：`CheckboxOption`、`ChoiceFieldNames`。

Public method type：`CheckboxGroupMethods`；`CheckboxGroupInstance` includes these methods.

### Reduced motion

Built-in CSS transitions follow `prefers-reduced-motion: reduce`. Removing transitions does not change final visibility, selected/expanded state or event semantics. Applications control custom animations inside slots.

### Style variables

| Variable                                 | Default                                |
| ---------------------------------------- | -------------------------------------- |
| `--c-checkbox-control-color`             | `var(--c-sys-color-content-secondary)` |
| `--c-checkbox-control-color-checked`     | `var(--c-sys-color-content-brand)`     |
| `--c-checkbox-mark-color`                | `var(--c-sys-color-surface-default)`   |
| `--c-checkbox-control-color-disabled`    | `var(--c-sys-color-content-disabled)`  |
| `--c-checkbox-control-color-error`       | `var(--c-sys-color-content-danger)`    |
| `--c-checkbox-control-size`              | `14px`                                 |
| `--c-checkbox-label-text-color`          | `var(--c-sys-color-content-primary)`   |
| `--c-checkbox-label-text-color-disabled` | `var(--c-sys-color-content-disabled)`  |
| `--c-checkbox-label-font-size`           | `var(--c-font-size-body-3)`            |
| `--c-checkbox-label-gap`                 | `var(--c-spacing-4)`                   |
| `--c-checkbox-action-padding`            | `5px`                                  |
| `--c-checkbox-group-gap`                 | `var(--c-spacing-7)`                   |
| `--c-checkbox-animation-duration`        | `var(--c-transition-duration-3)`       |

### Form field presentation and confirmation

This component supports `edit-mode` with field > FormItem > Form precedence. When unset, it defaults to `direct` and preserves `direct` editing. Supported values: `direct / click / dblclick`. Non-`direct` modes open the editor through the field value trigger and keep one draft; v-model updates only after confirmation. Cancel, reset or enabling readPretty discards the draft.

Cedar uses edit-mode="click" / "dblclick" to open an editor popup near the field. Enter/F2 also opens it; cancel/Escape discards the draft, and confirmation commits it. readPretty is an independent reading setting, separate from readonly and disabled.

`before-commit(value, { previousValue, signal })` can reject an overlay save. FormItem validates the candidate first and keeps the editor open on failure. `open / default-open / update:open` control the editor. Use `#read="{ value, text }"` to customize display. See the full field comparison in Form.

`read-pretty` is an independent boolean alongside `readonly` and `disabled`. It inherits from field to FormItem to Form; explicit `false` overrides the parent. The default is `false`. Reading mode renders no editor.

`empty-value` accepts explicit `null` (or `() => null`). Clearing publishes `null` unchanged; omitted values preserve the existing default. Editors render `null` as blank without converting ordinary empty-string input to `null`. In popup editing, clearing changes the draft; confirm commits it and cancel preserves the original model.

The `options` prop accepts an array or `(query, { signal }) => array/Promise`. The component manages loading, cancellation and stale-result isolation; failures emit load-error. Single/multiple groups initialize with an empty-string query, searchable fields reload when the query changes, and root loading for tree fields remains independent of existing load-more child loading.

---

Document: llms/en-US/components/col.md

<!-- Source: src/col/README.en-US.md; locale: en-US; page: /en/components/col/ -->

# Col

24-column Flex layout. Row manages gutters and alignment; Col manages spans, offsets, ordering and breakpoints. Use Grid for CSS Grid collapse and suffix items.

> **Choosing a layout**
>
> - Grid + GridItem: Use for form columns and card grids with consistent column widths, spans, responsive column counts, or collapsed rows and suffix items.
> - Row + Col: Use for 24-column Flex layouts that need horizontal/vertical alignment, wrapping control, fixed and flexible widths together, or responsive ordering. Row controls the row; Col controls width, offset and order.
> - Space: Use for simple groups of buttons, tags or text that only need spacing, direction and alignment. Use native Flex for more flexible width allocation.

## Basic examples

### Span and offset

Example source: src/col/__demos__/basic.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const span = ref(8)
const offset = ref(4)
</script>
<template><div>
  <div class="controls">Span<c-radio-group v-model="span"><c-radio v-for="value in [4, 8, 12]" :key="value" :value="value">{{ value }}</c-radio></c-radio-group></div>
  <div class="controls">Offset<c-radio-group v-model="offset"><c-radio v-for="value in [0, 4, 8]" :key="value" :value="value">{{ value }}</c-radio></c-radio-group></div>
  <c-row :gutter="12"><c-col :span="span" :offset="offset"><div class="cell">{{ span }} / +{{ offset }}</div></c-col><c-col :span="4"><div class="cell soft">4</div></c-col></c-row>
</div></template>

<style scoped>
.controls { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; }
.cell { box-sizing: border-box; padding: 12px; min-width: 0; border-radius: 4px; background: var(--c-color-primary); color: var(--c-color-white); text-align: center; overflow-wrap: anywhere; }
.soft { opacity: .7; }
</style>
```

## Layout and arrangement

### Flexible ratios and fixed widths

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `flex` | Ratio, fixed length or CSS flex value | Flexible ratios and fixed widths |
| `xs` | Responsive span or object containing span, offset and order | Responsive objects and visibility |
| `sm` | Responsive span or object containing span, offset and order | Responsive objects and visibility |
| `md` | Responsive span or object containing span, offset and order | Responsive objects and visibility |
| `span` | Column span; 0 hides | Responsive objects and visibility |
<!-- demo-config-notes:end -->


Example source: src/col/__demos__/flex.vue

```vue
<template><div>
  <c-row :gutter="12"><c-col :flex="1"><div class="cell">1</div></c-col><c-col :flex="2"><div class="cell soft">2</div></c-col></c-row>
  <c-row :gutter="12" :wrap="false"><c-col flex="100px"><div class="cell">100px</div></c-col><c-col flex="auto"><div class="cell soft">auto</div></c-col></c-row>
</div></template>

<style scoped>
.controls { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; }
.cell { box-sizing: border-box; padding: 12px; min-width: 0; border-radius: 4px; background: var(--c-color-primary); color: var(--c-color-white); text-align: center; overflow-wrap: anywhere; }
.soft { opacity: .7; }
</style>
```

### Responsive objects and visibility

Example source: src/col/__demos__/responsive.vue

```vue
<template><div>
  <p>xs → sm (576px) → md (768px). Hidden columns return at larger breakpoints.</p>
  <c-row :gutter="[12, 12]"><c-col :xs="24" :sm="12" :md="8"><div class="cell">24 / 12 / 8</div></c-col><c-col :xs="0" :sm="12" :md="8"><div class="cell soft">Hidden / 12 / 8</div></c-col><c-col :span="8" :xs="{ span: 20, offset: 4, order: 2 }" :md="{ span: 8, offset: 0, order: 0 }"><div class="cell">Reset offset / order</div></c-col></c-row>
</div></template>

<style scoped>
.controls { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; }
.cell { box-sizing: border-box; padding: 12px; min-width: 0; border-radius: 4px; background: var(--c-color-primary); color: var(--c-color-white); text-align: center; overflow-wrap: anywhere; }
.soft { opacity: .7; }
</style>
```

<!-- same-source-api:start -->

### Props

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| span | Column span; 0 hides | `number` | `24` |
| offset | Offset; 0 resets | `number` | `undefined` |
| order | Order; 0 resets | `number` | `undefined` |
| xs | Responsive span or object containing span, offset and order | `number / ColSizeDescriptor` | `undefined` |
| sm | Responsive span or object containing span, offset and order | `number / ColSizeDescriptor` | `undefined` |
| md | Responsive span or object containing span, offset and order | `number / ColSizeDescriptor` | `undefined` |
| lg | Responsive span or object containing span, offset and order | `number / ColSizeDescriptor` | `undefined` |
| xl | Responsive span or object containing span, offset and order | `number / ColSizeDescriptor` | `undefined` |
| xxl | Responsive span or object containing span, offset and order | `number / ColSizeDescriptor` | `undefined` |
| flex | Ratio, fixed length or CSS flex value | `number / string` | `undefined` |

### Events

| Event | Description |
| --- | --- |
| click | Native MouseEvent, emitted once per click |

### Slots

| Slot | Description |
| --- | --- |
| default | Layout content |

### Methods

| Method | Description |
| --- | --- |
<!-- same-source-api:end -->

The order example restores every column to `order: 0` when reverse is turned off. Responsive breakpoints use the browser viewport rather than the demo card width; widening the card alone does not activate a breakpoint. `span: 0` hides a column, and a matching larger breakpoint can restore it.

## Content and presentation

### Ordering and resetting to zero

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `span` | Column span; 0 hides | Ordering and resetting to zero |
| `order` | Order; 0 resets | Ordering and resetting to zero |
<!-- demo-config-notes:end -->


Example source: src/col/__demos__/order.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const reverse = ref(false)
</script>
<template><div><div class="controls"><c-switch v-model="reverse" aria-label="Reverse order" />Reverse order</div><c-row :gutter="12"><c-col v-for="i in 3" :key="i" :span="8" :order="reverse ? 3 - i : 0"><div class="cell">{{ i }}</div></c-col></c-row></div></template>

<style scoped>
.controls { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; }
.cell { box-sizing: border-box; padding: 12px; min-width: 0; border-radius: 4px; background: var(--c-color-primary); color: var(--c-color-white); text-align: center; overflow-wrap: anywhere; }
.soft { opacity: .7; }
</style>
```

## API

<!-- same-source-api:start -->
### Props

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| span | Column span; 0 hides | `number` | `24` |
| offset | Offset; 0 resets | `number` | `undefined` |
| order | Order; 0 resets | `number` | `undefined` |
| xs | Responsive span or object containing span, offset and order | `number / ColSizeDescriptor` | `undefined` |
| sm | Responsive span or object containing span, offset and order | `number / ColSizeDescriptor` | `undefined` |
| md | Responsive span or object containing span, offset and order | `number / ColSizeDescriptor` | `undefined` |
| lg | Responsive span or object containing span, offset and order | `number / ColSizeDescriptor` | `undefined` |
| xl | Responsive span or object containing span, offset and order | `number / ColSizeDescriptor` | `undefined` |
| xxl | Responsive span or object containing span, offset and order | `number / ColSizeDescriptor` | `undefined` |
| flex | Ratio, fixed length or CSS flex value | `number / string` | `undefined` |

### Events

| Event | Description |
| --- | --- |
| click | Native MouseEvent, emitted once per click |

### Slots

| Slot | Description |
| --- | --- |
| default | Layout content |

### Methods

| Method | Description |
| --- | --- |
<!-- same-source-api:end -->

The order example restores every column to `order: 0` when reverse is turned off. Responsive breakpoints use the browser viewport rather than the demo card width; widening the card alone does not activate a breakpoint. `span: 0` hides a column, and a matching larger breakpoint can restore it.

## Responsiveness and accessibility

Breakpoints use the browser viewport: xs is the base; sm ≥576, md ≥768, lg ≥992, xl ≥1200 and xxl ≥1600px. Configured values resolve downward from the largest matching breakpoint. SSR starts with xs and responds to the viewport after mounting. Grid collapsing and dynamic ordering are calculated after mounting. These layout containers add no keyboard shortcuts; callers supply content semantics and focusable elements. There are no public methods or dedicated theme tokens.

## Imports

Grid contains only Grid.Item. Row and Col are independent components with their own source, styles, navigation, documentation and demos. Grid.Row/Grid.Col, Row/Col re-exports from Grid and GridRowInstance/GridColInstance are removed. Import them from the library root or separate row/col entries. Installing Grid no longer registers Row/Col automatically.

---

Document: llms/en-US/components/collapse.md

<!-- Source: src/collapse/README.en-US.md; locale: en-US; page: /en/components/collapse/ -->

# Collapse

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

Preview configuration: `:default-value="['1', 2]"`, `title="Beijing Toutiao Technology Co., Ltd."`, `name="1"`, `:name="2"`.

Example source: src/collapse/__demos__/basic.vue

```vue
<template>
  <c-collapse :default-value="['1', 2]">
    <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="1">
      <div>Beijing Toutiao Technology Co., Ltd.</div>
    </c-collapse-item>
    <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." :name="2">
      <div>Beijing Toutiao Technology Co., Ltd.</div>
    </c-collapse-item>
    <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="3">
      <div>Beijing Toutiao Technology Co., Ltd.</div>
    </c-collapse-item>
  </c-collapse>
</template>
<script lang="ts" setup>
</script>
```

## Appearance and states

### Disabled

Preview configuration: `:default-value="[1]"`, `title="Beijing Toutiao Technology Co., Ltd."`, `:name="1"`, `:disabled="disabled"`.

Example source: src/collapse/__demos__/disabled.vue

```vue
<template>
  <c-space direction="column" :style="{ width: '100%' }">
    <c-button @click="disabled = !disabled">
      {{ disabled ? 'Enable' : 'Disable' }}
    </c-button>
    <c-collapse :default-value="[1]">
      <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." :name="1" :disabled="disabled">
        <div>Beijing Toutiao Technology Co., Ltd.</div>
      </c-collapse-item>
      <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." :name="2" :disabled="disabled">
        <div>Beijing Toutiao Technology Co., Ltd.</div>
      </c-collapse-item>
    </c-collapse>
  </c-space>
</template>
<script lang="ts" setup>
import { ref } from 'vue'

const disabled = ref(false)
</script>
```

## Layout and arrangement

### Nested

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `default-value` | Uncontrolled initial expanded names | Nested, Icon Position |
| `destroy-on-hide` | Destroy content when hidden | Nested |
| `offset` | Gap between expanded panels | Offset |
| `expand-icon-position` | Expand-icon position within the header: left or right, default left. Does not control content expansion direction | Icon Position |
| `show-expand-icon` | Whether to show expansion icons; child items decide when omitted | Icon Position |
<!-- demo-config-notes:end -->


Preview configuration: `:default-value="['1', 2]"`, `destroy-on-hide`, `title="Beijing Toutiao Technology Co., Ltd."`, `name="1"`.

Example source: src/collapse/__demos__/nested.vue

```vue
<template>
  <c-collapse :default-value="['1', 2]" destroy-on-hide>
    <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="1">
      <c-collapse :default-value="['1.1']" destroy-on-hide>
        <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="1.1">
          <div>Beijing Toutiao Technology Co., Ltd.</div>
        </c-collapse-item>
        <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="1.2">
          <div>Beijing Toutiao Technology Co., Ltd.</div>
        </c-collapse-item>
      </c-collapse>
    </c-collapse-item>
    <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." :name="2">
      <div>Beijing Toutiao Technology Co., Ltd.</div>
    </c-collapse-item>
    <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="3">
      <div>Beijing Toutiao Technology Co., Ltd.</div>
    </c-collapse-item>
  </c-collapse>
</template>
<script lang="ts" setup>
</script>
```

### Offset

Preview configuration: `:offset="offset"`, `title="Beijing Toutiao Technology Co., Ltd."`, `name="1"`, `name="2"`.

Example source: src/collapse/__demos__/offset.vue

```vue
<template>
  <c-space direction="column" :style="{ width: '100%' }">
    <c-button @click="offset = !offset">
      {{ offset ? 'Hide offset' : 'Show offset' }}
    </c-button>
    <c-collapse v-model="activeNames" :offset="offset">
      <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="1">
        <div>Beijing Toutiao Technology Co., Ltd.</div>
      </c-collapse-item>
      <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="2">
        <div>Beijing Toutiao Technology Co., Ltd.</div>
      </c-collapse-item>
      <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="3">
        <div>Beijing Toutiao Technology Co., Ltd.</div>
      </c-collapse-item>
    </c-collapse>
  </c-space>
</template>
<script lang="ts" setup>
import { ref } from 'vue'

const offset = ref(true)
const activeNames = ref<(string | number)[]>(['1', '2'])
</script>
```

### Icon Position

Preview configuration: `:default-value="['1']"`, `:expand-icon-position="position"`, `:show-expand-icon="!hideIcon"`, `title="Beijing Toutiao Technology Co., Ltd."`.

Example source: src/collapse/__demos__/icon-position.vue

```vue
<template>
  <c-space direction="column" :style="{ width: '100%' }">
    <c-space>
      <c-button @click="position = position === 'right' ? 'left' : 'right'">
        {{ position === 'right' ? 'Icon left' : 'Icon right' }}
      </c-button>
      <c-button @click="hideIcon = !hideIcon">
        {{ hideIcon ? 'Show icon' : 'Hide icon' }}
      </c-button>
    </c-space>
    <c-collapse :default-value="['1']" :expand-icon-position="position" :show-expand-icon="!hideIcon">
      <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="1">
        <template #extra>
          <c-tag size="sm">city</c-tag>
        </template>
        <div>Beijing Toutiao Technology Co., Ltd.</div>
      </c-collapse-item>
      <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="2" disabled>
        <div>Beijing Toutiao Technology Co., Ltd.</div>
      </c-collapse-item>
      <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="3">
        <div>Beijing Toutiao Technology Co., Ltd.</div>
      </c-collapse-item>
    </c-collapse>
  </c-space>
</template>
<script lang="ts" setup>
import { ref } from 'vue'

const position = ref<'left' | 'right'>('left')
const hideIcon = ref(false)
</script>
```

## Content and presentation

### Accordion

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `default-value` | Uncontrolled initial expanded names | Accordion, Borders and dividers, Expand Icon |
| `accordion` | Accordion mode; at most one open panel | Accordion |
| `bordered` | Whether to show border | Borders and dividers |
| `divider` | Show dividers | Borders and dividers |
| `destroy-on-hide` | Destroy content when hidden | Destroy |
<!-- demo-config-notes:end -->


Preview configuration: `:default-value="[1]"`, `accordion`, `title="Beijing Toutiao Technology Co., Ltd."`, `name="1"`.

Example source: src/collapse/__demos__/accordion.vue

```vue
<template>
  <c-collapse :default-value="[1]" accordion>
    <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="1">
      <div>Beijing Toutiao Technology Co., Ltd.</div>
    </c-collapse-item>
    <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="2">
      <div>Beijing Toutiao Technology Co., Ltd.</div>
    </c-collapse-item>
    <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="3">
      <div>Beijing Toutiao Technology Co., Ltd.</div>
    </c-collapse-item>
  </c-collapse>
</template>
<script lang="ts" setup>
</script>
```

### Borders and dividers

Compare outer borders and separators between panels, including their appearance while expanded.

Example source: src/collapse/__demos__/border-comparison.vue

```vue
<script setup lang="ts">
import { ref } from "vue"
import { proxyRefs as demoProxyRefs } from 'vue'

const scene2 = demoProxyRefs((() => {


const divider = ref(true)
return { divider }
})())
</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="border-less">
    <h4><span lang="zh-CN">无边框模式</span><span lang="en-US">border less</span></h4>
    <c-collapse :default-value="['1']" :bordered="false">
        <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="1">
          <div>Beijing Toutiao Technology Co., Ltd.</div>
        </c-collapse-item>
        <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="2" disabled>
          <div>Beijing Toutiao Technology Co., Ltd.</div>
        </c-collapse-item>
        <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="3">
          <div>Beijing Toutiao Technology Co., Ltd.</div>
        </c-collapse-item>
      </c-collapse>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="divider">
    <h4><span lang="zh-CN">分割线</span><span lang="en-US">divider</span></h4>
    <c-space direction="column" :style="{
      width: '100%'
    }">
        <c-button @click="scene2.divider = !scene2.divider">
          {{ scene2.divider ? 'Hide divider' : 'Show divider' }}
        </c-button>
        <c-collapse :default-value="[]" :divider="scene2.divider">
          <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="1">
            <div>Beijing Toutiao Technology Co., Ltd.</div>
          </c-collapse-item>
          <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="2">
            <div>Beijing Toutiao Technology Co., Ltd.</div>
          </c-collapse-item>
          <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="3">
            <div>Beijing Toutiao Technology Co., Ltd.</div>
          </c-collapse-item>
        </c-collapse>
      </c-space>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

### Extra

Preview configuration: `title="Beijing Toutiao Technology Co., Ltd."`, `name="1"`, `:name="2"`, `name="3"`.

Example source: src/collapse/__demos__/extra.vue

```vue
<template>
  <c-collapse>
    <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="1">
      <template #extra>Extra</template>
      <div>Beijing Toutiao Technology Co., Ltd.</div>
    </c-collapse-item>
    <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." :name="2">
      <template #extra>
        <c-button status="primary" size="sm">Action</c-button>
      </template>
      <div>Beijing Toutiao Technology Co., Ltd.</div>
    </c-collapse-item>
    <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="3">
      <template #extra>
        <c-tag size="sm">city</c-tag>
      </template>
      <div>Beijing Toutiao Technology Co., Ltd.</div>
    </c-collapse-item>
  </c-collapse>
</template>
<script lang="ts" setup>
</script>
```

### Expand Icon

Preview configuration: `:default-value="['1', 2]"`, `title="Beijing Toutiao Technology Co., Ltd."`, `name="1"`, `:name="2"`.

Example source: src/collapse/__demos__/expand-icon.vue

```vue
<template>
  <c-collapse :default-value="['1', 2]">
    <template #expand-icon="{ expanded }">
      <span>{{ expanded ? '▼' : '▶' }}</span>
    </template>
    <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="1">
      <template #expand-icon="{ expanded }">
        <span>{{ expanded ? '^^' : 'vv' }}</span>
      </template>
      <div>Beijing Toutiao Technology Co., Ltd.</div>
    </c-collapse-item>
    <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." :name="2">
      <div>Beijing Toutiao Technology Co., Ltd.</div>
    </c-collapse-item>
    <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="3">
      <div>Beijing Toutiao Technology Co., Ltd.</div>
    </c-collapse-item>
  </c-collapse>
</template>
<script lang="ts" setup>
</script>
```

### Destroy

Preview configuration: `:default-value="['1', 2]"`, `destroy-on-hide`, `title="Beijing Toutiao Technology Co., Ltd."`, `name="1"`.

Example source: src/collapse/__demos__/destroy.vue

```vue
<template>
  <c-collapse :default-value="['1', 2]" destroy-on-hide>
    <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="1">
      <div>Beijing Toutiao Technology Co., Ltd.</div>
    </c-collapse-item>
    <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." :name="2">
      <div>Beijing Toutiao Technology Co., Ltd.</div>
    </c-collapse-item>
    <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="3" :show-expand-icon="false">
      <div>Beijing Toutiao Technology Co., Ltd.</div>
    </c-collapse-item>
  </c-collapse>
</template>
<script lang="ts" setup>
</script>
```

## Customization and slots

### Custom

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `default-value` | Uncontrolled initial expanded names | Custom |
| `bordered` | Whether to show border | Custom |
<!-- demo-config-notes:end -->


Preview configuration: `:default-value="['1', 2]"`, `:bordered="false"`, `title="Beijing Toutiao Technology Co., Ltd."`, `name="1"`.

Example source: src/collapse/__demos__/custom.vue

```vue
<template>
  <c-collapse :default-value="['1', 2]" :bordered="false">
    <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." :style="customStyle" name="1">
      <div>Beijing Toutiao Technology Co., Ltd.</div>
    </c-collapse-item>
    <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." :style="customStyle" :name="2">
      <div>Beijing Toutiao Technology Co., Ltd.</div>
    </c-collapse-item>
    <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." :style="customStyle" name="3">
      <div>Beijing Toutiao Technology Co., Ltd.</div>
    </c-collapse-item>
  </c-collapse>
</template>
<script lang="ts" setup>
const customStyle = {
  borderRadius: '6px',
  marginBottom: '12px',
  overflow: 'hidden',
}
</script>
```

## Interaction and control

### Toggle All

Preview configuration: `title="Panel 1"`, `name="1"`, `title="Panel 2"`, `name="2"`.

Example source: src/collapse/__demos__/toggle-all.vue

```vue
<template>
  <c-space direction="column" :style="{ width: '100%' }">
    <c-space wrap>
      <c-button @click="toggleAll({ expand: 'inverse' })">Toggle all</c-button>
      <c-button @click="toggleAll({ expand: 'inverse', skipDisabled: true })">Toggle all (skip disabled)</c-button>
      <c-button @click="toggleAll({ expand: true })">Expand all</c-button>
      <c-button @click="toggleAll({ expand: true, skipDisabled: true })">Expand all (skip disabled)</c-button>
      <c-button @click="toggleAll({ expand: false })">Collapse all</c-button>
      <c-button @click="toggleAll({ expand: false, skipDisabled: true })">Collapse all (skip disabled)</c-button>
    </c-space>
    <c-collapse ref="collapseRef" v-model="activeNames">
      <c-collapse-item title="Panel 1" name="1">
        <div>Content 1</div>
      </c-collapse-item>
      <c-collapse-item title="Panel 2" name="2">
        <div>Content 2</div>
      </c-collapse-item>
      <c-collapse-item title="Panel 3" name="3" disabled>
        <div>Content 3</div>
      </c-collapse-item>
      <c-collapse-item title="Panel 4" name="4" disabled>
        <div>Content 4</div>
      </c-collapse-item>
    </c-collapse>
  </c-space>
</template>
<script lang="ts" setup>
import { ref } from 'vue'

const collapseRef = ref<{
  toggleAll: (options: { expand: boolean | 'inverse'; skipDisabled?: boolean }) => void
}>()
const activeNames = ref<(string | number)[]>(['2', '4'])

const toggleAll = (options: { expand: boolean | 'inverse'; skipDisabled?: boolean }) => {
  collapseRef.value?.toggleAll(options)
}
</script>
```

## Reading direction

Inherits the nearest `dir="ltr|rtl"` and supports runtime and nested overrides. Titles and expanded content inherit reading direction without changing expansion state. The left/right values of expand-icon-position remain physical sides. Custom expansion graphics are not additionally mirrored.

## API

The main value uses ordinary `v-model`: `modelValue` is an array of expanded panel names, including in accordion mode. `defaultValue` initializes uncontrolled state only on creation; later changes do not reset it. Initialization does not emit `update:modelValue`. When `modelValue` is provided, the parent controls the state and its value is authoritative.

<!-- same-source-api:start -->
### Props

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| model-value | Expanded names; v-model | `(string \| number)[]` | `—` |
| default-value | Uncontrolled initial expanded names | `(string \| number)[]` | `[]` |
| accordion | Accordion mode; at most one open panel | `boolean` | `false` |
| show-expand-icon | Whether to show expansion icons; child items decide when omitted | `boolean` | `—` |
| expand-icon-position | Expand-icon position within the header: left or right, default left. Does not control content expansion direction | `'left' \| 'right'` | `'left'` |
| bordered | Whether to show border | `boolean` | `true` |
| divider | Show dividers | `boolean` | `true` |
| offset | Gap between expanded panels | `boolean` | `false` |
| destroy-on-hide | Destroy content when hidden | `boolean` | `false` |

### Events

| Event | Description | Arguments |
| --- | --- | --- |
| update:model-value | Request an expanded-name update | `(string \| number)[]` |
| change | Emitted when expanded panels change | `(string \| number)[]`, `Event` |

### Slots

| Slot | Description | Scope |
| --- | --- | --- |
| default | Panel list | `—` |

### Methods

| Method | Description |
| --- | --- |
| toggleAll | Expand or collapse all panels (no-op in accordion) |

<!-- same-source-api:end -->

The parent `expand-icon` slot is forwarded to items that do not provide their own icon. Scope: `expanded`, `disabled`, `position`. It is not rendered on the root node.

#### CollapseToggleAllOptions

| Arguments | Description | Type | Default |
| --- | --- | --- | --- |
| expand | `'inverse'` toggles all; `boolean` expands or collapses all | `'inverse' \| boolean` | `—` |
| skipDisabled | Skip disabled panels | `boolean` | `false` |

### `<collapse-item>` Props

| Parameter | Description | Type | Default |
| --- | --- | --- | --- |
| name **(required)** | Unique panel identifier corresponding to a value in `modelValue` | `string \| number` | `—` |
| title | Panel title | `string` | `—` |
| disabled | Whether disabled | `boolean` | `false` |
| show-expand-icon | Whether to show an expansion icon | `boolean` | `true` |
| destroy-on-hide | Destroy content when hidden | `boolean` | `false` |

### `<collapse-item>` Slots

| Slot | Description | Arguments |
| --- | --- | --- |
| title | Panel title | `—` |
| extra | Extra content | `—` |
| expand-icon | Expand icon | expanded: `boolean`<br>disabled: `boolean`<br>position: `'left' \| 'right'` |
| default | Panel content | `—` |

### Type definitions

The component exports the following types. `Collapse.Item` and `CollapseItem` refer to the same component.

```ts
import type { CollapseInstance, CollapseToggleAllOptions, ExpandIconPosition } from '@cedar-design/ui'
```

## Color variables

Collapse public color variables default to system semantics consistently in Cedar and Maple:

| Variable | Default semantic value |
| --- | --- |
| `--c-collapse-border-color` | `--c-sys-color-border-default` |
| `--c-collapse-title-bg` | `--c-sys-color-surface-default` |
| `--c-collapse-title-bg-active` | `--c-sys-color-surface-default` |
| `--c-collapse-title-bg-disabled` | `--c-sys-color-surface-default` |
| `--c-collapse-title-text-color` | `--c-sys-color-content-primary` |
| `--c-collapse-title-text-color-disabled` | `--c-sys-color-content-disabled` |
| `--c-collapse-content-text-color` | `--c-sys-color-content-primary` |
| `--c-collapse-content-text-color-disabled` | `--c-sys-color-content-disabled` |
| `--c-collapse-content-bg` | `--c-sys-color-surface-muted` |
| `--c-collapse-expand-icon` | `var(--c-sys-color-content-secondary)` |
| `--c-collapse-item-border-color` | `--c-sys-color-border-default` |

### Reduced motion

Built-in CSS transitions follow `prefers-reduced-motion: reduce`. Removing transitions does not change final visibility, selected/expanded state or event semantics. Applications control custom animations inside slots.

---

Document: llms/en-US/components/color-picker.md

<!-- Source: src/color-picker/README.en-US.md; locale: en-US; page: /en/components/color-picker/ -->

# Color Picker

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

- `default-value`: Default value (uncontrolled state)

Example source: src/color-picker/__demos__/basic.vue

```vue
<template>
  <c-color-picker default-value="#00BEBE" />
</template>
```

## Appearance and states

### Disabled

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `default-value` | Default | Disabled |
| `disabled` | Disabled | Disabled |
| `hide-trigger` | Panel only, without a trigger | Disabled |
| `show-text` | Show color value | Disabled |
<!-- demo-config-notes:end -->


- `default-value`: Default value (uncontrolled state)
- `disabled`: disabled
- `hide-trigger`: There is no trigger element, only the color panel is displayed
- `show-text`: Show color value

Example source: src/color-picker/__demos__/disabled.vue

```vue
<template>
  <c-space>
    <c-color-picker defaultValue="#00BEBE" disabled :hide-trigger="false" />
    <c-color-picker defaultValue="#00BEBE" showText disabled :hide-trigger="false" />
  </c-space>
</template>
```

## Content and presentation

### Colors

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `default-value` | Default | Colors |
| `history-colors` | History colors | Colors |
| `show-history` | Show history colors | Colors |
| `show-preset` | Show preset colors | Colors |
<!-- demo-config-notes:end -->


- `default-value`: Default value (uncontrolled state)
- `history-colors`: Color array of historical colors
- `show-history`: Show history colors
- `show-preset`: Show preset colors

Example source: src/color-picker/__demos__/colors.vue

```vue
<template>
  <c-color-picker
    defaultValue="#00BEBE"
    :historyColors="history"
    showHistory
    showPreset
    @open-change="addHistory" />
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const history = ref(['#00BEBE'])
const addHistory = (visible, color) => {
  if (!visible) {
    const index = history.value.indexOf(color)
    if (index !== -1) {
      history.value.splice(index, 1)
    }
    history.value.unshift(color)
  }
}
</script>
```

## Data and options

### Format

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `default-value` | Default | Format |
| `format` | Color value format | Format |
| `show-text` | Show color value | Format |
| `hide-trigger` | Panel only, without a trigger | Format |
<!-- demo-config-notes:end -->


- `default-value`: Default value (uncontrolled state)
- `format`: Color value format
- `show-text`: Show color value
- `hide-trigger`: There is no trigger element, only the color panel is displayed

Example source: src/color-picker/__demos__/format.vue

```vue
<template>
  <c-space direction="column">
    <c-radio-group type="button" v-model="format">
      <c-radio v-for="item in formatList" :value="item">{{ item }}</c-radio>
    </c-radio-group>
    <c-color-picker defaultValue="#00BEBE" :format="format" showText :hide-trigger="false" />
  </c-space>
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const format = ref('hex')
const formatList = ['hex', 'rgb']
</script>
```

## API

### `<ColorPicker>` Props

| Parameter | Description | Type | Default |
| --- | --- | --- | --- |
| model-value **(v-model)** | Bound value | `string` | `-` |
| default-value | Default | `string` | `-` |
| format | Color value format | `'hex' \| 'rgb'` | `-` |
| size | Size | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` |
| show-text | Show color value | `boolean` | `false` |
| show-history | Show history colors | `boolean` | `false` |
| show-preset | Show preset colors | `boolean` | `false` |
| disabled | Disable interaction | `boolean` | `false` |
| disabled-alpha | Disable alpha | `boolean` | `false` |
| hide-trigger | Panel only, without a trigger | `boolean` | `true` |
| history-colors | History colors | `string[]` | `-` |
| preset-colors | Preset colors | `string[]` | `-` |


### Existing precedence of forwarded configuration (F07)

Existing triggerProps are spread after some internal Trigger settings, so nested fields such as disabled can currently override internal values. F07 preserves this order and type for compatibility; it does not apply AutoComplete managed-field rules, promise a new safe subset or automatically prohibit these existing capabilities.

Dragging uses the control owner view. KeepAlive deactivation or unmount ends the gesture and releases its listeners; a new activation requires a new gesture, and callbacks from old gestures cannot change its value.

---

Document: llms/en-US/components/color.md

<!-- Source: src/color/README.en-US.md; locale: en-US; page: /en/components/color/ -->

# Color

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

- `show-text`: Show color value

Example source: src/color/__demos__/basic.vue

```vue
<template>
  <c-color v-model="value" show-text />
</template>

<script setup>
import { ref } from 'vue'

const value = ref('#00BEBE')
</script>
```

## Appearance and states

### Size

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration | Purpose          | Related examples |
| ------------- | ---------------- | ---------------- |
| `size`        | Size             | Size             |
| `show-text`   | Show color value | Size             |

<!-- demo-config-notes:end -->

- `size`: ComponentSize
- `show-text`: Show color value

Example source: src/color/__demos__/size.vue

```vue
<template>
  <c-space>
    <c-color v-model="value" size="xs" />
    <c-color v-model="value" size="sm" />
    <c-color v-model="value" size="md" show-text />
    <c-color v-model="value" size="lg" show-text />
  </c-space>
</template>

<script setup>
import { ref } from 'vue'

const value = ref('#165DFF')
</script>
```

## API

### Empty values and reading placeholders

`empty-values` recognizes empty data; `empty-value` keeps existing clear output. `empty-text` defaults to `'-'` under `read-pretty`, with Field > FormItem > Form precedence and custom read slots first. With explicit empty-values, built-in required uses the policy; custom validators receive original data. See the [shared guide](llms/en-US/guide/empty-values.md).

| Prop         | Type               | Default and scope                                                           |
| ------------ | ------------------ | --------------------------------------------------------------------------- |
| empty-values | readonly unknown[] | Field > FormItem > Form > component-family default; replaces the whole list |
| empty-text   | string             | Field > FormItem > Form > '-'; explicit '' is valid                         |

These props belong to field presentation; pure panels do not gain reading mode. Form and FormItem provide inherited settings. The existing empty-value type and clear fallback remain component-specific.

### Props

| Arguments            | Description              | Type                         | Default |
| -------------------- | ------------------------ | ---------------------------- | ------- |
| `model-value`        | Bound value              | `string`                     | `-`     |
| `format`             | Color format             | `hex \| rgb`                 | `-`     |
| `size`               | Size                     | `xs \| sm \| md \| lg \| xl` | `md`    |
| `show-text`          | Show color value         | `boolean`                    | `false` |
| `show-history`       | Show history colors      | `boolean`                    | `false` |
| `show-preset`        | Show preset colors       | `boolean`                    | `false` |
| `disabled`           | Disable interaction      | `boolean`                    | `false` |
| `disabled-alpha`     | Disable alpha            | `boolean`                    | `false` |
| `color-picker-props` | Forwarded to ColorPicker | `object`                     | `{}`    |

### Form field presentation and confirmation

This component supports `edit-mode` with field > FormItem > Form precedence. When unset, it defaults to `direct` and preserves `direct` editing. Supported values: `direct / click / dblclick`. Non-`direct` modes open the editor through the field value trigger and keep one draft; v-model updates only after confirmation. Cancel, reset or enabling readPretty discards the draft.

Cedar uses edit-mode="click" / "dblclick" to open an editor popup near the field. Enter/F2 also opens it; cancel/Escape discards the draft, and confirmation commits it. readPretty is an independent reading setting, separate from readonly and disabled.

`before-commit(value, { previousValue, signal })` can reject an overlay save. FormItem validates the candidate first and keeps the editor open on failure. `open / default-open / update:open` control the editor. Use `#read="{ value, text }"` to customize display. See the full field comparison in Form.

`read-pretty` is an independent boolean alongside `readonly` and `disabled`. It inherits from field to FormItem to Form; explicit `false` overrides the parent. The default is `false`. Reading mode renders no editor.

Dragging uses the control owner view. KeepAlive deactivation or unmount ends the gesture and releases its listeners; a new activation requires a new gesture, and callbacks from old gestures cannot change its value.

---

Document: llms/en-US/components/config-provider.md

<!-- Source: src/config-provider/README.en-US.md; locale: en-US; page: /en/components/config-provider/ -->

# Config Provider

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

- `size`: ComponentSize

Example source: src/config-provider/__demos__/basic.vue

```vue
<template>
  <c-space direction="column">
    <c-button @click="large = !large">切换尺寸</c-button>
    <c-config-provider :size="large ? 'lg' : 'sm'">
      <c-space>
        <c-input placeholder="继承全局尺寸" />
        <c-button>继承尺寸</c-button>
      </c-space>
    </c-config-provider>
    <p role="status">当前尺寸：{{ large ? 'lg' : 'sm' }}</p>
  </c-space>
</template>
<script lang="ts" setup>
import { ref } from 'vue'
const large = ref(false)
</script>
```

## API

### ConfigProvider Props

| Prop | Description | Type | Default |
| ---- | -------- | ------ | ------ |
| dir | Reading direction; inherits the source scope when omitted. Physical left/right placements keep their meaning. | `ReadingDirection` (`ltr` / `rtl`) | — |
| type | Argument type | string | - |

### ConfigProvider Events

| Event | Description | Arguments |
| ------ | -------------- | ----------------------------- |
| click | Click event | `(event: MouseEvent) => void` |

### ConfigProvider Slots

| Slot | Description |
| ------- | -------------- |
| default | Custom default content |

## Type definitions

The component exports the following types

```ts
import type { ConfigProviderProps } from '@cedar-design/ui'
```


## Reading direction

Use `<c-config-provider dir="rtl">` to scope right-to-left layout. Omit `dir` to inherit, or nest `dir="ltr"` for a local override. Native DOM `dir` containers work too. The provider renders a `display: contents` div to carry direction to ordinary descendants without adding a layout box; place it in an HTML context that permits a div. It does not change the document direction. The former boolean `rtl` option is replaced by `dir` before release. Physical left/right placements retain their meaning.

---

Document: llms/en-US/components/count-to.md

<!-- Source: src/count-to/README.en-US.md; locale: en-US; page: /en/components/count-to/ -->

# Count To

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

Preview configuration: `:to="123456"`.

Example source: src/count-to/__demos__/basic.vue

```vue
<template>
  <c-count-to :to="123456" />
</template>
```

## Content and presentation

### Precision, duration and easing

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `to` | Target value | Precision, duration and easing |
| `precision` | Decimal precision | Precision, duration and easing |
| `duration` | Animation duration in milliseconds | Precision, duration and easing |
| `timing-function` | Animation easing function | Precision, duration and easing |
<!-- demo-config-notes:end -->


Compare final precision and the effect of duration and easing on number transitions. Manual playback remains separate.

Example source: src/count-to/__demos__/number-format-comparison.vue

```vue
<script setup lang="ts">
import { proxyRefs as demoProxyRefs } from 'vue'

const scene3 = demoProxyRefs((() => {

const easeOutCubic = (v: number) => 1 - Math.pow(1 - v, 3)
return { easeOutCubic }
})())
</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="precision">
    <h4><span lang="zh-CN">精度</span><span lang="en-US">precision</span></h4>
    <c-count-to :to="123456" :precision="2" />
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="duration">
    <h4><span lang="zh-CN">自定义时长</span><span lang="en-US">duration</span></h4>
    <c-count-to :to="123456" :duration="10000" />
  </section>

  <section class="demo-comparison-case demo-comparison-case--3" data-comparison-scene="timing-function">
    <h4><span lang="zh-CN">自定义动画曲线</span><span lang="en-US">timing function</span></h4>
    <c-count-to :to="123456" :timing-function="scene3.easeOutCubic" />
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

## Customization and slots

### Custom

Preview configuration: `:to="123456"`.

Example source: src/count-to/__demos__/custom.vue

```vue
<template>
  <c-count-to :to="123456">
    <template #default="{ value }">
      {{ value.toLocaleString() }}
    </template>
  </c-count-to>
</template>
```

## Interaction and control

### Manual

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `to` | Target value | Manual |
| `auto-start` | Whether to start animation automatically | Manual |
<!-- demo-config-notes:end -->


Preview configuration: `:to="123456"`, `:auto-start="false"`.

Example source: src/count-to/__demos__/manual.vue

```vue
<template>
  <c-space direction="column">
    <c-count-to ref="countToRef" :to="123456" :auto-start="false" />
    <c-space>
      <c-button status="primary" @click="countToRef?.start()">开始</c-button>
      <c-button @click="countToRef?.pause()">暂停</c-button>
      <c-button @click="countToRef?.reset()">重置</c-button>
    </c-space>
  </c-space>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import type { CountToInstance } from '../index'

const countToRef = ref<CountToInstance>()
</script>
```

## API

### CountTo Props

| Prop | Description | Type | Default |
| ----------------- | ------------------------ | ------------------------ | -------- |
| from | Start value | _number \| string_ | `0` |
| to | Target value | _number \| string_ | `0` |
| duration | Animation duration in milliseconds | _number \| string_ | `2000` |
| precision | Decimal precision | _number \| string_ | `0` |
| auto-start | Whether to start animation automatically | _boolean_ | `true` |
| timing-function | Animation easing function | _(v: number) => number_ | `-` |

### CountTo Events

| Event | Description | Callback arguments |
| ------ | -------------- | -------- |
| end | Triggered when animation ends | `-` |

### CountTo Slots

| Slot | Description | Arguments |
| ------- | ---------- | ----------------- |
| default | Custom content | `value: number` |

### CountTo Methods

| Method | Description | Arguments | Returns |
| ------ | ---------------------------------------------------------------- | ---- | ------ |
| start | Start the animation | `-` | `-` |
| pause | Pause the animation | `-` | `-` |
| reset | Reset the animation; when `auto-start` is `true`, playback starts automatically after reset | `-` | `-` |

## Type definitions

The component exports the following types

```ts
import type { CountToProps, CountToInstance } from '@cedar-design/ui'
```

### Style variables

| Variable | Default |
| ----------------------------- | -------------------------- |
| `--c-count-to-text-color` | `var(--c-sys-color-content-primary)` |
| `--c-count-to-text-font-size` | `var(--c-font-size-lg)` |

## Shared implementation and platform boundaries

Each platform maintains a complete local implementation. They do not import a common core or share component instances or reactive state. Changes must update both implementations. Component bodies, props, key styles and paired tests have read-only source consistency checks; theme tokens and installation entries remain local to each library.

Animation pauses on unmount and KeepAlive deactivation and resumes on reactivation. Each instance keeps independent values and animation state.

---

Document: llms/en-US/components/countdown.md

<!-- Source: src/countdown/README.en-US.md; locale: en-US; page: /en/components/countdown/ -->

# Countdown

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

Preview configuration: `:time="2 * 60 * 60 * 1000"`.

Example source: src/countdown/__demos__/basic.vue

```vue
<template>
  <c-countdown :time="2 * 60 * 60 * 1000" />
</template>
```

## Content and presentation

### Time format and custom content

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `time` | Countdown duration in milliseconds | Time format and custom content, Statistic |
| `format` | Display format | Time format and custom content, Statistic |
<!-- demo-config-notes:end -->


Compare unit formats, milliseconds and custom time fragments, independently of playback controls.

Example source: src/countdown/__demos__/format-comparison.vue

```vue
<script setup lang="ts">


</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="format">
    <h4><span lang="zh-CN">自定义格式</span><span lang="en-US">format</span></h4>
    <c-countdown :time="4 * 24 * 60 * 60 * 1000" format="DD 天 HH 时 mm 分 ss 秒" />
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="millisecond">
    <h4><span lang="zh-CN">显示毫秒</span><span lang="en-US">millisecond</span></h4>
    <c-countdown :time="2 * 60 * 60 * 1000" format="HH:mm:ss.SSS" />
  </section>

  <section class="demo-comparison-case demo-comparison-case--3" data-comparison-scene="custom">
    <h4><span lang="zh-CN">自定义样式</span><span lang="en-US">custom</span></h4>
    <c-countdown :time="108000000">
        <template #default="{ hours, minutes, seconds }">
          <span class="countdown-block">{{ hours }}</span>
          <span class="countdown-colon">:</span>
          <span class="countdown-block">{{ minutes }}</span>
          <span class="countdown-colon">:</span>
          <span class="countdown-block">{{ seconds }}</span>
        </template>
      </c-countdown>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }
.demo-comparison-case--3 {

.countdown-block {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  width: 36px;
  height: 36px;
  color: var(--c-color-white);
  background: var(--c-color-primary-6);
  border-radius: 8px;
}

.countdown-colon {
  margin: 0 6px;
  font-weight: 500;
}

}
</style>
```

### Statistic

- `format`: Controls the displayed format.

Example source: src/countdown/__demos__/statistic.vue

```vue
<template>
  <c-space size="xl" wrap>
    <c-statistic title="Countdown">
      <c-countdown :time="2 * 60 * 60 * 1000" />
    </c-statistic>
    <c-statistic title="Campaign">
      <c-countdown :time="4 * 24 * 60 * 60 * 1000" format="DD 天 HH 时 mm 分 ss 秒" />
    </c-statistic>
  </c-space>
</template>
```

## Interaction and control

### Manual

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `time` | Countdown duration in milliseconds | Manual |
| `auto-start` | Whether to auto start count down | Manual |
| `format` | Display format | Manual |
<!-- demo-config-notes:end -->


- `format`: Controls the displayed format.

Example source: src/countdown/__demos__/manual.vue

```vue
<template>
  <c-space direction="column" align="flex-start">
    <c-countdown
      ref="countdownRef"
      :time="5000"
      :auto-start="false"
      format="ss.SSS"
      @end="handleEnd"
    />
    <c-space>
      <c-button status="primary" @click="countdownRef?.start()">开始</c-button>
      <c-button @click="countdownRef?.pause()">暂停</c-button>
      <c-button @click="countdownRef?.reset()">重置</c-button>
    </c-space>
  </c-space>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import { Message } from '@cedar-design/ui'
import type { CountdownInstance } from '../index'

const countdownRef = ref<CountdownInstance>()

const handleEnd = () => {
  Message.info('end!')
}
</script>
```

## API

### Countdown Props

| Prop | Description | Type | Default |
| ------------- | ------------------------------------------ | -------------------- | ------------ |
| `time` | Countdown duration in milliseconds | `number \| string` | `0` |
| `format` | Display format | `string` | `'HH:mm:ss'` |
| `auto-start` | Whether to auto start count down | `boolean` | `true` |

### format placeholders

| Format | Description |
| ----- | ------------- |
| `DD` | Day |
| `HH` | Hour |
| `mm` | Minute |
| `ss` | Seconds |
| `S` | Milliseconds: 1 digit |
| `SS` | Milliseconds: 2 digits |
| `SSS` | Milliseconds: 3 digits |

### Countdown Events

| Event | Description | Arguments |
| -------- | ---------------- | --------------------- |
| `change` | Emitted after countdown changed | `timeData: TimeData` |
| `end` | Emitted after countdown ended | `-` |

### Countdown Slots

| Slot | Description | Arguments |
| --------- | ---------- | --------------------- |
| `default` | Custom content | `timeData: TimeData` |

### TimeData

| Name | Description | Type |
| -------------- | -------- | -------- |
| `days` | Remain days | `number` |
| `hours` | Remain hours | `number` |
| `minutes` | Remain minutes | `number` |
| `seconds` | Remaining seconds | `number` |
| `milliseconds` | Remain milliseconds | `number` |

### Countdown Methods

| Method | Description | Arguments | Returns |
| ------- | ----------------------------------------------------------------- | ---- | ------ |
| `start` | Start countdown | `-` | `-` |
| `pause` | Pause countdown | `-` | `-` |
| `reset` | Reset the countdown; when `auto-start` is `true`, it starts automatically after reset | `-` | `-` |

## Type definitions

The component exports the following types

```ts
import type { CountdownProps, CountdownInstance, TimeData } from '@cedar-design/ui'
```

### Style variables

| Variable | Default |
| ------------------------------- | -------------------------- |
| `--c-countdown-text-color` | `var(--c-sys-color-content-primary)` |
| `--c-countdown-text-font-size` | `var(--c-font-size-lg)` |

## Shared implementation and platform boundaries

Each platform maintains a complete local implementation. They do not import a common core or share component instances or reactive state. Changes must update both implementations. Component bodies, props, key styles and paired tests have read-only source consistency checks; theme tokens and installation entries remain local to each library.

SSR renders the initial formatted time. Changing format while paused updates the display. The finish event fires once per round; reset starts another round. Unmounting cleans up animation frames.

---

Document: llms/en-US/components/date-picker.md

<!-- Source: src/date/picker/README.en-US.md; locale: en-US; page: /en/components/date-picker/ -->

# Date Picker

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

- `default-value`: Default value

Example source: src/date/picker/__demos__/basic.vue

```vue
<template>
  <c-date-picker default-value="2019-06-03" />
</template>
```

## Date views and presentation

### Mode

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `type` | Panel type | Mode, Month Labels, Locale Isolation |
| `disable-confirm` | Commit immediately | Month Labels, Responsive Panels |
| `day-start-of-week` | First weekday, calendar only; integer 0–6 | Locale Isolation |
| `show-time` | Include time selection | Responsive Panels |
<!-- demo-config-notes:end -->


Preview configuration: `type="week"`, `type="month"`, `type="year"`, `type="quarter"`.

Example source: src/date/picker/__demos__/mode.vue

```vue
<template>
  <c-space direction="column" fill>
    <c-date-picker type="week" />
    <c-date-picker type="month" />
    <c-date-picker type="year" />
    <c-date-picker type="quarter" />
  </c-space>
</template>
```

### Month Labels

- `picker-value`: The date displayed in the default panel
- `abbreviation`: Whether to enable abbreviation

Example source: src/date/picker/__demos__/month-labels.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const abbreviation = ref(true)
</script>

<template>
  <c-checkbox v-model="abbreviation">月份缩写</c-checkbox>
  <c-date-picker type="month" picker-value="2025-01" :abbreviation="abbreviation" :disable-confirm="false" />
  <c-date-range-picker type="month" :abbreviation="abbreviation" />
</template>
```

### Locale Isolation

- `picker-value`: The date displayed in the default panel
- `day-start-of-week`: The first day of the week starts on the day of the week, 0-Sunday, 1-Monday, and so on.

Example source: src/date/picker/__demos__/locale-isolation.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const first = ref('2021-01-03')
const second = ref('2021-01-03')
const monday = ref(true)
const monthModel = ref('2025 January 15')
</script>

<template>
  <p>两个实例独立管理周起始日。可切换顶部语言，模型不随展示语言改变。</p>
  <c-date v-model="first" type="week" :date-picker-props="{ dayStartOfWeek: 0 }" />
  <c-date v-model="second" type="week" :date-picker-props="{ dayStartOfWeek: monday ? 1 : 2 }" />
  <c-checkbox v-model="monday">第二个实例周一起始（关闭为周二）</c-checkbox>
  <c-date-picker type="week" v-model="first" picker-value="2021-01-01" :day-start-of-week="0" />
  <c-date-picker type="week" v-model="second" picker-value="2021-01-01" :day-start-of-week="monday ? 1 : 2" />
  <c-date v-model="monthModel" value-format="YYYY MMMM DD" format="YYYY MMMM DD" />
  <p>月份名称模型（稳定英文协议）：{{ monthModel }}</p>
</template>
```

### Responsive Panels

- `show-time`: Whether to increase time selection
- `shortcuts`: Quick selection of preset time range
- `shortcuts-position`: The position of the preset range on the panel, which is placed at the bottom by default, and the side is generally used for scenes with a large number of preset times

Example source: src/date/picker/__demos__/responsive-panels.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
const selected = ref("2026-10-20 09:30:00");
const selectedRange = ref(["2026-10-20 09:30:00", "2026-10-22 18:00:00"]);
const position = ref<"left" | "right" | "bottom">("left");
const positions = ["left", "right", "bottom"].map((value) => ({
  label: value,
  value,
}));
const types = ["date", "month", "year"] as const;
const shortcuts = [{ label: "本月工作日范围", value: "2026-10-20 09:30:00" }];
const rangeShortcuts = [
  {
    label: "本月工作日范围",
    value: ["2026-10-20 09:30:00", "2026-10-22 18:00:00"],
  },
];
</script>
<template>
  <div>
    <c-form-item layout="vertical" size="sm" label="独立面板快捷位置">
      <c-radio-group
        v-model="position"
        aria-label="独立面板快捷位置"
        :options="positions"
        variant="button"
        size="sm"
      />
    </c-form-item>

    <section
      v-for="type in types"
      :key="type"
      :aria-label="'独立 ' + type + ' 面板'"
    >
      <h4>{{ type }} · DatePicker / DateRangePicker</h4>
      <c-date-picker :type="type" :disable-confirm="false" />
      <c-date-range-picker :type="type" :disable-confirm="false" />
    </section>
    <section aria-label="独立日期时间面板">
      <h4>DatePicker · 时间与快捷项</h4>
      <c-date-picker
        v-model="selected"
        show-time
        :shortcuts="shortcuts"
        :shortcuts-position="position"
        :disable-confirm="false"
      />
    </section>
    <p role="status" aria-label="独立日期时间已提交">{{ selected }}</p>
    <section aria-label="独立日期时间范围面板">
      <h4>DateRangePicker · 时间与快捷项</h4>
      <c-date-range-picker
        v-model="selectedRange"
        show-time
        :shortcuts="rangeShortcuts"
        :shortcuts-position="position"
        :disable-confirm="false"
      />
    </section>
    <p role="status" aria-label="独立日期时间范围已提交">{{ selectedRange }}</p>
  </div>
</template>
```

## Time and selection rules

### Show Time

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `show-time` | Include time selection | Show Time, Disabled Parts, Time Presentation |
| `format` | Display format | Show Time, Time Presentation |
| `value-format` | Model and event value format: a date format string, Date, or timestamp | Current Range, Time Presentation |
| `default-value` | Uncontrolled initial value, read once | Show Time |
| `disabled-date` | Return true to disable a date | Disabled Parts |
| `disabled-time` | Disabled times for the current date and endpoint | Disabled Parts |
<!-- demo-config-notes:end -->


- `show-time`: Whether to increase time selection
- `default-value`: Default value
- `format`: Display the format of the date, refer to [String Parsing Format](#string-parsing-format)

Example source: src/date/picker/__demos__/show-time.vue

```vue
<template>
  <c-date-picker
    show-time
    default-value="2025-01-15 09:09:06"
    format="YYYY-MM-DD HH:mm:ss"
  />
</template>
```

### Disabled Parts

- `disabled-date`: Unselectable date
- `show-time`: Whether to increase time selection
- `disabled-time`: Unselectable time

Example source: src/date/picker/__demos__/disabled-parts.vue

```vue
<template>
  <c-date-picker style="margin: 0 24px 24px 0"
    :disabled-date="(current: any) => dayjs(current).isBefore(dayjs())"
  />
  <c-date-picker style="margin-right: 24px; margin-bottom: 24px"
    show-time
    :disabled-date="(current: any) => dayjs(current).isBefore(dayjs())"
    :disabled-time="getDisabledTime"
  />
</template>

<script lang="ts">
import { defineComponent } from 'vue'
import dayjs from 'dayjs'

export default defineComponent({
  setup() {
    function range(start: any, end: any) {
      const result = []
      for (let i = start; i < end; i++) {
        result.push(i)
      }
      return result
    }

    function getDisabledTime(date: any) {
      return {
        disabledHours: () => range(6, 24),
        disabledMinutes: () => range(30, 60),
        disabledSeconds: () => range(30, 60),
      }
    }
    return {
      dayjs,
      getDisabledTime,
    }
  },
})
</script>
```

### Current Range

- `value-format`: The format of the value, valid for `value` `defaultValue` `pickerValue` `defaultPickerValue` and the return value in the event, supports setting as timestamp, Date and string (refer to [String parsing format](#string-parsing-format) ). If not specified, it will be formatted as a string, in the same format as `format`.
- `default-picker-value`: Date displayed on the panel
- `show-now-button`: Whether to display the now button when showTime

Example source: src/date/picker/__demos__/current-range.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'

const yesterday = new Date()
yesterday.setDate(yesterday.getDate() - 1)
const selected = ref(yesterday)
const showCurrent = ref(true)
const showNowButton = ref(true)
const exchangeTime = ref(true)
const range = ref(['2025-01-05 09:00', '2025-01-10 18:00'])
</script>
<template>
  <div>
    <p>今日高亮和选择当前是两个独立功能。</p>
    <c-checkbox v-model="showCurrent"> 今日高亮</c-checkbox>
    <c-checkbox v-model="showNowButton"> 选择当前按钮</c-checkbox>
    <c-date-picker
      v-model="selected"
      value-format="Date"
      :default-picker-value="new Date()"
      :show-current="showCurrent"
      :show-now-button="showNowButton"
      :disable-confirm="false"
    />
    <p>确认后选中：{{ selected }}</p>
    <c-checkbox v-model="exchangeTime"> 日期反序时连同时间交换</c-checkbox>
    <p>先选较晚日期，再选较早日期，对比起止时间。</p>
    <c-date-range-picker
      v-model="range"
      show-time
      format="YYYY-MM-DD HH:mm"
      value-format="YYYY-MM-DD HH:mm"
      :exchange-time="exchangeTime"
      :disable-confirm="false"
    />
    <p>确认后范围：{{ range }}</p>
  </div>
</template>
```

### Time Presentation

- `model-value`: Value
- `show-time`: Whether to increase time selection
- `format`: Display the format of the date, refer to [String Parsing Format](#string-parsing-format)
- `value-format`: The format of the value, valid for `value` `defaultValue` `pickerValue` `defaultPickerValue` and the return value in the event, supports setting as timestamp, Date and string (refer to [String parsing format](#string-parsing-format) ). If not specified, it will be formatted as a string, in the same format as `format`.

Example source: src/date/picker/__demos__/time-presentation.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'

const use12Hours = ref(true)
const timeOptions = { step: { minute: 15 }, hideDisabledOptions: true }
</script>

<template>
  <c-checkbox v-model="use12Hours">十二小时展示</c-checkbox>

  <c-date-picker
    model-value="2025-01-05 13:30"
    show-time
    format="YYYY-MM-DD HH:mm"
    value-format="YYYY-MM-DD HH:mm"
    :time-picker-props="{ ...timeOptions, use12Hours }"
  />
</template>
```

## Shortcuts and customization

### Short Cuts

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `disable-confirm` | Commit immediately | Panel Tools, Entry Boundary |
| `show-time` | Include time selection | Short Cuts |
| `day-start-of-week` | First weekday, calendar only; integer 0–6 | Entry Boundary |
<!-- demo-config-notes:end -->


- `shortcuts`: Quick selection of preset time range
- `show-time`: Whether to increase time selection

Example source: src/date/picker/__demos__/short-cuts.vue

```vue
<template>
  <c-date-picker style="margin: 0 24px 24px 0"
    :shortcuts="[
      {
        label: '2 hours later',
        value: () => dayjs().add(2, 'hour'),
      },
      {
        label: 'a week later',
        value: () => dayjs().add(1, 'week'),
      },
      {
        label: 'a month later',
        value: () => dayjs().add(1, 'month'),
      },
    ]"
    show-time
  />
</template>

<script lang="ts">
import { defineComponent } from 'vue'
import dayjs from 'dayjs'

export default defineComponent({
  setup() {
    return {
      dayjs,
    }
  },
})
</script>
```

### Footer

Preview configuration: `showTime`.

Example source: src/date/picker/__demos__/footer.vue

```vue
<template>
  <c-date-picker style="margin-bottom: 20px">
    <template #extra>Extra footer</template>
  </c-date-picker>
  <br />
  <c-date-range-picker showTime>
    <template #extra>Extra footer</template>
  </c-date-range-picker>
</template>

<script lang="ts">
import { defineComponent } from 'vue'
export default defineComponent({
  })
</script>
```

### Panel Tools

- `picker-value`: The date displayed in the default panel
- `shortcuts`: Quick selection of preset time range

Example source: src/date/picker/__demos__/panel-tools.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
const selected = ref("2025-01-15");
const viewport = ref("2025-01-01");
const acceptNavigation = ref(true);
const shortcuts = [
  { label: "月初", value: "2025-01-01" },
  { label: "下个月", value: () => "2025-02-01" },
  { label: "不可选", value: "2025-03-01", disabled: true },
];
function navigate(value: unknown) {
  if (acceptNavigation.value && typeof value === "string")
    viewport.value = value;
}
</script>
<template>
  <div>
    <p>选择值：{{ selected }}；视口：{{ viewport }}</p>
    <c-checkbox v-model="acceptNavigation"> 接受视口导航</c-checkbox>
    <c-date-picker
      v-model="selected"
      :picker-value="viewport"
      :shortcuts="shortcuts"
      :disable-confirm="false"
      @update:picker-value="navigate"
    />
    <p>范围快捷项走同一套确认与校验。</p>
    <c-date-range-picker
      :default-value="['2025-01-10', '2025-01-15']"
      :shortcuts="[{ label: '第一周', value: ['2025-01-01', '2025-01-07'] }]"
      :disable-confirm="false"
    />
  </div>
</template>
```

### Entry Boundary

- `min`: Sets the lower bound.
- `max`: Sets the upper bound.
- `day-start-of-week`: The first day of the week starts on the day of the week, 0-Sunday, 1-Monday, and so on.

Example source: src/date/picker/__demos__/entry-boundary.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import type { DateSelection } from "@cedar-design/ui";
const limited = ref(true);
const fieldValue = ref<DateSelection>("2025-02-12");
const panelValue = ref<DateSelection>("2025-02-12");
const week = ref<0 | 1 | 6>(1);
</script>

<template>
  <div class="entry-demo">
    <p>仅允许选择 2025 年 2 月；移除限制不会改变已有选中值。</p>
    <c-button @click="limited = !limited">{{
      limited ? "移除日期限制" : "恢复日期限制"
    }}</c-button>
    <c-space wrap>
      <c-button @click="week = 0">周日起始</c-button>
      <c-button @click="week = 1">周一起始</c-button>
      <c-button @click="week = 6">周六起始</c-button>
    </c-space>
    <div>
      <p>字段：管理输入与浮层；面板参数放在 date-picker-props。</p>
      <c-date
        :min="limited ? '2025-02-01' : undefined"
        :max="limited ? '2025-02-28' : undefined"
        v-model="fieldValue"
        :date-picker-props="{ dayStartOfWeek: week }"
        placeholder="选择日期"
      />
    </div>
    <div>
      <p>纯面板：直接嵌入页面，不使用 open / popup-container。</p>
      <c-date-picker
        :min="limited ? '2025-02-01' : undefined"
        :max="limited ? '2025-02-28' : undefined"
        v-model="panelValue"
        :day-start-of-week="week"
        :disable-confirm="false"
      />
      <p>已提交：{{ panelValue }}</p>
    </div>
  </div>
</template>

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

## Reading direction

Inherits the nearest `dir="ltr|rtl"`, including runtime changes and local overrides. Calendar dates, months and years follow reading order; navigation icons mirror, while date values keep their meaning. In paged grids, Left/Right moves focus visually, Up/Down moves one row, and Home/End moves to the row boundary, skipping disabled items. Focus navigation does not select; Enter/Space keeps the existing selection behavior. Navigation is bounded by the displayed grid. Explicit `shortcuts-position="left|right"` remains physical; `bottom` stays below. Field popovers inherit their source direction.

## API

### Props

Pure panels do not accept field/popup props such as open/default-open, popup-container, placement, trigger-props, placeholder, variant or clearable. Configure popups through Date/DateRange popup-props, and typing through input-editable. disable-confirm alone controls confirmation tools; show-confirm-btn is removed.

| Arguments | Description | Type | Default |
| ------------------- | ------------------------------- | ------------------------------------------ | ------- |
| `model-value` | Bound value | `Date \| string \| number` | `-` |
| `type` | Panel type | `date \| week \| month \| year \| quarter` | `date` |
| `format` | Display format | `string \| Function` | `-` |
| `day-start-of-week` | First weekday, calendar only; integer 0–6 | `DateWeekStart` | `0` |
| `readonly` | Readonly; does not change selection | `boolean` | `false` |
| `time-picker-props` | Local time-panel display options | `Partial<TimePickerProps>` | `-` |
| `show-time` | Include time selection | `boolean` | `false` |
| `disabled` | Disable interaction | `boolean` | `false` |
| `disabled-date` | Return true to disable a date | `Function` | `-` |

Desktop calendar capabilities, including shortcuts, footer and cell slots, remain in a separate presentation implementation.

### Shared date-family contract

| Arguments | Description | Type | Default |
| ----------------- | ------------------------------------------------------- | ------------------------------------------------ | ------- |
| `default-value` | Uncontrolled initial value, read once | DateValue / DateValue[] | — |
| `value-format` | Model and event value format: a date format string, Date, or timestamp | string | Follows type |
| `min` / `max` | Inclusive bounds; string bounds use value-format | DateValue | — |
| `disabled-time` | Disabled times for the current date and endpoint | (date: Date, side: DateSide) => DateDisabledTime | — |
| `disable-confirm` | Commit immediately | boolean | true |

`DateValue = Date | string | number`. Clearing a single value produces undefined; clearing a range produces [].
The date argument of `disabledDate(date, side)` and `disabledTime(date, side)` is always a Date; side is start/end.
Time callbacks return numeric lists from `disabledHours()`, `disabledMinutes(hour)` and `disabledSeconds(hour, minute)`.
Invalid dates and incomplete/reversed ranges cannot be committed. Confirmation revalidates dynamic disabling rules. Locked range endpoints cannot be cleared or changed.
Nested panel props configure presentation only; they must not override top-level model-value, format, bounds, disabling rules or control events.

### Events

| Event | Description | Arguments |
| -------------------- | ----------------------- | --------------------------------- |
| `update:model-value` | Request a model update | value |
| `select` | Select a draft; does not imply submission | value, date(s), formatted text(s) |
| `change` | Committed value changes | value, date(s), formatted text(s) |
| `confirm` | Confirm valid selection; does not use ok | value, date(s), formatted text(s) |

Set `:disable-confirm="false"` to show confirmation tools. The `actions` slot provides `{ confirm, disabled }`; custom `actions` must still call confirm to validate.

---

Document: llms/en-US/components/date-range.md

<!-- Source: src/date-range/README.en-US.md; locale: en-US; page: /en/components/date-range/ -->

# DateRange

A date range field. The bound model is an array; use DateRangePicker for a standalone panel.

## String range models

Set format="MM-DD" and value-format="MM-DD" to get ['09-10', '10-10'] directly. These values have no year; parsing uses the current year and cannot preserve cross-year ordering. For real bookings store YYYY-MM-DD and map the payload in application code. format only changes display, while value-format changes the model and events.

Without time-zone the browser-local time zone remains in effect. An explicit IANA time zone changes the civil-time interpretation of strings; Date/timestamp values preserve their instant. Editing one endpoint does not change an untouched endpoint's repeated-hour occurrence or milliseconds.

## Basic examples

### Basic

Example source: src/date-range/__demos__/basic.vue

```vue
<template>
  <c-date-range v-model="range" style="width: 300px" clearable />
</template>

<script setup>
import { ref } from 'vue'

const range = ref()
</script>
```

### Interaction state comparison

Toggle disabled, read-only and error states, then interact with the same instance. Recovery controls remain outside the target; error appearance alone does not validate data.

<details>
<summary>Configuration details and limits</summary>

#### State Lab

## Appearance and date presentation

### Appearance configuration comparison

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration  | Purpose                                                                | Related examples                    |
| -------------- | ---------------------------------------------------------------------- | ----------------------------------- |
| `clearable`    | Show the clear action                                                  | Mode, Separator                     |
| `value-format` | Model and event value format: a date format string, Date, or timestamp | Appearance configuration comparison |
| `type`         | Mode                                                                   | Mode                                |
| `separator`    | Range separator                                                        | Separator                           |
| `placeholder`  | Placeholder                                                            | Separator                           |

<!-- demo-config-notes:end -->

Choose a dimension to compare all its values side by side while keeping other settings and content identical. Change the other settings to inspect combinations; input specimens share one model.

Example source: src/date-range/__demos__/appearance-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref(["2026-10-23", "2026-10-25"]);
const __demoAppearance = __demoReactive({ variant: "filled", size: "md" });

import { computed as demoComputed, ref as demoRef } from 'vue'
const demoCompareFields = [{"name":"variant","values":["filled","outline","standard"]},{"name":"size","values":["xs","sm","md","lg","xl"]}]
const demoCompareAxis = demoRef("variant")
const demoComparedOptions = demoComputed(() => demoCompareFields.find(field => field.name === demoCompareAxis.value)?.values ?? [])
</script>
<template>
  <c-space direction="column" :size="16">
    <c-form layout="vertical">
      <c-form-item layout="vertical" size="sm" label="variant">
        <c-radio-group
          v-model="__demoAppearance['variant']"
          aria-label="variant"
          :options="[
            { label: 'filled', value: 'filled' },
            { label: 'outline', value: 'outline' },
            { label: 'standard', value: 'standard' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
      <c-form-item layout="vertical" size="sm" label="size">
        <c-radio-group
          v-model="__demoAppearance['size']"
          aria-label="size"
          :options="[
            { label: 'xs', value: 'xs' },
            { label: 'sm', value: 'sm' },
            { label: 'md', value: 'md' },
            { label: 'lg', value: 'lg' },
            { label: 'xl', value: 'xl' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
    </c-form>
    <p class="demo-config-comparison-hint"><span lang="zh-CN">选择一个对比维度；其他配置和内容保持一致。输入类示例共享同一个值，便于比较外观。</span><span lang="en-US">Compare one dimension while keeping the other settings and content identical. Input specimens share the same value.</span></p>
<c-radio-group v-model="demoCompareAxis" aria-label="Compare configuration" :options="demoCompareFields.map(field => ({ label: field.name, value: field.name }))" />
<div class="demo-config-comparison">
<section v-for="sample in demoComparedOptions" :key="String(sample)">
<p><code>{{ demoCompareAxis }}={{ sample }}</code></p>
<c-date-range
      v-model="value"
      value-format="YYYY-MM-DD"
      v-bind="{ ...__demoAppearance, [demoCompareAxis]: sample }"
    ></c-date-range>
</section>
</div>
  </c-space>
</template>

<style scoped>
.demo-config-comparison { display: grid; grid-template-columns: repeat(auto-fit, minmax(min(100%, 220px), 1fr)); gap: 20px; min-width: 0; max-width: 100%; }
.demo-config-comparison > section { min-width: 0; }
.demo-config-comparison p { margin: 0 0 8px; }
html:not([lang='en-US']) .demo-config-comparison-hint > [lang='en-US'],
html[lang='en-US'] .demo-config-comparison-hint > [lang='zh-CN'] { display: none; }
</style>
```

### Mode

Example source: src/date-range/__demos__/mode.vue

```vue
<template>
  <c-space direction="column" fill>
    <c-date-range v-model="dateRange" style="width: 300px" clearable />
    <c-date-range v-model="weekRange" type="week" style="width: 300px" clearable />
    <c-date-range v-model="monthRange" type="month" style="width: 300px" clearable />
    <c-date-range v-model="yearRange" type="year" style="width: 300px" clearable />
    <c-date-range v-model="quarterRange" type="quarter" style="width: 300px" clearable />
  </c-space>
</template>

<script setup>
import { ref } from 'vue'

const dateRange = ref()
const weekRange = ref()
const monthRange = ref()
const yearRange = ref()
const quarterRange = ref()
</script>
```

### Separator

Example source: src/date-range/__demos__/separator.vue

```vue
<template>
  <c-date-range
    v-model="range"
    style="width: 300px"
    separator=" 至 "
    :placeholder="['开始日期', '结束日期']"
    clearable
  />
</template>

<script setup>
import { ref } from 'vue'

const range = ref()
</script>
```

## Time and range rules

### Show Time

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration   | Purpose                                                                | Related examples      |
| --------------- | ---------------------------------------------------------------------- | --------------------- |
| `format`        | Display format                                                         | Show Time, Boundaries |
| `show-time`     | Include time selection                                                 | Show Time             |
| `clearable`     | Show the clear action                                                  | Show Time             |
| `value-format`  | Model and event value format: a date format string, Date, or timestamp | Boundaries            |
| `disabled-date` | Return true to disable a date                                          | Boundaries            |

<!-- demo-config-notes:end -->

Example source: src/date-range/__demos__/show-time.vue

```vue
<template>
  <c-date-range
    v-model="range"
    style="width: 380px"
    show-time
    format="YYYY-MM-DD HH:mm:ss"
    clearable
  />
  <p role="status" aria-label="Date-time range model">{{ JSON.stringify(range) ?? 'undefined' }}</p>
</template>

<script setup>
import { ref } from 'vue'

const range = ref()
</script>
```

### Boundaries

Example source: src/date-range/__demos__/boundaries.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const value = ref(['2026/09/10', '2026/09/15'])
const disabledDate = (date: Date, side: 'start' | 'end') => side === 'end' && date.getDay() === 0
</script>
<template>
  <div class="date-contract-demo">
    <c-date-range v-model="value" value-format="YYYY/MM/DD" format="DD-MM-YYYY"
      min="2026/09/01" max="2026/09/30" :disabled-date="disabledDate" />
    <p>仅可选九月，结束日期不能是周日。请选齐两个端点；确认提交，Escape 取消草稿。</p>
    <output>{{ value }}</output>
  </div>
</template>
<style scoped>
.date-contract-demo { display: flex; flex-direction: column; gap: 12px; }
.date-contract-demo p { margin: 0; }
</style>
```

## Value model and text input

### String Values

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration  | Purpose                                                                | Related examples          |
| -------------- | ---------------------------------------------------------------------- | ------------------------- |
| `format`       | Display format                                                         | String Values, Text Entry |
| `value-format` | Model and event value format: a date format string, Date, or timestamp | String Values             |
| `disabled`     | Disable interaction                                                    | Text Entry                |

<!-- demo-config-notes:end -->

Example source: src/date-range/__demos__/en-US/string-values.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
const date = ref("2026-09-10");
const month = ref("2026-09");
const range = ref(["09-10", "10-10"]);
</script>
<template>
  <c-space direction="column">
    <c-date v-model="date" format="YYYY-MM-DD" value-format="YYYY-MM-DD" />
    <p>String: {{ JSON.stringify(date) }}</p>
    <c-date
      v-model="month"
      type="month"
      format="YYYY-MM"
      value-format="YYYY-MM"
    />
    <p>Month string: {{ JSON.stringify(month) }}</p>
    <c-date-range v-model="range" format="MM-DD" value-format="MM-DD" />
    <p>Month/day array: {{ JSON.stringify(range) }}</p>
  </c-space>
</template>
```

### Text Entry

Example source: src/date/picker/__demos__/text-entry.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'

const value = ref('2025-01-15')
const range = ref(['2025-01-15', '2025-01-20'])
const panelOnly = ref(false)
</script>

<template>
  <p>输入 DD/MM/YYYY，Enter 或失焦提交；非法日期和范围外输入恢复模型显示。</p>
  <c-date v-model="value" format="DD/MM/YYYY" min="2025-01-10" max="2025-01-25" :input-editable="!panelOnly" />
  <p>模型：{{ value }}</p>
  <c-switch v-model="panelOnly" />
  <p>仅面板选择：{{ panelOnly }}</p>
  <c-date-range v-model="range" format="DD/MM/YYYY" :disabled="[true, false]" :input-editable="!panelOnly" />
  <p>起点锁定，终点不能早于起点：{{ range }}</p>
</template>
```

## Interaction and field configuration

### Api Review

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration             | Purpose                                                                      | Related examples                    |
| ------------------------- | ---------------------------------------------------------------------------- | ----------------------------------- |
| `open`                    | Controlled popup visibility                                                  | Rejected Close, Passthrough Options |
| `date-range-picker-props` | Panel presentation options                                                   | Field Panel Tools, Entry Boundary   |
| `value-format`            | Model and event value format: a date format string, Date, or timestamp       | Api Review                          |
| `readonly`                | Read-only interaction                                                        | Api Review                          |
| `format`                  | Display format                                                               | Field Panel Tools                   |
| `popup-props`             | Trigger presentation options; cannot override owned visibility or date rules | Passthrough Options                 |

<!-- demo-config-notes:end -->

</details>

Example source: src/date-range/__demos__/state-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref(["2026-10-23", "2026-10-25"]);
const __demoState = __demoReactive({ readonly: false, error: false });
</script>
<template>
  <c-space direction="column" :size="16">
    <c-space wrap>
      <c-checkbox v-model="__demoState['readonly']">readonly</c-checkbox>
      <c-checkbox v-model="__demoState['error']">error</c-checkbox>
    </c-space>
    <c-date-range
      v-model="value"
      value-format="YYYY-MM-DD"
      v-bind="__demoState"
    ></c-date-range>
  </c-space>
</template>
```

### Rejected Close

Example source: src/date-range/__demos__/rejected-close.vue

```vue
<script setup>
import { ref } from "vue";

const value = ref(["2026-09-22", "2026-09-24"]);
const open = ref(false);
const closeRequests = ref(0);
const commits = ref(0);

function requestOpen(next) {
  if (next) open.value = true;
  else closeRequests.value++;
}
</script>

<template>
  <c-space direction="column" size="12px">
    <p>
      关闭请求会被父级拒绝；修改起止日期后可再次确认，重复确认不应重复提交。
    </p>
    <c-date-range
      v-model="value"
      :open="open"
      @update:open="requestOpen"
      @change="commits++"
    >
      <template #actions="{ confirm, disabled }">
        <c-button :disabled="disabled" @click="confirm()">确认</c-button>
        <c-button @click="open = false">允许关闭</c-button>
      </template>
    </c-date-range>
    <span data-test="date-range-transaction-state"
      >值：{{ value.join(" ~ ") }}；提交：{{ commits }}；拒绝关闭：{{
        closeRequests
      }}</span
    >
  </c-space>
</template>
```

### Field Panel Tools

Example source: src/date-range/__demos__/field-panel-tools.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import type { DateShortcut } from "@cedar-design/ui";

const selected = ref(["2025-01-15", "2025-01-20"]);
const viewport = ref(["2025-01-01", "2025-02-01"]);
const acceptNavigation = ref(true);
const notice = ref("");
const shortcutNotice = ref("");
const shortcuts: DateShortcut[] = [
  { label: "下个月", value: ["2025-02-15", "2025-02-20"] },
  { label: "不可选", value: ["2025-03-01", "2025-03-05"], disabled: true },
];
function navigate(value: unknown) {
  if (
    acceptNavigation.value &&
    Array.isArray(value) &&
    value.length === 2 &&
    value.every((part) => typeof part === "string")
  )
    viewport.value = value;
}
function observe(_value: unknown, _dates: unknown, texts: unknown) {
  notice.value = String(texts);
}
function choose(shortcut: DateShortcut) {
  shortcutNotice.value = String(shortcut.label);
}
</script>

<template>
  <c-checkbox v-model="acceptNavigation"> 接受视口请求</c-checkbox>
  <c-date-range
    v-model="selected"
    :input-editable="false"
    format="DD/MM/YYYY"
    :date-range-picker-props="{ pickerValue: viewport, shortcuts }"
    @update:picker-value="navigate"
    @picker-value-change="observe"
    @select-shortcut="choose"
  />
  <p>选择模型：{{ selected }}；受控视口：{{ viewport }}</p>
  <p>视口通知：{{ notice }}；快捷项通知：{{ shortcutNotice }}</p>
  <p>
    导航不改变选择模型；拒绝视口请求后，日历仍显示原月份。快捷项先选择草稿，确认后提交。
  </p>
</template>
```

### Entry Boundary

Example source: src/date-range/__demos__/entry-boundary.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import type { DateValue } from "@cedar-design/ui";
const limited = ref(true);
const blockEnd20 = ref(false);
const disabledEnd = (date: Date, side: "start" | "end") =>
  side === "end" && blockEnd20.value && date.getDate() === 20;
const fieldValue = ref<DateValue[]>(["2025-02-12", "2025-02-14"]);
const panelValue = ref<DateValue[]>(["2025-02-12", "2025-02-14"]);
</script>

<template>
  <div class="entry-demo">
    <p>仅允许选择 2025 年 2 月；移除限制不会改变已有选中值。</p>
    <c-button @click="limited = !limited">{{
      limited ? "移除日期限制" : "恢复日期限制"
    }}</c-button>
    <div>
      <p>范围字段：管理输入、浮层和确认流程。</p>
      <c-date-range
        :min="limited ? '2025-02-01' : undefined"
        :max="limited ? '2025-02-28' : undefined"
        v-model="fieldValue"
        :date-range-picker-props="{ dayStartOfWeek: 1 }"
      />
    </div>
    <div>
      <p>范围面板：日历从周一开始，点击确认后才提交。</p>
      <c-checkbox v-model="blockEnd20">
        禁用20日结束（不改已提交值）</c-checkbox
      >
      <c-date-range-picker
        :min="limited ? '2025-02-01' : undefined"
        :max="limited ? '2025-02-28' : undefined"
        v-model="panelValue"
        :day-start-of-week="1"
        :disable-confirm="false"
        :disabled-date="disabledEnd"
      >
        <template #actions="{ confirm, disabled }">
          <c-button :disabled="disabled" @click="confirm"
            >提交日期范围</c-button
          >
        </template>
      </c-date-range-picker>
      <p>已提交：{{ panelValue.join(" ~ ") }}</p>
    </div>
  </div>
</template>

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

### Passthrough Options

Example source: src/date-range/__demos__/passthrough-options.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import type { DateRangePopupOptions } from "@cedar-design/ui";
const open = ref(false);
const popupOptions: DateRangePopupOptions = {
  placement: "top-start",
  popupTranslate: [0, -8],
  popupContainer: false,
};
</script>
<template>
  <c-space direction="column" fill>
    <c-button @click="open = !open">{{
      open ? "关闭面板" : "打开面板"
    }}</c-button>
    <c-date-range
      edit-mode="direct"
      v-model:open="open"
      :popup-props="popupOptions"
      aria-label="透传配置示例"
    />
    <p role="status">顶层 open：{{ open }}；嵌套配置：向上展开并调整偏移。</p>
  </c-space>
</template>
```

### Props

| Arguments                 | Description                                                                                                                      | Type                                       | Default   |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | --------- |
| `open-trigger-target`     | Pointer opening target: the whole field or only the suffix icon. Explicit keyboard opening and controlled open remain available. | `'field' \| 'icon'`                        | `'field'` |
| `model-value`             | Bound value                                                                                                                      | `(Date \| string \| number)[]`             | `-`       |
| `type`                    | Date precision                                                                                                                   | `date \| week \| month \| year \| quarter` | `date`    |
| `open`                    | Controlled popup visibility                                                                                                      | `boolean`                                  | `-`       |
| `clearable`               | Show the clear action                                                                                                            | `boolean`                                  | `true`    |
| `disabled`                | Disable interaction                                                                                                              | `boolean \| boolean[]`                     | `-`       |
| `readonly`                | Read-only interaction                                                                                                            | `boolean`                                  | `false`   |
| `size`                    | Component size                                                                                                                   | `xs \| sm \| md \| lg \| xl`               | `-`       |
| `variant`                 | Field appearance                                                                                                                 | `filled \| outline \| standard`            | `filled`  |
| `separator`               | Range separator                                                                                                                  | `string`                                   | `-`       |
| `placeholder`             | Placeholder                                                                                                                      | `string[]`                                 | `-`       |
| `disabled-date`           | Return true to disable a date                                                                                                    | `Function`                                 | `-`       |
| `format`                  | Display format                                                                                                                   | `string`                                   | `-`       |
| `show-time`               | Include time selection                                                                                                           | `boolean`                                  | `false`   |
| `date-range-picker-props` | Panel presentation options                                                                                                       | `DateRangePickerOptions`                   | `{}`      |

#### Copying and editing

With open-trigger-target="icon", use the input area to edit or copy and the suffix button to open. Existing text remains copyable when editing or search is disabled.

Example source: src/date-range/__demos__/open-trigger-target.en-US.vue

```vue
<template>
  <c-space direction="column">
    <c-radio-group
      v-model="target"
      :options="[
        { label: 'Whole field', value: 'field' },
        { label: 'Suffix icon only', value: 'icon' },
      ]"
    />
    <label><c-switch v-model="editable" /> Allow editing / search</label>
    <c-date-range
      v-model="value"
      edit-mode="direct"
      :open-trigger-target="target"
      :input-editable="editable"
    />
    <p>
      Disable editing to copy existing text. In icon mode, editing does not open
      the panel.
    </p>
  </c-space>
</template>
<script setup lang="ts">
import { ref } from "vue";
const target = ref<"field" | "icon">("icon");
const editable = ref(true);
const value = ref(["2026-10-27", "2026-10-28"]);
</script>
```

### Shared field loading

`loading` displays the shared field indicator. `loading-mode` is `default` (indicator) or `line` (an indeterminate bottom line); it defaults to `default`. Rendering belongs to FieldDecorator. Loading does not implicitly disable editing or change readonly. Set those states separately.

## Reading direction

Range values remain `[start, end]` across direction changes; switching direction neither swaps endpoints nor commits drafts. Range ribbons and boundary corners follow reading order. Paged calendar grids use visual Left/Right focus movement and chronological rows. Maple endpoint editing and continuous range highlighting are separate presentations. Explicit shortcut positions `left/right` remain physical, and popovers inherit their source direction.

## API

### Empty values and reading placeholders

`empty-values` recognizes empty data; `empty-value` keeps existing clear output. `empty-text` defaults to `'-'` under `read-pretty`, with Field > FormItem > Form precedence and custom read slots first. With explicit empty-values, built-in required uses the policy; custom validators receive original data. See the [shared guide](llms/en-US/guide/empty-values.md).

| Prop         | Type               | Default and scope                                                           |
| ------------ | ------------------ | --------------------------------------------------------------------------- |
| empty-values | readonly unknown[] | Field > FormItem > Form > component-family default; replaces the whole list |
| empty-text   | string             | Field > FormItem > Form > '-'; explicit '' is valid                         |

These props belong to field presentation; pure panels do not gain reading mode. Form and FormItem provide inherited settings. The existing empty-value type and clear fallback remain component-specific.

### Props

| Arguments                 | Description                                                                                                                      | Type                                       | Default   |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | --------- |
| `open-trigger-target`     | Pointer opening target: the whole field or only the suffix icon. Explicit keyboard opening and controlled open remain available. | `'field' \| 'icon'`                        | `'field'` |
| `model-value`             | Bound value                                                                                                                      | `(Date \| string \| number)[]`             | `-`       |
| `type`                    | Date precision                                                                                                                   | `date \| week \| month \| year \| quarter` | `date`    |
| `open`                    | Controlled popup visibility                                                                                                      | `boolean`                                  | `-`       |
| `clearable`               | Show the clear action                                                                                                            | `boolean`                                  | `true`    |
| `disabled`                | Disable interaction                                                                                                              | `boolean \| boolean[]`                     | `-`       |
| `readonly`                | Read-only interaction                                                                                                            | `boolean`                                  | `false`   |
| `size`                    | Size                                                                                                                             | `xs \| sm \| md \| lg \| xl`               | `-`       |
| `variant`                 | Field appearance                                                                                                                 | `filled \| outline \| standard`            | `filled`  |
| `separator`               | Range separator                                                                                                                  | `string`                                   | `-`       |
| `placeholder`             | Placeholder                                                                                                                      | `string[]`                                 | `-`       |
| `disabled-date`           | Return true to disable a date                                                                                                    | `Function`                                 | `-`       |
| `format`                  | Display format                                                                                                                   | `string`                                   | `-`       |
| `show-time`               | Include time selection                                                                                                           | `boolean`                                  | `false`   |
| `date-range-picker-props` | Panel presentation options                                                                                                       | `DateRangePickerOptions`                   | `{}`      |

### Shared date-family contract

| Arguments         | Description                                                                   | Type                                               | Default      |
| ----------------- | ----------------------------------------------------------------------------- | -------------------------------------------------- | ------------ |
| `default-value`   | Uncontrolled initial value, read once                                         | DateValue / DateValue[]                            | —            |
| `value-format`    | Model and event value format: a date format string, Date, or timestamp        | string                                             | Follows type |
| `min` / `max`     | Inclusive bounds; string bounds use value-format                              | DateValue                                          | —            |
| `disabled-time`   | Disabled times for the current date and endpoint                              | (date: Date, side: DateSide) => DateDisabledTime   | —            |
| `disable-confirm` | Commit immediately                                                            | boolean                                            | false        |
| `default-open`    | Uncontrolled initial open state                                               | boolean                                            | false        |
| `popup-props`     | Trigger presentation options; cannot override owned visibility or date rules  | object                                             | {}           |
| `popup-container` | Portal target; the top-level value wins, including false for inline rendering | string / HTMLElement / (() => HTMLElement) / false | —            |

`DateValue = Date | string | number`. Clearing a single value produces undefined; clearing a range produces [].
The date argument of `disabledDate(date, side)` and `disabledTime(date, side)` is always a Date; side is start/end.

`disabled-date` restricts range endpoints. A range may cross disabled interior values; it is not scanned item by item or truncated automatically. This applies to dates, months and years. Interior disabled values remain gray. Changing pages preserves the selected start and clears hover preview; reverse selection is sorted chronologically.
Time callbacks return numeric lists from `disabledHours()`, `disabledMinutes(hour)` and `disabledSeconds(hour, minute)`.
Invalid dates and incomplete/reversed ranges cannot be committed. Confirmation revalidates dynamic disabling rules. Locked range endpoints cannot be cleared or changed.
Nested panel props configure presentation only; they must not override top-level model-value, format, bounds, disabling rules or control events.

### Events

| Event                         | Description                               | Arguments                         |
| ----------------------------- | ----------------------------------------- | --------------------------------- |
| `update:model-value`          | Request a model update                    | value                             |
| `select`                      | Select a draft; does not imply submission | value, date(s), formatted text(s) |
| `change`                      | Committed value changes                   | value, date(s), formatted text(s) |
| `update:open` / `open-change` | Popup visibility changes                  | open: boolean                     |
| `clear`                       | Clear the selection                       | None                              |
| `focus` / `blur`              | Focus enters or leaves the whole field    | None                              |
| `click`                       | Click the field                           | event                             |

Desktop supports keyboard editing. The default panel edits a draft before confirmation; disable-confirm commits directly. Escape or closing discards the draft. focus(index = 0) focuses a start/end input, and blur() closes the popup.

## Configuring the cleared value

`empty-value` / `emptyValue` sets the model value produced by clearing. It accepts a value in the component model type or a zero-argument factory. Omission preserves the existing default; use `() => undefined` to distinguish omission from returning undefined. Arrays are shallow-copied on every clear; selected items that cannot be cleared remain. It does not redefine emptiness, alter Form reset defaults or treat 0/false as universally empty.

`empty-value` accepts explicit `null` (or `() => null`). Clearing publishes `null` unchanged; omitted values preserve the existing default. Editors render `null` as blank without converting ordinary empty-string input to `null`. In popup editing, clearing changes the draft; confirm commits it and cancel preserves the original model.

---

Document: llms/en-US/components/date.md

<!-- Source: src/date/README.en-US.md; locale: en-US; page: /en/components/date/ -->

# Date

Floating date panels use the visual viewport height so the full calendar is visible when space permits. Short windows scroll content while keeping actions visible. Override `--c-date-picker-popover-max-height` to adjust the limit (default `100dvh - 32px`).

A date field with a trigger. Use DatePicker for a standalone panel.

## String models and time zones

format controls display; value-format controls the model and events. Use YYYY-MM-DD for a date string or YYYY-MM for a month string. MM-DD has no year and parsing uses the current year, so retain a full date for cross-year ordering or explicit leap-year rules.

Omitting time-zone preserves browser-local behavior. With an IANA time zone, Date and timestamps represent instants while strings represent local civil times in that zone. Invalid DST times are rejected; newly entered repeated times resolve to the first occurrence. Untouched Date/timestamp range endpoints preserve their exact instant and hidden precision. Maple-only scroll/line views do not change Cedar panel defaults.

## Basic examples

### Basic

Example source: src/date/__demos__/basic.vue

```vue
<template>
  <c-date v-model="value" style="width: 200px" clearable />
</template>

<script setup>
import { ref } from 'vue'

const value = ref()
</script>
```

### Interaction state comparison

Toggle disabled, read-only and error states, then interact with the same instance. Recovery controls remain outside the target; error appearance alone does not validate data.

<details>
<summary>Configuration details and limits</summary>

#### State Lab

## Appearance and date presentation

### Appearance configuration comparison

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration  | Purpose                                                                | Related examples                                      |
| -------------- | ---------------------------------------------------------------------- | ----------------------------------------------------- |
| `value-format` | Model and event value format: a date format string, Date, or timestamp | Appearance configuration comparison, Locale Isolation |
| `type`         | Type                                                                   | Type, Locale Isolation                                |
| `size`         | Size                                                                   | Control Sizes                                         |
| `variant`      | Field appearance                                                       | Control Sizes                                         |
| `placeholder`  | Placeholder                                                            | Control Sizes                                         |
| `clearable`    | Show the clear action                                                  | Type                                                  |

<!-- demo-config-notes:end -->

Choose a dimension to compare all its values side by side while keeping other settings and content identical. Change the other settings to inspect combinations; input specimens share one model.

Example source: src/date/__demos__/appearance-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref("2026-10-23");
const __demoAppearance = __demoReactive({ variant: "filled", size: "md" });

import { computed as demoComputed, ref as demoRef } from 'vue'
const demoCompareFields = [{"name":"variant","values":["filled","outline","standard"]},{"name":"size","values":["xs","sm","md","lg","xl"]}]
const demoCompareAxis = demoRef("variant")
const demoComparedOptions = demoComputed(() => demoCompareFields.find(field => field.name === demoCompareAxis.value)?.values ?? [])
</script>
<template>
  <c-space direction="column" :size="16">
    <c-form layout="vertical">
      <c-form-item layout="vertical" size="sm" label="variant">
        <c-radio-group
          v-model="__demoAppearance['variant']"
          aria-label="variant"
          :options="[
            { label: 'filled', value: 'filled' },
            { label: 'outline', value: 'outline' },
            { label: 'standard', value: 'standard' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
      <c-form-item layout="vertical" size="sm" label="size">
        <c-radio-group
          v-model="__demoAppearance['size']"
          aria-label="size"
          :options="[
            { label: 'xs', value: 'xs' },
            { label: 'sm', value: 'sm' },
            { label: 'md', value: 'md' },
            { label: 'lg', value: 'lg' },
            { label: 'xl', value: 'xl' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
    </c-form>
    <p class="demo-config-comparison-hint"><span lang="zh-CN">选择一个对比维度；其他配置和内容保持一致。输入类示例共享同一个值，便于比较外观。</span><span lang="en-US">Compare one dimension while keeping the other settings and content identical. Input specimens share the same value.</span></p>
<c-radio-group v-model="demoCompareAxis" aria-label="Compare configuration" :options="demoCompareFields.map(field => ({ label: field.name, value: field.name }))" />
<div class="demo-config-comparison">
<section v-for="sample in demoComparedOptions" :key="String(sample)">
<p><code>{{ demoCompareAxis }}={{ sample }}</code></p>
<c-date
      v-model="value"
      value-format="YYYY-MM-DD"
      v-bind="{ ...__demoAppearance, [demoCompareAxis]: sample }"
    ></c-date>
</section>
</div>
  </c-space>
</template>

<style scoped>
.demo-config-comparison { display: grid; grid-template-columns: repeat(auto-fit, minmax(min(100%, 220px), 1fr)); gap: 20px; min-width: 0; max-width: 100%; }
.demo-config-comparison > section { min-width: 0; }
.demo-config-comparison p { margin: 0 0 8px; }
html:not([lang='en-US']) .demo-config-comparison-hint > [lang='en-US'],
html[lang='en-US'] .demo-config-comparison-hint > [lang='zh-CN'] { display: none; }
</style>
```

### Control Sizes

Example source: src/field-decorator/__demos__/control-sizes.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
const sizes = ["xs", "sm", "md", "lg", "xl"] as const;
const variants = ["outline", "filled", "standard"] as const;
const size = ref<(typeof sizes)[number]>("md");
const variant = ref<(typeof variants)[number]>("outline");
const options = [
  { value: "beijing", label: "Beijing" },
  { value: "shanghai", label: "Shanghai" },
];
const cascaderOptions = [{ value: "china", label: "China", children: options }];

const inputValue = ref("Beijing");
const selectValue = ref("beijing");
const cascaderValue = ref("beijing");
const selectMultiple = ref(["beijing", "shanghai"]);
const cascaderMultiple = ref(["beijing", "shanghai"]);
const selectOverflow = ref(["long", "beijing", "shanghai"]);
const cascaderOverflow = ref(["long", "beijing", "shanghai"]);
const selectedOptions = [
  ...options,
  {
    value: "long",
    label:
      "A very long selected option label for overflow comparison — full text preview keeps the selected value unchanged.",
  },
];
const selectedCascaderOptions = [
  { value: "china", label: "China", children: selectedOptions },
];
function resetSelections() {
  inputValue.value = "Beijing";
  selectValue.value = "beijing";
  cascaderValue.value = "beijing";
  selectMultiple.value = ["beijing", "shanghai"];
  cascaderMultiple.value = ["beijing", "shanghai"];
  selectOverflow.value = ["long", "beijing", "shanghai"];
  cascaderOverflow.value = ["long", "beijing", "shanghai"];
}
</script>
<template>
  <section
    aria-label="Form control size comparison"
    class="control-size-comparison"
  >
    <c-space wrap :size="12">
      <c-radio-group v-model="size" aria-label="Comparison size">
        <c-radio v-for="item in sizes" :key="item" :value="item">{{
          item
        }}</c-radio>
      </c-radio-group>
      <c-radio-group v-model="variant" aria-label="Comparison variant">
        <c-radio v-for="item in variants" :key="item" :value="item">{{
          item
        }}</c-radio>
      </c-radio-group>
    </c-space>
    <div class="control-size-comparison__grid">
      <div data-control="Input">
        <p>Input</p>
        <c-input :size="size" :variant="variant" placeholder="Input" />
      </div>
      <div data-control="Button">
        <p>Button</p>
        <c-button :size="size" variant="outline">Button</c-button>
      </div>
      <div data-control="Select">
        <p>Select</p>
        <c-select
          :size="size"
          :variant="variant"
          :options="options"
          placeholder="Select"
        />
      </div>
      <div data-control="Date">
        <p>Date</p>
        <c-date :size="size" :variant="variant" placeholder="Date" />
      </div>
      <div data-control="Time">
        <p>Time</p>
        <c-time :size="size" :variant="variant" placeholder="Time" />
      </div>
      <div data-control="InputNumber">
        <p>InputNumber</p>
        <c-input-number :size="size" :variant="variant" placeholder="Number" />
      </div>
      <div data-control="AutoComplete">
        <p>AutoComplete</p>
        <c-auto-complete
          :size="size"
          :variant="variant"
          :options="options"
          placeholder="AutoComplete"
        />
      </div>
      <div data-control="Cascader">
        <p>Cascader</p>
        <c-cascader
          :size="size"
          :variant="variant"
          :options="cascaderOptions"
          placeholder="Cascader"
        />
      </div>
      <div data-control="DateRange">
        <p>DateRange</p>
        <c-date-range
          :size="size"
          :variant="variant"
          :placeholder="['Start', 'End']"
        />
      </div>
      <div data-control="TimeRange">
        <p>TimeRange</p>
        <c-time-range
          :size="size"
          :variant="variant"
          :placeholder="['Start', 'End']"
        />
      </div>
    </div>

    <section
      aria-label="Selected control size comparison"
      class="control-size-comparison__states"
    >
      <c-space wrap align="center" :size="12">
        <span>Selected / Clearable / Multiple — 有值、可清空与多选不换行</span>
        <span
          >Hover or focus truncated text; tap on touch screens /
          悬停或聚焦省略正文查看全文；触屏点按查看，点外部关闭</span
        >
        <c-button size="sm" variant="outline" @click="resetSelections"
          >Reset / 恢复选中值</c-button
        >
      </c-space>
      <div class="control-size-comparison__grid">
        <div data-control="InputValue">
          <p>Input · clearable</p>
          <c-input
            v-model="inputValue"
            :size="size"
            :variant="variant"
            clearable
            placeholder="Input value"
          />
        </div>
        <div data-control="ButtonReference">
          <p>Button · reference</p>
          <c-button :size="size" variant="outline">Button</c-button>
        </div>
        <div data-control="SelectValue">
          <p>Select · clearable</p>
          <c-select
            v-model="selectValue"
            :size="size"
            :variant="variant"
            :options="selectedOptions"
            clearable
            placeholder="Select value"
          />
        </div>
        <div data-control="CascaderValue">
          <p>Cascader · clearable</p>
          <c-cascader
            v-model="cascaderValue"
            :size="size"
            :variant="variant"
            :options="selectedCascaderOptions"
            clearable
            placeholder="Cascader value"
          />
        </div>
        <div data-control="SelectMultiple">
          <p>Select · multiple / nowrap</p>
          <c-select
            v-model="selectMultiple"
            :size="size"
            :variant="variant"
            :options="selectedOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Select multiple"
          />
        </div>
        <div data-control="CascaderMultiple">
          <p>Cascader · multiple / nowrap</p>
          <c-cascader
            v-model="cascaderMultiple"
            :size="size"
            :variant="variant"
            :options="selectedCascaderOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Cascader multiple"
          />
        </div>
        <div data-control="SelectOverflow">
          <p>Select · long values / nowrap</p>
          <c-select
            v-model="selectOverflow"
            edit-mode="direct"
            :size="size"
            :variant="variant"
            :options="selectedOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Select long values"
          />
        </div>
        <div data-control="CascaderOverflow">
          <p>Cascader · long values / nowrap</p>
          <c-cascader
            v-model="cascaderOverflow"
            edit-mode="direct"
            :size="size"
            :variant="variant"
            :options="selectedCascaderOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Cascader long values"
          />
        </div>
      </div>
    </section>
  </section>
</template>
<style scoped>
.control-size-comparison,
.control-size-comparison__states {
  display: grid;
  gap: 24px;
}
.control-size-comparison__grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
  align-items: start;
  gap: 24px 16px;
}
.control-size-comparison__grid > div {
  min-width: 0;
}
.control-size-comparison__grid p {
  margin: 0 0 12px;
  font-size: 14px;
  line-height: 20px;
}
.control-size-comparison__grid :deep(.c-input-number),
.control-size-comparison__grid :deep(.c-auto-complete) {
  width: 100%;
}
</style>
```

### Type

Example source: src/date/__demos__/type.vue

```vue
<template>
  <c-space direction="column" fill>
    <c-date v-model="date" style="width: 200px" clearable />
    <c-date v-model="week" type="week" style="width: 200px" clearable />
    <c-date v-model="month" type="month" style="width: 200px" clearable />
    <c-date v-model="year" type="year" style="width: 200px" clearable />
    <c-date v-model="quarter" type="quarter" style="width: 200px" clearable />
  </c-space>
</template>

<script setup>
import { ref } from 'vue'

const date = ref()
const week = ref()
const month = ref()
const year = ref()
const quarter = ref()
</script>
```

### Month Labels

Example source: src/date/picker/__demos__/month-labels.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const abbreviation = ref(true)
</script>

<template>
  <c-checkbox v-model="abbreviation">月份缩写</c-checkbox>
  <c-date-picker type="month" picker-value="2025-01" :abbreviation="abbreviation" :disable-confirm="false" />
  <c-date-range-picker type="month" :abbreviation="abbreviation" />
</template>
```

### Locale Isolation

Example source: src/date/picker/__demos__/locale-isolation.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const first = ref('2021-01-03')
const second = ref('2021-01-03')
const monday = ref(true)
const monthModel = ref('2025 January 15')
</script>

<template>
  <p>两个实例独立管理周起始日。可切换顶部语言，模型不随展示语言改变。</p>
  <c-date v-model="first" type="week" :date-picker-props="{ dayStartOfWeek: 0 }" />
  <c-date v-model="second" type="week" :date-picker-props="{ dayStartOfWeek: monday ? 1 : 2 }" />
  <c-checkbox v-model="monday">第二个实例周一起始（关闭为周二）</c-checkbox>
  <c-date-picker type="week" v-model="first" picker-value="2021-01-01" :day-start-of-week="0" />
  <c-date-picker type="week" v-model="second" picker-value="2021-01-01" :day-start-of-week="monday ? 1 : 2" />
  <c-date v-model="monthModel" value-format="YYYY MMMM DD" format="YYYY MMMM DD" />
  <p>月份名称模型（稳定英文协议）：{{ monthModel }}</p>
</template>
```

## Time and selection rules

### Show Time

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration  | Purpose                                                                | Related examples |
| -------------- | ---------------------------------------------------------------------- | ---------------- |
| `show-time`    | Include time selection                                                 | Show Time        |
| `format`       | Display format                                                         | Show Time        |
| `value-format` | Model and event value format: a date format string, Date, or timestamp | Show Time        |
| `clearable`    | Show the clear action                                                  | Show Time        |

<!-- demo-config-notes:end -->

Example source: src/date/__demos__/show-time.vue

```vue
<script setup>
import { ref } from 'vue'
const minute = ref()
const second = ref()
</script>

<template>
  <c-space direction="column" size="lg">
    <span>分钟精度：显式设置显示格式和模型格式</span>
    <c-date v-model="minute" show-time format="YYYY-MM-DD HH:mm" value-format="YYYY-MM-DD HH:mm" clearable />
    <span>已提交值：{{ minute || '未选择' }}</span>
    <span>秒精度：Cedar 的日期时间默认格式</span>
    <c-date v-model="second" show-time clearable />
    <span>已提交值：{{ second || '未选择' }}</span>
  </c-space>
</template>
```

### Time Presentation

Example source: src/date/picker/__demos__/time-presentation.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'

const use12Hours = ref(true)
const timeOptions = { step: { minute: 15 }, hideDisabledOptions: true }
</script>

<template>
  <c-checkbox v-model="use12Hours">十二小时展示</c-checkbox>

  <c-date-picker
    model-value="2025-01-05 13:30"
    show-time
    format="YYYY-MM-DD HH:mm"
    value-format="YYYY-MM-DD HH:mm"
    :time-picker-props="{ ...timeOptions, use12Hours }"
  />
</template>
```

## Value model and text input

### Value Formats

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration       | Purpose                                                                | Related examples                         |
| ------------------- | ---------------------------------------------------------------------- | ---------------------------------------- |
| `format`            | Display format                                                         | Value Formats, String Values, Text Entry |
| `value-format`      | Model and event value format: a date format string, Date, or timestamp | Value Formats, String Values             |
| `type`              | Type                                                                   | String Values, Period Text               |
| `date-picker-props` | Panel presentation options                                             | Period Text                              |

<!-- demo-config-notes:end -->

Example source: src/date/__demos__/value-formats.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const timestamp = ref(new Date(2026, 8, 15).getTime())
const objectValue = ref(new Date(2026, 8, 16))
</script>
<template>
  <div class="date-contract-demo">
    <c-date v-model="timestamp" value-format="timestamp" format="DD/MM/YYYY" />
    <p>时间戳模型：{{ timestamp }}</p>
    <c-date v-model="objectValue" value-format="Date" format="YYYY年MM月DD日" />
    <p>Date 对象模型：{{ objectValue }}</p>
  </div>
</template>
<style scoped>
.date-contract-demo { display: flex; flex-direction: column; gap: 12px; }
.date-contract-demo p { margin: 0; }
</style>
```

### String Values

Example source: src/date/__demos__/en-US/string-values.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
const date = ref("2026-09-10");
const month = ref("2026-09");
const range = ref(["09-10", "10-10"]);
</script>
<template>
  <c-space direction="column">
    <c-date v-model="date" format="YYYY-MM-DD" value-format="YYYY-MM-DD" />
    <p>String: {{ JSON.stringify(date) }}</p>
    <c-date
      v-model="month"
      type="month"
      format="YYYY-MM"
      value-format="YYYY-MM"
    />
    <p>Month string: {{ JSON.stringify(month) }}</p>
    <c-date-range v-model="range" format="MM-DD" value-format="MM-DD" />
    <p>Month/day array: {{ JSON.stringify(range) }}</p>
  </c-space>
</template>
```

### Period Text

Example source: src/date/picker/__demos__/period-text.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'

const week = ref('2020-12-28')
const quarter = ref('2025-04')
const range = ref(['2020-12-28', '2021-01-04'])
</script>

<template>
  <p>周一起始，中文可手输 2020-53周；切换英文后使用英文序数。提交为该周起始日。</p>
  <c-date v-model="week" type="week" :date-picker-props="{ dayStartOfWeek: 1 }" />
  <p>周模型：{{ week }}</p>
  <c-date v-model="quarter" type="quarter" />
  <p>季度输入 2025-Q2，模型为季度首月：{{ quarter }}</p>
  <c-date-range v-model="range" type="week" :date-range-picker-props="{ dayStartOfWeek: 1 }" />
  <p>周范围不自动交换手输端点：{{ range }}</p>
</template>
```

### Text Entry

Example source: src/date/picker/__demos__/text-entry.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'

const value = ref('2025-01-15')
const range = ref(['2025-01-15', '2025-01-20'])
const panelOnly = ref(false)
</script>

<template>
  <p>输入 DD/MM/YYYY，Enter 或失焦提交；非法日期和范围外输入恢复模型显示。</p>
  <c-date v-model="value" format="DD/MM/YYYY" min="2025-01-10" max="2025-01-25" :input-editable="!panelOnly" />
  <p>模型：{{ value }}</p>
  <c-switch v-model="panelOnly" />
  <p>仅面板选择：{{ panelOnly }}</p>
  <c-date-range v-model="range" format="DD/MM/YYYY" :disabled="[true, false]" :input-editable="!panelOnly" />
  <p>起点锁定，终点不能早于起点：{{ range }}</p>
</template>
```

## Interaction and field configuration

### Api Review

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration       | Purpose                                                                | Related examples                    |
| ------------------- | ---------------------------------------------------------------------- | ----------------------------------- |
| `disabled`          | Disable interaction                                                    | Api Review, Field Protocol          |
| `open`              | Controlled popup visibility                                            | Rejected Close, Passthrough Options |
| `date-picker-props` | Panel presentation options                                             | Field Panel Tools, Entry Boundary   |
| `placeholder`       | Placeholder                                                            | Field Protocol, Entry Boundary      |
| `value-format`      | Model and event value format: a date format string, Date, or timestamp | Api Review                          |
| `readonly`          | Read-only interaction                                                  | Api Review                          |

<!-- demo-config-notes:end -->

</details>

Example source: src/date/__demos__/state-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref("2026-10-23");
const __demoState = __demoReactive({
  disabled: false,
  readonly: false,
  error: false,
});
</script>
<template>
  <c-space direction="column" :size="16">
    <c-space wrap>
      <c-checkbox v-model="__demoState['disabled']">disabled</c-checkbox>
      <c-checkbox v-model="__demoState['readonly']">readonly</c-checkbox>
      <c-checkbox v-model="__demoState['error']">error</c-checkbox>
    </c-space>
    <c-date
      v-model="value"
      value-format="YYYY-MM-DD"
      v-bind="__demoState"
    ></c-date>
  </c-space>
</template>
```

### Rejected Close

Example source: src/date/__demos__/rejected-close.vue

```vue
<script setup>
import { ref } from "vue";

const value = ref("2026-09-22");
const open = ref(false);
const closeRequests = ref(0);
const commits = ref(0);

function requestOpen(next) {
  if (next) open.value = true;
  else closeRequests.value++;
}
</script>

<template>
  <c-space direction="column" size="12px">
    <p>关闭请求会被父级拒绝；选择新日期后可再次确认，重复确认不应重复提交。</p>
    <c-date
      v-model="value"
      :open="open"
      @update:open="requestOpen"
      @change="commits++"
    >
      <template #actions="{ confirm, disabled }">
        <c-button :disabled="disabled" @click="confirm()">确认</c-button>
        <c-button @click="open = false">允许关闭</c-button>
      </template>
    </c-date>
    <span data-test="date-transaction-state"
      >值：{{ value }}；提交：{{ commits }}；拒绝关闭：{{ closeRequests }}</span
    >
  </c-space>
</template>
```

### Field Panel Tools

Example source: src/date/picker/__demos__/field-panel-tools.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import type { DateShortcut } from "@cedar-design/ui";

const selected = ref("2025-01-15");
const viewport = ref("2025-01-01");
const acceptNavigation = ref(true);
const notice = ref("");
const shortcutNotice = ref("");
const shortcuts: DateShortcut[] = [
  { label: "下个月", value: "2025-02-15" },
  { label: "不可选", value: "2025-03-01", disabled: true },
];
function navigate(value: unknown) {
  if (acceptNavigation.value && typeof value === "string")
    viewport.value = value;
}
function observe(_value: unknown, _dates: unknown, texts: unknown) {
  notice.value = String(texts);
}
function choose(shortcut: DateShortcut) {
  shortcutNotice.value = String(shortcut.label);
}
</script>

<template>
  <c-checkbox v-model="acceptNavigation"> 接受视口请求</c-checkbox>
  <c-date
    v-model="selected"
    :input-editable="false"
    format="DD/MM/YYYY"
    :date-picker-props="{ pickerValue: viewport, shortcuts }"
    @update:picker-value="navigate"
    @picker-value-change="observe"
    @select-shortcut="choose"
  />
  <p>选择模型：{{ selected }}；受控视口：{{ viewport }}</p>
  <p>视口通知：{{ notice }}；快捷项通知：{{ shortcutNotice }}</p>
  <p>
    导航不改变选择模型；拒绝视口请求后，日历仍显示原月份。快捷项先选择草稿，确认后提交。
  </p>
</template>
```

### Field Protocol

Example source: src/date/__demos__/field-protocol.vue

```vue
<script setup>
import { ref } from 'vue'
const disabled = ref(false)
const date = ref('2026-09-22')
const dateRange = ref(['2026-09-22', '2026-09-24'])
const time = ref('09:00:00')
const timeRange = ref(['23:00:00', '01:00:00'])
</script>

<template>
  <c-space direction="column">
    <p>范围字段：点击右侧输入可从结束端选择；Tab 切换两端不提交，回车或离开整个字段再提交。</p>
    <span>禁用字段</span>
    <c-switch v-model="disabled" aria-label="禁用字段" />
    <c-date v-model="date" :disabled="disabled" clearable placeholder="日期" />
    <c-date-range v-model="dateRange" :disabled="disabled" clearable :placeholder="['开始日期', '结束日期']" />
    <c-time v-model="time" :disabled="disabled" clearable placeholder="时间" />
    <c-time-range v-model="timeRange" :disabled="disabled" clearable show-next-day :placeholder="['开始时间', '结束时间']" />
    <p>日期：{{ date || '未选择' }}；日期范围：{{ dateRange }}</p>
    <p>时间：{{ time || '未选择' }}；时间范围：{{ timeRange }}</p>
  </c-space>
</template>
```

### Entry Boundary

Example source: src/date/picker/__demos__/entry-boundary.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import type { DateSelection } from "@cedar-design/ui";
const limited = ref(true);
const fieldValue = ref<DateSelection>("2025-02-12");
const panelValue = ref<DateSelection>("2025-02-12");
const week = ref<0 | 1 | 6>(1);
</script>

<template>
  <div class="entry-demo">
    <p>仅允许选择 2025 年 2 月；移除限制不会改变已有选中值。</p>
    <c-button @click="limited = !limited">{{
      limited ? "移除日期限制" : "恢复日期限制"
    }}</c-button>
    <c-space wrap>
      <c-button @click="week = 0">周日起始</c-button>
      <c-button @click="week = 1">周一起始</c-button>
      <c-button @click="week = 6">周六起始</c-button>
    </c-space>
    <div>
      <p>字段：管理输入与浮层；面板参数放在 date-picker-props。</p>
      <c-date
        :min="limited ? '2025-02-01' : undefined"
        :max="limited ? '2025-02-28' : undefined"
        v-model="fieldValue"
        :date-picker-props="{ dayStartOfWeek: week }"
        placeholder="选择日期"
      />
    </div>
    <div>
      <p>纯面板：直接嵌入页面，不使用 open / popup-container。</p>
      <c-date-picker
        :min="limited ? '2025-02-01' : undefined"
        :max="limited ? '2025-02-28' : undefined"
        v-model="panelValue"
        :day-start-of-week="week"
        :disable-confirm="false"
      />
      <p>已提交：{{ panelValue }}</p>
    </div>
  </div>
</template>

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

### Passthrough Options

Example source: src/date/__demos__/passthrough-options.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import type { DatePopupOptions } from "@cedar-design/ui";
const open = ref(false);
const popupOptions: DatePopupOptions = {
  placement: "top-start",
  popupTranslate: [0, -8],
  popupContainer: false,
};
</script>
<template>
  <c-space direction="column" fill>
    <c-button @click="open = !open">{{
      open ? "关闭面板" : "打开面板"
    }}</c-button>
    <c-date
      edit-mode="direct"
      v-model:open="open"
      :popup-props="popupOptions"
      aria-label="透传配置示例"
    />
    <p role="status">顶层 open：{{ open }}；嵌套配置：向上展开并调整偏移。</p>
  </c-space>
</template>
```

### Props

| Arguments             | Description                                                                                                                      | Type                                       | Default         |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | --------------- |
| `open-trigger-target` | Pointer opening target: the whole field or only the suffix icon. Explicit keyboard opening and controlled open remain available. | `'field' \| 'icon'`                        | `'field'`       |
| `model-value`         | Bound value                                                                                                                      | `Date \| string \| number`                 | `-`             |
| `type`                | Date precision                                                                                                                   | `date \| week \| month \| year \| quarter` | `date`          |
| `open`                | Controlled popup visibility                                                                                                      | `boolean`                                  | `-`             |
| `clearable`           | Show the clear action                                                                                                            | `boolean`                                  | `true`          |
| `disabled`            | Disable interaction                                                                                                              | `boolean`                                  | `false`         |
| `readonly`            | Read-only interaction                                                                                                            | `boolean`                                  | `false`         |
| `size`                | Component size                                                                                                                   | `xs \| sm \| md \| lg \| xl`               | `-`             |
| `variant`             | Field appearance                                                                                                                 | `filled \| outline \| standard`            | `filled`        |
| `placeholder`         | Placeholder                                                                                                                      | `string`                                   | `-`             |
| `disabled-date`       | Return true to disable a date                                                                                                    | `Function`                                 | `-`             |
| `format`              | Display format                                                                                                                   | `string \| Function`                       | Depends on type |
| `show-time`           | Include time selection                                                                                                           | `boolean`                                  | `false`         |
| `date-picker-props`   | Panel presentation options                                                                                                       | `DatePickerOptions`                        | `{}`            |

#### Copying and editing

With open-trigger-target="icon", use the input area to edit or copy and the suffix button to open. Existing text remains copyable when editing or search is disabled.

Example source: src/date/__demos__/open-trigger-target.en-US.vue

```vue
<template>
  <c-space direction="column">
    <c-radio-group
      v-model="target"
      :options="[
        { label: 'Whole field', value: 'field' },
        { label: 'Suffix icon only', value: 'icon' },
      ]"
    />
    <label><c-switch v-model="editable" /> Allow editing / search</label>
    <c-date
      v-model="value"
      edit-mode="direct"
      :open-trigger-target="target"
      :input-editable="editable"
    />
    <p>
      Disable editing to copy existing text. In icon mode, editing does not open
      the panel.
    </p>
  </c-space>
</template>
<script setup lang="ts">
import { ref } from "vue";
const target = ref<"field" | "icon">("icon");
const editable = ref(true);
const value = ref("2026-10-27");
</script>
```

### Shared field loading

`loading` displays the shared field indicator. `loading-mode` is `default` (indicator) or `line` (an indeterminate bottom line); it defaults to `default`. Rendering belongs to FieldDecorator. Loading does not implicitly disable editing or change readonly. Set those states separately.

## Reading direction

Inherits the nearest `dir="ltr|rtl"`, including runtime changes and local overrides. Calendar dates, months and years follow reading order; navigation icons mirror, while date values keep their meaning. In paged grids, Left/Right moves focus visually, Up/Down moves one row, and Home/End moves to the row boundary, skipping disabled items. Focus navigation does not select; Enter/Space keeps the existing selection behavior. Navigation is bounded by the displayed grid. Explicit `shortcuts-position="left|right"` remains physical; `bottom` stays below. Field popovers inherit their source direction.

## API

### Empty values and reading placeholders

`empty-values` recognizes empty data; `empty-value` keeps existing clear output. `empty-text` defaults to `'-'` under `read-pretty`, with Field > FormItem > Form precedence and custom read slots first. With explicit empty-values, built-in required uses the policy; custom validators receive original data. See the [shared guide](llms/en-US/guide/empty-values.md).

| Prop         | Type               | Default and scope                                                           |
| ------------ | ------------------ | --------------------------------------------------------------------------- |
| empty-values | readonly unknown[] | Field > FormItem > Form > component-family default; replaces the whole list |
| empty-text   | string             | Field > FormItem > Form > '-'; explicit '' is valid                         |

These props belong to field presentation; pure panels do not gain reading mode. Form and FormItem provide inherited settings. The existing empty-value type and clear fallback remain component-specific.

### Props

| Arguments             | Description                                                                                                                      | Type                                       | Default        |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | -------------- |
| `open-trigger-target` | Pointer opening target: the whole field or only the suffix icon. Explicit keyboard opening and controlled open remain available. | `'field' \| 'icon'`                        | `'field'`      |
| `model-value`         | Bound value                                                                                                                      | `Date \| string \| number`                 | `-`            |
| `type`                | Date precision                                                                                                                   | `date \| week \| month \| year \| quarter` | `date`         |
| `open`                | Controlled popup visibility                                                                                                      | `boolean`                                  | `-`            |
| `clearable`           | Show the clear action                                                                                                            | `boolean`                                  | `true`         |
| `disabled`            | Disable interaction                                                                                                              | `boolean`                                  | `false`        |
| `readonly`            | Read-only interaction                                                                                                            | `boolean`                                  | `false`        |
| `size`                | Size                                                                                                                             | `xs \| sm \| md \| lg \| xl`               | `-`            |
| `variant`             | Field appearance                                                                                                                 | `filled \| outline \| standard`            | `filled`       |
| `placeholder`         | Placeholder                                                                                                                      | `string`                                   | `-`            |
| `disabled-date`       | Return true to disable a date                                                                                                    | `Function`                                 | `-`            |
| `format`              | Display format                                                                                                                   | `string \| Function`                       | Follows `type` |
| `show-time`           | Include time selection                                                                                                           | `boolean`                                  | `false`        |
| `date-picker-props`   | Panel presentation options                                                                                                       | `DatePickerOptions`                        | `{}`           |

### Shared date-family contract

| Arguments         | Description                                                                                                                                                                                                                                             | Type                                               | Default      |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- | ------------ |
| `default-value`   | Uncontrolled initial value, read once                                                                                                                                                                                                                   | DateValue / DateValue[]                            | —            |
| `value-format`    | Model and event value format: a date format string, Date, or timestamp                                                                                                                                                                                  | string                                             | Follows type |
| `min` / `max`     | Inclusive bounds; string bounds use value-format                                                                                                                                                                                                        | DateValue                                          | —            |
| `disabled-time`   | Disabled times for the current date and endpoint                                                                                                                                                                                                        | (date: Date, side: DateSide) => DateDisabledTime   | —            |
| `disable-confirm` | Commit immediately                                                                                                                                                                                                                                      | boolean                                            | false        |
| `default-open`    | Uncontrolled initial open state                                                                                                                                                                                                                         | boolean                                            | false        |
| `popup-props`     | Optional field-popup presentation settings. Placement defaults to bottom-start and is positioned automatically by the underlying Trigger; the preferred side can be overridden. No top-level placement prop; field state and rules cannot be overridden | object                                             | {}           |
| `popup-container` | Portal target; the top-level value wins, including false for inline rendering                                                                                                                                                                           | string / HTMLElement / (() => HTMLElement) / false | —            |

`DateValue = Date | string | number`. Clearing a single value produces undefined; clearing a range produces [].
The date argument of `disabledDate(date, side)` and `disabledTime(date, side)` is always a Date; side is start/end.
Time callbacks return numeric lists from `disabledHours()`, `disabledMinutes(hour)` and `disabledSeconds(hour, minute)`.
Invalid dates and incomplete/reversed ranges cannot be committed. Confirmation revalidates dynamic disabling rules. Locked range endpoints cannot be cleared or changed.
Nested panel props configure presentation only; they must not override top-level model-value, format, bounds, disabling rules or control events.

### Events

| Event                         | Description                               | Arguments                         |
| ----------------------------- | ----------------------------------------- | --------------------------------- |
| `update:model-value`          | Request a model update                    | value                             |
| `select`                      | Select a draft; does not imply submission | value, date(s), formatted text(s) |
| `change`                      | Committed value changes                   | value, date(s), formatted text(s) |
| `update:open` / `open-change` | Popup visibility changes                  | open: boolean                     |
| `clear`                       | Clear the selection                       | None                              |
| `focus` / `blur`              | Focus enters or leaves the whole field    | None                              |
| `click`                       | Click the field                           | event                             |

Desktop supports keyboard editing. The default panel edits a draft before confirmation; disable-confirm commits directly. Escape or closing discards the draft. focus(index = 0) focuses a start/end input, and blur() closes the popup.

## Explicit time zones

`timeZone` accepts IANA names such as `Asia/Shanghai`. Date objects and millisecond timestamps represent instants; strings represent local time in the target zone. Display, typed input, min/max, shortcuts and disabling rules use the same protocol; event Date objects retain the actual instant. Omitting `timeZone` preserves local-zone behavior. Nonexistent daylight-saving times and invalid zones cannot be committed; repeated times use the first occurrence. Maple scroll / line are mobile calendar presentations; desktop retains its existing panel.

## Configuring the cleared value

`empty-value` / `emptyValue` sets the model value produced by clearing. It accepts a value in the component model type or a zero-argument factory. Omission preserves the existing default; use `() => undefined` to distinguish omission from returning undefined. Arrays are shallow-copied on every clear; selected items that cannot be cleared remain. It does not redefine emptiness, alter Form reset defaults or treat 0/false as universally empty.

`empty-value` accepts explicit `null` (or `() => null`). Clearing publishes `null` unchanged; omitted values preserve the existing default. Editors render `null` as blank without converting ordinary empty-string input to `null`. In popup editing, clearing changes the draft; confirm commits it and cancel preserves the original model.

### Placement semantics and configuration

The Date field prefers bottom-start below its input. Override the preferred side through popupProps.placement only when needed; the underlying Trigger positions it, not Popup or Popover. DatePicker is a standalone date panel with no input anchor; placement in the legacy date/picker directory is not a current public DatePicker prop.

---

Document: llms/en-US/components/descriptions.md

<!-- Source: src/descriptions/README.en-US.md; locale: en-US; page: /en/components/descriptions/ -->

# Descriptions

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

- `data`: Supplies the example data.

Example source: src/descriptions/__demos__/basic.vue

```vue
<template>
  <c-space direction="column" fill size="lg">
    <c-descriptions :data="data" title="User Info" />
    <c-descriptions :column="{ xs: 1, md: 3, lg: 4 }" title="User Info">
      <c-descriptions-item v-for="item of data" :key="item.label" :label="item.label" :span="item.span ?? 1">
        <c-tag>{{ item.value }}</c-tag>
      </c-descriptions-item>
    </c-descriptions>
  </c-space>
</template>

<script lang="ts" setup>
const data = [
  {
    label: 'Name',
    value: 'Socrates',
  },
  {
    label: 'Mobile',
    value: '123-1234-1234',
  },
  {
    label: 'Residence',
    value: 'Beijing',
  },
  {
    label: 'Hometown',
    value: 'Beijing',
  },
  {
    label: 'Address',
    value: 'Yingdu Building, Zhichun Road, Beijing',
  },
]
</script>
```

## Layout and arrangement

### Label Text Alignment

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `data` | Description-list data | Label Text Alignment, Layout Pattern |
| `title` | Description-list title | Label Text Alignment, Layout Pattern |
| `layout` | Description-list arrangement | Label Text Alignment, Layout Pattern |
| `align` | Text alignment | Label Text Alignment |
| `size` | Description-list size | Layout Pattern |
| `bordered` | Whether to show border | Layout Pattern |
<!-- demo-config-notes:end -->


- `data`: Supplies the example data.
- `align`: Controls alignment on the cross axis.

Example source: src/descriptions/__demos__/label-text-alignment.vue

```vue
<template>
  <c-space direction="column" size="lg">
    <c-descriptions :data="data" align="right" title="User Info" />
    <c-descriptions :align="{ label: 'right' }" :data="data" title="User Info" />
    <c-descriptions :data="data" layout="inline-vertical" title="User Info" />
  </c-space>
</template>

<script lang="ts" setup>
const data = [
  {
    label: 'Name',
    value: 'Socrates',
  },
  {
    label: 'Mobile',
    value: '123-1234-1234',
  },
  {
    label: 'Residence',
    value: 'Beijing',
  },
  {
    label: 'Hometown',
    value: 'Beijing',
  },
  {
    label: 'Address',
    value: 'Yingdu Building, Zhichun Road, Beijing',
  },
]
</script>
```

### Layout Pattern

- `data`: Supplies the example data.
- `size`: Controls the component size.

Example source: src/descriptions/__demos__/layout-pattern.vue

```vue
<template>
  <c-radio-group v-model="size" variant="button">
    <c-radio value="xs">xs</c-radio>
    <c-radio value="sm">sm</c-radio>
    <c-radio value="md">md</c-radio>
    <c-radio value="lg">lg</c-radio>
    <c-radio value="xl">xl</c-radio>
  </c-radio-group>
  <div style="margin-top: 20px">
    <c-descriptions :data="data" :size="size" title="User Info (horizontal)" bordered />
    <c-descriptions :data="data" :size="size" title="User Info (inline-horizontal)" layout="inline-horizontal" bordered />
    <c-descriptions :data="data" :size="size" title="User Info (vertical)" layout="vertical" bordered />
    <c-descriptions :data="data" :size="size" title="User Info (inline-vertical)" layout="inline-vertical" bordered />
    <c-descriptions :data="inlineAutoData" :size="size" title="User Info (inline-auto)" layout="inline-auto" />
  </div>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
const size = ref('md')

const data = [
  {
    label: 'Name',
    value: 'Socrates',
  },
  {
    label: 'Mobile',
    value: '123-1234-1234',
  },
  {
    label: 'Residence',
    value: 'Beijing',
  },
  {
    label: 'Hometown',
    value: 'Beijing',
  },
  {
    label: 'Address',
    value: 'Yingdu Building, Zhichun Road, Beijing',
  },
]

const inlineAutoData = [
  {
    label: 'Name:',
    value: 'Socrates',
  },
  {
    label: 'Mobile:',
    value: '123-1234-1234',
  },
  {
    label: 'Residence:',
    value: 'Beijing',
  },
]
</script>
```

## Content and presentation

### Singel Column Style

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `data` | Description-list data | Singel Column Style, Border Background List |
| `title` | Description-list title | Singel Column Style, Border Background List |
| `column` | Items per row. Responsive configuration is supported since 2.20.0; see Grid | Singel Column Style |
| `size` | Description-list size | Singel Column Style |
| `bordered` | Whether to show border | Border Background List |
<!-- demo-config-notes:end -->


- `data`: Supplies the example data.
- `size`: Controls the component size.

Example source: src/descriptions/__demos__/singel-column-style.vue

```vue
<template>
  <c-radio-group v-model="size" variant="button">
    <c-radio value="xs">xs</c-radio>
    <c-radio value="sm">sm</c-radio>
    <c-radio value="md">md</c-radio>
    <c-radio value="lg">lg</c-radio>
    <c-radio value="xl">xl</c-radio>
  </c-radio-group>
  <c-descriptions :column="1" :data="data" :size="size" style="margin-top: 20px" title="User Info" />
</template>

<script lang="ts" setup>
import { ref } from 'vue'
const size = ref('md')
const data = [
  {
    label: 'Name',
    value: 'Socrates',
  },
  {
    label: 'Mobile',
    value: '123-1234-1234',
  },
  {
    label: 'Residence',
    value: 'Beijing',
  },
  {
    label: 'Hometown',
    value: 'Beijing',
  },
  {
    label: 'Address',
    value: 'Yingdu Building, Zhichun Road, Beijing',
  },
]
</script>
```

### Border Background List

- `data`: Supplies the example data.

Example source: src/descriptions/__demos__/border-background-list.vue

```vue
<template>
  <c-descriptions :data="data" title="User Info" bordered />
</template>

<script lang="ts" setup>
const data = [
  {
    label: 'Name',
    value: 'Socrates',
  },
  {
    label: 'Mobile',
    value: '123-1234-1234',
  },
  {
    label: 'Residence',
    value: 'Beijing',
  },
  {
    label: 'Hometown',
    value: 'Beijing',
  },
  {
    label: 'Address',
    value: 'Yingdu Building, Zhichun Road, Beijing',
  },
]
</script>
```

## Reading direction

Inherits the nearest `dir="ltr|rtl"` and supports runtime and nested overrides. Labels, values, borders and default text alignment follow logical reading edges. Direction changes do not reverse records, column definitions or span semantics.

## API

### `<Descriptions>` Props

| Prop | Description | Type | Default |
| ------------ | ------------------------------------------------------------------ | :---------------------------------------------------------------------------------------: | :------------- |
| data | Description-list data | `DescData[]` | `[]` |
| column | Items per row. Responsive configuration is supported since 2.20.0; see Grid | `number \| ResponsiveValue` | `3` |
| title | Description-list title | `string` | `-` |
| layout | Description-list arrangement | `'horizontal' \| 'vertical' \| 'inline-horizontal' \| 'inline-vertical' \| 'inline-auto'` | `'horizontal'` |
| align | Text alignment | `TextAlign \| { label?: TextAlign; value?: TextAlign }` | `'left'` |
| size | Description-list size | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | `-` |
| bordered | Whether to show border | `boolean` | `false` |
| label-style | Label styles | `CSSProperties` | `-` |
| value-style | Content styles | `CSSProperties` | `-` |
| table-layout | Table-style `layout-fixed`; setting `fixed` distributes widths evenly | `'auto' \| 'fixed'` | `'auto'` |
| aria-label | Accessible description-list label | `string` | `-` |

### `<Descriptions>` Slots

| Slot | Description | Arguments |
| ------ | :------: | ------------------------------------------------------ |
| value | Content | value: `string`<br>index: `number`<br>data: `DescData` |
| label | Label | label: `string`<br>index: `number`<br>data: `DescData` |
| title | Title | - |

### `<DescriptionsItem>` Props

| Prop | Description | Type | Default |
| ----- | -------- | :------: | :----- |
| span | Column span | `number` | `1` |
| label | Label | `string` | `-` |

### `<DescriptionsItem>` Slots

| Slot | Description | Arguments |
| ------- | :--: | ---- |
| default | Content | - |
| label | Label | - |

### DescData

| Parameter | Description | Type | Default |
| ------ | -------- | -------------------------- | :----: |
| label | Label | `string \| RenderFunction` | `-` |
| value | Data | `string \| RenderFunction` | `-` |
| span | Column span | `number` | `-` |

## Type definitions

The component exports the following types

```ts
import type { DescriptionsProps } from "@cedar-design/ui";
```

---

Document: llms/en-US/components/dialog.md

<!-- Source: src/dialog/README.en-US.md; locale: en-US; page: /en/components/dialog/ -->

# Dialog

A modal dialog with matching declarative and programmatic APIs.

## Basic examples

### Basic

Example source: src/dialog/__demos__/basic.vue

```vue
<template>
  <c-button @click="open = true">Open Dialog</c-button>

  <c-dialog
    v-model:open="open"
    title="Dialog Title"
    message="This is a basic component dialog."
    @confirm="Message.success('Confirmed')"
    @cancel="Message.info('Cancelled')"
  />
</template>

<script setup lang="ts">
import { Message } from "@cedar-design/ui";
import { ref } from "vue";

const open = ref(false);
</script>
```

## Invocation and content

### Global

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `title` | Title | Confirm, Form, Simple |
| `type` | Status icon: `info`, `success`, `warning` or `error` | Confirm, Simple |
| `message` | Message content; the default slot is also supported | Confirm, Simple |
| `before-close` | Return a boolean/Promise or call done; the first completion wins | Form |
| `simple` | Compact layout with a centered footer | Simple |
<!-- demo-config-notes:end -->


Example source: src/dialog/__demos__/global.vue

```vue
<template>
  <c-space>
    <c-button @click="openBasic">Basic</c-button>
    <c-button @click="openDialog">Open</c-button>
    <c-button @click="openAndUpdate">Open and Update</c-button>
    <c-button @click="awaitAction">Await Action</c-button>
    <c-button @click="hideButtons">Hide Footer Buttons</c-button>
  </c-space>
</template>

<script setup lang="ts">
import { Dialog, Message } from "@cedar-design/ui";

function openBasic() {
  Dialog.open("This dialog was opened from a string message.");
}

function openDialog() {
  Dialog.open({
    title: "Global Method",
    message: "This dialog was opened programmatically.",
  });
}

function openAndUpdate() {
  const instance = Dialog.open({
    title: "Submitting",
    message: "Processing the request…",
  });
  window.setTimeout(
    () =>
      instance.update({
        title: "Completed",
        message: "The request succeeded.",
      }),
    800,
  );
}

async function awaitAction() {
  const action = await Dialog.open("Choose an action to close this dialog.");
  if (action) Message.info(`Dialog action: ${action}`);
}

function hideButtons() {
  Dialog.open({
    title: "No Footer Buttons",
    message: "Click the overlay or press Esc to dismiss this dialog.",
    confirmButton: false,
    cancelButton: false,
  });
}
</script>
```

### Alert

Example source: src/dialog/__demos__/alert.vue

```vue
<template>
  <c-button @click="handleClick">Alert</c-button>
</template>

<script lang="ts">
import { Dialog } from '@cedar-design/ui'

export default {
  setup() {
    const handleClick = () => {
      Dialog.alert({
        title: 'Alert',
        message: 'This is an alert description.',
        type: 'info',
      })
    }

    return { handleClick }
  },
}
</script>
```

### Confirm

Example source: src/dialog/__demos__/confirm.vue

```vue
<template>
  <c-space>
    <c-button @click="openConfirm">Confirm</c-button>
    <c-button status="danger" @click="openDangerConfirm">Delete</c-button>
    <c-button @click="componentOpen = true">Component Confirm</c-button>
  </c-space>

  <c-dialog
    v-model:open="componentOpen"
    type="warning"
    title="Confirm Action"
    message="Are you sure you want to continue?"
  />
</template>

<script setup lang="ts">
import { ref } from "vue";
import { Dialog, Message } from "@cedar-design/ui";

const componentOpen = ref(false);

async function openConfirm() {
  const action = await Dialog.confirm({
    title: "Confirm Action",
    message: "Are you sure you want to continue?",
  });
  if (action) Message.info(`Dialog action: ${action}`);
}

async function openDangerConfirm() {
  const action = await Dialog.confirm({
    title: "Dangerous Action",
    message: "This action cannot be undone. Continue?",
    confirmButtonText: "Delete",
    confirmButtonProps: { variant: "default", status: "danger" },
  });
  if (action) Message.info(`Dialog action: ${action}`);
}
</script>
```

### Message

Example source: src/dialog/__demos__/message.vue

```vue
<template>
  <c-space>
    <c-button @click="handleClickInfo">Info</c-button>
    <c-button status="success" @click="handleClickSuccess">Success</c-button>
    <c-button status="warning" @click="handleClickWarning">Warning</c-button>
    <c-button status="danger" @click="handleClickError">Error</c-button>
  </c-space>
</template>

<script lang="ts">
import { Dialog } from '@cedar-design/ui'

export default {
  setup() {
    const handleClickInfo = () => {
      Dialog.info({
        title: 'Info Notification',
        message: 'This is an info description which directly indicates a neutral informative change or action.',
      })
    }
    const handleClickSuccess = () => {
      Dialog.success({
        title: 'Success Notification',
        message: 'This is a success notification',
      })
    }
    const handleClickWarning = () => {
      Dialog.warning({
        title: 'Warning Notification',
        message: 'This is a warning description which directly indicates a warning that might need attention.',
      })
    }
    const handleClickError = () => {
      Dialog.error({
        title: 'Error Notification',
        message: 'This is an error description which directly indicates a dangerous or potentially negative action.',
      })
    }

    return {
      handleClickInfo,
      handleClickSuccess,
      handleClickWarning,
      handleClickError,
    }
  },
}
</script>
```

### Form

Example source: src/dialog/__demos__/form.vue

```vue
<template>
  <c-button @click="handleClick">Open Form Dialog</c-button>
  <c-dialog v-model:open="visible" title="Dialog Form" @cancel="handleCancel" :before-close="handleBeforeClose">
    <c-form :model="form">
      <c-form-item field="name" label="Name">
        <c-input v-model="form.name" />
      </c-form-item>
      <c-form-item field="post" label="Post">
        <c-select v-model="form.post">
          <c-option value="post1">Post1</c-option>
          <c-option value="post2">Post2</c-option>
          <c-option value="post3">Post3</c-option>
          <c-option value="post4">Post4</c-option>
        </c-select>
      </c-form-item>
    </c-form>
  </c-dialog>
</template>

<script lang="ts">
import { defineComponent, reactive, ref } from 'vue'

export default defineComponent({
  setup() {
    const visible = ref(false)
    const form = reactive({
      name: '',
      post: '',
    })

    const handleClick = () => {
      visible.value = true
    }

    const handleBeforeClose = ({ action }, done) => {
      if (action !== 'confirm') {
        done()
        return
      }

      window.setTimeout(() => {
        done()
      }, 2000)
    }

    const handleCancel = () => {
      visible.value = false
    }

    return {
      visible,
      form,
      handleClick,
      handleBeforeClose,
      handleCancel,
    }
  },
})
</script>
```

### Simple

Example source: src/dialog/__demos__/simple.vue

```vue
<template>
  <c-button @click="open = true">Open Simple Dialog</c-button>

  <c-dialog
    v-model:open="open"
    simple
    type="info"
    title="Simple Dialog"
    message="A compact dialog for short and focused information."
  />
</template>

<script setup lang="ts">
import { ref } from "vue";

const open = ref(false);
</script>
```

## Sizing and layout

### Dialog sizing and long content

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `title` | Title | No Padding, Max Height |
| `body-style` | Body style | No Padding, Max Height |
| `width` | Width | Dialog sizing and long content |
| `fullscreen` | Fullscreen layout | Dialog sizing and long content |
<!-- demo-config-notes:end -->


Open one dialog at a time to compare widths, fullscreen layouts and long-content boundaries.

Example source: src/dialog/__demos__/size-comparison.vue

```vue
<script setup lang="ts">
import { ref } from "vue"
import { proxyRefs as demoProxyRefs } from 'vue'

const scene1 = demoProxyRefs((() => {


    const visibleSmall = ref(false)


    const visibleMedium = ref(false)


    const visibleLarge = ref(false)



    const handleClickSmall = () => {
      visibleSmall.value = true
    }


    const handleClickMedium = () => {
      visibleMedium.value = true
    }


    const handleClickLarge = () => {
      visibleLarge.value = true
    }


    const handleConfirm = () => {
      visibleSmall.value = false
      visibleMedium.value = false
      visibleLarge.value = false
    }


    const handleCancel = () => {
      visibleSmall.value = false
      visibleMedium.value = false
      visibleLarge.value = false
    }
return { visibleSmall, visibleMedium, visibleLarge, handleClickSmall, handleClickMedium, handleClickLarge, handleConfirm, handleCancel }
})())

const scene2 = demoProxyRefs((() => {


    const show = ref(false)



    const handleClick = () => {
      show.value = true
    }


    const handleConfirm = () => {
      show.value = false
    }


    const handleCancel = () => {
      show.value = false
    }
return { show, handleClick, handleConfirm, handleCancel }
})())
</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="width">
    <h4><span lang="zh-CN">对话框宽度</span><span lang="en-US">Width</span></h4>
    <c-space>
        <c-button @click="scene1.handleClickSmall">Small Dialog</c-button>
        <c-button @click="scene1.handleClickMedium">Medium Dialog</c-button>
        <c-button @click="scene1.handleClickLarge">Large Dialog</c-button>
      </c-space>
      <c-dialog :width="400" v-model:open="scene1.visibleSmall" @confirm="scene1.handleConfirm" @cancel="scene1.handleCancel">
        <template #title>Small Dialog</template>
        <div>
          You can customize modal body text by the current situation. This modal will be closed immediately once you press
          the OK button.
        </div>
      </c-dialog>
      <c-dialog v-model:open="scene1.visibleMedium" @confirm="scene1.handleConfirm" @cancel="scene1.handleCancel">
        <template #title>Medium Dialog</template>
        <div>
          You can customize modal body text by the current situation. This modal will be closed immediately once you press
          the OK button.
        </div>
      </c-dialog>
      <c-dialog :width="720" v-model:open="scene1.visibleLarge" @confirm="scene1.handleConfirm" @cancel="scene1.handleCancel">
        <template #title>Large Dialog</template>
        <div>
          You can customize modal body text by the current situation. This modal will be closed immediately once you press
          the OK button.
        </div>
      </c-dialog>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="fullscreen">
    <h4><span lang="zh-CN">全屏</span><span lang="en-US">Fullscreen</span></h4>
    <c-button @click="scene2.handleClick">Open Dialog</c-button>
      <c-dialog v-model:open="scene2.show" @confirm="scene2.handleConfirm" @cancel="scene2.handleCancel" fullscreen>
        <template #title>Title</template>
        <div>
          You can customize modal body text by the current situation. This modal will be closed immediately once you press
          the OK button.
        </div>
      </c-dialog>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

### No Padding

Example source: src/dialog/__demos__/no-padding.vue

```vue
<template>
  <c-space>
    <c-button @click="handleClick">Open Dialog</c-button>
  </c-space>

  <c-dialog
    v-model:open="show"
    title="no-padding"
    :body-style="{ padding: 0 }"
    @cancel="handleCancel"
    @confirm="handleConfirm"
  >
    <div class="p-24">
      You can customize modal body text by the current situation. This modal
      will be closed immediately once you press the OK button.
    </div>
  </c-dialog>
</template>

<script lang="ts">
import { defineComponent, ref } from "vue";
export default defineComponent({
  setup() {
    const show = ref(false);

    const handleClick = () => {
      show.value = true;
    };
    const handleConfirm = () => {
      show.value = false;
    };
    const handleCancel = () => {
      show.value = false;
    };

    return {
      show,
      handleClick,
      handleConfirm,
      handleCancel,
    };
  },
});
</script>
```

### Max Height

Example source: src/dialog/__demos__/max-height.vue

```vue
<template>
  <c-button @click="open = true">Open Long Content Dialog</c-button>

  <c-dialog
    v-model:open="open"
    title="Long Content"
    :body-style="{ maxHeight: '50vh', overflowY: 'auto' }"
  >
    <p v-for="item in 12" :key="item">
      {{ item }}. Long dialog content remains scrollable while the title and
      actions stay visible.
    </p>
  </c-dialog>
</template>

<script setup lang="ts">
import { ref } from "vue";

const open = ref(false);
</script>
```

## Interaction and customization

### Draggable

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `unmount-on-close` | Unmount after closing | Custom Text, Advanced |
| `draggable` | Draggable | Draggable |
| `confirm-button-text` | Confirm button text | Custom Text |
| `cancel-button-text` | Cancel button text | Custom Text |
| `footer` | Whether to show the footer | Advanced |
| `type` | Status icon: `info`, `success`, `warning` or `error` | Advanced |
<!-- demo-config-notes:end -->


Example source: src/dialog/__demos__/draggable.vue

```vue
<template>
  <c-button @click="handleClick">Open Dialog</c-button>
  <c-dialog v-model:open="show" @confirm="handleConfirm" @cancel="handleCancel" draggable>
    <template #title>Title</template>
    <div>
      You can customize modal body text by the current situation. This modal will be closed immediately once you press
      the OK button.
    </div>
  </c-dialog>
</template>

<script lang="ts">
import { defineComponent, ref } from 'vue'
export default defineComponent({
  setup() {
    const show = ref(false)

    const handleClick = () => {
      show.value = true
    }
    const handleConfirm = () => {
      show.value = false
    }
    const handleCancel = () => {
      show.value = false
    }

    return {
      show,
      handleClick,
      handleConfirm,
      handleCancel,
    }
  },
})
</script>
```

### Custom Footer

Example source: src/dialog/__demos__/custom-footer.vue

```vue
<template>
  <c-button @click="open = true">Open Custom Footer Dialog</c-button>

  <c-dialog v-model:open="open">
    <template #title>Custom Slots</template>
    Use the footer slot when the actions need different priorities or wording.
    <template #footer="{ close, cancel, confirm }">
      <c-space>
        <c-button variant="text" @click="close">Later</c-button>
        <c-button variant="outline" @click="cancel">Cancel</c-button>
        <c-button status="primary" @click="confirm">Continue</c-button>
      </c-space>
    </template>
  </c-dialog>
</template>

<script setup lang="ts">
import { ref } from "vue";

const open = ref(false);
</script>
```

### Custom Text

Example source: src/dialog/__demos__/custom-text.vue

```vue
<template>
  <c-button @click="handleClick">Open Dialog</c-button>
  <c-dialog
    v-model:open="show"
    @confirm="handleConfirm"
    @cancel="handleCancel"
    confirmButtonText="Confirm"
    cancelButtonText="Exit"
    unmountOnClose
  >
    <template #title>Title</template>
    <div>
      You can customize modal body text by the current situation. This modal will be closed immediately once you press
      the OK button.
    </div>
  </c-dialog>
</template>

<script lang="ts">
import { defineComponent, ref } from 'vue'
export default defineComponent({
  setup() {
    const show = ref(false)

    const handleClick = () => {
      show.value = true
    }
    const handleConfirm = () => {
      show.value = false
    }
    const handleCancel = () => {
      show.value = false
    }

    return {
      show,
      handleClick,
      handleConfirm,
      handleCancel,
    }
  },
})
</script>
```

### Advanced

Example source: src/dialog/__demos__/advanced.vue

```vue
<template>
  <c-space>
    <c-button @click="footerHiddenOpen = true">Hide Footer</c-button>
    <c-button @click="titleHiddenOpen = true">Hide Title</c-button>
    <c-button @click="customBodyOpen = true">Custom Body</c-button>
    <c-button @click="unmountOpen = true">Unmount on Close</c-button>
  </c-space>

  <c-dialog
    v-model:open="footerHiddenOpen"
    :footer="false"
    type="info"
    title="Read Only"
    message="This dialog intentionally has no footer actions."
  />
  <c-dialog
    v-model:open="titleHiddenOpen"
    hide-title
    aria-label="Dialog without a visible title"
    type="warning"
    message="Use aria-label when the visible title is hidden."
  />
  <c-dialog
    v-model:open="customBodyOpen"
    type="info"
    title="Custom Body"
    message="The body supports custom alignment, classes, and inline styles."
    message-align="center"
    body-class="dialog-demo__body--custom"
    :body-style="{
      padding: '16px 20px',
      background: 'rgba(22, 93, 255, 0.08)',
      borderRadius: '8px',
    }"
  />
  <c-dialog
    v-model:open="unmountOpen"
    unmount-on-close
    title="Unmount on Close"
  >
    This content is removed from the DOM after the close transition.
  </c-dialog>
</template>

<script setup lang="ts">
import { ref } from "vue";

const footerHiddenOpen = ref(false);
const titleHiddenOpen = ref(false);
const customBodyOpen = ref(false);
const unmountOpen = ref(false);
</script>

<style scoped>
:deep(.dialog-demo__body--custom) {
  font-weight: 500;
}
</style>
```

## Async actions and closing

### Async

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `before-close` | Return a boolean/Promise or call done; the first completion wins | Async, Guard Protocol |
| `title` | Title | Async |
| `message` | Message content; the default slot is also supported | Async |
<!-- demo-config-notes:end -->


Example source: src/dialog/__demos__/async.vue

```vue
<template>
  <c-space>
    <c-button @click="asyncOpen = true">Async Close</c-button>
    <c-button @click="loadingOpen = true">Button Loading</c-button>
  </c-space>

  <c-dialog
    v-model:open="asyncOpen"
    title="Async Close"
    message="Every action waits for the asynchronous task to finish."
    :before-close="beforeClose"
  />
  <c-dialog
    v-model:open="loadingOpen"
    title="Button Loading"
    message="The confirm button displays loading while the task is running."
    :before-close="buttonLoadingClose"
  />
</template>

<script setup lang="ts">
import { ref } from "vue";
import type { DialogAction } from "../types";

const asyncOpen = ref(false);
const loadingOpen = ref(false);

function beforeClose({ action: _action }: { action: DialogAction }, done: () => void) {
  window.setTimeout(done, 1000);
}

function buttonLoadingClose(
  { action }: { action: DialogAction },
  done: () => void,

) {
  if (action !== "confirm") {
    done();
    return;
  }

  window.setTimeout(() => {
    done();
  }, 1000);
}
</script>
```

### Api Review

### Guard Protocol

Example source: src/dialog/__demos__/en-US/guard-protocol.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import type { DialogBeforeClose } from "@cedar-design/ui";
const open = ref(false);
const mode = ref("promise");
const allowed = ref(false);
const status = ref("");
const check: DialogBeforeClose = (payload, done, { signal }) => {
  status.value = `Waiting: ${payload.action}`;
  if (mode.value === "done") {
    setTimeout(() => {
      status.value = allowed.value ? "Allowed" : "Rejected";
      done(!signal.aborted && allowed.value);
    }, 500);
    return;
  }
  return new Promise<boolean>((resolve) =>
    setTimeout(() => {
      status.value = allowed.value ? "Allowed" : "Rejected";
      resolve(!signal.aborted && allowed.value);
    }, 500),
  );
};
</script>
<template>
  <c-space direction="column" align="stretch">
    <c-switch v-model="allowed" />
    <c-form-item layout="vertical" size="sm" label="mode">
      <c-radio-group
        aria-label="mode"
        v-model="mode"
        :options="[
          { value: 'promise', label: 'Promise' },
          { value: 'done', label: 'done callback' },
        ]"
        variant="button"
        size="sm"
      />
    </c-form-item>
    <c-button @click="open = true">Open</c-button>
    <c-dialog
      v-model:open="open"
      :before-close="check"
      @guard-error="status = 'Error'"
    >
      <template #default
        ><c-button v-if="false" @click="open = true">Confirm action</c-button
        ><span v-else>Close with beforeClose</span></template
      >
    </c-dialog>
    <p role="status">{{ status }}</p>
  </c-space>
</template>
```

### `<Dialog>` Props

| Name | Description | Type | Default |
| ------------------------- | -------------------------------------------- | -------------------------------- | ------------ |
| dir | Reading direction; inherits the source scope when omitted. Physical left/right placements keep their meaning. | `ReadingDirection` (`ltr` / `rtl`) | — |
| `open` **(v-model)** | Visible state | `boolean` | `-` |
| `default-open` | Initial uncontrolled state | `boolean` | `false` |
| `title` | Title | `string` | `-` |
| `message` | Message content; the default slot is also supported | `string` | `-` |
| `message-align` | Message alignment | `'left' \| 'center' \| 'right'` | `'left'` |
| `type` | Status icon: info, success, warning or error | `string` | `-` |
| `simple` | Compact layout with a centered footer | `boolean` | `false` |
| `width` | Width | `number \| string` | `-` |
| `top` | Top offset; ignored when align-center is enabled | `number \| string` | `-` |
| `title-align` | Title alignment | `'start' \| 'center'` | `'center'` |
| `align-center` | Center vertically and horizontally | `boolean` | `true` |
| `overlay` | Show overlay | `boolean` | `true` |
| `overlay-class` | Overlay class | `string` | `-` |
| `overlay-style` | Overlay style | `CSSProperties` | `-` |
| `overlay-closable` | Request closure on an overlay click | `boolean` | `true` |
| `esc-to-close` | Request closure on Escape | `boolean` | `true` |
| `lock-scroll` | Lock background scrolling while open | `boolean` | `true` |
| `close-on-route-change` | Close on browser history or hash changes | `boolean` | `false` |
| `popup-container` | Teleport target; `false` disables teleport | `string \| HTMLElement \| false` | `'body'` |
| `confirm-button` | Show the confirm button | `boolean` | `true` |
| `cancel-button` | Show the cancel button | `boolean` | `true` |
| `closable` | Show close button | `boolean` | `true` |
| `confirm-button-text` | Confirm button text | `string` | `-` |
| `cancel-button-text` | Cancel button text | `string` | `-` |
| `confirm-button-loading` | Confirm button loading state | `boolean` | `false` |
| `cancel-button-loading` | Cancel button loading state | `boolean` | `false` |
| `confirm-button-disabled` | Disable the confirm button | `boolean` | `false` |
| `cancel-button-disabled` | Disable the cancel button | `boolean` | `false` |
| `confirm-button-props` | Confirm button props | `ButtonProps` | `-` |
| `cancel-button-props` | Cancel button props | `ButtonProps` | `-` |
| `footer` | Show the footer | `boolean` | `true` |
| `dialog-class` | Dialog class | `string \| any[]` | `-` |
| `dialog-style` | Dialog style | `CSSProperties` | `-` |
| `body-class` | Body class | `string \| any[]` | `-` |
| `body-style` | Body style | `StyleValue` | `-` |
| `hide-title` | Hide the title | `boolean` | `false` |
| `unmount-on-close` | Unmount after closing | `boolean` | `false` |
| `draggable` | Allow dragging | `boolean` | `false` |
| `fullscreen` | Fullscreen layout | `boolean` | `false` |
| `overlay-animation-name` | Overlay animation name | `string` | `fade-modal` |
| `dialog-animation-name` | Dialog animation name | `string` | `zoom-modal` |
| `z-index` | Stack level | `number` | `-` |
| `before-close` | Return a boolean/Promise or call done; the first completion wins | `DialogBeforeClose` | — |

### `<Dialog>` Events

| Event | Description | Arguments |
| ------------ | ------------- | --------------- |
| `open` | Opening begins | `-` |
| `opened` | Opening transition completes | `-` |
| `close` | Closing begins | `-` |
| `closed` | Closing transition completes | `-` |
| `confirm` | Accepted confirm action | `Event` |
| `cancel` | Accepted cancel or close action | `Event` |
| `click-overlay` | `MouseEvent` | `MouseEvent` |
| `key-escape` | ESC | `KeyboardEvent` |

### `<Dialog>` Slots

| Slot | Description | Arguments |
| --------- | ---- | ---------------------------- |
| `default` | Content | `-` |
| `title` | Title | `-` |
| `footer` | Footer | `cancel`, `confirm`, `close` |

### DialogConfig

| Name | Description | Type |
| ------------- | ---------------------------------- | -------------------------- |
| `content` | Renderable content; takes priority over message | `RenderContent` |
| `footer` | Footer visibility or custom footer content | `boolean \| RenderContent` |
| `onConfirm` | Confirm callback | `(e?: Event) => void` |
| `onCancel` | Cancel callback | `(e?: Event) => void` |
| `onClickOverlay` | Overlay click callback | `() => void` |
| `onKeyEscape` | Escape callback | `() => void` |

### DialogMethod

| Method | Description | Return value |
| ---------------------------------- | ------------------------------ | -------------------------------------- |
| `Dialog.open(config)` | Open a dialog | `Promise<DialogAction> & DialogReturn` |
| `Dialog.confirm(config)` | Confirmation dialog; defaults to warning | Same as above |
| `Dialog.alert(config)` | Alert dialog without a cancel button | Same as above |
| `Dialog.info(config)` | Information dialog | Same as above |
| `Dialog.success(config)` | Success dialog | Same as above |
| `Dialog.warning(config)` | Warning dialog | Same as above |
| `Dialog.error(config)` | Error dialog | Same as above |
| `Dialog.close()` | Close the latest functional dialog | `void` |
| `Dialog.setDefaultOptions(config)` | Set default programmatic options | `void` |
| `Dialog.resetDefaultOptions()` | Reset default programmatic options | `void` |

### DialogReturn

| Prop | Description |
| ---------------- | -------- |
| `close()` | Close |
| `update(config)` | Update options |

### Reading direction

Inherits the nearest `dir="ltr|rtl"` and supports runtime and nested overrides. Content, headings and action gaps use logical edges. Portals inherit their source direction. Direction changes preserve close, confirm, cancel and pending-state semantics.

## API details
| Variable | Default |
| --- | --- |
| `--c-dialog-background` | `var(--c-sys-color-surface-raised)` |
| `--c-dialog-overlay-background` | `var(--c-sys-color-scrim)` |
| `--c-dialog-border-color` | `var(--c-sys-color-border-default)` |
| `--c-dialog-border-width` | `1px` |
| `--c-dialog-border-radius` | `var(--c-sys-radius-md)` |
| `--c-dialog-width` | `520px` |
| `--c-dialog-margin-top` | `100px` |
| `--c-dialog-title-text-color` | `var(--c-sys-color-content-primary)` |
| `--c-dialog-title-font-size` | `var(--c-sys-font-size-lg)` |
| `--c-dialog-title-font-weight` | `var(--c-sys-font-weight-medium)` |
| `--c-dialog-title-padding` | `0 var(--c-sys-space-8)` |
| `--c-dialog-title-min-height` | `48px` |
| `--c-dialog-title-justify` | `center` |
| `--c-dialog-content-text-color` | `var(--c-sys-color-content-primary)` |
| `--c-dialog-content-font-size` | `var(--c-sys-font-size-md)` |
| `--c-dialog-content-line-height` | `var(--c-line-height)` |
| `--c-dialog-content-padding` | `28px var(--c-sys-space-8)` |
| `--c-dialog-actions-padding` | `var(--c-sys-space-7) var(--c-sys-space-8)` |
| `--c-dialog-actions-button-gap` | `var(--c-sys-space-6)` |
| `--c-dialog-close-button-size` | `32px` |
| `--c-dialog-close-button-color` | `var(--c-sys-color-content-secondary)` |
| `--c-dialog-close-button-font-size` | `var(--c-sys-font-size-lg)` |
| `--c-dialog-close-button-inset-inline-end` | `var(--c-sys-space-7)` |
| `--c-dialog-status-icon-size` | `18px` |
| `--c-dialog-status-icon-gap` | `var(--c-sys-space-5)` |
| `--c-dialog-status-info-color` | `var(--c-sys-color-content-info)` |
| `--c-dialog-status-success-color` | `var(--c-sys-color-content-success)` |
| `--c-dialog-status-warning-color` | `var(--c-sys-color-content-warning)` |
| `--c-dialog-status-danger-color` | `var(--c-sys-color-content-danger)` |
| `--c-dialog-simple-width` | `400px` |
| `--c-dialog-simple-border-radius` | `var(--c-sys-radius-md)` |
| `--c-dialog-simple-padding` | `28px 32px 32px` |
| `--c-dialog-simple-content-gap` | `28px` |
| `--c-dialog-simple-actions-gap` | `32px` |
| `--c-dialog-fullscreen-width` | `100vw` |
| `--c-dialog-fullscreen-height` | `100vh` |
| `--c-dialog-animation-duration` | `var(--c-sys-motion-duration-slow)` |
| `--c-dialog-animation-easing` | `var(--c-sys-motion-easing-standard)` |


Promise and done share a single completion state: false/done(false) rejects; true/done() allows; a resolved Promise&lt;void&gt; allows. The first completion wins. Errors emit guard-error; cancellation/unmount invalidates late completion. Synchronous void retains the callback protocol and waits for done on these close/confirm guards.


Cancellable hooks use `(payload, done, context)`: closure payloads contain `{ action }`, change/commit payloads contain `{ value, previousValue }`, and Popup uses `{ reason }`. Context provides `signal` and an optional original `event`. Return a boolean/Promise, or call done()/done(false). Synchronous void waits for done; Promise&lt;void&gt; allows the operation. First completion wins. Pending state controls loading/disabled automatically. Cancellation invalidates stale results. Button refs are not exposed.

## API

### `<Dialog>` Props

| Parameter | Description | Type | Default |
| ------------------------- | -------------------------------------------- | -------------------------------- | ------------ |
| dir | Reading direction; inherits the source scope when omitted. Physical left/right placements keep their meaning. | `ReadingDirection` (`ltr` / `rtl`) | — |
| `open` **(v-model)** | Visible state | `boolean` | `-` |
| `default-open` | Initial uncontrolled state | `boolean` | `false` |
| `title` | Title | `string` | `-` |
| `message` | Message content; the default slot is also supported | `string` | `-` |
| `message-align` | Message alignment | `'left' \| 'center' \| 'right'` | `'left'` |
| `type` | Status icon: `info`, `success`, `warning` or `error` | `string` | `-` |
| `simple` | Compact layout with a centered footer | `boolean` | `false` |
| `width` | Width | `number \| string` | `-` |
| `top` | Top offset; ignored when `align-center` is enabled | `number \| string` | `-` |
| `title-align` | Title alignment | `'start' \| 'center'` | `'center'` |
| `align-center` | Center vertically and horizontally | `boolean` | `true` |
| `overlay` | Show overlay | `boolean` | `true` |
| `overlay-class` | Overlay class | `string` | `-` |
| `overlay-style` | Overlay style | `CSSProperties` | `-` |
| `overlay-closable` | Request closure on an overlay click | `boolean` | `true` |
| `esc-to-close` | Request closure on Escape | `boolean` | `true` |
| `lock-scroll` | Lock background scrolling while open | `boolean` | `true` |
| `close-on-route-change` | Close on browser history or hash changes | `boolean` | `false` |
| `popup-container` | Teleport target; `false` disables teleport | `string \| HTMLElement \| false` | `'body'` |
| `confirm-button` | Show the confirm button | `boolean` | `true` |
| `cancel-button` | Show the cancel button | `boolean` | `true` |
| `closable` | Show close button | `boolean` | `true` |
| `confirm-button-text` | Confirm button text | `string` | `-` |
| `cancel-button-text` | Cancel button text | `string` | `-` |
| `confirm-button-loading` | Confirm button loading state | `boolean` | `false` |
| `cancel-button-loading` | Cancel button loading state | `boolean` | `false` |
| `confirm-button-disabled` | Disable the confirm button | `boolean` | `false` |
| `cancel-button-disabled` | Disable the cancel button | `boolean` | `false` |
| `confirm-button-props` | Confirm button props | `ButtonProps` | `-` |
| `cancel-button-props` | Cancel button props | `ButtonProps` | `-` |
| `footer` | Whether to show the footer | `boolean` | `true` |
| `dialog-class` | Dialog class | `string \| any[]` | `-` |
| `dialog-style` | Dialog style | `CSSProperties` | `-` |
| `body-class` | Body class | `string \| any[]` | `-` |
| `body-style` | Body style | `StyleValue` | `-` |
| `hide-title` | Hide the title | `boolean` | `false` |
| `unmount-on-close` | Unmount after closing | `boolean` | `false` |
| `draggable` | Allow dragging | `boolean` | `false` |
| `fullscreen` | Fullscreen layout | `boolean` | `false` |
| `overlay-animation-name` | Overlay animation name | `string` | `fade-modal` |
| `dialog-animation-name` | Dialog animation name | `string` | `zoom-modal` |
| `z-index` | Stack level | `number` | `-` |
| `before-close` | Return a boolean/Promise or call done; the first completion wins | `DialogBeforeClose` | — |

### `<Dialog>` Events

| Event | Description | Arguments |
| ------------ | ------------- | --------------- |
| `open` | When opened | `-` |
| `opened` | Opening transition completes | `-` |
| `close` | Closing begins | `-` |
| `closed` | Closing transition completes | `-` |
| `confirm` | Accepted confirm action | `Event` |
| `cancel` | Accepted cancel or close action | `Event` |
| `click-overlay` | `MouseEvent` | `MouseEvent` |
| `key-escape` | ESC | `KeyboardEvent` |

The `close` button, overlay, ESC and `close()` use `close` semantics without an additional `cancel` event.

### `<Dialog>` Slots

| Slot | Description | Arguments |
| --------- | ---- | ---------------------------- |
| `default` | Content | `-` |
| `title` | Title | `-` |
| `footer` | Footer | `cancel`, `confirm`, `close` |

Confirm and cancel buttons use Button's `default` status and `text` variant unless `confirmButtonProps` or `cancelButtonProps` overrides them.

### Global methods

Function-based Dialog calls default to simple layout (`simple: true`) with the top-right close button hidden (`closable: false`). Explicit options or global defaults can override both.

#### DialogConfig

Accepts the component props in camelCase, plus:

| Parameter | Description | Type |
| ------------- | ---------------------------------- | -------------------------- |
| `content` | Renderable content; takes priority over `message` | `RenderContent` |
| `footer` | Whether to show a footer, or custom footer content | `boolean \| RenderContent` |
| `onConfirm` | Confirm callback | `(e?: Event) => void` |
| `onCancel` | Cancel callback | `(e?: Event) => void` |
| `onClickOverlay` | Overlay click callback | `() => void` |
| `onKeyEscape` | Escape callback | `() => void` |

#### DialogMethod

| Method | Description | Returns |
| ---------------------------------- | ------------------------------ | -------------------------------------- |
| `Dialog.open(config)` | Open a dialog | `Promise<DialogAction> & DialogReturn` |
| `Dialog.confirm(config)` | Confirmation dialog; defaults to `type: warning` | As above |
| `Dialog.alert(config)` | Alert dialog without a cancel button | As above |
| `Dialog.info(config)` | Information dialog | As above |
| `Dialog.success(config)` | Success dialog | As above |
| `Dialog.warning(config)` | Warning dialog | As above |
| `Dialog.error(config)` | Error dialog | As above |
| `Dialog.close()` | Close the latest functional dialog | `void` |
| `Dialog.setDefaultOptions(config)` | Set default programmatic options | `void` |
| `Dialog.resetDefaultOptions()` | Reset default programmatic options | `void` |

#### DialogReturn

| Prop | Description |
| ---------------- | -------- |
| `close()` | Close |
| `update(config)` | Update options |

After installation, call through `app.config.globalProperties.$dialog`.

### Type definitions

```ts
import type {
  DialogAction,
  DialogConfig,
  DialogMethod,
  DialogReturn,
  DialogService,
  DialogType,
} from "@cedar-design/ui";
```

### Style variables

Dialog public color variables have the same meanings as Maple: `--c-dialog-background` is the raised panel background (`surface-raised`); `--c-dialog-overlay-background` is the scrim; `--c-dialog-title-text-color` and `--c-dialog-content-text-color` are primary content; `--c-dialog-close-button-color` is the secondary action. `--c-dialog-status-{info|success|warning|danger}-color` uses readable content-info/success/warning/danger, not status fills. Business themes should override these component variables; shared themes should override the corresponding system variables. Borders, widths, spacing and layout retain desktop specifications.

#### Complete variable defaults

The backdrop consumes `sys-color-scrim` through the Dialog component variable. Maple no longer uses Popup colors for Dialog. Set a per-instance backdrop variable via `overlay-style`; a variable on the panel (`dialog-style`) does not inherit to its sibling backdrop. Explicit `overlay-style.backgroundColor` wins. Teleported content needs variables on its actual DOM ancestors. Dark themes inherit the same semantic colors; geometry remains platform-specific. Status icons use readable content colors.

Variables are grouped by purpose: background/overlay-background for panel/scrim; border-* for panel/divider borders; title-* for title typography; content-* for body typography; actions-* for actions; close-button-* for the close button; status-* for semantic icons; simple-*/fullscreen-* for mode dimensions; animation-* for enter/leave motion. width/margin-top control ordinary panel layout. Internal drag/position variables are not public customization points.

| Variable | Default |
| --- | --- |
| `--c-dialog-background` | `var(--c-sys-color-surface-raised)` |
| `--c-dialog-overlay-background` | `var(--c-sys-color-scrim)` |
| `--c-dialog-border-color` | `var(--c-sys-color-border-default)` |
| `--c-dialog-border-width` | `1px` |
| `--c-dialog-border-radius` | `var(--c-sys-radius-md)` |
| `--c-dialog-width` | `520px` |
| `--c-dialog-margin-top` | `100px` |
| `--c-dialog-title-text-color` | `var(--c-sys-color-content-primary)` |
| `--c-dialog-title-font-size` | `var(--c-sys-font-size-lg)` |
| `--c-dialog-title-font-weight` | `var(--c-sys-font-weight-medium)` |
| `--c-dialog-title-padding` | `0 var(--c-sys-space-8)` |
| `--c-dialog-title-min-height` | `48px` |
| `--c-dialog-title-justify` | `center` |
| `--c-dialog-content-text-color` | `var(--c-sys-color-content-primary)` |
| `--c-dialog-content-font-size` | `var(--c-sys-font-size-md)` |
| `--c-dialog-content-line-height` | `var(--c-line-height)` |
| `--c-dialog-content-padding` | `28px var(--c-sys-space-8)` |
| `--c-dialog-actions-padding` | `var(--c-sys-space-7) var(--c-sys-space-8)` |
| `--c-dialog-actions-button-gap` | `var(--c-sys-space-6)` |
| `--c-dialog-close-button-size` | `32px` |
| `--c-dialog-close-button-color` | `var(--c-sys-color-content-secondary)` |
| `--c-dialog-close-button-font-size` | `var(--c-sys-font-size-lg)` |
| `--c-dialog-close-button-inset-inline-end` | `var(--c-sys-space-7)` |
| `--c-dialog-status-icon-size` | `18px` |
| `--c-dialog-status-icon-gap` | `var(--c-sys-space-5)` |
| `--c-dialog-status-info-color` | `var(--c-sys-color-content-info)` |
| `--c-dialog-status-success-color` | `var(--c-sys-color-content-success)` |
| `--c-dialog-status-warning-color` | `var(--c-sys-color-content-warning)` |
| `--c-dialog-status-danger-color` | `var(--c-sys-color-content-danger)` |
| `--c-dialog-simple-width` | `400px` |
| `--c-dialog-simple-border-radius` | `var(--c-sys-radius-md)` |
| `--c-dialog-simple-padding` | `28px 32px 32px` |
| `--c-dialog-simple-content-gap` | `28px` |
| `--c-dialog-simple-actions-gap` | `32px` |
| `--c-dialog-fullscreen-width` | `100vw` |
| `--c-dialog-fullscreen-height` | `100vh` |
| `--c-dialog-animation-duration` | `var(--c-sys-motion-duration-slow)` |
| `--c-dialog-animation-easing` | `var(--c-sys-motion-easing-standard)` |

### Before-hook waiting feedback

Before-hook waits show visible feedback and aria-busy. Rejected or failed operations recover; duplicate submissions do not start another copy. Notification event Promises never drive loading.

Service notification callbacks do not control task completion. The selected/closed result is settled independently of callback errors, and closing completion always releases the owned host. Callback errors still propagate through the calling/Vue error path; returned Promises do not control loading or closing.

---

Document: llms/en-US/components/divider.md

<!-- Source: src/divider/README.en-US.md; locale: en-US; page: /en/components/divider/ -->

# Divider

Separate content sections in lists and layouts.

## Basic examples

### Basic Usage

Separate adjacent content sections.

Example source: src/divider/__demos__/basic.vue

```vue
<template>
  <div>
    <p>内容上方 / Before</p>
    <c-divider />
    <p>内容下方 / After</p>
  </div>
</template>
```

## Layout and arrangement

### Vertical Divider

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `orientation` | Horizontal/vertical orientation of the divider itself, default horizontal; does not control text alignment | Vertical Divider |
| `type` | Line style | Vertical Divider |
| `text-align` | Text position along the line; start/end follow logical direction | Vertical Divider |
| `description` | Description text; the default slot takes priority | Vertical Divider |
<!-- demo-config-notes:end -->


Set `orientation="vertical"` in a flex container with available height. Text follows the vertical direction.

Example source: src/divider/__demos__/vertical.vue

```vue
<template>
  <div>
    <div class="vertical-row">
      <span>Before</span>
      <c-divider orientation="vertical" />
      <span>Middle</span>
      <c-divider orientation="vertical" type="dashed" />
      <span>After</span>
    </div>
    <div class="vertical-labels">
      <c-divider orientation="vertical" text-align="start" description="Start" />
      <c-divider orientation="vertical" description="Center" />
      <c-divider orientation="vertical" text-align="end" description="End" />
    </div>
  </div>
</template>

<style scoped>
.vertical-row {
  display: flex;
  align-items: center;
  min-height: 40px;
}
.vertical-labels {
  display: flex;
  height: 160px;
}
</style>
```

## Content and presentation

### Line size, style and color

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `inset` | Inset along the line: left/right horizontally, top/bottom vertically | Line size, style and color |
| `spacing` | Outer spacing across the line: top/bottom horizontally, left/right vertically | Line size, style and color |
| `orientation` | Horizontal/vertical orientation of the divider itself, default horizontal; does not control text alignment | Line size, style and color |
| `type` | Line style | Line size, style and color |
| `thickness` | Line width in px; theme defaults to 1px; hairline takes priority | Line size, style and color |
| `color` | Line color; defaults to the theme border color | Line size, style and color |
<!-- demo-config-notes:end -->


Compare thickness or insets, line style and color. Text and custom content remain separate.

<details>
<summary>Configuration details and limits</summary>

#### Spacing & Inset

Compare five presets, numbers, CSS lengths and asymmetric pairs. The vertical example shows how spacing follows orientation.

#### Line Style

Compare solid, dashed, dotted and double lines using `type`. Use a `thickness` of at least 3px for a visible double line.

#### Color, Thickness & Opacity

Customize the line using `color`, `thickness` and `opacity`. Zero opacity preserves layout; `hairline` takes priority over `thickness`.

</details>

Example source: src/divider/__demos__/line-appearance-comparison.vue

```vue
<script setup lang="ts">
import { proxyRefs as demoProxyRefs } from 'vue'

const scene1 = demoProxyRefs((() => {

const presets = ['xs', 'sm', 'md', 'lg', 'xl']
return { presets }
})())
</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="size-inset">
    <h4><span lang="zh-CN">间距与缩进</span><span lang="en-US">Spacing &amp; Inset</span></h4>
    <div>
        <div v-for="size in scene1.presets" :key="size">
          <code>inset="{{ size }}" spacing="{{ size }}"</code>
          <c-divider :inset="size" :spacing="size" />
        </div>
        <p>数值 / Number · inset=24, spacing=16</p>
        <c-divider :inset="24" :spacing="16" />
        <p>CSS 长度 / CSS length · inset=2rem</p>
        <c-divider inset="2rem" />
        <p>非对称 / Asymmetric · inset=[8, 32], spacing=[12, 24]</p>
        <c-divider :inset="[8, 32]" :spacing="[12, 24]" />
        <p>竖直 / Vertical · inset=[8, 24], spacing=[12, 20]</p>
        <div class="vertical-preview">
          <span>Before</span>
          <c-divider orientation="vertical" :inset="[8, 24]" :spacing="[12, 20]" />
          <span>After</span>
        </div>
      </div>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="line-type">
    <h4><span lang="zh-CN">线型</span><span lang="en-US">Line Style</span></h4>
    <div>
        <p>实线 / solid</p>
        <c-divider />
        <p>虚线 / dashed</p>
        <c-divider type="dashed" />
        <p>点线 / dotted</p>
        <c-divider type="dotted" />
        <p>双线 / double · 3px</p>
        <c-divider type="double" :thickness="3" />
      </div>
  </section>

  <section class="demo-comparison-case demo-comparison-case--3" data-comparison-scene="opacity-color">
    <h4><span lang="zh-CN">颜色、线宽与透明度</span><span lang="en-US">Color, Thickness &amp; Opacity</span></h4>
    <div>
        <p>主题色 / Theme color</p>
        <c-divider color="var(--c-sys-color-action-primary)" />
        <p>线宽 / Thickness · 3px</p>
        <c-divider :thickness="3" />
        <p>半透明 / Half opacity · 0.5</p>
        <c-divider :thickness="3" :opacity="0.5" />
        <p>隐藏线条，保留间距 / Zero opacity preserves spacing</p>
        <c-divider :opacity="0" />
        <p>细线优先 / Hairline overrides thickness</p>
        <c-divider hairline :thickness="4" />
      </div>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }
.demo-comparison-case--1 {

.vertical-preview {
  display: flex;
  align-items: center;
  height: 96px;
}

}
</style>
```

### With Text

Use `description` and `text-align` to position text at the start, center or end. Toggle RTL to inspect logical start/end alignment.

Example source: src/divider/__demos__/with-text.vue

```vue
<script setup>
import { ref } from 'vue'

const rtl = ref(false)
</script>

<template>
  <div>
    <c-checkbox v-model="rtl">RTL</c-checkbox>
    <div :dir="rtl ? 'rtl' : 'ltr'">
      <c-divider text-align="start" description="起点 / Start" />
      <c-divider description="居中 / Center" />
      <c-divider text-align="end" description="终点 / End" />
    </div>
  </div>
</template>
```

## Customization and slots

### Custom Content

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `type` | Line style | Custom Content |
| `description` | Description text; the default slot takes priority | Custom Content |
<!-- demo-config-notes:end -->


The default slot takes priority over `description`. Provide padding for custom content in the caller.

Example source: src/divider/__demos__/custom.vue

```vue
<template>
  <c-divider type="dashed" description="默认插槽优先 / Slot takes priority">
    <span class="divider-label">★ 自定义内容 / Custom content</span>
  </c-divider>
</template>

<style scoped>
.divider-label {
  padding-inline: 8px;
}
</style>
```

## Interaction and control

### Live Properties

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `orientation` | Horizontal/vertical orientation of the divider itself, default horizontal; does not control text alignment | Live Properties |
| `opacity` | Opacity of the entire divider, including text, from 0 to 1; zero preserves layout | Live Properties |
| `hairline` | Scale the theme line width by half; 0.5px with the default theme | Live Properties |
| `thickness` | Line width in px; theme defaults to 1px; hairline takes priority | Live Properties |
| `inset` | Inset along the line: left/right horizontally, top/bottom vertically | Live Properties |
| `spacing` | Outer spacing across the line: top/bottom horizontally, left/right vertically | Live Properties |
<!-- demo-config-notes:end -->


Toggle orientation, default slot text, opacity and hairline to inspect updates and restoration.

Example source: src/divider/__demos__/live-properties.vue

```vue
<script setup>
import { ref } from 'vue'

const vertical = ref(false)
const text = ref(false)
const invisible = ref(false)
const hairline = ref(false)
</script>

<template>
  <section class="divider-live-demo">
    <div class="controls">
      <c-checkbox v-model="vertical">Vertical divider</c-checkbox>
      <c-checkbox v-model="text">Divider text</c-checkbox>
      <c-checkbox v-model="invisible">Zero opacity</c-checkbox>
      <c-checkbox v-model="hairline">Hairline divider</c-checkbox>
    </div>
    <p role="status">Orientation: {{ vertical ? 'vertical' : 'horizontal' }}; opacity: {{ invisible ? 0 : 1 }}</p>
    <div class="preview" :class="{ vertical }">
      <span>Before</span>
      <c-divider
        data-testid="live-divider"
        :orientation="vertical ? 'vertical' : 'horizontal'"
        :opacity="invisible ? 0 : 1"
        :hairline="hairline"
        :thickness="4"
        :inset="[8, 16]"
        :spacing="[12, 20]"
        ><template v-if="text" #default>Section</template></c-divider
      >
      <span>After</span>
    </div>
  </section>
</template>

<style scoped>
.controls {
  display: flex;
  flex-wrap: wrap;
  gap: 12px;
}
.controls label {
  display: inline-flex;
  align-items: center;
  gap: 4px;
}
.preview {
  display: flex;
  flex-direction: column;
  min-height: 160px;
}
.preview.vertical {
  flex-direction: row;
  align-items: center;
}
</style>
```

## Reading direction

Inherits the nearest `dir="ltr|rtl"`. Horizontal text start/end follows reading order; vertical start/end remains top/bottom. Inset controls along-line indentation and spacing controls perpendicular margins. Paired horizontal inset and vertical spacing uses logical start/end. Vertical borders use inline start; hairline, border type and aria-orientation retain their meaning. Direction changes preserve content nodes.

### Content height and minimum thickness

Explicit thickness accepts finite numbers greater than or equal to 1. hairline still takes priority, using half the theme width. Values below 1 (including zero and negative values), and non-finite values, are ignored and use the theme width; development builds warn.

Multiline descriptions and custom content occupy their full height, including spacing=0. Subsequent content stays below the divider.

Example source: src/divider/__demos__/content-flow.vue

```vue
<template>
  <section class="divider-flow-demo">
    <h4>1px：最小显式线宽 / Minimum explicit width</h4>
    <div class="flow-sample">
      <c-divider
        data-min-line
        :thickness="1"
        :spacing="0"
        description="内容仍正常占位 / Content stays in normal flow"
      />
      <p>后续正文 / Following content</p>
    </div>
    <h4>4px：多行文字 / Multiline content</h4>
    <div class="flow-sample">
      <c-divider
        data-multiline
        :thickness="4"
        :spacing="0"
        description="分区标题支持换行，并为后续内容保留完整空间 / A wrapping section title reserves its full height"
      />
      <p>后续正文 / Following content</p>
    </div>
    <h4>默认插槽 / Custom content</h4>
    <div class="flow-sample">
      <c-divider data-custom-content :spacing="0"
        ><span class="flow-content"
          >第一行 / First line<br />第二行 / Second line</span
        ></c-divider
      >
      <p>后续正文 / Following content</p>
    </div>
    <p>
      thickness ≥ 1；hairline 优先，使用主题线宽的一半。hairline takes priority
      and halves the theme width.
    </p>
  </section>
</template>
<style scoped>
.flow-sample {
  max-width: 280px;
}
.flow-sample p {
  margin: 0;
}
.flow-content {
  padding: 12px 0;
}
</style>
```

## API

### Props

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| `orientation` | Horizontal/vertical orientation of the divider itself, default horizontal; does not control text alignment | `horizontal` \| `vertical` | `horizontal` |
| `type` | Line style | `solid` \| `dashed` \| `dotted` \| `double` | `solid` |
| `text-align` | Text position along the line; start/end follow logical direction | `start` \| `center` \| `end` | `center` |
| `description` | Description text; the default slot takes priority | `string` | — |
| `inset` | Inset along the line: left/right horizontally, top/bottom vertically | `DividerSize` | — |
| `spacing` | Outer spacing across the line: top/bottom horizontally, left/right vertically | `DividerSize` | `md` |
| `thickness` | Line width in px; theme defaults to 1px; hairline takes priority | `number` | — |
| `hairline` | Scale the theme line width by half; 0.5px with the default theme | `boolean` | `false` |
| `color` | Line color; defaults to the theme border color | `string` | — |
| `opacity` | Opacity of the entire divider, including text, from 0 to 1; zero preserves layout | `number` | — |

### Spacing values

`DividerSize = number | string | [number | string] | [number | string, number | string]`

`inset` controls the ends of the line; `spacing` controls the outer gap between the line and adjacent content. Both accept presets `xs`, `sm`, `md`, `lg`, `xl`, a number in px, a CSS length, or an array. A scalar or single-item array applies to both ends; `[start, end]` sets each end separately. Array entries are lengths, not preset names.

| Direction | inset array order | spacing array order |
| --- | --- | --- |
| horizontal | Inline start/end inset; right/left in RTL | Top/bottom margin |
| vertical | Top/bottom inset | Inline start/end margin; right/left in RTL |

`inset` has no `inset` by default; `spacing` defaults to the platform’s `md` `spacing`. Presets use platform theme tokens, so pixel values may differ.


Development builds diagnose invalid orientation, text-align, type, size structure, thickness and opacity. Invalid enums use their defaults; invalid inset is omitted, invalid spacing uses md, and invalid opacity is omitted. Opacity must be finite and within [0,1]. Size arrays contain one or two lengths, without preset names inside arrays. Finite negative margins and CSS var/calc expressions remain supported; the browser parses CSS expressions.

### Slots

| Slot | Description |
| --- | --- |
| `default` | Custom divider content; overrides description |

## Type definitions

```ts
import type { DividerProps, DividerInstance, DividerSize, DividerSizePreset, DividerOrientation, DividerTextAlign, DividerType } from '@cedar-design/ui'
```

### Style variables

| Variable | Default |
| --- | --- |
| `--c-divider-color` | `var(--c-sys-color-border-default)` |
| `--c-divider-text-color` | `var(--c-sys-color-content-secondary)` |
| `--c-divider-border-width` | `1px` |
| `--c-divider-text-padding` | `16px` |
| `--c-divider-text-align-inset` | `24px` |
| `--c-divider-orientation-vertical-inset-xs` | `2px` |
| `--c-divider-orientation-horizontal-inset-xs` | `12px` |
| `--c-divider-orientation-vertical-spacing-xs` | `4px` |
| `--c-divider-orientation-horizontal-spacing-xs` | `8px` |
| `--c-divider-orientation-vertical-inset-sm` | `4px` |
| `--c-divider-orientation-horizontal-inset-sm` | `16px` |
| `--c-divider-orientation-vertical-spacing-sm` | `8px` |
| `--c-divider-orientation-horizontal-spacing-sm` | `12px` |
| `--c-divider-orientation-vertical-inset-md` | `6px` |
| `--c-divider-orientation-horizontal-inset-md` | `24px` |
| `--c-divider-orientation-vertical-spacing-md` | `12px` |
| `--c-divider-orientation-horizontal-spacing-md` | `16px` |
| `--c-divider-orientation-vertical-inset-lg` | `8px` |
| `--c-divider-orientation-horizontal-inset-lg` | `32px` |
| `--c-divider-orientation-vertical-spacing-lg` | `16px` |
| `--c-divider-orientation-horizontal-spacing-lg` | `24px` |
| `--c-divider-orientation-vertical-inset-xl` | `12px` |
| `--c-divider-orientation-horizontal-inset-xl` | `40px` |
| `--c-divider-orientation-vertical-spacing-xl` | `24px` |
| `--c-divider-orientation-horizontal-spacing-xl` | `32px` |

Presets read the active platform theme. Text spacing is 16px on desktop and 8px on mobile.

---

Document: llms/en-US/components/drawer.md

<!-- Source: src/drawer/README.en-US.md; locale: en-US; page: /en/components/drawer/ -->

# Drawer

A side panel with declarative and programmatic APIs and cancellable before-close operations.

## Basic examples

### Basic

Example source: src/drawer/__demos__/basic.vue

```vue
<template>
  <c-button status="primary" @click="handleClick">Open Drawer</c-button>
  <c-drawer v-model:open="visible" :width="340" @confirm="handleConfirm" @cancel="handleCancel" unmount-on-close>
    <template #title>Title</template>
    <div>
      You can customize modal body text by the current situation. This modal will be closed immediately once you press
      the OK button.
    </div>
  </c-drawer>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
const visible = ref(false)

const handleClick = () => {
  visible.value = true
}
const handleConfirm = () => {
  visible.value = false
}
const handleCancel = () => {
  visible.value = false
}
</script>
```

## Sizing and positioning

### Drawer size and placement

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `unmount-on-close` | Unmount content after the closing transition | Drawer size and placement |
| `placement` | Side of the containing area where the drawer appears, default right. It is not anchored to a button and does not perform popup collision flipping | Drawer size and placement |
| `popup-container` | Portal container | Popup Container |
<!-- demo-config-notes:end -->


Open each drawer separately to compare placement and occupied space. Nesting, containers and guards remain separate.

Example source: src/drawer/__demos__/position-size-comparison.vue

```vue
<script setup lang="ts">
import { ref } from "vue"
import { proxyRefs as demoProxyRefs } from 'vue'

const scene1 = demoProxyRefs((() => {

const visibleSmall = ref(false)

const visibleMedium = ref(false)

const visibleLarge = ref(false)


const handleClickSmall = () => {
  visibleSmall.value = true
}

const handleClickMedium = () => {
  visibleMedium.value = true
}

const handleClickLarge = () => {
  visibleLarge.value = true
}

const handleConfirm = () => {
  visibleSmall.value = false
  visibleMedium.value = false
  visibleLarge.value = false
}

const handleCancel = () => {
  visibleSmall.value = false
  visibleMedium.value = false
  visibleLarge.value = false
}
return { visibleSmall, visibleMedium, visibleLarge, handleClickSmall, handleClickMedium, handleClickLarge, handleConfirm, handleCancel }
})())

const scene2 = demoProxyRefs((() => {

const visible = ref(false)

const position = ref('right')


const handleClick = () => {
  visible.value = true
}

const handleConfirm = () => {
  visible.value = false
}

const handleCancel = () => {
  visible.value = false
}
return { visible, position, handleClick, handleConfirm, handleCancel }
})())
</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="size">
    <h4><span lang="zh-CN">自定义宽度</span><span lang="en-US">Size</span></h4>
    <c-space>
        <c-button status="primary" @click="scene1.handleClickSmall">sm Drawer</c-button>
        <c-button status="primary" @click="scene1.handleClickMedium">md Drawer</c-button>
        <c-button status="primary" @click="scene1.handleClickLarge">lg Drawer</c-button>
      </c-space>
      <c-drawer v-model:open="scene1.visibleSmall" :width="280" @confirm="scene1.handleConfirm" @cancel="scene1.handleCancel" unmount-on-close>
        <template #title>Title</template>
        <div>
          You can customize modal body text by the current situation. This modal will be closed immediately once you press
          the OK button.
        </div>
      </c-drawer>
      <c-drawer v-model:open="scene1.visibleMedium" :width="420" @confirm="scene1.handleConfirm" @cancel="scene1.handleCancel" unmount-on-close>
        <template #title>Title</template>
        <div>
          You can customize modal body text by the current situation. This modal will be closed immediately once you press
          the OK button.
        </div>
      </c-drawer>
      <c-drawer v-model:open="scene1.visibleLarge" :width="640" @confirm="scene1.handleConfirm" @cancel="scene1.handleCancel" unmount-on-close>
        <template #title>Title</template>
        <div>
          You can customize modal body text by the current situation. This modal will be closed immediately once you press
          the OK button.
        </div>
      </c-drawer>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="location">
    <h4><span lang="zh-CN">抽屉位置</span><span lang="en-US">Location</span></h4>
    <c-radio-group v-model="scene2.position">
        <c-radio value="top">Top</c-radio>
        <c-radio value="right">Right</c-radio>
        <c-radio value="bottom">Bottom</c-radio>
        <c-radio value="left">Left</c-radio>
      </c-radio-group>
      <div :style="{
      marginTop: '20px'
    }">
        <c-button status="primary" @click="scene2.handleClick">Open Drawer</c-button>
      </div>
      <c-drawer
        :width="340"
        :height="340"
        v-model:open="scene2.visible"
        :placement="scene2.position"
        @confirm="scene2.handleConfirm"
        @cancel="scene2.handleCancel"
        unmountOnClose
      >
        <template #title> Title </template>
        <div>
          You can customize modal body text by the current situation. This modal will be closed immediately once you press
          the OK button.
        </div>
      </c-drawer>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

### Popup Container

Example source: src/drawer/__demos__/popup-container.vue

```vue
<template>
  <div>
    <div
      id="parentNode"
      style="
        width: 100%;
        height: 300px;
        background-color: var(--c-color-bg-white);
        position: relative;
        overflow: hidden;
        line-height: 300px;
        text-align: center;
      "
    >
      <c-button status="primary" @click="handleClick">Open Drawer</c-button>
    </div>
  </div>
  <c-drawer v-model:open="visible" popup-container="#parentNode" @confirm="handleConfirm" @cancel="handleCancel">
    <template #title>Title</template>
    <div>
      You can customize modal body text by the current situation. This modal will be closed immediately once you press
      the OK button.
    </div>
  </c-drawer>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
const visible = ref(false)

const handleClick = () => {
  visible.value = true
}
const handleConfirm = () => {
  visible.value = false
}
const handleCancel = () => {
  visible.value = false
}
</script>
```

## Content and nesting

### Nest Drawer

Example source: src/drawer/__demos__/nest-drawer.vue

```vue
<template>
  <c-button status="primary" @click="handleClick">Open Drawer</c-button>
  <c-drawer v-model:open="visible" :width="500" @confirm="handleConfirm" @cancel="handleCancel" unmount-on-close>
    <template #title>Title</template>
    <div :style="{ marginBottom: '20px' }">
      You can customize modal body text by the current situation. This modal will be closed immediately once you press
      the OK button.
    </div>
    <c-button status="primary" @click="handleNestedClick">Open Nested Drawer</c-button>
  </c-drawer>
  <c-drawer v-model:open="nestedVisible" @confirm="handleNestedConfirm" @cancel="handleNestedCancel" unmount-on-close>
    <template #title>Title</template>
    <div>
      You can customize modal body text by the current situation. This modal will be closed immediately once you press
      the OK button.
    </div>
  </c-drawer>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
const visible = ref(false)
const nestedVisible = ref(false)

const handleClick = () => {
  visible.value = true
}
const handleConfirm = () => {
  visible.value = false
}
const handleCancel = () => {
  visible.value = false
}
const handleNestedClick = () => {
  nestedVisible.value = true
}
const handleNestedConfirm = () => {
  nestedVisible.value = false
}
const handleNestedCancel = () => {
  nestedVisible.value = false
}
</script>
```

### Custom Node

Example source: src/drawer/__demos__/custom-node.vue

```vue
<template>
  <c-checkbox-group v-model="custom" :options="['hide header', 'hide footer', 'hide cancel']" />
  <div :style="{ marginTop: '20px' }">
    <c-button status="primary" @click="handleClick">Open Drawer</c-button>
  </div>
  <c-drawer
    :width="340"
    :header="!custom.includes('hide header')"
    :footer="!custom.includes('hide footer')"
    :cancel-button="!custom.includes('hide cancel')"
    v-model:open="visible"
    @confirm="handleConfirm"
    @cancel="handleCancel"
    unmountOnClose
  >
    <template #header>
      <span>Header and title</span>
    </template>
    <div>
      You can customize modal body text by the current situation. This modal will be closed immediately once you press
      the OK button.
    </div>
  </c-drawer>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
const visible = ref(false)
const custom = ref([])

const handleClick = () => {
  visible.value = true
}
const handleConfirm = () => {
  visible.value = false
}
const handleCancel = () => {
  visible.value = false
}
</script>
```

### Function Call

Example source: src/drawer/__demos__/function-call.vue

```vue
<template>
  <c-button status="primary" @click="handleClick">Open Drawer</c-button>
</template>

<script lang="ts" setup>
import { Drawer } from '@cedar-design/ui'

const handleClick = () => {
  Drawer.open({
    title: 'Info Title',
    content: 'This is an info message',
    width: 340,
  })
}
</script>
```

### Api Review

## Closing and async control

### Guard Protocol

Example source: src/drawer/__demos__/en-US/guard-protocol.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import type { DrawerBeforeClose } from "@cedar-design/ui";
const open = ref(false);
const mode = ref("promise");
const allowed = ref(true);
const status = ref("");
const check: DrawerBeforeClose = (payload, done, { signal }) => {
  status.value = `Waiting: ${payload.action}`;
  if (mode.value === "done") {
    setTimeout(() => {
      status.value = allowed.value ? "Allowed" : "Rejected";
      done(!signal.aborted && allowed.value);
    }, 500);
    return;
  }
  return new Promise<boolean>((resolve) =>
    setTimeout(() => {
      status.value = allowed.value ? "Allowed" : "Rejected";
      resolve(!signal.aborted && allowed.value);
    }, 500),
  );
};
</script>
<template>
  <c-space direction="column" align="stretch">
    <c-form-item layout="vertical" label="Allow closing"><c-switch v-model="allowed" aria-label="Allow closing" /></c-form-item>
    <c-form-item layout="vertical" size="sm" label="mode">
      <c-radio-group
        aria-label="mode"
        v-model="mode"
        :options="[
          { value: 'promise', label: 'Promise' },
          { value: 'done', label: 'done callback' },
        ]"
        variant="button"
        size="sm"
      />
    </c-form-item>
    <c-button @click="open = true">Open</c-button>
    <c-drawer
      v-model:open="open"
      :before-close="check"
      @guard-error="status = 'Error'"
    >
      <p>The guard waits briefly before closing. Turn off the switch to reject once, then enable it here and retry.</p>
      <c-form-item layout="vertical" label="Allow closing"><c-switch v-model="allowed" aria-label="Allow closing inside drawer" /></c-form-item>
      <c-button @click="allowed = true; open = false">Allow and close</c-button>
      <p role="status">{{ status }}</p>
    </c-drawer>
    <p role="status">{{ status }}</p>
  </c-space>
</template>
```

### Props

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| dir | Reading direction; inherits the source scope when omitted. Physical left/right placements keep their meaning. | `ReadingDirection` (`ltr` / `rtl`) | — |
| open **(v-model)** | Controlled visibility | `boolean` | - |
| default-open | Initial uncontrolled visibility | `boolean` | `false` |
| placement | Side of the containing area where the drawer appears, default right. It is not anchored to a button and does not perform popup collision flipping | `'top' \| 'right' \| 'bottom' \| 'left'` | `'right'` |
| title | Title | `string` | - |
| overlay | Show the overlay | `boolean` | `true` |
| overlay-class / overlay-style | Overlay class and style | `string / CSSProperties` | - |
| overlay-closable | Request closure on overlay click | `boolean` | `true` |
| closable | Show the close button | `boolean` | `true` |
| confirm-button-text / cancel-button-text | Action button text | `string` | - |
| confirm-button-loading / cancel-button-loading | Action button loading state | `boolean` | `false` |
| confirm-button-disabled / cancel-button-disabled | Action button disabled state | `boolean` | `false` |
| confirm-button-props / cancel-button-props | Action button props | `ButtonProps` | - |
| unmount-on-close | Unmount content after the closing transition | `boolean` | `false` |
| width / height | Width for left/right placement; height for top/bottom placement | `number \| string` | `250` |
| popup-container | Portal container | `string \| HTMLElement \| false` | `'body'` |
| drawer-class / drawer-style | Panel class and style | `string \| any[] / CSSProperties` | - |
| body-class / body-style | Body class and style | `string \| any[] / StyleValue` | - |
| `before-close` | Return a boolean/Promise or call done; the first completion wins | `DrawerBeforeClose` | — |
| esc-to-close | Request closure on Escape | `boolean` | `true` |
| lock-scroll | Lock scrolling on the host | `boolean` | `true` |
| close-on-route-change | Request closure on route changes | `boolean` | `false` |
| z-index | Custom z-index | `number` | Automatically allocated |
| header / footer / cancel-button | Show the corresponding region | `boolean` | `true` |

### Events

| Event | Description | Arguments |
| --- | --- | --- |
| update:open | Request a visibility update | `boolean` |
| confirm / cancel | Accepted confirm or cancel action | `Event` |
| open / close | Opening or closing begins | - |
| opened / closed | Opening or closing transition completes | - |
| click-overlay | Click the topmost overlay | `MouseEvent` |
| key-escape | Escape reaches the topmost drawer | `KeyboardEvent` |

### CSS

| Variable | Default |
| --- | --- |
| `--c-drawer-header-height` | `var(--c-size-12)` |
| `--c-drawer-footer-button-margin-left` | `var(--c-spacing-6)` |
| `--c-drawer-header-font-size` | `var(--c-font-size-title-1)` |
| `--c-drawer-padding-horizontal` | `var(--c-spacing-7)` |
| `--c-drawer-footer-padding-vertical` | `var(--c-spacing-7)` |
| `--c-drawer-content-padding-vertical` | `var(--c-spacing-6)` |
| `--c-drawer-header-font-weight` | `var(--c-font-weight-500)` |
| `--c-drawer-border-color` | `var(--c-sys-color-border-default)` |
| `--c-drawer-border-width` | `var(--c-border-width-1)` |
| `--c-drawer-header-text-color` | `var(--c-sys-color-content-primary)` |
| `--c-drawer-content-text-color` | `var(--c-sys-color-content-primary)` |
| `--c-drawer-bg` | `var(--c-sys-color-surface-raised)` |
| `--c-drawer-overlay-bg` | `var(--c-sys-color-scrim)` |
| `--c-drawer-line-height` | `var(--c-line-height)` |
| `--c-drawer-z-index` | `var(--c-z-index-drawer)` |
| `--c-drawer-close-icon-font-size` | `var(--c-size-3)` |
| `--c-drawer-close-btn-margin-left` | `var(--c-spacing-4)` |
| `--c-drawer-transition-duration` | `var(--c-transition-duration-3)` |
| `--c-drawer-transition-timing-function` | `var(--c-transition-timing-function-standard)` |


Promise and done share a single completion state: false/done(false) rejects; true/done() allows; a resolved Promise&lt;void&gt; allows. The first completion wins. Errors emit guard-error; cancellation/unmount invalidates late completion. Synchronous void retains the callback protocol and waits for done on these close/confirm guards.


Cancellable hooks use `(payload, done, context)`: closure payloads contain `{ action }`, change/commit payloads contain `{ value, previousValue }`, and Popup uses `{ reason }`. Context provides `signal` and an optional original `event`. Return a boolean/Promise, or call done()/done(false). Synchronous void waits for done; Promise&lt;void&gt; allows the operation. First completion wins. Pending state controls loading/disabled automatically. Cancellation invalidates stale results. Button refs are not exposed.

## Reading direction

Inherits the nearest `dir="ltr|rtl"` and supports runtime and nested overrides. Drawer placement=left/right remains physical, including entry and exit motion. Headings, content and footer actions inherit reading direction. Direction changes do not submit or clear content.

## API

### Props

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| dir | Reading direction; inherits the source scope when omitted. Physical left/right placements keep their meaning. | `ReadingDirection` (`ltr` / `rtl`) | — |
| open **(v-model)** | Controlled visibility | `boolean` | - |
| default-open | Initial uncontrolled visibility | `boolean` | `false` |
| placement | Side of the containing area where the drawer appears, default right. It is not anchored to a button and does not perform popup collision flipping | `'top' \| 'right' \| 'bottom' \| 'left'` | `'right'` |
| title | Title | `string` | - |
| overlay | Show the overlay | `boolean` | `true` |
| overlay-class / overlay-style | Overlay class and style | `string / CSSProperties` | - |
| overlay-closable | Request closure on overlay click | `boolean` | `true` |
| closable | Show the close button | `boolean` | `true` |
| confirm-button-text / cancel-button-text | Action button text | `string` | - |
| confirm-button-loading / cancel-button-loading | Action button loading state | `boolean` | `false` |
| confirm-button-disabled / cancel-button-disabled | Action button disabled state | `boolean` | `false` |
| confirm-button-props / cancel-button-props | Action button props | `ButtonProps` | - |
| unmount-on-close | Unmount content after the closing transition | `boolean` | `false` |
| width / height | Width for left/right placement; height for top/bottom placement | `number \| string` | `250` |
| popup-container | Portal container | `string \| HTMLElement \| false` | `'body'` |
| drawer-class / drawer-style | Panel class and style | `string \| any[] / CSSProperties` | - |
| body-class / body-style | Body class and style | `string \| any[] / StyleValue` | - |
| `before-close` | Return a boolean/Promise or call done; the first completion wins | `DrawerBeforeClose` | — |
| esc-to-close | Request closure on Escape | `boolean` | `true` |
| lock-scroll | Lock scrolling on the host | `boolean` | `true` |
| close-on-route-change | Request closure on route changes | `boolean` | `false` |
| z-index | Custom z-index | `number` | Automatically distributed |
| header / footer / cancel-button | Show the corresponding region | `boolean` | `true` |


### Events

| Event | Description | Arguments |
| --- | --- | --- |
| update:open | Request a visibility update | `boolean` |
| confirm / cancel | Accepted confirm or cancel action | `Event` |
| open / close | Opening or closing begins | - |
| opened / closed | Opening or closing transition completes | - |
| click-overlay | Click the topmost overlay | `MouseEvent` |
| key-escape | Escape reaches the topmost drawer | `KeyboardEvent` |

### Slots

`default`, `header`, `title`, `footer`. The `footer` slot receives `confirm`, `cancel` and `close` methods.

### Imperative calls

`Drawer.open(config)` uses camelCase options such as `cancelButtonText`, `beforeClose` and `closeOnRouteChange`. Notifications use `onConfirm`, `onCancel`, `onOpen`, `onOpened`, `onClose`, `onClosed`, `onClickOverlay` and `onKeyEscape`.

```ts
import type { DrawerAction, DrawerConfig, DrawerProps } from '@cedar-design/ui'
```

## CSS variables and color semantics

Built-in fade and four-direction slide disable transitions and initial displacement under prefers-reduced-motion: reduce. Component styles handle this without global fallbacks. Default durations remain unchanged; business-defined animations require separate handling. Compiled-CSS checks do not substitute for testing live OS preference changes.

Panel bg uses surface-raised; overlay-bg uses sys-color-scrim; header-text-color/content-text-color use content-primary, with the close button inheriting header-text-color; border-color uses border-default. Drawer keeps its existing geometry, motion and stacking defaults. Drawer is a Cedar component; Maple does not define empty same-name variables.

overlay-style sets instance scrim variables; drawer-style sets panel variables. These sibling nodes do not inherit variables from one another. Set global system theme variables on a real common ancestor. Explicit background props take precedence over variable consumption. The unused close-icon-right variable is removed; title layout and close-btn-margin-left position the close button, without an ineffective compatibility alias.

| Variable | Default |
| --- | --- |
| `--c-drawer-header-height` | `var(--c-size-12)` |
| `--c-drawer-footer-button-margin-left` | `var(--c-spacing-6)` |
| `--c-drawer-header-font-size` | `var(--c-font-size-title-1)` |
| `--c-drawer-padding-horizontal` | `var(--c-spacing-7)` |
| `--c-drawer-footer-padding-vertical` | `var(--c-spacing-7)` |
| `--c-drawer-content-padding-vertical` | `var(--c-spacing-6)` |
| `--c-drawer-header-font-weight` | `var(--c-font-weight-500)` |
| `--c-drawer-border-color` | `var(--c-sys-color-border-default)` |
| `--c-drawer-border-width` | `var(--c-border-width-1)` |
| `--c-drawer-header-text-color` | `var(--c-sys-color-content-primary)` |
| `--c-drawer-content-text-color` | `var(--c-sys-color-content-primary)` |
| `--c-drawer-bg` | `var(--c-sys-color-surface-raised)` |
| `--c-drawer-overlay-bg` | `var(--c-sys-color-scrim)` |
| `--c-drawer-line-height` | `var(--c-line-height)` |
| `--c-drawer-z-index` | `var(--c-z-index-drawer)` |
| `--c-drawer-close-icon-font-size` | `var(--c-size-3)` |
| `--c-drawer-close-btn-margin-left` | `var(--c-spacing-4)` |
| `--c-drawer-transition-duration` | `var(--c-transition-duration-3)` |
| `--c-drawer-transition-timing-function` | `var(--c-transition-timing-function-standard)` |

### Before-hook waiting feedback

Before-hook waits show visible feedback and aria-busy. Rejected or failed operations recover; duplicate submissions do not start another copy. Notification event Promises never drive loading.

---

Document: llms/en-US/components/ellipsis.md

<!-- Source: src/ellipsis/README.en-US.md; locale: en-US; page: /en/components/ellipsis/ -->

# Ellipsis

Single-line or multi-line truncation with optional expansion and Tooltip.

## Basic examples

### Single line

Example source: src/ellipsis/__demos__/basic.vue

```vue
<template>
  <div class="ellipsis-demo">
    <c-ellipsis
      style="width: 240px; max-width: 100%"
    >
      这是一段较长的说明文字，用于展示有限宽度内的省略效果。点击或使用键盘可以展开查看完整内容，再次操作可以收起。容器宽度改变时，文本会根据新的空间重新排版。
    </c-ellipsis>
  </div>
</template>

<style scoped>
.ellipsis-demo { display: flex; flex-direction: column; align-items: flex-start; gap: 12px; }
.ellipsis-demo p { margin: 0; }
</style>
```

## Content and presentation

### Multiple lines

Example source: src/ellipsis/__demos__/multiline.vue

```vue
<template>
  <div class="ellipsis-demo">
    <c-ellipsis
      style="width: 240px; max-width: 100%"
      :line-clamp="2"
    >
      这是一段较长的说明文字，用于展示有限宽度内的省略效果。点击或使用键盘可以展开查看完整内容，再次操作可以收起。容器宽度改变时，文本会根据新的空间重新排版。
    </c-ellipsis>
  </div>
</template>

<style scoped>
.ellipsis-demo { display: flex; flex-direction: column; align-items: flex-start; gap: 12px; }
.ellipsis-demo p { margin: 0; }
</style>
```

## Customization and slots

### Custom tooltip

Example source: src/ellipsis/__demos__/custom-tooltip.vue

```vue
<template>
  <div class="ellipsis-demo">
    <c-ellipsis
      style="width: 240px; max-width: 100%"
      :tooltip="{ status: 'primary', trigger: ['hover', 'focus', 'click'], content: '独立的提示内容，不会重复拼接正文' }"
    >
      这是一段较长的说明文字，用于展示有限宽度内的省略效果。点击或使用键盘可以展开查看完整内容，再次操作可以收起。容器宽度改变时，文本会根据新的空间重新排版。
    </c-ellipsis>
  </div>
</template>

<style scoped>
.ellipsis-demo { display: flex; flex-direction: column; align-items: flex-start; gap: 12px; }
.ellipsis-demo p { margin: 0; }
</style>
```

## Interaction and control

### Interactive expansion

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `line-clamp` | Positive line count; omitted or invalid means single line | Interactive expansion, Controlled expansion |
| `expand-trigger` | Enable click / Enter / Space toggling | Interactive expansion, Controlled expansion |
| `tooltip` | Tooltip configuration; false disables it | Interactive expansion, Controlled expansion |
| `expand` | Controlled expansion | Controlled expansion |
<!-- demo-config-notes:end -->


Example source: src/ellipsis/__demos__/expand.vue

```vue
<template>
  <div class="ellipsis-demo">
    <c-ellipsis
      style="width: 240px; max-width: 100%"
      :line-clamp="2"
      expand-trigger="click"
      :tooltip="false"
    >
      这是一段较长的说明文字，用于展示有限宽度内的省略效果。点击或使用键盘可以展开查看完整内容，再次操作可以收起。容器宽度改变时，文本会根据新的空间重新排版。
    </c-ellipsis>
    <p>点击文本，或聚焦后按 Enter / Space 展开与收起。</p>
  </div>
</template>

<style scoped>
.ellipsis-demo { display: flex; flex-direction: column; align-items: flex-start; gap: 12px; }
.ellipsis-demo p { margin: 0; }
</style>
```

### Controlled expansion

Example source: src/ellipsis/__demos__/controlled.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const expanded = ref(false)
</script>

<template>
  <div class="ellipsis-demo">
    <c-button @click="expanded = !expanded">外部切换: {{ expanded }}</c-button>
    <c-ellipsis
      style="width: 240px; max-width: 100%"
      :line-clamp="2"
      expand-trigger="click"
      :tooltip="false"
      v-model:expand="expanded"
    >
      这是一段较长的说明文字，用于展示有限宽度内的省略效果。点击或使用键盘可以展开查看完整内容，再次操作可以收起。容器宽度改变时，文本会根据新的空间重新排版。
    </c-ellipsis>
  </div>
</template>

<style scoped>
.ellipsis-demo { display: flex; flex-direction: column; align-items: flex-start; gap: 12px; }
.ellipsis-demo p { margin: 0; }
</style>
```

## API

### Props

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| `expand` | Controlled expansion | `boolean` | `undefined` |
| `default-expand` | Initial uncontrolled expansion | `boolean` | `false` |
| `expand-trigger` | Enable click / Enter / Space toggling | `'click'` | `—` |
| `line-clamp` | Positive line count; omitted or invalid means single line | `number \| string` | `—` |
| `tooltip` | Tooltip configuration; false disables it | `boolean \| TooltipProps` | `true` |

Providing `expand` makes the component request updates from its parent rather than changing controlled state. When omitted, internal state is used, initialized once by `default-expand`. Tooltip follows its own width and trigger defaults; display does not depend on measured overflow. Touch callers can include `click` in `tooltip.trigger` explicitly. External class/style/width apply directly to the text node.

### Events and slots

- `update:expand(expand: boolean)`: the new state requested by user interaction; external updates do not emit it.
- `default`: body text.
- `tooltip-content`: tooltip content. Without it, tooltip.content takes precedence, then body text; content is not concatenated twice.
- Keyboard: expandable text supports Enter / Space; tooltip-enabled text is focusable with Tab. No public instance methods.

### Types

```ts
import type { EllipsisProps, EllipsisInstance, EllipsisExpandTrigger } from '@cedar-design/ui'
```

### Style variables

| Token | Default |
| --- | --- |
| `--c-ellipsis-focus-color` | `var(--c-sys-color-content-brand)` |
| `--c-ellipsis-focus-width` | `2px` |
| `--c-ellipsis-focus-offset` | `2px` |

---

Document: llms/en-US/components/empty.md

<!-- Source: src/empty/README.en-US.md; locale: en-US; page: /en/components/empty/ -->

# Empty

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

Preview configuration: `description="暂无数据"`.

Example source: src/empty/__demos__/basic.vue

```vue
<template>
  <c-empty description="暂无数据" />
</template>
```

## Appearance and states

### Size

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `image-size` | Image/icon size | Size |
| `description` | Description; falls back to i18n | Size |
<!-- demo-config-notes:end -->


Preview configuration: `:image-size="size"`, `:description="image-size: ${size}"`.

Example source: src/empty/__demos__/size.vue

```vue
<template>
  <c-space direction="column">
    <c-empty v-for="size in sizes" :key="size" :image-size="size" :description="`image-size: ${size}`" />
  </c-space>
</template>

<script lang="ts">
import { defineComponent } from 'vue'

export default defineComponent({
  setup() {
    const sizes = ['xs', 'sm', 'md', 'lg', 'xl']
    return { sizes }
  },
})
</script>
```

## Content and presentation

### Empty-state image and actions

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `description` | Description; falls back to i18n | Empty-state image and actions, Show |
| `image-url` | Custom image URL | Empty-state image and actions |
| `alt` | Image alternative text | Empty-state image and actions |
| `show-icon` | Whether to show the icon | Show |
| `show-description` | Whether to show the description | Show |
<!-- demo-config-notes:end -->


Compare custom artwork and extra actions to distinguish content replacement from supplemental controls.

Example source: src/empty/__demos__/content-comparison.vue

```vue
<script setup lang="ts">
import { ref } from "vue"
import { proxyRefs as demoProxyRefs } from 'vue'

const scene1 = demoProxyRefs((() => {

const attempts = ref(0)
return { attempts }
})())
</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="extra">
    <h4><span lang="zh-CN">操作按钮</span><span lang="en-US">extra</span></h4>
    <c-empty :description="scene1.attempts ? 'No data. Local refresh completed.' : 'No data, please reload'">
        <template #extra>
          <c-button status="primary" @click="scene1.attempts++">Reload</c-button>
          <p aria-live="polite">Local refresh attempts: {{ scene1.attempts }}</p>
        </template>
      </c-empty>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="user-define">
    <h4><span lang="zh-CN">自定义图片和文案</span><span lang="en-US">user define</span></h4>
    <c-space direction="column">
        <c-empty>
          <template #image>
            <c-icon-exclamation-circle-fill />
          </template>
          No data, please reload!!
        </c-empty>
        <c-empty image-url="/cat.jpg" alt="空状态图片" description="自定义图片和文案" />
      </c-space>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

### Show

Preview configuration: `data-demo-empty`, `description="Dynamic empty state"`, `:show-icon="showIcon"`, `:show-description="showDescription"`.

Example source: src/empty/__demos__/show.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const showIcon = ref(true)
const showDescription = ref(true)
</script>

<template>
  <c-space direction="column" :size="16">
    <c-space wrap>
      <c-button @click="showIcon = !showIcon">Toggle icon</c-button>
      <c-button @click="showDescription = !showDescription">Toggle description</c-button>
    </c-space>
    <c-empty data-demo-empty description="Dynamic empty state" :show-icon="showIcon" :show-description="showDescription" />
  </c-space>
</template>
```

## API

### `<Empty>` Props

| Prop | Description | Type | Default |
| ------------------ | ---------------------------- | -------------------------------------------------------- | ------- |
| description | Description; falls back to i18n | `string` | - |
| image-url | Custom image URL | `string` | - |
| alt | Image alternative text | `string` | `''` |
| image-size | Image/icon size | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| number \| string` | `'md'` |
| show-icon | Whether to show the icon | `boolean` | `true` |
| show-description | Whether to show the description | `boolean` | `true` |

### `<Empty>` Events

| Event | Description | Arguments |
| ------ | -------- | --------------------- |
| click | Click callback | `(ev: MouseEvent)` |

### `<Empty>` Slots

| Slot | Description | Arguments |
| ------- | --------- | ---- |
| image | Image/icon | - |
| default | Description content | - |
| extra | Extra actions | - |

### Type definitions

The component exports the following types

```ts
import type { EmptyImageSize, EmptyProps } from '@cedar-design/ui'
```

ConfigProvider's `empty` slot can replace Empty content when no custom content is supplied; it is not a public Empty prop.

### Style variables

| Variable | Default | Purpose |
| --- | --- | --- |
| `--c-empty-description-color` | `var(--c-sys-color-content-tertiary)` | Low-emphasis empty-state description |
| `--c-empty-icon-color` | `var(--c-sys-color-content-decorative)` | Decorative nontext icon; not for text users need to read |
| `--c-empty-padding` | `var(--c-spacing-5) 0` | Container spacing |
| `--c-empty-image-margin-bottom` | `var(--c-spacing-2)` | Icon-to-description gap |
| `--c-empty-description-font-size` | `var(--c-font-size-body-3)` | Description font size |
| `--c-empty-description-line-height` | `var(--c-line-height)` | Description line height |
| `--c-empty-extra-margin-top` | `var(--c-spacing-5)` | Gap above additional actions |
| `--c-empty-size-xs/sm/md/lg/xl` | `var(--c-size-15/20/25/35/45)` | Default icon/image size presets |

Descriptions are text and must meet text contrast requirements; decorative icons may be weaker. Custom images/slots may have their own colors and are not forcibly recolored by `icon-color`. Desktop/mobile maintain their own dimensions and spacing while keeping variable responsibilities consistent.

---

Document: llms/en-US/components/field-decorator.md

<!-- Source: src/field-decorator/README.en-US.md; locale: en-US; page: /en/components/field-decorator/ -->

# Field Decorator

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

Focused inputs do not draw an additional outer outline. Existing variant borders, underlines or backgrounds provide focus feedback. This applies to consumers including Input, Textarea, Date and Time.

Input, textarea and numeric-input carets use `currentColor`, matching the current input text. Error state does not override caret color separately.

`--c-field-caret-color` defaults to `currentColor` and controls Input, InputNumber and Textarea carets without changing text color.

## Basic examples

### Control Sizes

Preview configuration: `aria-label="Comparison size"`, `:value="item"`, `aria-label="Comparison variant"`, `:size="size"`.

Example source: src/field-decorator/__demos__/control-sizes.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
const sizes = ["xs", "sm", "md", "lg", "xl"] as const;
const variants = ["outline", "filled", "standard"] as const;
const size = ref<(typeof sizes)[number]>("md");
const variant = ref<(typeof variants)[number]>("outline");
const options = [
  { value: "beijing", label: "Beijing" },
  { value: "shanghai", label: "Shanghai" },
];
const cascaderOptions = [{ value: "china", label: "China", children: options }];

const inputValue = ref("Beijing");
const selectValue = ref("beijing");
const cascaderValue = ref("beijing");
const selectMultiple = ref(["beijing", "shanghai"]);
const cascaderMultiple = ref(["beijing", "shanghai"]);
const selectOverflow = ref(["long", "beijing", "shanghai"]);
const cascaderOverflow = ref(["long", "beijing", "shanghai"]);
const selectedOptions = [
  ...options,
  {
    value: "long",
    label:
      "A very long selected option label for overflow comparison — full text preview keeps the selected value unchanged.",
  },
];
const selectedCascaderOptions = [
  { value: "china", label: "China", children: selectedOptions },
];
function resetSelections() {
  inputValue.value = "Beijing";
  selectValue.value = "beijing";
  cascaderValue.value = "beijing";
  selectMultiple.value = ["beijing", "shanghai"];
  cascaderMultiple.value = ["beijing", "shanghai"];
  selectOverflow.value = ["long", "beijing", "shanghai"];
  cascaderOverflow.value = ["long", "beijing", "shanghai"];
}
</script>
<template>
  <section
    aria-label="Form control size comparison"
    class="control-size-comparison"
  >
    <c-space wrap :size="12">
      <c-radio-group v-model="size" aria-label="Comparison size">
        <c-radio v-for="item in sizes" :key="item" :value="item">{{
          item
        }}</c-radio>
      </c-radio-group>
      <c-radio-group v-model="variant" aria-label="Comparison variant">
        <c-radio v-for="item in variants" :key="item" :value="item">{{
          item
        }}</c-radio>
      </c-radio-group>
    </c-space>
    <div class="control-size-comparison__grid">
      <div data-control="Input">
        <p>Input</p>
        <c-input :size="size" :variant="variant" placeholder="Input" />
      </div>
      <div data-control="Button">
        <p>Button</p>
        <c-button :size="size" variant="outline">Button</c-button>
      </div>
      <div data-control="Select">
        <p>Select</p>
        <c-select
          :size="size"
          :variant="variant"
          :options="options"
          placeholder="Select"
        />
      </div>
      <div data-control="Date">
        <p>Date</p>
        <c-date :size="size" :variant="variant" placeholder="Date" />
      </div>
      <div data-control="Time">
        <p>Time</p>
        <c-time :size="size" :variant="variant" placeholder="Time" />
      </div>
      <div data-control="InputNumber">
        <p>InputNumber</p>
        <c-input-number :size="size" :variant="variant" placeholder="Number" />
      </div>
      <div data-control="AutoComplete">
        <p>AutoComplete</p>
        <c-auto-complete
          :size="size"
          :variant="variant"
          :options="options"
          placeholder="AutoComplete"
        />
      </div>
      <div data-control="Cascader">
        <p>Cascader</p>
        <c-cascader
          :size="size"
          :variant="variant"
          :options="cascaderOptions"
          placeholder="Cascader"
        />
      </div>
      <div data-control="DateRange">
        <p>DateRange</p>
        <c-date-range
          :size="size"
          :variant="variant"
          :placeholder="['Start', 'End']"
        />
      </div>
      <div data-control="TimeRange">
        <p>TimeRange</p>
        <c-time-range
          :size="size"
          :variant="variant"
          :placeholder="['Start', 'End']"
        />
      </div>
    </div>

    <section
      aria-label="Selected control size comparison"
      class="control-size-comparison__states"
    >
      <c-space wrap align="center" :size="12">
        <span>Selected / Clearable / Multiple — 有值、可清空与多选不换行</span>
        <span
          >Hover or focus truncated text; tap on touch screens /
          悬停或聚焦省略正文查看全文；触屏点按查看，点外部关闭</span
        >
        <c-button size="sm" variant="outline" @click="resetSelections"
          >Reset / 恢复选中值</c-button
        >
      </c-space>
      <div class="control-size-comparison__grid">
        <div data-control="InputValue">
          <p>Input · clearable</p>
          <c-input
            v-model="inputValue"
            :size="size"
            :variant="variant"
            clearable
            placeholder="Input value"
          />
        </div>
        <div data-control="ButtonReference">
          <p>Button · reference</p>
          <c-button :size="size" variant="outline">Button</c-button>
        </div>
        <div data-control="SelectValue">
          <p>Select · clearable</p>
          <c-select
            v-model="selectValue"
            :size="size"
            :variant="variant"
            :options="selectedOptions"
            clearable
            placeholder="Select value"
          />
        </div>
        <div data-control="CascaderValue">
          <p>Cascader · clearable</p>
          <c-cascader
            v-model="cascaderValue"
            :size="size"
            :variant="variant"
            :options="selectedCascaderOptions"
            clearable
            placeholder="Cascader value"
          />
        </div>
        <div data-control="SelectMultiple">
          <p>Select · multiple / nowrap</p>
          <c-select
            v-model="selectMultiple"
            :size="size"
            :variant="variant"
            :options="selectedOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Select multiple"
          />
        </div>
        <div data-control="CascaderMultiple">
          <p>Cascader · multiple / nowrap</p>
          <c-cascader
            v-model="cascaderMultiple"
            :size="size"
            :variant="variant"
            :options="selectedCascaderOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Cascader multiple"
          />
        </div>
        <div data-control="SelectOverflow">
          <p>Select · long values / nowrap</p>
          <c-select
            v-model="selectOverflow"
            edit-mode="direct"
            :size="size"
            :variant="variant"
            :options="selectedOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Select long values"
          />
        </div>
        <div data-control="CascaderOverflow">
          <p>Cascader · long values / nowrap</p>
          <c-cascader
            v-model="cascaderOverflow"
            edit-mode="direct"
            :size="size"
            :variant="variant"
            :options="selectedCascaderOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Cascader long values"
          />
        </div>
      </div>
    </section>
  </section>
</template>
<style scoped>
.control-size-comparison,
.control-size-comparison__states {
  display: grid;
  gap: 24px;
}
.control-size-comparison__grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
  align-items: start;
  gap: 24px 16px;
}
.control-size-comparison__grid > div {
  min-width: 0;
}
.control-size-comparison__grid p {
  margin: 0 0 12px;
  font-size: 14px;
  line-height: 20px;
}
.control-size-comparison__grid :deep(.c-input-number),
.control-size-comparison__grid :deep(.c-auto-complete) {
  width: 100%;
}
</style>
```

## Loading and waiting

### Shared field loading

`loading` displays the shared field indicator. `loading-mode` is `default` (indicator) or `line` (an indeterminate bottom line); it defaults to `default`. Rendering belongs to FieldDecorator. Loading does not implicitly disable editing or change readonly. Set those states separately.

 Example source: src/field-decorator/__demos__/loading.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const busy = ref(true)
const mode = ref<'default' | 'line'>('line')
const text = ref('加载时仍可编辑')
</script>
<template>
  <c-space direction="column" :size="16">
    <c-space><c-switch v-model="busy" />加载状态</c-space>
    <c-radio-group v-model="mode" :options="['default', 'line']" variant="button" aria-label="字段加载布局" />
    <c-form layout="vertical">
      <c-form-item label="文本"><c-input v-model="text" :loading="busy" :loading-mode="mode" /></c-form-item>
      <c-form-item label="多行文本"><c-textarea v-model="text" :loading="busy" :loading-mode="mode" /></c-form-item>
      <c-form-item label="选择"><c-select edit-mode="direct" :options="[{ label: '选项', value: 'a' }]" :loading="busy" :loading-mode="mode" /></c-form-item>
      <c-form-item label="日期"><c-date edit-mode="direct" :loading="busy" :loading-mode="mode" /></c-form-item>
    </c-form>
    <p>加载展示由同一个 FieldDecorator 实现，不隐式禁用输入；需要禁止操作时单独设置 disabled 或 readonly。</p>
  </c-space>
</template>
```

### Loading tokens

| Token | Default |
| --- | --- |
| `--c-field-loading-line-size` | `2px` |
| `--c-field-loading-duration` | `1s` |
| `--c-field-loading-color` | `var(--c-field-focus-color)` |

## Props

The outline notch uses `fieldset / legend`, not a background mask. It starts aligned with the content column and reserves `hint-space` on both sides. CSS `max()/calc()` in `padding-inline-start` must be emitted verbatim by Less, preventing different Less versions from prematurely evaluating it as `0px`. `check:input` checks source parity and both libraries’ Less output.

| Prop | Type | Default / meaning |
| --- | --- | --- |
| `tag` | `'div' \| 'span'` | `div`; wrapper element |
| `value` | `unknown` | Checks only whether content is empty |
| `id` | `string` | Native control id associated with the floating label |
| `title` | `string` | Native title tooltip |
| `size` | `ComponentSize` | `md`; implements all five sizes |
| `variant` | `'outline' \| 'filled' \| 'standard'` | `outline` |
| `placeholder` | `string` | Floating label text |
| `hint` | `boolean` | Cedar false / Maple true |
| `hint-center` | `boolean` | `true`; use false for multiline controls |
| `line` | `boolean` | `true`; whether to show a border or underline |
| `focused` | `boolean` | Consumer-supplied focus state |
| `composing` | `boolean` | Keep the label floated during IME composition |
| `disabled` / `readonly` / `error` | `boolean` | Provided by the consumer after merging Form / Group state |
| `clearable` | `boolean` | `false`; whether clearing is allowed |
| `text-color` / `focus-color` / `blur-color` | `string` | Custom text, focused and unfocused colors |
| `cursor` | `string` | Custom caret |

## Slots and events

`default` contains a native input, tags or display content. `prefix` / `suffix` contain adornments. `clear-icon` receives `clear(event?)`; a custom button should call it. Clearing does not bubble to open the selection panel.

`clear(event)` asks the consumer to update the value; `mousedown(event)` lets the consumer manage focus. The wrapper does not mutate the model itself.

Style semantics use `--c-field-*` / `--mp-field-*`, declared in each library's `style/token.less`. Implementations are not shared across libraries. Consumers must not draw a second border.

## Error and disabled border variables

Prefix these suffixes with `--c-field-` / `--mp-field-`: `variant-outline-border-color-error` controls outline error borders; `variant-standard-line-color-error` controls standard error underlines; `variant-standard-line-color-disabled` controls standard disabled underlines and defaults to system border-subtle. Disabled overrides error, hover and focus. All three support local overrides. `field-error-color` still controls error text. Internal variables are not business API; unused legacy declarations are removed without aliases.

Changing `tag` rebinds size observation to the current root and content elements. KeepAlive deactivation releases observation and queued measurement; frames from an earlier activation cannot update the current layout.

---

Document: llms/en-US/components/filter-form.md

<!-- Source: src/filter-form/README.en-US.md; locale: en-US; page: /en/components/filter-form/ -->

# Filter Form

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

Preview configuration: `v-model:collapsed="collapsed"`, `:fields="fields"`, `:rules="rules"`.

Example source: src/filter-form/__demos__/basic.vue

```vue
<template>
  <c-filter-form
    v-model="filter"
    v-model:collapsed="collapsed"
    :fields="fields"
    :rules="rules"
  >
    <template #actions>
      <c-button variant="outline" :elevation="false" @click="reset">重置</c-button>
      <c-button status="primary" :elevation="false" @click="search">搜索</c-button>
    </template>
  </c-filter-form>
  <pre class="demo-filter-json">{{ filter }}</pre>
  <p role="status">{{ result }}</p>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import {
  Cascader,
  DateRange,
  Input,
  Select,
  type FilterFormField,
} from '@cedar-design/ui'

const collapsed = ref(true)
const result = ref('尚未搜索')
const filter = ref<Record<string, unknown>>({
  region: undefined,
  status: undefined,
  keyword: '',
  timeRange: undefined,
})

const options = {
  status: [
    { label: '待处理', value: 'pending' },
    { label: '进行中', value: 'doing' },
    { label: '已完成', value: 'done' },
  ],
  owner: [
    { label: '张三', value: 'zhang' },
    { label: '李四', value: 'li' },
  ],
}

const rules = {
  keyword: [{ maxLength: 50, message: '最多 50 个字符' }],
}

const fields: FilterFormField[] = [
  {
    component: Cascader,
    field: 'region',
    label: '地区',
    props: {
      clearable: true,
      placeholder: '请选择地区',
      pathMode: true,
      variant: 'outline',
      options: [
        {
          value: 'beijing',
          label: '北京',
          children: [
            { value: 'chaoyang', label: '朝阳' },
            { value: 'haidian', label: '海淀' },
          ],
        },
        {
          value: 'shanghai',
          label: '上海',
          children: [{ value: 'huangpu', label: '黄浦' }],
        },
      ],
    },
  },
  {
    component: Select,
    field: 'status',
    label: '状态',
    props: { variant: 'outline', clearable: true, placeholder: '全部', options: options.status },
  },
  {
    component: Select,
    field: 'owner',
    label: '负责人',
    props: { variant: 'outline', clearable: true, placeholder: '全部', options: options.owner },
  },
  {
    component: Input,
    field: 'keyword',
    label: '关键词',
    autoEmitChange: false,
    props: { variant: 'outline', clearable: true, placeholder: '回车或失焦触发' },
  },
  {
    component: DateRange,
    field: 'timeRange',
    label: '时间范围',
    gridItemProps: { span: 2 },
    props: { variant: 'outline', valueFormat: 'timestamp', clearable: true, showTime: true },
  },
]

function search() {
  result.value = `搜索条件：${JSON.stringify(filter.value)}`
}

function reset() {
  result.value = '已重置'
  filter.value = {
    region: undefined,
    status: undefined,
    keyword: '',
    timeRange: undefined,
  }
}
</script>

<style scoped>
.demo-filter-json {
  margin-top: 16px;
  padding: 12px 16px;
  border-radius: 4px;
  background: var(--c-sys-color-surface-muted);
  color: var(--c-sys-color-content-secondary);
  font-size: 12px;
  line-height: 1.5;
  white-space: pre-wrap;
  word-break: break-all;
}
</style>
```

## Content and presentation

### Registered Fields

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `fields` | Filter-item schema | Registered Fields |
| `field-map` | Optional field-component registry | Registered Fields |
| `collapsible` | Whether expanding/collapsing is enabled | Registered Fields |
<!-- demo-config-notes:end -->


Preview configuration: `:fields="fields"`, `:field-map="fieldMap"`, `:collapsible="false"`.

Example source: src/filter-form/__demos__/registered-fields.vue

```vue
<template>
  <c-filter-form v-model="filter" :fields="fields" :field-map="fieldMap" :collapsible="false" />
  <pre>{{ filter }}</pre>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import { Input, Select, type FilterFormField, type FilterFormFieldMap } from '@cedar-design/ui'

const filter = ref<Record<string, unknown>>({ keyword: '', status: undefined })
const fieldMap: FilterFormFieldMap = {
  input: Input,
  select: { component: Select, defaultProps: { clearable: true, placeholder: '全部' } },
}
const fields: FilterFormField[] = [
  { field: 'keyword', label: '关键词', component: 'input', props: { clearable: true } },
  {
    field: 'status',
    label: '状态',
    component: 'select',
    props: { options: [{ label: '启用', value: 'enabled' }, { label: '停用', value: 'disabled' }] },
  },
]
</script>
```

## Async and dynamic data

### Async Options

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `fields` | Filter-item schema | Async Options |
| `collapsible` | Whether expanding/collapsing is enabled | Async Options |
<!-- demo-config-notes:end -->


Preview configuration: `:fields="fields"`, `:collapsed="false"`, `:collapsible="false"`.

Example source: src/filter-form/__demos__/async-options.vue

```vue
<template>
  <c-space direction="column" style="width: 100%">
    <c-alert>
      异步加载选项后，通过 computed 更新字段的 props.options。
    </c-alert>
    <c-filter-form
      v-model="filter"
      :fields="fields"
      :collapsed="false"
      :collapsible="false"
    >
      <template #actions>
        <c-space>
          <c-button @click="reset">重置</c-button>
          <c-button status="primary" @click="search">搜索</c-button>
        </c-space>
      </template>
    </c-filter-form>
  </c-space>
  <p role="status">{{ result }}</p>
</template>

<script lang="ts" setup>
import { computed, onMounted, onUnmounted, ref } from 'vue'
import {
  Input,
  Select,
  type FilterFormField,
} from '@cedar-design/ui'

const filter = ref<Record<string, unknown>>({
  category: undefined,
  tag: undefined,
  name: '',
})

const options = ref<Record<string, unknown>>({
  category: [],
  tag: [],
})

const fields = computed<FilterFormField[]>(() => [
  {
    component: Select,
    field: 'category',
    label: '分类',
    props: { clearable: true, placeholder: '请选择', options: options.value.category },
  },
  {
    component: Select,
    field: 'tag',
    label: '标签',
    props: { clearable: true, multiple: true, placeholder: '请选择', options: options.value.tag },
  },
  {
    component: Input,
    field: 'name',
    label: '名称',
    props: { clearable: true },
  },
])

let timer: ReturnType<typeof setTimeout>
onUnmounted(() => clearTimeout(timer))

onMounted(() => {
  timer = setTimeout(() => {
    options.value = {
      category: [
        { label: '组件', value: 'component' },
        { label: '工具', value: 'tool' },
      ],
      tag: [
        { label: '推荐', value: 'hot' },
        { label: '新品', value: 'new' },
      ],
    }
  }, 800)
})

const result = ref('尚未搜索')
function search() {
  result.value = `搜索条件：${JSON.stringify(filter.value)}`
}

function reset() {
  filter.value = {
    category: undefined,
    tag: undefined,
    name: '',
  }
}
</script>
```

## API

### Value and default value

Use ordinary `v-model`. `modelValue` is the filter-fields object. `defaultValue` initializes uncontrolled state once; later changes do not reset it. Explicit binding takes precedence, and initialization emits no `update:modelValue`.

### FilterForm Props

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| model-value **(v-model)** | Form value | `Record<string, unknown>` | `{}` |
| fields | Filter-item schema | `FilterFormField[]` | `[]` |
| field-map | Optional field-component registry | `FilterFormFieldMap` | `{}` |
| rules | Forwarded Form validation rules | object | - |
| collapsed **(v-model)** | Whether to collapse extra items | boolean | `true` |
| collapsible | Whether expanding/collapsing is enabled | boolean | `true` |
| cols | Responsive column count | number \| object | `{ xs:1, sm:2, md:3, lg:3, xl:4, xxl:5 }` |
| grid-props | Other Grid props | object | - |
| change-debounce | Change debounce interval in milliseconds | number | `500` |

### FilterFormField

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| component | Vue component or a key in `fieldMap` | `string \| Component` | - |
| field | Form field path | string | - |
| label | Label | string | - |
| visible | Whether to render | boolean | `true` |
| autoEmitChange | Whether input emits change while editing | boolean | `true` |
| props | Props forwarded to the field component | object | - |
| gridItemProps | GridItem props | object | - |
| formItemProps | FormItem props | object | - |

### FilterFormFieldRegistration

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| component | Field component | Component | - |
| defaultProps | Default props | object | - |

### Events

| Event | Description | Arguments |
| --- | --- | --- |
| update:model-value | v-model | `(value) => void` |
| update:collapsed | Collapsed state changes | `(collapsed) => void` |
| change | Debounced field-value changes | `(value, field) => void` |

### Slots

| Slot | Description |
| --- | --- |
| actions | Action area for search/reset, on the same row as the expand/collapse control |

### Methods

| Method | Description |
| --- | --- |
| formRef | Internal Form instance |

## Style variables

| Variable | Default |
| --- | --- |
| `--c-filter-form-border-radius` | `var(--c-border-radius-md)` |
| `--c-filter-form-background-color` | `var(--c-sys-color-surface-default)` |
| `--c-filter-form-padding` | `var(--c-sys-space-7)`（20px） |
| `--c-filter-form-border-color` | `var(--c-sys-color-border-subtle)` |
| `--c-filter-form-border-width` | `1px` |
| `--c-filter-form-action-offset` | `calc(1em * var(--c-form-line-height) + var(--c-form-vertical-label-margin-bottom))` |
| `--c-filter-form-item-margin-bottom` | `0px`; Grid controls row spacing |
| `--c-filter-form-actions-gap` | `var(--c-sys-space-5)`（12px） |
| `--c-filter-form-collapse-gap` | `4px` |
| `--c-filter-form-collapse-color` | `var(--c-color-text-2)` |
| `--c-filter-form-collapse-hover-color` | `var(--c-sys-color-content-brand)` |
| `--c-filter-form-focus-width` | `2px` |
| `--c-filter-form-focus-offset` | `3px` |

Consumption verified on 2026-10-16: real Less compilation and mounted DOM confirm these 13 variables feed the container, FormItem, action-area and collapse-button rules. The static style entry also imports Form styles. Multi-column action `padding-top` consumes action-offset; stacked single-column mode overrides it to `0`. Root derived aliases do not necessarily recompute after locally overriding Form dependencies; adjust alignment by overriding `--c-filter-form-action-offset` on the actual FilterForm root.

## Types

```ts
import type {
  FilterFormProps,
  FilterFormField,
  FilterFormFieldMap,
  FilterFormFieldRegistration,
} from '@cedar-design/ui'
```

Grid column spacing is controlled by `grid-props.colGap` in numeric px. There is no same-name CSS override, ensuring numerical Grid measurements match actual spacing.

Changing changeDebounce reschedules a pending snapshot with the new delay;0 publishes immediately. Enter cancels its pending duplicate. Model resets invalidate stale snapshots while an accepted matching update:modelValue echo retains its change notification. Deactivation/unmount cancel pending work; reactivation accepts new input.

---

Document: llms/en-US/components/form.md

<!-- Source: src/form/README.en-US.md; locale: en-US; page: /en/components/form/ -->

# Form

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Reading direction

Form and FormItem accept start/end/left/center/right for content-align and start/end/left/right for label-align. Content defaults to start and labels to end: default LTR placement stays the same while RTL follows reading order. Explicit left/right remain physical. Item overrides and explicit label-column styles retain precedence. Direction changes preserve values, validation and disabled/readonly state.

## Basic examples

### Basic usage

- `model`: Form data object

Example source: src/form/__demos__/basic.vue

```vue
<template>
  <c-form ref="refForm" :model="form" @submit="handleSubmit">
    <c-form-item field="name" label="Username" required>
      <c-select v-model="form.name">
        <c-optgroup label="Group-1">
          <c-option>Beijing</c-option>
          <c-option>Shanghai</c-option>
        </c-optgroup>
        <c-option>Guangzhou</c-option>
        <c-option disabled>Disabled</c-option>
      </c-select>
    </c-form-item>
    <c-form-item>
      <c-button html-type="submit">Submit</c-button>
    </c-form-item>
  </c-form>
  {{ form.name }}
</template>
<script setup lang="ts">
import { reactive, ref } from "vue";
import type { FormInstance } from "../index";

const refForm = ref<FormInstance>();
const form = reactive({ name: "", post: "", isRead: false });
const handleSubmit = (data: any) => refForm.value?.resetFields(data);
</script>
```

## Form appearance and layout

### Disabled

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration      | Purpose                                                                       | Related examples                           |
| ------------------ | ----------------------------------------------------------------------------- | ------------------------------------------ |
| `layout`           | The layout of the form, including horizontal, vertical, and multi-column      | Layout, Decoration, Label width strategies |
| `model`            | Form data object                                                              | Decoration, Label width strategies         |
| `disabled`         | Whether to disable the form                                                   | Disabled                                   |
| `label-align`      | Label alignment                                                               | Label width strategies                     |
| `auto-label-width` | Automatically measure label widths; only effective with `layout="horizontal"` | Label width strategies                     |
| `label-col-flex`   | Label-column flex; numbers are flex ratios, unit-bearing strings are widths   | Label width strategies                     |

<!-- demo-config-notes:end -->

- `disabled`: Whether to disable the form

Example source: src/form/__demos__/disabled.vue

```vue
<template>
  <c-form :style="{ width: '600px' }" disabled>
    <c-form-item field="name" label="Username">
      <c-input placeholder="please enter your username..." />
    </c-form-item>
  </c-form>
</template>
<script lang="ts">
import { defineComponent } from 'vue'
export default defineComponent({
  })
</script>
```

### Layout

`edit-mode` describes editing behavior: `direct` always shows the control; `click` and `dblclick` activate the existing editor overlay near the field. `readPretty` is an independent boolean. FormItem and fields inherit the mode when omitted. The legacy field `presentation` prop has been removed; use `edit-mode` to configure editing behavior. Replace `presentation="inline"` with `edit-mode="direct"`; `layout="inline"` is unchanged.

Combine `layout`, `content-align` with `direct / click / dblclick` editing and the independent `readPretty` boolean to compare label, value and wrapped-text alignment. Notes can override the form layout, and values survive every switch. Click or double-click a value to edit in a popover; readPretty displays saved text.

Example source: src/form/__demos__/en-US/layout.vue

```vue
<script setup lang="ts">
import Comparison from "../layout.vue";
</script>

<template><Comparison english /></template>
```

### Decoration

- `model`: Form data object
- `layout`: The layout of the form, including horizontal, vertical, and multi-column

Example source: src/form/__demos__/decoration.vue

```vue
<script setup lang="ts">
import { reactive } from 'vue'
const model = reactive({ name: '', notes: '' })
</script>

<template>
  <c-form :model="model" layout="vertical">
    <c-form-item field="name" label="公开名称" required show-colon tooltip="名称将展示在个人主页。" :label-attrs="{ for: 'decorated-name' }">
      <c-input id="decorated-name" v-model="model.name" placeholder="输入公开名称" />
    </c-form-item>
    <c-form-item field="notes" label="备注" label-component="div" :content-flex="false" content-class="decoration-grid">
      <c-input v-model="model.notes" placeholder="支持自定义内容布局" />
      <small>content-flex=false 后由业务自行布局。</small>
    </c-form-item>
  </c-form>
</template>

<style scoped>
.decoration-grid { display: grid; gap: 8px; }
</style>
```

### Extra

Preview configuration: `type="text"`, `placeholder="请输入"`.

Example source: src/form/__demos__/extra.vue

```vue
<template>
  <c-form>
    <c-form-item field="name" label="Username" required>
      <c-input type="text" placeholder="请输入" />
      <template #extra>
        <div>UserName</div>
      </template>
    </c-form-item>
    <c-form-item field="post" label="Postname" required>
      <c-input type="text" placeholder="请输入" />
      <template #extra>
        <div>PostName</div>
      </template>
      <template #help>
        <div>Custom valitae message</div>
      </template>
    </c-form-item>
  </c-form>
</template>
<script lang="ts">
import { defineComponent } from 'vue'
export default defineComponent({
  setup() {
    return {}
  },
})
</script>
```

### Label width strategies

Enter values, then switch between measured labels, responsive columns and fixed widths: all three strategies retain the same form model. Edit the longest label or hide the contact field to observe remeasurement. Below 576px, the responsive strategy stacks labels above controls; fixed widths use 6rem with an 8rem contact-field override.

Example source: src/form/__demos__/en-US/label-width-comparison.vue

```vue
<script setup lang="ts">
import Comparison from '../label-width-comparison.vue'
</script>
<template><Comparison english /></template>
```

## Fields and data model

### Nested Data

- `model`: Form data object

Example source: src/form/__demos__/nested-data.vue

```vue
<template>
  <c-form :model="form" :style="{ width: '600px' }">
    <c-form-item
      label="Username"
      :content-flex="false"
      :merge-props="false"
      extra="Show error message together"
    >
      <c-row :gutter="8">
        <c-col :span="12">
          <c-form-item
            field="together.firstname"
            validate-trigger="input"
            :rules="[{ required: true, message: 'firstname is required' }]"
            no-style
          >
            <c-input
              v-model="form.together.firstname"
              placeholder="please enter your firstname..."
            />
          </c-form-item>
        </c-col>
        <c-col :span="12">
          <c-form-item
            field="together.lastname"
            validate-trigger="input"
            :rules="[{ required: true, message: 'lastname is required' }]"
            no-style
          >
            <c-input
              v-model="form.together.lastname"
              placeholder="please enter your lastname..."
            />
          </c-form-item>
        </c-col>
      </c-row>
    </c-form-item>
    <c-form-item label="Username" :content-flex="false" :merge-props="false">
      <c-row :gutter="8">
        <c-col :span="12">
          <c-form-item
            field="separate.firstname"
            validate-trigger="input"
            extra="Show error message separate"
            :rules="[{ required: true, message: 'firstname is required' }]"
            hide-label
          >
            <c-input
              v-model="form.separate.firstname"
              placeholder="please enter your firstname..."
            />
          </c-form-item>
        </c-col>
        <c-col :span="12">
          <c-form-item
            field="separate.lastname"
            validate-trigger="input"
            :rules="[{ required: true, message: 'lastname is required' }]"
            hide-label
          >
            <c-input
              v-model="form.separate.lastname"
              placeholder="please enter your lastname..."
            />
          </c-form-item>
        </c-col>
      </c-row>
    </c-form-item>
    <c-form-item label="Posts" :content-flex="false" :merge-props="false">
      <c-space direction="column" align="stretch">
        <c-form-item field="posts.post1" label="Post1">
          <c-input
            v-model="form.posts.post1"
            placeholder="please enter your post..."
          />
        </c-form-item>
        <c-form-item field="posts.post2" label="Post2">
          <c-input
            v-model="form.posts.post2"
            placeholder="please enter your post..."
          />
        </c-form-item>
      </c-space>
    </c-form-item>
    <c-form-item field="isRead">
      <c-checkbox v-model="form.isRead"> I have read the manual </c-checkbox>
    </c-form-item>
  </c-form>
  {{ form }}
</template>
<script lang="ts">
import { reactive, ref, defineComponent } from "vue";
export default defineComponent({
  setup() {
    const form = reactive({
      together: {
        firstname: "",
        lastname: "",
      },
      separate: {
        firstname: "",
        lastname: "",
      },
      posts: {
        post1: "",
        post2: "",
      },
      isRead: false,
    });

    return {
      form,
    };
  },
});
</script>
```

### Field Components

- `model`: Form data object

Example source: src/form/__demos__/field-components.vue

```vue
<script setup>
import ModelOutput from "../__demo-utils__/ModelOutput.vue";
import { ref } from "vue";
const editMode = ref("direct");
const presentations = ["direct", "click", "dblclick"].map((value) => ({
  value,
  label: value,
}));
const model = ref({
  name: "表单输入示例",
  notes: "每个字段都继承上方的展示与触发方式",
  count: 3,
  code: "123456",
});
</script>

<template>
  <c-space direction="column" align="stretch" :size="16">
    <c-form-item layout="vertical" size="sm" label="字段展示方式">
      <c-radio-group
        v-model="editMode"
        aria-label="字段展示方式"
        :options="presentations"
        variant="button"
        size="sm"
      />
    </c-form-item>
    <c-form :model="model" :edit-mode="editMode">
      <c-form-item field="name" label="单行文本"
        ><c-input v-model="model.name"
      /></c-form-item>
      <c-form-item field="notes" label="多行文本"
        ><c-textarea v-model="model.notes"
      /></c-form-item>
      <c-form-item field="count" label="数量"
        ><c-input-number v-model="model.count" :min="0" :max="100"
      /></c-form-item>
      <c-form-item field="code" label="验证码"
        ><c-verification-code v-model="model.code" :length="6"
      /></c-form-item>
    </c-form>
    <ModelOutput aria-label="当前模型">{{
      JSON.stringify(model, null, 2)
    }}</ModelOutput>
  </c-space>
</template>
```

### Field Choice

- `model`: Form data object

Example source: src/form/__demos__/field-choice.vue

```vue
<script setup>
import ModelOutput from "../__demo-utils__/ModelOutput.vue";
import { ref } from "vue";
const editMode = ref("direct");
const presentations = ["direct", "click", "dblclick"].map((value) => ({
  value,
  label: value,
}));
const choices = [
  { label: "研发", value: "dev" },
  { label: "设计", value: "design" },
  { label: "运营", value: "ops" },
];
const model = ref({
  enabled: true,
  agreed: true,
  teams: ["dev", "design"],
  role: "dev",
});
</script>

<template>
  <c-space direction="column" align="stretch" :size="16">
    <c-form-item layout="vertical" size="sm" label="字段展示方式">
      <c-radio-group
        v-model="editMode"
        aria-label="字段展示方式"
        :options="presentations"
        variant="button"
        size="sm"
      />
    </c-form-item>
    <c-form :model="model" :edit-mode="editMode">
      <c-form-item field="enabled" label="启用"
        ><c-switch v-model="model.enabled"
      /></c-form-item>
      <c-form-item field="agreed" label="确认状态"
        ><c-checkbox v-model="model.agreed">已阅读说明</c-checkbox></c-form-item
      >
      <c-form-item field="teams" label="协作部门"
        ><c-checkbox-group v-model="model.teams" :options="choices"
      /></c-form-item>
      <c-form-item field="role" label="所属部门"
        ><c-radio-group v-model="model.role" :options="choices"
      /></c-form-item>
    </c-form>
    <ModelOutput aria-label="当前模型">{{
      JSON.stringify(model, null, 2)
    }}</ModelOutput>
  </c-space>
</template>
```

### Field Selection

- `model`: Form data object

Example source: src/form/__demos__/field-selection.vue

```vue
<script setup>
import ModelOutput from "../__demo-utils__/ModelOutput.vue";
import { ref, watch } from "vue";
const editMode = ref("direct");
const presentations = ["direct", "click", "dblclick"].map((value) => ({
  value,
  label: value,
}));
const devices = [
  {
    isGroup: true,
    label: "常用设备",
    options: [
      { value: "laptop", label: "笔记本" },
      { value: "phone", label: "手机" },
      { value: "tablet", label: "平板" },
    ],
  },
  {
    isGroup: true,
    label: "其他设备",
    options: [
      { value: "desktop", label: "台式工作站" },
      { value: "watch", label: "智能手表（暂不可选）", disabled: true },
    ],
  },
];
const people = [
  { value: "lin", label: "林晓 · 研发" },
  { value: "chen", label: "陈晨 · 设计" },
  { value: "zhou", label: "周宁 · 运营" },
];
const suggestions = [
  {
    isGroup: true,
    label: "技术团队",
    options: [
      { value: "研发" },
      { value: "研发平台" },
      { value: "研发基础设施" },
    ],
  },
  {
    isGroup: true,
    label: "协作团队",
    options: [
      { value: "设计" },
      { value: "运营" },
      { value: "归档团队", disabled: true },
    ],
  },
];
const model = ref({
  device: "laptop",
  devices: ["laptop", "phone"],
  keyword: "研发",
  person: "lin",
});
</script>

<template>
  <c-space direction="column" align="stretch" :size="16">
    <c-form-item layout="vertical" size="sm" label="字段展示方式">
      <c-radio-group
        v-model="editMode"
        aria-label="字段展示方式"
        :options="presentations"
        variant="button"
        size="sm"
      />
    </c-form-item>
    <c-form :model="model" :edit-mode="editMode">
      <c-form-item field="device" label="单选设备"
        ><c-select v-model="model.device" :options="devices" filterable
      /></c-form-item>
      <c-form-item field="devices" label="多选设备"
        ><c-select
          v-model="model.devices"
          :options="devices"
          multiple
          filterable
          :limit="3"
      /></c-form-item>
      <c-form-item field="keyword" label="自动补全"
        ><c-auto-complete
          v-model="model.keyword"
          :options="suggestions"
          clearable
          placeholder="输入或选择团队"
      /></c-form-item>
      <c-form-item field="person" label="人员"
        ><c-people-select
          v-model="model.person"
          :label="people.find((item) => item.value === model.person)?.label"
          :options="people"
          clearable
          placeholder="搜索人员"
      /></c-form-item>
    </c-form>
    <ModelOutput aria-label="当前模型">{{
      JSON.stringify(model, null, 2)
    }}</ModelOutput>
  </c-space>
</template>
```

### Field Tree

- `model`: Form data object

Example source: src/form/__demos__/field-tree.vue

```vue
<script setup>
import ModelOutput from "../__demo-utils__/ModelOutput.vue";
import { ref } from "vue";
const editMode = ref("direct");
const presentations = ["direct", "click", "dblclick"].map((value) => ({
  value,
  label: value,
}));
const regions = [
  {
    label: "华东",
    value: "east",
    children: [
      { label: "上海", value: "shanghai" },
      {
        label: "浙江",
        value: "zhejiang",
        children: [
          { label: "杭州", value: "hangzhou" },
          { label: "宁波", value: "ningbo" },
        ],
      },
    ],
  },
  {
    label: "华北",
    value: "north",
    children: [
      { label: "北京", value: "beijing" },
      { label: "天津", value: "tianjin" },
    ],
  },
  { label: "华南（暂不可选）", value: "south", disabled: true },
];
const treeOptions = [
  {
    value: "east",
    label: "华东",
    children: [
      { value: "shanghai", label: "上海" },
      {
        value: "zhejiang",
        label: "浙江",
        children: [
          { value: "hangzhou", label: "杭州" },
          { value: "ningbo", label: "宁波" },
        ],
      },
    ],
  },
  {
    value: "north",
    label: "华北",
    children: [
      { value: "beijing", label: "北京" },
      { value: "tianjin", label: "天津", disabled: true },
    ],
  },
];
const model = ref({
  regions: ["shanghai", "hangzhou"],
  region: "shanghai",
  tree: "shanghai",
  trees: ["shanghai", "hangzhou"],
});
</script>

<template>
  <c-space direction="column" align="stretch" :size="16">
    <c-form-item layout="vertical" size="sm" label="字段展示方式">
      <c-radio-group
        v-model="editMode"
        aria-label="字段展示方式"
        :options="presentations"
        variant="button"
        size="sm"
      />
    </c-form-item>
    <c-form :model="model" :edit-mode="editMode">
      <c-form-item field="region" label="地区"
        ><c-cascader v-model="model.region" :options="regions" filterable
      /></c-form-item>
      <c-form-item field="regions" label="多选地区"
        ><c-cascader
          v-model="model.regions"
          :options="regions"
          multiple
          filterable
          show-path-label
      /></c-form-item>
      <c-form-item field="tree" label="树选择"
        ><c-tree-select
          v-model="model.tree"
          :data="treeOptions"
          :filter-tree-node="
            (query, node) => String(node.label).includes(query)
          "
          filterable
      /></c-form-item>
      <c-form-item field="trees" label="多选树节点"
        ><c-tree-select
          v-model="model.trees"
          :data="treeOptions"
          multiple
          tree-checkable
          :filter-tree-node="
            (query, node) => String(node.label).includes(query)
          "
          filterable
      /></c-form-item>
    </c-form>
    <ModelOutput aria-label="当前模型">{{
      JSON.stringify(model, null, 2)
    }}</ModelOutput>
  </c-space>
</template>
```

### Field Date

- `model`: Form data object

Example source: src/form/__demos__/field-date.vue

```vue
<script setup>
import ModelOutput from "../__demo-utils__/ModelOutput.vue";
import { ref } from "vue";
const editMode = ref("direct");
const presentations = ["direct", "click", "dblclick"].map((value) => ({
  value,
  label: value,
}));
const model = ref({
  datetime: "2026-10-20 09:30:00",
  dateTimes: ["2026-10-20 09:30:00", "2026-10-22 18:00:00"],
  day: "2026-10-19",
  days: ["2026-10-19", "2026-10-22"],
});
</script>

<template>
  <c-space direction="column" align="stretch" :size="16">
    <c-form-item layout="vertical" size="sm" label="字段展示方式">
      <c-radio-group
        v-model="editMode"
        aria-label="字段展示方式"
        :options="presentations"
        variant="button"
        size="sm"
      />
    </c-form-item>
    <c-form :model="model" :edit-mode="editMode">
      <c-form-item field="day" label="日期"
        ><c-date v-model="model.day" value-format="YYYY-MM-DD"
      /></c-form-item>
      <c-form-item field="days" label="日期范围"
        ><c-date-range v-model="model.days" value-format="YYYY-MM-DD"
      /></c-form-item>
      <c-form-item field="datetime" label="日期时间"
        ><c-date v-model="model.datetime" show-time
      /></c-form-item>
      <c-form-item field="dateTimes" label="日期时间范围"
        ><c-date-range v-model="model.dateTimes" show-time
      /></c-form-item>
    </c-form>
    <ModelOutput aria-label="当前模型">{{
      JSON.stringify(model, null, 2)
    }}</ModelOutput>
  </c-space>
</template>
```

### Field Time

- `model`: Form data object

Example source: src/form/__demos__/field-time.vue

```vue
<script setup>
import ModelOutput from "../__demo-utils__/ModelOutput.vue";
import { ref } from "vue";
const editMode = ref("direct");
const presentations = ["direct", "click", "dblclick"].map((value) => ({
  value,
  label: value,
}));
const model = ref({
  time: "09:30",
  times: ["09:30", "18:00"],
});
</script>

<template>
  <c-space direction="column" align="stretch" :size="16">
    <c-form-item layout="vertical" size="sm" label="字段展示方式">
      <c-radio-group
        v-model="editMode"
        aria-label="字段展示方式"
        :options="presentations"
        variant="button"
        size="sm"
      />
    </c-form-item>
    <c-form :model="model" :edit-mode="editMode">
      <c-form-item field="time" label="时间"
        ><c-time v-model="model.time" format="HH:mm"
      /></c-form-item>
      <c-form-item field="times" label="时间范围"
        ><c-time-range v-model="model.times" format="HH:mm"
      /></c-form-item>
    </c-form>
    <ModelOutput aria-label="当前模型">{{
      JSON.stringify(model, null, 2)
    }}</ModelOutput>
  </c-space>
</template>
```

### Field Rating

- `model`: Form data object

Example source: src/form/__demos__/field-rating.vue

```vue
<script setup>
import ModelOutput from "../__demo-utils__/ModelOutput.vue";
import { ref } from "vue";
const editMode = ref("direct");
const presentations = ["direct", "click", "dblclick"].map((value) => ({
  value,
  label: value,
}));
const model = ref({
  progress: 40,
  score: 4,
});
</script>

<template>
  <c-space direction="column" align="stretch" :size="16">
    <c-form-item layout="vertical" size="sm" label="字段展示方式">
      <c-radio-group
        v-model="editMode"
        aria-label="字段展示方式"
        :options="presentations"
        variant="button"
        size="sm"
      />
    </c-form-item>
    <c-form :model="model" :edit-mode="editMode">
      <c-form-item field="progress" label="进度"
        ><c-slider v-model="model.progress"
      /></c-form-item>
      <c-form-item field="score" label="评分"
        ><c-rate v-model="model.score"
      /></c-form-item>
    </c-form>
    <ModelOutput aria-label="当前模型">{{
      JSON.stringify(model, null, 2)
    }}</ModelOutput>
  </c-space>
</template>
```

### Field Upload

- `model`: Form data object

Example source: src/form/__demos__/field-upload.vue

```vue
<script setup>
import ModelOutput from "../__demo-utils__/ModelOutput.vue";
import { ref } from "vue";
const editMode = ref("direct");
const presentations = ["direct", "click", "dblclick"].map((value) => ({
  value,
  label: value,
}));
const model = ref({
  attachments: [],
});
</script>

<template>
  <c-space direction="column" align="stretch" :size="16">
    <c-form-item layout="vertical" size="sm" label="字段展示方式">
      <c-radio-group
        v-model="editMode"
        aria-label="字段展示方式"
        :options="presentations"
        variant="button"
        size="sm"
      />
    </c-form-item>
    <c-form :model="model" :edit-mode="editMode">
      <c-form-item field="attachments" label="附件"
        ><c-upload v-model="model.attachments" :auto-upload="false"
      /></c-form-item>
    </c-form>
    <ModelOutput aria-label="当前模型">{{
      JSON.stringify(model, null, 2)
    }}</ModelOutput>
  </c-space>
</template>
```

### Field Specialized

- `model`: Form data object

Example source: src/form/__demos__/field-specialized.vue

```vue
<script setup>
import ModelOutput from "../__demo-utils__/ModelOutput.vue";
import { ref } from "vue";
const editMode = ref("direct");
const presentations = ["direct", "click", "dblclick"].map((value) => ({
  value,
  label: value,
}));
const choices = [
  { label: "研发", value: "dev" },
  { label: "设计", value: "design" },
  { label: "运营", value: "ops" },
];
const model = ref({
  mention: "@设计 请确认",
  color: "#36b5ac",
  tags: ["Vue", "TypeScript"],
  transferred: [{ value: "dev", label: "研发" }],
});
</script>

<template>
  <c-space direction="column" align="stretch" :size="16">
    <c-form-item layout="vertical" size="sm" label="字段展示方式">
      <c-radio-group
        v-model="editMode"
        aria-label="字段展示方式"
        :options="presentations"
        variant="button"
        size="sm"
      />
    </c-form-item>
    <c-form :model="model" :edit-mode="editMode">
      <c-form-item field="mention" label="提及"
        ><c-mention v-model="model.mention" :options="['研发', '设计', '运营']"
      /></c-form-item>
      <c-form-item field="color" label="颜色"
        ><c-color v-model="model.color"
      /></c-form-item>
      <c-form-item field="tags" label="标签"
        ><c-input-tag v-model="model.tags"
      /></c-form-item>
      <c-form-item field="transferred" label="穿梭选择"
        ><c-transfer v-model="model.transferred" :data="choices"
      /></c-form-item>
    </c-form>
    <ModelOutput aria-label="当前模型">{{
      JSON.stringify(model, null, 2)
    }}</ModelOutput>
  </c-space>
</template>
```

## Validation and submission

### Validate

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration | Purpose                                                                  | Related examples                     |
| ------------- | ------------------------------------------------------------------------ | ------------------------------------ |
| `model`       | Form data object                                                         | Validate, Cross Field, Clear Trigger |
| `layout`      | The layout of the form, including horizontal, vertical, and multi-column | Clear Trigger                        |

<!-- demo-config-notes:end -->

- `model`: Form data object

Example source: src/form/__demos__/validate.vue

```vue
<template>
  <c-form ref="formRef" :model="form" :style="{ width: '600px' }" @submit="handleSubmit">
    <c-form-item
      field="name"
      label="Username"
      :rules="[
        { required: true, message: 'name is required' },
        { minLength: 5, message: 'must be greater than 5 characters' },
      ]"
      :validate-trigger="['change', 'input']"
    >
      <c-input v-model="form.name" placeholder="please enter your username..." />
    </c-form-item>
    <c-form-item
      field="age"
      label="Age"
      :rules="[
        { required: true, message: 'age is required' },
        { type: 'number', max: 200, message: 'age is max than 200' },
      ]"
    >
      <c-input v-model="form.age" placeholder="please enter your age..." />
    </c-form-item>
    <c-form-item field="date" label="date" :rules="[{ required: true, message: 'age is required' }]">
      <c-date-picker v-model="form.date" placeholder="please enter date..." />
    </c-form-item>
    <c-form-item field="section" label="Section" :rules="[{ match: /section one/, message: 'must select one' }]">
      <c-select v-model="form.section" placeholder="Please select ..." clearable>
        <c-option value="section one">Section One</c-option>
        <c-option value="section two">Section Two</c-option>
        <c-option value="section three">Section Three</c-option>
      </c-select>
    </c-form-item>
  </c-form>
</template>
<script lang="ts">
import { defineComponent, reactive } from 'vue'
export default defineComponent({
  setup() {
    const handleSubmit = (data: any) => {
      console.log(data)
    }

    const form = reactive({
      size: 'md',
      name: '',
      age: undefined,
      section: '',
      province: 'haidian',
      options: [],
      date: '',
      time: '',
      radio: 'radio one',
      slider: 5,
      score: 5,
      switch: false,
      multiSelect: ['section one'],
      treeSelect: '',
    })
    const options = [
      {
        value: 'beijing',
        label: 'Beijing',
        children: [
          {
            value: 'chaoyang',
            label: 'ChaoYang',
            children: [
              {
                value: 'datunli',
                label: 'Datunli',
              },
            ],
          },
          {
            value: 'haidian',
            label: 'Haidian',
          },
          {
            value: 'dongcheng',
            label: 'Dongcheng',
          },
          {
            value: 'xicheng',
            label: 'XiCheng',
          },
        ],
      },
      {
        value: 'shanghai',
        label: 'Shanghai',
        children: [
          {
            value: 'shanghaishi',
            label: 'Shanghai',
            children: [
              {
                value: 'huangpu',
                label: 'Huangpu',
              },
            ],
          },
        ],
      },
    ]

    return {
      form,
      options,
      handleSubmit,
    }
  },
})
</script>
```

### Cross Field

- `model`: Form data object

Example source: src/form/__demos__/cross-field.vue

```vue
<script setup>
import ModelOutput from "../__demo-utils__/ModelOutput.vue";

import {
  onBeforeUnmount,
  onDeactivated,
  reactive,
  ref,
  shallowRef,
  useId,
} from "vue";

const formRef = ref();
const id = useId();
const model = reactive({ source: "", confirmation: "" });
const result = ref("尚未提交");
const submissions = ref(0);
const snapshot = ref("");
const message = "两次代码须相同且不能为空";
const sourceRules = [{ required: true, message: "请输入源代码" }];
const paused = ref(false);
const pending = shallowRef([]);
let epoch = 0;
function complete() {
  const [resolve, ...rest] = pending.value;
  pending.value = rest;
  resolve?.();
}
function cleanup() {
  epoch++;
  const tasks = pending.value;
  pending.value = [];
  tasks.forEach((resolve) => resolve());
}
onBeforeUnmount(cleanup);
onDeactivated(cleanup);
const confirmationRules = [
  {
    validator: async (value, callback) => {
      if (paused.value)
        await new Promise((resolve) => {
          pending.value = [...pending.value, resolve];
        });
      if (!value || value !== model.source) callback(message);
    },
  },
];
function submitted({ errors, values }) {
  submissions.value++;
  result.value = errors ? "未通过" : "通过";
  snapshot.value = JSON.stringify(values);
}
async function validateConfirmation() {
  const current = ++epoch;
  const errors = await formRef.value?.validateField("confirmation");
  if (current === epoch) result.value = errors ? "确认值未通过" : "确认值通过";
}
function reset() {
  cleanup();
  result.value = "已重置";
  snapshot.value = "";
}
</script>

<template>
  <section class="cross-field-form-demo">
    <p>
      仅使用本地合成代码。校验时确认值比较当前源代码；修改源代码不自动复验依赖字段。
    </p>
    <c-form ref="formRef" :model="model" @submit="submitted" @reset="reset">
      <c-form-item
        field="source"
        label="源代码"
        :label-attrs="{ for: id + '-source' }"
        :rules="sourceRules"
        :validate-trigger="[]"
        feedback
      >
        <c-input :id="id + '-source'" v-model="model.source" />
      </c-form-item>
      <c-form-item
        field="confirmation"
        label="确认代码"
        :label-attrs="{ for: id + '-confirmation' }"
        :rules="confirmationRules"
        :validate-trigger="[]"
        feedback
      >
        <c-input :id="id + '-confirmation'" v-model="model.confirmation" />
      </c-form-item>
      <c-space wrap>
        <c-button html-type="submit">提交代码</c-button>
        <c-button @click="validateConfirmation">只校验确认值</c-button>
        <c-button html-type="reset">重置代码</c-button>
      </c-space>
    </c-form>
    <p role="status">结果：{{ result }}；提交次数：{{ submissions }}</p>
    <c-button
      html-type="button"
      :aria-pressed="paused"
      @click="paused = !paused"
      >暂停跨字段校验</c-button
    >
    <c-button html-type="button" :disabled="!pending.length" @click="complete"
      >返回跨字段结果</c-button
    >
    <p class="cross-field-pending">等待：{{ pending.length }}</p>
    <ModelOutput>模型：{{ model }}</ModelOutput>
    <ModelOutput>上次提交值：{{ snapshot || "-" }}</ModelOutput>
  </section>
</template>
```

### Clear Trigger

- `model`: Form data object
- `layout`: The layout of the form, including horizontal, vertical, and multi-column

Example source: src/form/__demos__/clear-trigger.vue

```vue
<script setup lang="ts">
import { reactive, ref } from 'vue'

const model = reactive({ keyword: 'Cedar' })
const formRef = ref()
</script>

<template>
  <c-form ref="formRef" :model="model" layout="vertical" style="max-width: 360px">
    <c-form-item field="keyword" label="关键词" :rules="[{ required: true, message: '请输入关键词' }]" validate-trigger="clear">
      <c-input v-model="model.keyword" clearable placeholder="清空后立即校验" />
    </c-form-item>
    <c-button @click="formRef?.resetFields()">重置</c-button>
  </c-form>
</template>
```

### Empty markers and required validation

The API uses -1 for no selection. Validate the initial value to see a required error, choose a department and validate successfully, then clear to -1 and validate again. Form provides recognition settings; the field defines clear output. Custom validators still receive the original value.

Example source: src/form/__demos__/en-US/empty-values-validation.vue

```vue
<script setup lang="ts">
import { reactive, ref } from "vue";
const model = reactive({ department: -1 as number | null | undefined });
const form = ref();
const result = ref("Not validated");
const options = [
  { value: 1, label: "Engineering" },
  { value: 2, label: "Product" },
];
async function validate() {
  const errors = await form.value.validate();
  result.value = errors ? "Required error" : "Valid";
}
</script>
<template>
  <c-space direction="column">
    <p>
      Validate the initial -1, then select a department and validate again.
      Clearing restores -1.
    </p>
    <c-form
      ref="form"
      :model="model"
      layout="vertical"
      :empty-values="[null, undefined, -1]"
    >
      <c-form-item field="department" label="Department" required>
        <c-select
          v-model="model.department"
          :options="options"
          edit-mode="direct"
          clearable
          :empty-value="-1"
        />
      </c-form-item>
    </c-form>
    <c-button @click="validate">Validate</c-button>
    <p role="status">{{ result }}</p>
    <p>
      Current model: <output>{{ String(model.department) }}</output>
    </p>
  </c-space>
</template>
```

### Feedback

Preview configuration: `placeholder="please enter your username..."`.

Example source: src/form/__demos__/feedback.vue

```vue
<template>
  <c-form :style="{ width: '600px' }">
    <c-form-item field="name" label="Username" validate-status="success" feedback>
      <c-input placeholder="please enter your username..." />
    </c-form-item>
  </c-form>
</template>
<script lang="ts">
import { defineComponent } from 'vue'
export default defineComponent({
  })
</script>
```

## Field presentation and interaction

### State Lab

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration     | Purpose                                                                                                                            | Related examples                                         |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
| `layout`          | The layout of the form, including horizontal, vertical, and multi-column                                                           | State Lab, Presentation Status, Platform Presentation    |
| `model`           | Form data object                                                                                                                   | Field Presentation, Platform Presentation, Scroll Assign |
| `disabled`        | Whether to disable the form                                                                                                        | State Lab                                                |
| `readonly`        | Whether form controls are readonly                                                                                                 | State Lab                                                |
| `scroll-to-error` | After failed validation, scroll to the first (start) or last (end) invalid field in document order; this is not viewport alignment | Scroll Assign                                            |

<!-- demo-config-notes:end -->

- `layout`: The layout of the form, including horizontal, vertical, and multi-column

Example source: src/form/__demos__/state-lab.vue

```vue
<script setup lang="ts">
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
import type { FormItemValidateStatus } from "@cedar-design/ui";
const status = ref<FormItemValidateStatus>("warning");
const __demoState = __demoReactive({ disabled: false, readonly: false });
</script>
<template>
  <c-space direction="column" :size="16">
    <c-space wrap>
      <c-checkbox v-model="__demoState['disabled']">disabled</c-checkbox>
      <c-checkbox v-model="__demoState['readonly']">readonly</c-checkbox>
    </c-space>
    <c-form layout="vertical" v-bind="__demoState">
      <c-form-item
        label="展示状态"
        feedback
        :validate-status="status"
        help="显式状态只控制外观，不改变实际校验结果。"
      >
        <c-input placeholder="切换上方状态" />
      </c-form-item>
    </c-form>
  </c-space>
</template>
<style scoped>
.status-demo {
  display: flex;
  flex-direction: column;
  gap: 16px;
}
</style>
```

### Field Presentation

- `model`: Form data object

Example source: src/form/__demos__/field-presentation.vue

```vue
<script setup>
import ModelOutput from "../__demo-utils__/ModelOutput.vue";

import { computed, ref } from "vue";

const editMode = ref("direct");
const readPretty = ref(false);

const options = ref([
  { value: 1, label: "研发设备" },
  { value: 2, label: "设计设备" },
  { value: 3, label: "运营设备" },
]);
const form = ref({
  name: "默认可直接编辑",
  deviceIds: [2],
  note: "此项始终直接编辑",
  summary: "只读展示",
});
const status = ref("");

const modeOptions = ["direct", "click", "dblclick"].map((value) => ({
  label: value,
  value,
}));
const committed = computed(() => JSON.stringify(form.value));
const presentationHint = computed(() =>
  readPretty.value
    ? "只展示已保存的值；下方“单项覆盖 direct”通过 readPretty=false 保持可编辑。"
    : editMode.value === "direct"
      ? "直接编辑，即时更新下方模型；选择设备无需额外确认。"
      : "按展示方式进入编辑；确认才更新下方模型，取消不保存本次修改。",
);
</script>
<template>
  <c-space direction="column" align="stretch" :size="16">
    <c-form-item layout="vertical" size="sm" label="Form 展示方式">
      <c-radio-group
        aria-label="Form 展示方式"
        v-model="editMode"
        :options="modeOptions"
        variant="button"
        size="sm"
      />
    </c-form-item>
    <c-space wrap>
      <c-checkbox v-model="readPretty">纯阅读 readPretty</c-checkbox>
    </c-space>
    <p>
      {{ presentationHint }}<br />设备 4 已停用，最多选择 3
      个设备；可切换本地搜索与模拟远程搜索。
    </p>
    <c-form
      :model="form"
      :edit-mode="editMode"
      :read-pretty="readPretty"
      @submit-success="status = '表单已提交'"
      @submit-failed="status = '请完成当前编辑或修正校验错误'"
    >
      <c-form-item
        field="name"
        label="名称"
        :rules="[{ required: true, message: '名称不能为空' }]"
      >
        <c-input v-model="form.name" placeholder="请输入名称" clearable />
      </c-form-item>
      <c-form-item
        field="deviceIds"
        label="设备"
        :rules="[{ type: 'array', required: true, message: '请选择设备' }]"
      >
        <c-select
          v-model="form.deviceIds"
          :options="options"
          multiple
          filterable
          :limit="3"
          placeholder="搜索设备"
        />
      </c-form-item>
      <c-form-item
        field="note"
        label="单项覆盖 direct"
        edit-mode="direct"
        :read-pretty="false"
      >
        <c-input v-model="form.note" />
      </c-form-item>
      <c-form-item field="summary" label="固定 readPretty" read-pretty>
        <c-input v-model="form.summary" />
      </c-form-item>
      <c-button html-type="submit">提交表单</c-button>
    </c-form>
    <ModelOutput role="status">当前模型：{{ committed }}</ModelOutput>
    <p v-if="status" role="status">{{ status }}</p>
  </c-space>
</template>
```

### Reading placeholders and inheritance

Initially in reading mode, Name inherits Form’s default “-”, Code uses the FormItem override, Nickname uses the field override, and Quantity remains 0. Changing Form text only affects inheriting fields. Toggling reading/editing does not rewrite the model. Precedence is Field > FormItem > Form; custom read slots win.

Example source: src/form/__demos__/en-US/empty-text.vue

```vue
<script setup lang="ts">
import { reactive, ref } from "vue";
const reading = ref(true);
const emptyText = ref("-");
const model = reactive({
  name: null as string | null,
  code: null as string | null,
  nickname: null as string | null,
  quantity: 0 as number | null | undefined,
});
</script>
<template>
  <c-space direction="column">
    <p>
      Initially, reading mode shows “-” for Name, overrides for Code and
      Nickname, and the valid number 0 for Quantity.
    </p>
    <c-space wrap>
      <c-button @click="reading = !reading">Toggle reading/editing</c-button>
      <c-button @click="emptyText = 'No data'">Use “No data”</c-button>
      <c-button @click="emptyText = '-'">Use default “-”</c-button>
    </c-space>
    <c-form
      :model="model"
      layout="vertical"
      :read-pretty="reading"
      :empty-text="emptyText"
    >
      <c-form-item field="name" label="Name: inherits Form"
        ><c-input v-model="model.name"
      /></c-form-item>
      <c-form-item
        field="code"
        label="Code: FormItem override"
        empty-text="Unassigned"
        ><c-input v-model="model.code"
      /></c-form-item>
      <c-form-item
        field="nickname"
        label="Nickname: field override"
        empty-text="Unassigned"
        ><c-input v-model="model.nickname" empty-text="Anonymous"
      /></c-form-item>
      <c-form-item field="quantity" label="Quantity"
        ><c-input-number v-model="model.quantity"
      /></c-form-item>
    </c-form>
    <p>
      Current model: <output>{{ JSON.stringify(model) }}</output>
    </p>
  </c-space>
</template>
```

### Presentation Status

- `layout`: The layout of the form, including horizontal, vertical, and multi-column

Example source: src/form/__demos__/presentation-status.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
import type { FormItemValidateStatus } from '@cedar-design/ui'
const status = ref<FormItemValidateStatus>('warning')
const statuses: FormItemValidateStatus[] = ['success', 'warning', 'error', 'validating']
</script>

<template>
  <div class="status-demo">
    <c-space wrap>
      <c-button v-for="item in statuses" :key="item" @click="status = item">{{ item }}</c-button>
    </c-space>
    <c-form layout="vertical">
      <c-form-item label="展示状态" feedback :validate-status="status" help="显式状态只控制外观，不改变实际校验结果。">
        <c-input placeholder="切换上方状态" />
      </c-form-item>
    </c-form>
  </div>
</template>

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

### Platform Presentation

- `model`: Form data object
- `layout`: The layout of the form, including horizontal, vertical, and multi-column

Example source: src/form/__demos__/platform-presentation.vue

```vue
<script setup>
import { computed, ref } from "vue";
const initialModel = () => ({
  title: "设备巡检",
  department: "design",
  date: undefined,
  time: undefined,
});
const model = ref(initialModel());
const departments = [
  { value: "dev", label: "研发部" },
  { value: "design", label: "设计部" },
  { value: "ops", label: "运营部" },
];
const committed = computed(() =>
  JSON.stringify({
    title: model.value.title,
    department: model.value.department,
    date: model.value.date ?? null,
    time: model.value.time ?? null,
  }),
);
function reset() {
  model.value = initialModel();
}
</script>
<template>
  <c-space direction="column" class="platform-presentation-demo">
    <p>桌面字段在当前位置展开面板；选择后观察已提交模型。</p>
    <c-form :model="model" layout="vertical">
      <c-form-item label="任务名称" field="title"
        ><c-input
          v-model="model.title"
          edit-mode="direct"
          placeholder="输入任务名称"
      /></c-form-item>
      <c-form-item label="负责部门" field="department"
        ><c-select
          v-model="model.department"
          :options="departments"
          edit-mode="direct"
          placeholder="选择部门"
      /></c-form-item>
      <c-form-item label="执行日期" field="date"
        ><c-date v-model="model.date" edit-mode="direct" placeholder="选择日期"
      /></c-form-item>
      <c-form-item label="执行时间" field="time"
        ><c-time v-model="model.time" edit-mode="direct" placeholder="选择时间"
      /></c-form-item>
    </c-form>
    <div class="platform-presentation-demo__model">
      <strong>已提交模型</strong
      ><output aria-label="已提交模型" role="status">{{ committed }}</output>
    </div>
    <c-button @click="reset">重置本例</c-button>
  </c-space>
</template>
<style scoped>
.platform-presentation-demo {
  width: 100%;
  min-width: 0;
}
.platform-presentation-demo__model {
  width: 100%;
  padding: 12px;
  border-radius: 8px;
  background: var(--c-color-fill-1);
  color: var(--c-color-text-1);
}
.platform-presentation-demo__model output {
  display: block;
  margin-top: 8px;
  overflow-wrap: anywhere;
  font-size: 12px;
}
</style>
```

### Field Panel Actions

Preview configuration: `default-value="2026-10-20 09:30:00"`, `show-time`, `:disable-confirm="false"`.

Example source: src/form/__demos__/field-panel-actions.vue

```vue
<template>
  <c-space direction="column" :size="16">
    <c-date-picker
      default-value="2026-10-20 09:30:00"
      show-time
      :disable-confirm="false"
    />
    <c-date-picker
      default-value="2026-10-20 09:30:00"
      show-time
      :disable-confirm="false"
    >
      <template #actions="{ selectNow, nowDisabled, confirm, disabled }">
        <c-button variant="text" :disabled="nowDisabled" @click="selectNow"
          >此刻</c-button
        >
        <c-button :disabled="disabled" @click="confirm">完成</c-button>
      </template>
    </c-date-picker>
  </c-space>
</template>
```

### Scroll Assign

- `model`: Form data object
- `scroll-to-error`: Scroll to the first (start) or last (end) invalid field; omitted disables scrolling

Example source: src/form/__demos__/scroll-assign.vue

```vue
<template>
  <c-space>
    <c-button @click="formRef && formRef.validate()">Submit</c-button>
    <c-button @click="formRef && formRef.resetFields()">Reset</c-button>
    <c-button @click="formRef && formRef.scrollToField('name19')">Scroll to the last field</c-button>
  </c-space>
  <c-form
    ref="formRef"
    style="width: 500px; height: 300px; margin-top: 20px; padding-right: 16px; overflow: auto"
    :model="form"
    scroll-to-error="start"
  >
    <template v-for="(fieldName, index) in fieldNames" :key="index">
      <c-form-item :field="fieldName" :label="'user' + index" :rules="[{ required: true, message: 'Name is required' }]">
        <c-input v-model="form[fieldName]" />
      </c-form-item>
    </template>
  </c-form>
</template>
<script lang="ts">
import { reactive, ref, defineComponent } from 'vue'
export default defineComponent({
  setup() {
    const formRef = ref<FormInstance>()
    const fieldCount = 20
    const fieldNames = Array.from({ length: fieldCount }, (_, index) => `name${index}`)
    const form = reactive(
      Object.fromEntries(fieldNames.map((fieldName, index) => [fieldName, index === 7 ? '' : index.toString()])),
    )

    return {
      form,
      formRef,
      fieldCount,
      fieldNames,
    }
  },
})
</script>
```

## Dynamic and async fields

### Dynamic Form

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration | Purpose                            | Related examples                                |
| ------------- | ---------------------------------- | ----------------------------------------------- |
| `model`       | Form data object                   | Dynamic Form, Async Validate Form, Async Fields |
| `disabled`    | Whether to disable the form        | Presentation State, Async Race                  |
| `readonly`    | Whether form controls are readonly | Presentation State, Async Race                  |
| `rules`       | Form item validation rules         | Presentation State                              |

<!-- demo-config-notes:end -->

- `model`: Form data object

Example source: src/form/__demos__/dynamic-form.vue

```vue
<template>
  <c-form :model="form" :style="{ width: '600px' }">
    <c-form-item field="name" label="Username">
      <c-input v-model="form.name" placeholder="please enter your username..." />
    </c-form-item>
    <c-form-item
      v-for="(post, index) of form.posts"
      :field="`posts[${index}].value`"
      :label="`Post-${index}`"
      :key="index"
    >
      <c-input v-model="post.value" placeholder="please enter your post..." />
      <c-button @click="handleDelete(index)" :style="{ marginLeft: '10px' }">Delete</c-button>
    </c-form-item>
  </c-form>
  <div>
    <c-button @click="handleAdd">Add Post</c-button>
  </div>
  {{ form }}
</template>
<script lang="ts">
import { reactive, defineComponent } from 'vue'
export default defineComponent({
  setup() {
    const form = reactive({
      name: '',
      posts: [{ value: '' }],
    })
    const handleAdd = () => {
      form.posts.push({
        value: '',
      })
    }
    const handleDelete = (index) => {
      form.posts.splice(index, 1)
    }

    return {
      form,
      handleAdd,
      handleDelete,
    }
  },
})
</script>
```

### Async Validate Form

- `model`: Form data object

Example source: src/form/__demos__/async-validate-form.vue

```vue
<template>
  <section class="async-form-demo" @submit.capture="beginSubmit">
    <p>本地模拟异步校验：用户名只能是 admin，延迟 600ms，不访问外部接口。</p>
    <c-form
      ref="formRef"
      :model="form"
      @submit="handleSubmit"
      @reset="handleReset"
    >
      <c-form-item
        field="name"
        label="用户名"
        :label-attrs="{ for: `${demoId}-name` }"
        :rules="rules"
        feedback
      >
        <c-input
          :id="`${demoId}-name`"
          v-model="form.name"
          placeholder="请输入 admin"
        />
      </c-form-item>
      <c-form-item
        field="post"
        label="岗位"
        :label-attrs="{ for: `${demoId}-post` }"
      >
        <c-input
          :id="`${demoId}-post`"
          v-model="form.post"
          placeholder="请输入岗位"
        />
      </c-form-item>
      <c-form-item field="isRead">
        <c-checkbox v-model="form.isRead">已阅读说明</c-checkbox>
      </c-form-item>
      <c-form-item>
        <c-space>
          <c-button html-type="submit" status="primary" :loading="submitting"
            >提交</c-button
          >
          <c-button html-type="reset">重置</c-button>
          <c-button @click="setStatus">模拟服务端错误</c-button>
        </c-space>
      </c-form-item>
    </c-form>
    <p role="status">提交结果：{{ result }}；活动校验：{{ pendingCount }}</p>
    <ModelOutput>{{ form }}</ModelOutput>
  </section>
</template>

<script setup lang="ts">
import ModelOutput from '../__demo-utils__/ModelOutput.vue'

import { onBeforeUnmount, onDeactivated, reactive, ref, useId } from "vue";
import type { FormInstance, FieldRule } from "@cedar-design/ui";

const formRef = ref<FormInstance>();
const demoId = useId();
const form = reactive({ name: "", post: "", isRead: false });
const result = ref("尚未提交");
const submitting = ref(false);
const pendingCount = ref(0);
const pending = new Map<ReturnType<typeof setTimeout>, () => void>();
let generation = 0;
let submittedGeneration = -1;
const rules: FieldRule[] = [
  {
    validator: (value, callback) =>
      new Promise<void>((resolve) => {
        const current = generation;
        const timer = setTimeout(() => {
          pending.delete(timer);
          pendingCount.value = pending.size;
          if (current === generation && value !== "admin")
            callback("用户名必须是 admin");
          resolve();
        }, 600);
        pending.set(timer, resolve);
        pendingCount.value = pending.size;
      }),
  },
];

function beginSubmit() {
  submittedGeneration = generation;
  submitting.value = true;
  result.value = "校验中";
}
function cancelPending() {
  generation++;
  pending.forEach((resolve, timer) => {
    clearTimeout(timer);
    resolve();
  });
  pending.clear();
  pendingCount.value = 0;
  submitting.value = false;
}
function handleSubmit({ errors }: { errors?: unknown }) {
  if (submittedGeneration !== generation) return;
  submitting.value = false;
  result.value = errors ? "未通过" : "通过";
}
function handleReset() {
  cancelPending();
  result.value = "已重置";
}
function setStatus() {
  formRef.value?.setFields({
    name: { status: "error", message: "模拟服务端用户名错误" },
    post: { status: "error", message: "模拟服务端岗位错误" },
  });
  result.value = "服务端错误已展示";
}
onBeforeUnmount(cancelPending);
onDeactivated(cancelPending);
</script>
```

### Async Fields

- `model`: Form data object

Example source: src/form/__demos__/async-fields.vue

```vue
<script setup>
import ModelOutput from "../__demo-utils__/ModelOutput.vue";

import {
  onBeforeUnmount,
  onDeactivated,
  reactive,
  ref,
  shallowRef,
  useId,
} from "vue";
const formRef = ref();
const id = useId();
const model = reactive({ name: "", code: "" });
const pending = shallowRef([]);
const submissions = ref(0);
const submittedResult = ref("-");
function submitted({ errors }) {
  submissions.value++;
  submittedResult.value = errors ? "未通过" : "通过";
}
const result = ref("尚未校验");
let run = 0;
function request(field, value) {
  return new Promise((resolve) => {
    pending.value = [...pending.value, { field, value, resolve }];
  });
}
function rules(field) {
  return [
    {
      validator: async (value, callback) => {
        const answer = await request(field, value);
        if (answer !== true) callback(answer);
      },
    },
  ];
}
const nameRules = rules("name");
const codeRules = rules("code");
async function validate() {
  const current = ++run;
  result.value = "校验中";
  const errors = await formRef.value?.validate();
  if (current === run) result.value = errors ? "未通过" : "通过";
}
function complete(field, latest = false) {
  const tasks = pending.value.filter((item) => item.field === field);
  const task = latest ? tasks.at(-1) : tasks[0];
  if (!task) return;
  pending.value = pending.value.filter((item) => item !== task);
  task.resolve(
    task.value === (field === "name" ? "admin" : "1234")
      ? true
      : field === "name"
        ? "用户名必须是 admin"
        : "代码必须是 1234",
  );
}
function reset() {
  run++;
  formRef.value?.resetFields();
  result.value = "已重置";
}
function clear() {
  run++;
  formRef.value?.clearValidate();
  result.value = "已清空";
}
function serverError() {
  run++;
  formRef.value?.setFields({
    name: { status: "error", message: "模拟服务端拒绝" },
  });
  result.value = "服务端错误";
}
function cleanup() {
  run++;
  const tasks = pending.value;
  pending.value = [];
  tasks.forEach((task) => task.resolve(true));
}
onBeforeUnmount(cleanup);
onDeactivated(cleanup);
</script>
<template>
  <section class="async-fields-form-demo">
    <p>
      两个独立本地 Promise 规则分别接受 admin 和
      1234；手动返回各字段，不访问网络。
    </p>
    <c-form ref="formRef" :model="model" @submit="submitted">
      <c-form-item
        field="name"
        label="用户名"
        :label-attrs="{ for: id + '-name' }"
        :rules="nameRules"
        :validate-trigger="[]"
        feedback
      >
        <c-input :id="id + '-name'" v-model="model.name" />
      </c-form-item>
      <c-form-item
        field="code"
        label="代码"
        :label-attrs="{ for: id + '-code' }"
        :rules="codeRules"
        :validate-trigger="[]"
        feedback
      >
        <c-input :id="id + '-code'" v-model="model.code" />
      </c-form-item>
      <c-button html-type="submit">原生异步提交</c-button>
    </c-form>
    <c-button html-type="button" @click="clear">清空校验</c-button>
    <c-button html-type="button" @click="serverError">写入服务端错误</c-button>
    <p class="async-submit-status">
      原生提交：{{ submissions }}；结果：{{ submittedResult }}
    </p>
    <c-space wrap>
      <c-button @click="validate">校验两个字段</c-button>
      <c-button
        :disabled="!pending.some((item) => item.field === 'name')"
        @click="complete('name')"
        >返回用户名结果</c-button
      >
      <c-button
        :disabled="!pending.some((item) => item.field === 'code')"
        @click="complete('code')"
        >返回代码结果</c-button
      >
      <c-button
        :disabled="!pending.some((item) => item.field === 'name')"
        @click="complete('name', true)"
        >返回最新用户名结果</c-button
      >
      <c-button
        :disabled="!pending.some((item) => item.field === 'code')"
        @click="complete('code', true)"
        >返回最新代码结果</c-button
      >
      <c-button @click="reset">重置两个字段</c-button>
    </c-space>
    <p role="status">
      结果：{{ result }}；用户名等待：{{
        pending.filter((item) => item.field === "name").length
      }}；代码等待：{{ pending.filter((item) => item.field === "code").length }}
    </p>
    <ModelOutput>{{ model }}</ModelOutput>
  </section>
</template>
```

### Presentation State

- `model`: Form data object
- `disabled`: Whether to disable the form
- `readonly`: Whether form controls are readonly
- `rules`: Form item validation rules

Example source: src/form/__demos__/presentation-state.vue

```vue
<script setup>
import ModelOutput from "../__demo-utils__/ModelOutput.vue";

import { computed, onBeforeUnmount, ref, shallowRef } from "vue";

const form = ref();
const editMode = ref("dblclick");
const disabled = ref(false);
const readonly = ref(false);
const model = ref({ title: "原名称", note: "原备注", department: "dev" });

const choices = [
  { value: "dev", label: "研发" },
  { value: "design", label: "设计" },
];

const check = (predicate) => [
  {
    validator: (value, callback) => {
      const result = predicate(value);
      callback(result === true ? undefined : result);
    },
  },
];
const rules = { title: check((value) => Boolean(value) || "名称必填") };

const scenario = ref("success");
const scenarios = [
  { value: "success", label: "保存成功" },
  { value: "failure", label: "保存失败，保留草稿" },
  { value: "reset", label: "等待期间重置表单" },
  { value: "disabled", label: "等待期间设为禁用" },
  { value: "readonly", label: "等待期间设为只读" },
];
const pending = shallowRef();
const result = ref("尚未保存");
const current = computed(() => JSON.stringify(model.value));
function save(value, { signal }) {
  return new Promise((resolve, reject) => {
    const timer = { id: undefined };
    let settled = false;
    const task = {
      value,
      finish(error, aborted = false) {
        if (settled) return;
        settled = true;
        clearTimeout(timer.id);
        signal.removeEventListener("abort", abort);
        if (pending.value === task) pending.value = undefined;
        result.value = aborted
          ? "保存已取消，旧结果不会提交"
          : error
            ? "保存失败，保留草稿"
            : "保存成功";
        if (error) reject(new Error("模拟保存失败，请重试"));
        else resolve(aborted ? false : undefined);
      },
    };
    const abort = () => task.finish(false, true);
    if (signal.aborted) {
      abort();
      return;
    }
    signal.addEventListener("abort", abort, { once: true });
    pending.value = task;
    result.value = "模拟保存中（1.2 秒）";
    timer.id = setTimeout(() => {
      if (scenario.value === "reset") form.value.resetFields();
      else if (scenario.value === "disabled") disabled.value = true;
      else if (scenario.value === "readonly") readonly.value = true;
      else task.finish(scenario.value === "failure");
    }, 1200);
  });
}
onBeforeUnmount(() => pending.value?.finish(false, true));
</script>
<template>
  <c-space direction="column" align="stretch" :size="16">
    <c-form-item layout="vertical" size="sm" label="异步保存场景">
      <c-radio-group
        v-model="scenario"
        aria-label="异步保存场景"
        :options="scenarios"
        variant="button"
        size="sm"
      />
    </c-form-item>
    <c-checkbox v-model="disabled">禁用状态示例</c-checkbox>
    <c-checkbox v-model="readonly">只读状态示例</c-checkbox>
    <p>
      编辑名称、备注或部门并保存，模拟等待 1.2
      秒。选择保存结果，或在等待时禁用、只读、重置，观察草稿是否提交。
    </p>
    <c-form
      ref="form"
      :model="model"
      :edit-mode="editMode"
      :disabled="disabled"
      :readonly="readonly"
      :rules="rules"
    >
      <c-form-item field="title" label="事务名称"
        ><c-input v-model="model.title" :before-commit="save"
      /></c-form-item>
      <c-form-item field="note" label="事务备注"
        ><c-textarea v-model="model.note" :before-commit="save"
      /></c-form-item>
      <c-form-item field="department" label="事务部门"
        ><c-select
          v-model="model.department"
          :options="choices"
          filterable
          :before-commit="save"
      /></c-form-item>
    </c-form>
    <c-space>
      <c-button @click="form.resetFields()">重置状态示例</c-button>
    </c-space>
    <p role="status" aria-label="事务保存状态">{{ result }}</p>
    <ModelOutput aria-label="事务当前模型">{{ current }}</ModelOutput>
  </c-space>
</template>
```

### Async Race

- `model`: Form data object
- `disabled`: Whether to disable the form
- `readonly`: Whether form controls are readonly

Example source: src/form/__demos__/async-race.vue

```vue
<template>
  <section class="async-race-form-demo">
    <p>本地异步规则只接受 admin；手动返回最早或最新结果，不访问网络。</p>
    <c-form
      ref="formRef"
      :model="model"
      :disabled="disabled"
      :readonly="readonly"
    >
      <c-form-item
        v-if="mounted"
        field="name"
        label="用户名"
        :label-attrs="{ for: demoId }"
        :rules="rules"
        :validate-trigger="[]"
        feedback
      >
        <c-input :id="demoId" v-model="model.name" placeholder="请输入 admin" />
      </c-form-item>
    </c-form>
    <div class="async-race-controls">
      <c-checkbox v-model="disabled"> Disable async form</c-checkbox>
      <c-checkbox v-model="readonly"> Readonly async form</c-checkbox>
      <c-checkbox v-model="mounted"> Mount async field</c-checkbox>
    </div>
    <c-space wrap>
      <c-button :disabled="!mounted" @click="validate">校验字段</c-button>
      <c-button :disabled="!mounted" @click="validateAll">校验整表</c-button>
      <c-button :disabled="!pending.length" @click="complete(false)"
        >返回最早结果</c-button
      >
      <c-button :disabled="!pending.length" @click="complete(true)"
        >返回最新结果</c-button
      >
      <c-button :disabled="!mounted" @click="serverError"
        >写入服务端错误</c-button
      >
      <c-button @click="clear">清空校验</c-button>
      <c-button @click="reset">重置</c-button>
    </c-space>
    <p role="status">校验结果：{{ result }}；等待结果：{{ pending.length }}</p>
    <p>本次校验值：{{ checkedValue || "空" }}</p>
    <ModelOutput>{{ model }}</ModelOutput>
  </section>
</template>
<script setup lang="ts">
import ModelOutput from "../__demo-utils__/ModelOutput.vue";

import {
  onBeforeUnmount,
  onDeactivated,
  reactive,
  ref,
  shallowRef,
  useId,
} from "vue";
import type { FormInstance, FieldRule } from "@cedar-design/ui";

interface Pending {
  value: unknown;
  resolve: (result: true | string) => void;
}
const demoId = useId();
const disabled = ref(false);
const readonly = ref(false);
const mounted = ref(true);
const formRef = ref<FormInstance>();
const model = reactive({ name: "" });
const pending = shallowRef<Pending[]>([]);
const result = ref("尚未校验");
const checkedValue = ref("");
let run = 0;

function request(value: unknown) {
  return new Promise<true | string>((resolve) => {
    pending.value = [...pending.value, { value, resolve }];
  });
}
const rules: FieldRule[] = [
  {
    validator: async (value, callback) => {
      const answer = await request(value);
      if (answer !== true) callback(answer);
    },
  },
];

function validate() {
  return validateScope(false);
}
function validateAll() {
  return validateScope(true);
}
async function validateScope(all: boolean) {
  const current = ++run;
  checkedValue.value = model.name;
  result.value = "校验中";
  const errors = await (all
    ? formRef.value?.validate()
    : formRef.value?.validateField("name"));
  if (current === run) result.value = errors ? "未通过" : "通过";
}
function complete(latest: boolean) {
  const task = latest ? pending.value.at(-1) : pending.value[0];
  if (!task) return;
  pending.value = pending.value.filter((item) => item !== task);
  task.resolve(task.value === "admin" ? true : "用户名必须是 admin");
}
function clear() {
  run++;
  formRef.value?.clearValidate();
  result.value = "已清空";
}
function serverError() {
  run++;
  formRef.value?.setFields({
    name: { status: "error", message: "模拟服务端拒绝" },
  });
  result.value = "服务端错误";
}
function reset() {
  run++;
  formRef.value?.resetFields();
  checkedValue.value = "";
  result.value = "已重置";
}
function cleanup() {
  run++;
  result.value = "已取消";
  const tasks = pending.value;
  pending.value = [];
  tasks.forEach((task) => task.resolve(true));
}
onBeforeUnmount(cleanup);
onDeactivated(cleanup);
</script>

<style scoped>
.async-race-controls {
  display: flex;
  flex-wrap: wrap;
  gap: 12px;
}
.async-race-controls label {
  display: inline-flex;
  align-items: center;
  gap: 4px;
}
</style>
```

### Field Range Boundaries

- `model`: Form data object

Example source: src/form/__demos__/field-range-boundaries.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import ModelOutput from "../__demo-utils__/ModelOutput.vue";
const model = ref<{
  days: [string, string];
  months: [string, string];
  years: [string, string];
}>({
  days: ["2026-12-29", "2027-01-03"],
  months: ["2026-11", "2027-02"],
  years: ["2098", "2102"],
});
const disabledDay = (date: Date) =>
  date.getFullYear() === 2027 && date.getMonth() === 0 && date.getDate() === 1;
const disabledMonth = (date: Date) =>
  date.getFullYear() === 2026 && date.getMonth() === 11;
const disabledYear = (date: Date) => date.getFullYear() === 2100;
</script>
<template>
  <c-space direction="column" :size="16">
    <c-form :model="model">
      <c-form-item field="days" label="跨月日期"
        ><c-date-range
          v-model="model.days"
          value-format="YYYY-MM-DD"
          :disabled-date="disabledDay"
      /></c-form-item>
      <c-form-item field="months" label="跨年月份"
        ><c-date-range
          v-model="model.months"
          type="month"
          value-format="YYYY-MM"
          :disabled-date="disabledMonth"
      /></c-form-item>
      <c-form-item field="years" label="跨页年份"
        ><c-date-range
          v-model="model.years"
          type="year"
          value-format="YYYY"
          :disabled-date="disabledYear"
      /></c-form-item>
    </c-form>
    <ModelOutput>{{ JSON.stringify(model, null, 2) }}</ModelOutput>
  </c-space>
</template>
```

## Business workflows

### Task Workflow

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration | Purpose                                                                  | Related examples |
| ------------- | ------------------------------------------------------------------------ | ---------------- |
| `model`       | Form data object                                                         | Task Workflow    |
| `layout`      | The layout of the form, including horizontal, vertical, and multi-column | Task Workflow    |

<!-- demo-config-notes:end -->

- `model`: Form data object
- `layout`: The layout of the form, including horizontal, vertical, and multi-column

Example source: src/form/__demos__/task-workflow.vue

```vue
<script setup>
import { computed, onBeforeUnmount, onDeactivated, ref } from "vue";
const fresh = () => ({ title: "", department: "ops", priority: "normal" });
const draft = ref(fresh());
const saved = ref(null);
const stage = ref("edit");
const message = ref("填写任务后进入确认；也可以直接提交空表单查看校验。");
const busy = ref(false);
const failNext = ref(false);
const formRef = ref();
const rules = [{ required: true, whitespace: true, message: "请输入任务名称" }];
const departments = [
  { value: "ops", label: "运营部" },
  { value: "dev", label: "研发部" },
  { value: "design", label: "设计部" },
];
const priorities = [
  { value: "normal", label: "普通" },
  { value: "urgent", label: "紧急" },
];
const departmentLabel = computed(
  () =>
    departments.find((item) => item.value === draft.value.department)?.label,
);
let timer;
let epoch = 0;
function cancelPending() {
  epoch++;
  clearTimeout(timer);
  busy.value = false;
}
onBeforeUnmount(cancelPending);
onDeactivated(cancelPending);
function review({ errors }) {
  if (errors) {
    message.value = "请补全必填项，任务尚未提交。";
    return;
  }
  stage.value = "review";
  message.value = "核对信息后确认提交；返回修改不会改变上次提交记录。";
}
function submit() {
  if (busy.value) return;
  const current = ++epoch;
  const snapshot = { ...draft.value };
  const shouldFail = failNext.value;
  failNext.value = false;
  busy.value = true;
  message.value = "正在本地模拟保存…";
  timer = setTimeout(() => {
    if (current !== epoch) return;
    busy.value = false;
    if (shouldFail) {
      message.value = "保存失败：草稿已保留，请点击“重试提交”。";
      return;
    }
    saved.value = snapshot;
    stage.value = "done";
    message.value = "提交成功，已生成任务记录。";
  }, 500);
}
function reset() {
  cancelPending();
  draft.value = fresh();
  saved.value = null;
  stage.value = "edit";
  failNext.value = false;
  message.value = "已重置，可以重新演示。";
  formRef.value?.clearValidate();
}
function fill() {
  draft.value = {
    title: "展厅设备巡检",
    department: "ops",
    priority: "urgent",
  };
  formRef.value?.clearValidate();
}
</script>
<template>
  <section class="workflow-demo" aria-label="巡检任务完整流程">
    <ol class="workflow-demo__steps" aria-label="任务流程">
      <li :aria-current="stage === 'edit' ? 'step' : undefined">
        01 填写与校验
      </li>
      <li :aria-current="stage === 'review' ? 'step' : undefined">
        02 核对与提交
      </li>
      <li :aria-current="stage === 'done' ? 'step' : undefined">
        03 结果与记录
      </li>
    </ol>
    <c-form
      v-if="stage === 'edit'"
      ref="formRef"
      :model="draft"
      layout="vertical"
      @submit="review"
    >
      <c-form-item label="任务名称" field="title" :rules="rules" feedback
        ><c-input
          v-model="draft.title"
          edit-mode="direct"
          placeholder="例如：展厅设备巡检"
      /></c-form-item>
      <c-form-item label="执行部门" field="department"
        ><c-select
          v-model="draft.department"
          :options="departments"
          edit-mode="direct"
      /></c-form-item>
      <c-form-item label="任务优先级" field="priority"
        ><c-select
          v-model="draft.priority"
          :options="priorities"
          edit-mode="direct"
      /></c-form-item>
      <c-space wrap
        ><c-button html-type="submit" status="primary">校验并预览</c-button
        ><c-button @click="fill">填入演示数据</c-button></c-space
      >
    </c-form>
    <div v-else-if="stage === 'review'">
      <h4>确认巡检任务</h4>
      <dl>
        <dt>任务</dt>
        <dd>{{ draft.title }}</dd>
        <dt>部门</dt>
        <dd>{{ departmentLabel }}</dd>
        <dt>优先级</dt>
        <dd>{{ draft.priority === "urgent" ? "紧急" : "普通" }}</dd>
      </dl>
      <c-checkbox v-model="failNext" :disabled="busy"
        >模拟下一次保存失败（本地）</c-checkbox
      >
      <c-space wrap
        ><c-button
          status="primary"
          :loading="busy"
          :disabled="busy"
          @click="submit"
          >{{
            message.includes("保存失败") ? "重试提交" : "确认提交"
          }}</c-button
        ><c-button :disabled="busy" @click="stage = 'edit'"
          >返回修改</c-button
        ></c-space
      >
    </div>
    <div v-else>
      <h4>任务已创建</h4>
      <p>
        {{ saved.title }} ·
        {{ saved.priority === "urgent" ? "紧急处理" : "普通处理" }}
      </p>
      <c-button @click="stage = 'edit'">继续编辑</c-button>
    </div>
    <p role="status" aria-live="polite">{{ message }}</p>
    <c-collapse>
      <c-collapse-item title="查看已提交记录" name="saved">
        <pre>{{
          saved
            ? JSON.stringify(saved, null, 2)
            : "尚无记录；校验失败、返回修改或保存失败都不会创建记录。"
        }}</pre>
      </c-collapse-item>
    </c-collapse>
    <c-button @click="reset">重新演示</c-button>
    <small
      >本例使用本地模拟保存，不访问业务服务。校验、确认、保存与失败恢复由业务流程组合。</small
    >
  </section>
</template>
<style scoped>
.workflow-demo {
  width: 100%;
  min-width: 0;
}
.workflow-demo__steps {
  display: flex;
  flex-wrap: wrap;
  gap: 12px;
  list-style: none;
  padding: 0;
}
.workflow-demo__steps li {
  padding: 8px 12px;
  border-radius: 8px;
  background: var(--c-color-fill-1);
}
.workflow-demo__steps [aria-current] {
  color: var(--c-color-primary);
  font-weight: 700;
}
.workflow-demo dl {
  display: grid;
  grid-template-columns: 80px 1fr;
  gap: 8px;
}
.workflow-demo dd {
  margin: 0;
  overflow-wrap: anywhere;
}
.workflow-demo pre {
  white-space: pre-wrap;
  overflow-wrap: anywhere;
}
.workflow-demo small {
  display: block;
  margin-top: 12px;
  color: var(--c-color-text-2);
}
</style>
```

## API

### Empty values and reading placeholders

Form / FormItem provide empty recognition through `empty-values`; each field defines clear output with its own `empty-value`. `empty-text` defaults to `'-'` under `read-pretty`, with Field > FormItem > Form precedence and custom read slots first. With explicit empty-values, built-in required uses the policy; custom validators receive original data. See the [shared guide](llms/en-US/guide/empty-values.md).

| Prop         | Type               | Default and scope                                                           |
| ------------ | ------------------ | --------------------------------------------------------------------------- |
| empty-values | readonly unknown[] | Field > FormItem > Form > component-family default; replaces the whole list |
| empty-text   | string             | Field > FormItem > Form > '-'; explicit '' is valid                         |

These props belong to field presentation; pure panels do not gain reading mode. Form and FormItem provide inherited settings. The existing empty-value type and clear fallback remain component-specific.

### `<Form>` Props

| Parameter         | Description                                                                                                                                    | Type                                       |        Default        |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | :-------------------: |
| model             | Form data object                                                                                                                               | `object`                                   |         `{}`          |
| layout            | The layout of the form, including horizontal, vertical, and multi-column                                                                       | `'horizontal' \| 'vertical' \| 'inline'`   |    `'horizontal'`     |
| size              | The size of the form                                                                                                                           | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'`     |        `'md'`         |
| label-col-flex    | Label-column flex; numbers are flex ratios, unit-bearing strings are widths                                                                    | `number \| string`                         |          `-`          |
| label-col-style   | Per-instance label column style                                                                                                                | `CSSProperties`                            |          `-`          |
| wrapper-col-style | Per-instance control column style                                                                                                              | `CSSProperties`                            |          `-`          |
| label-col-props   | Label layout options; same parameters as the col component                                                                                     | `object`                                   | `span: 5, offset: 0`  |
| wrapper-col-props | Form-control layout options; same parameters as the col component                                                                              | `object`                                   | `span: 19, offset: 0` |
| label-align       | Label alignment                                                                                                                                | `'start' \| 'end' \| 'left' \| 'right'`                        |       `'end'`       |
| `content-align`   | Content alignment shared by direct fields, editor triggers and readPretty output; independent of label-align                                   | `'start' \| 'end' \| 'left' \| 'center' \| 'right'`            |       `'start'`        |
| `read-pretty`     | Independent reading toggle. When true, displays the saved value; when false, restores the current edit-mode. FormItem inherits Form when unset | `boolean`                                  |          `-`          |
| `edit-mode`       | Shared editing mode for form fields; when unset, preserves each field default                                                                  | `'direct' \| 'click' \| 'dblclick'`        |          `-`          |
| disabled          | Whether to disable the form                                                                                                                    | `boolean`                                  |          `-`          |
| readonly          | Whether form controls are readonly                                                                                                             | `boolean`                                  |          `-`          |
| rules             | Form item validation rules                                                                                                                     | `Record<string, FieldRule \| FieldRule[]>` |          `-`          |
| auto-label-width  | Automatically measure label widths; only effective with `layout="horizontal"`                                                                  | `boolean`                                  |        `false`        |
| id                | Prefix for form-control ids                                                                                                                    | `string`                                   |          `-`          |
| scroll-to-error   | After failed validation, scroll to the first (start) or last (end) invalid field in document order; this is not viewport alignment             | `'start' \| 'end'`                         |     Do not scroll     |

### `<Form>` Events

| Event          | Description                                                            | Arguments                                                                                                 |
| -------------- | ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| submit         | Triggered when the form is submitted                                   | data: `{values: Record<string, any>; errors: Record<string, ValidatedError> \| undefined}`<br>ev: `Event` |
| submit-success | Emitted when validation succeeds                                       | values: `Record<string, any>`<br>ev: `Event`                                                              |
| submit-failed  | Emitted when validation fails                                          | data: `{values: Record<string, any>; errors: Record<string, ValidatedError>}`<br>ev: `Event`              |
| reset          | Emitted on native reset; also resets field values and validation state | ev: `Event`                                                                                               |

### `<form>` Methods

| Method        | Description                     | Arguments                                                                                                | Returns                                              |
| ------------- | ------------------------------- | -------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| validate      | Validate all form data          | callback: `(errors: undefined \| Record<string, ValidatedError>) => void`                                | Promise<undefined \| Record<string, ValidatedError>> |
| validateField | Validate selected form fields   | field: `string \| string[]`<br>callback: `(errors: undefined \| Record<string, ValidatedError>) => void` | Promise<undefined \| Record<string, ValidatedError>> |
| resetFields   | Reset form data                 | field: `string \| string[]`                                                                              | -                                                    |
| clearValidate | Clear validation state          | field: `string \| string[]`                                                                              | -                                                    |
| setFields     | Set form-item values and states | data: `Record<string, FieldData>`                                                                        | -                                                    |
| scrollToField | Scroll to a form item           | `field: string`                                                                                          | `-`                                                  |

### `<FormItem>` Props

Layout, label/content columns, styles, alignment and flex inherit from Form when omitted; explicit values override them.

| Parameter         | Description                                                                                                                                    | Type                                                  |       Default       |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | :-----------------: |
| field             | Field path in the data object; required for data fields                                                                                        | `string`                                              |        `''`         |
| label             | Label text                                                                                                                                     | `string`                                              |         `-`         |
| tooltip           | Hint content                                                                                                                                   | `string`                                              |         `-`         |
| show-colon        | Whether to show a colon                                                                                                                        | `boolean`                                             |       `false`       |
| no-style          | Whether to remove styling                                                                                                                      | `boolean`                                             |       `false`       |
| disabled          | Whether disabled                                                                                                                               | `boolean`                                             |         `-`         |
| readonly          | Readonly state; inherits from Form when omitted                                                                                                | `boolean`                                             |         `-`         |
| help              | Help text                                                                                                                                      | `string`                                              |         `-`         |
| extra             | Extra text                                                                                                                                     | `string`                                              |         `-`         |
| required          | Whether a value is required                                                                                                                    | `boolean`                                             |       `false`       |
| asterisk-position | Logical start/end position of the required asterisk within the field label, default start; not the form or popup position                      | `'start' \| 'end'`                                    |      `'start'`      |
| rules             | Field validation rules; take precedence over Form rules                                                                                        | `FieldRule \| FieldRule[]`                            |         `-`         |
| validate-status   | Validation state                                                                                                                               | `'success' \| 'warning' \| 'error' \| 'validating'`   |         `-`         |
| validate-trigger  | Events that trigger validation; `clear` is emitted only by a control `clear` action and is distinct from `change`                              | `'change' \| 'input' \| 'focus' \| 'blur' \| 'clear'` |     `'change'`      |
| size              | Control size; inherits from Form when omitted. Form layout still controls label appearance                                                     | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'`                |         `-`         |
| layout            | Form-item layout; inherits from Form when omitted                                                                                              | `'horizontal' \| 'vertical' \| 'inline'`              |         `-`         |
| label-align       | Label alignment; inherits from Form when omitted                                                                                               | `'start' \| 'end' \| 'left' \| 'right'`                                   |         `-`         |
| `content-align`   | Content alignment shared by direct fields, editor triggers and readPretty output; independent of label-align                                   | `'start' \| 'end' \| 'left' \| 'center' \| 'right'`                       | `-` (inherits Form) |
| `read-pretty`     | Independent reading toggle. When true, displays the saved value; when false, restores the current edit-mode. FormItem inherits Form when unset | `boolean`                                             |         `-`         |
| `edit-mode`       | Editing mode; inherits Form when unset and may be overridden by individual fields                                                              | `'direct' \| 'click' \| 'dblclick'`                   |         `-`         |
| label-col-props   | Label layout options; same parameters as the col component                                                                                     | `object`                                              |         `-`         |
| wrapper-col-props | Form-control layout options; same parameters as the col component                                                                              | `object`                                              |         `-`         |
| hide-label        | Hide label                                                                                                                                     | `boolean`                                             |       `false`       |
| hide-asterisk     | Whether to hide the required marker                                                                                                            | `boolean`                                             |       `false`       |
| label-col-style   | Style for the label layout component                                                                                                           | `object`                                              |         `-`         |
| wrapper-col-style | Style for the control layout component                                                                                                         | `object`                                              |         `-`         |
| row-props         | Form-item layout options; same parameters as the row component                                                                                 | `object`                                              |         `-`         |
| row-class         | Class for the form-item layout component                                                                                                       | `string\|array\|object`                               |         `-`         |
| content-class     | Class for the control wrapper                                                                                                                  | `string\|array\|object`                               |         `-`         |
| content-flex      | Whether the content wrapper uses flex layout                                                                                                   | `boolean`                                             |       `true`        |
| label-col-flex    | Sets flex on the label `Col` component; the control `Col` flex is then set to `auto`                                                           | `number\|string`                                      |         `-`         |
| feedback          | Whether to show control feedback icons                                                                                                         | `boolean`                                             |       `false`       |
| label-component   | Element used to render the form-item label                                                                                                     | `string`                                              |      `'label'`      |
| label-attrs       | Native label attributes; for targets the actual control id                                                                                     | `object`                                              |         `-`         |

### `<FormItem>` Slots

| Slot  |  Description  | Arguments |
| ----- | :-----------: | --------- |
| label |     Label     | -         |
| help  | Help content  | -         |
| extra | Extra content | -         |

## Type

### FieldRule

| Parameter | Description                                       | Type                                                                                                        | Default |
| --------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | :-----: |
| type      | Validated value type; defaults to `'string'`      | `'string'    \| 'number'    \| 'boolean'    \| 'array'    \| 'object'    \| 'email'    \| 'url'    \| 'ip'` |   `-`   |
| required  | Whether the value is required                     | `boolean`                                                                                                   | `false` |
| message   | Message displayed on validation failure           | `string`                                                                                                    |   `-`   |
| length    | Required length for string/array values           | `number`                                                                                                    |   `-`   |
| maxLength | Maximum string length                             | `number`                                                                                                    |   `-`   |
| minLength | Minimum string length                             | `number`                                                                                                    |   `-`   |
| match     | Pattern matching for strings                      | `RegExp`                                                                                                    |   `-`   |
| uppercase | Uppercase string validation                       | `boolean`                                                                                                   | `false` |
| lowercase | Lowercase string validation                       | `boolean`                                                                                                   | `false` |
| min       | Minimum numeric value                             | `number`                                                                                                    |   `-`   |
| max       | Maximum numeric value                             | `number`                                                                                                    |   `-`   |
| equal     | Numeric-value validation                          | `number`                                                                                                    |   `-`   |
| positive  | Positive-number validation                        | `boolean`                                                                                                   | `false` |
| negative  | Negative-number validation                        | `boolean`                                                                                                   | `false` |
| true      | Whether a boolean is `true`                       | `boolean`                                                                                                   | `false` |
| false     | Whether a boolean is `false`                      | `boolean`                                                                                                   | `false` |
| includes  | Whether an array contains the specified value     | `any[]`                                                                                                     |   `-`   |
| deepEqual | Whether array elements are equal                  | `any`                                                                                                       |   `-`   |
| empty     | Whether an object is empty                        | `boolean`                                                                                                   | `false` |
| hasKeys   | Whether an object contains the specified property | `string[]`                                                                                                  |   `-`   |
| validator | Custom validation rule                            | `(    value: FieldValue \| undefined,    callback: (error?: string) => void  ) => void`                     |   `-`   |

### FieldData

| Parameter | Description         | Type             | Default |
| --------- | ------------------- | ---------------- | :-----: |
| value     | Field value         | `any`            |   `-`   |
| status    | Field state         | `ValidateStatus` |   `-`   |
| message   | Field error message | `string`         |   `-`   |

### ValidatedError

| Parameter       | Description                              | Type      | Default |
| --------------- | ---------------------------------------- | --------- | :-----: |
| label           | Label text                               | `string`  |   `-`   |
| field           | Field name                               | `string`  |   `-`   |
| value           | Field value                              | `any`     |   `-`   |
| type            | Field type                               | `string`  |   `-`   |
| isRequiredError | Whether this is a `required`-field error | `boolean` | `false` |
| message         | Error message                            | `string`  |   `-`   |

### FormItemEventHandler

| Parameter | Description | Type                   | Default |
| --------- | ----------- | ---------------------- | :-----: |
| onChange  | onChange    | `(ev?: Event) => void` |   `-`   |
| onInput   | onInput     | `(ev?: Event) => void` |   `-`   |
| onFocus   | onFocus     | `(ev?: Event) => void` |   `-`   |
| onBlur    | onBlur      | `(ev?: Event) => void` |   `-`   |

### useFormItem

```ts
const useFormItem = (data: {
  size?: Ref<Size | undefined>;
  disabled?: Ref<boolean>;
  error?: Ref<boolean>;
}) => {
  mergedSize: Ref<Size>;
  mergedDisabled: Ref<boolean>;
  mergedError: Ref<boolean>;
  feedback: Ref<string>;
  eventHandlers: Ref<FormItemEventHandler>;
};
```

## Type definitions

The component exports the following types

```ts
import type { FormProps } from "@cedar-design/ui";
```

### Five density levels and item spacing

xs/sm/md/lg/xl select geometry through size classes. Item bottom spacing and reserved validation-message height both use size-*-item-margin-bottom. Inline layout uses inline-item-margin-bottom; error/help do not add item bottom spacing again.

| Variable                              | Default                     |
| ------------------------------------- | --------------------------- |
| `--c-form-size-xl-height`             | `var(--c-size-xl)`          |
| `--c-form-size-xl-label-font-size`    | `var(--c-sys-font-size-lg)` |
| `--c-form-size-xl-item-margin-bottom` | `var(--c-spacing-8)`        |

### edit-mode inheritance

Form supports `direct / click / dblclick`. When unset, each field retains its own default; FormItem and fields inherit explicitly configured ancestor values, and an explicit field value takes precedence. readPretty controls reading independently of readonly/disabled. Submitting the form fails while a confirmation editor remains unfinished, preserving its draft; reset cancels editing. Existing default slots and v-model are unchanged, and no editor slot is required.

`read-pretty` is an independent boolean alongside `readonly` and `disabled`. It inherits from field to FormItem to Form; explicit `false` overrides the parent. The default is `false`. Reading mode renders no editor.

---

Document: llms/en-US/components/grid.md

<!-- Source: src/grid/README.en-US.md; locale: en-US; page: /en/components/grid/ -->

# Grid

CSS Grid columns, spans, gaps, collapse and suffix items. Use Row / Col for 24-column Flex layouts.

> **Choosing a layout**
>
> - Grid + GridItem: Use for form columns and card grids with consistent column widths, spans, responsive column counts, or collapsed rows and suffix items.
> - Row + Col: Use for 24-column Flex layouts that need horizontal/vertical alignment, wrapping control, fixed and flexible widths together, or responsive ordering. Row controls the row; Col controls width, offset and order.
> - Space: Use for simple groups of buttons, tags or text that only need spacing, direction and alignment. Use native Flex for more flexible width allocation.

## Basic examples

### Columns, spans and offsets

Example source: src/grid/__demos__/basic.vue

```vue
<template><div>
  <c-grid :cols="4" :col-gap="12" :row-gap="12"><c-grid-item v-for="i in 8" :key="i" class="cell">{{ i }}</c-grid-item></c-grid>
  <c-grid :cols="4" :col-gap="12" :row-gap="12"><c-grid-item :span="2" class="cell">span 2</c-grid-item><c-grid-item :offset="1" class="cell soft">offset 1</c-grid-item><c-grid-item :span="4" class="cell">span 4</c-grid-item></c-grid>
</div></template>

<style scoped>
.controls { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; }
.cell { box-sizing: border-box; padding: 12px; min-width: 0; border-radius: 4px; background: var(--c-color-primary); color: var(--c-color-white); text-align: center; overflow-wrap: anywhere; }
.soft { opacity: .7; }
</style>
```

## Layout and arrangement

### Responsive columns, gaps and spans

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `cols` | Columns per row, minimum 1 | Responsive columns, gaps and spans |
| `col-gap` | Column gap in px | Responsive columns, gaps and spans |
| `row-gap` | Row gap in px | Responsive columns, gaps and spans |
<!-- demo-config-notes:end -->


Example source: src/grid/__demos__/responsive.vue

```vue
<template><div>
  <p>xs: 1 column · sm: 2 columns · md: 4 columns</p>
  <c-grid :cols="{ xs: 1, sm: 2, md: 4 }" :col-gap="{ xs: 8, md: 16 }" :row-gap="{ xs: 8, md: 16 }">
    <c-grid-item :span="{ xs: 1, md: 2 }" class="cell">Responsive span</c-grid-item><c-grid-item v-for="i in 6" :key="i" class="cell soft">{{ i }}</c-grid-item>
  </c-grid>
</div></template>

<style scoped>
.controls { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; }
.cell { box-sizing: border-box; padding: 12px; min-width: 0; border-radius: 4px; background: var(--c-color-primary); color: var(--c-color-white); text-align: center; overflow-wrap: anywhere; }
.soft { opacity: .7; }
</style>
```

## Customization and slots

### Collapsed rows and suffix slot

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `cols` | Columns per row, minimum 1 | Collapsed rows and suffix slot |
| `col-gap` | Column gap in px | Collapsed rows and suffix slot |
| `row-gap` | Row gap in px | Collapsed rows and suffix slot |
| `collapsed` | Collapse overflowing rows | Collapsed rows and suffix slot |
| `collapsed-rows` | Visible rows while collapsed, minimum 1 | Collapsed rows and suffix slot |
<!-- demo-config-notes:end -->


Example source: src/grid/__demos__/collapse.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const collapsed = ref(true)
const rows = ref(1)
</script>
<template><div>
  <div class="controls"><c-switch v-model="collapsed" aria-label="Collapsed" />Collapsed<c-radio-group v-model="rows"><c-radio :value="1">1 row</c-radio><c-radio :value="2">2 rows</c-radio></c-radio-group></div>
  <c-grid :cols="4" :col-gap="12" :row-gap="12" :collapsed="collapsed" :collapsed-rows="rows">
    <c-grid-item v-for="i in 9" :key="i" class="cell">{{ i }}</c-grid-item>
    <c-grid-item suffix v-slot="{ overflow }"><c-button block variant="outline" @click="collapsed = !collapsed">{{ overflow ? 'More' : 'Less' }}</c-button></c-grid-item>
  </c-grid>
</div></template>

<style scoped>
.controls { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; }
.cell { box-sizing: border-box; padding: 12px; min-width: 0; border-radius: 4px; background: var(--c-color-primary); color: var(--c-color-white); text-align: center; overflow-wrap: anywhere; }
.soft { opacity: .7; }
</style>
```

## Interaction and control

### Insert, remove and reorder

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `cols` | Columns per row, minimum 1 | Insert, remove and reorder |
| `col-gap` | Column gap in px | Insert, remove and reorder |
| `row-gap` | Row gap in px | Insert, remove and reorder |
| `collapsed` | Collapse overflowing rows | Insert, remove and reorder |
<!-- demo-config-notes:end -->


Example source: src/grid/__demos__/dynamic.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const items = ref([1, 2, 3, 4, 5])
let next = 6
</script>
<template><div>
  <div class="controls"><c-button @click="items.unshift(next++)">Insert first</c-button><c-button :disabled="!items.length" @click="items.shift()">Remove first</c-button><c-button @click="items.reverse()">Reverse</c-button></div>
  <c-grid :cols="3" :col-gap="12" :row-gap="12" collapsed><c-grid-item v-for="i in items" :key="i" class="cell">{{ i }}</c-grid-item><c-grid-item suffix v-slot="{ overflow }" class="cell soft">{{ overflow ? '…' : 'End' }}</c-grid-item></c-grid>
</div></template>

<style scoped>
.controls { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; }
.cell { box-sizing: border-box; padding: 12px; min-width: 0; border-radius: 4px; background: var(--c-color-primary); color: var(--c-color-white); text-align: center; overflow-wrap: anywhere; }
.soft { opacity: .7; }
</style>
```

<!-- same-source-api:start -->

### Props

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| cols | Columns per row, minimum 1 | `number / ResponsiveValue` | `24` |
| row-gap | Row gap in px | `number / ResponsiveValue` | `0` |
| col-gap | Column gap in px | `number / ResponsiveValue` | `0` |
| collapsed | Collapse overflowing rows | `boolean` | `false` |
| collapsed-rows | Visible rows while collapsed, minimum 1 | `number` | `1` |

### Events

| Event | Description |
| --- | --- |

### Slots

| Slot | Description |
| --- | --- |
| default | Layout content |

### Methods

| Method | Description |
| --- | --- |
<!-- same-source-api:end -->

## API

<!-- same-source-api:start -->
### Props

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| cols | Columns per row, minimum 1 | `number / ResponsiveValue` | `24` |
| row-gap | Row gap in px | `number / ResponsiveValue` | `0` |
| col-gap | Column gap in px | `number / ResponsiveValue` | `0` |
| collapsed | Collapse overflowing rows | `boolean` | `false` |
| collapsed-rows | Visible rows while collapsed, minimum 1 | `number` | `1` |

### Events

| Event | Description |
| --- | --- |

### Slots

| Slot | Description |
| --- | --- |
| default | Layout content |

### Methods

| Method | Description |
| --- | --- |
<!-- same-source-api:end -->

## Responsiveness and accessibility

Breakpoints use the browser viewport: xs is the base; sm ≥576, md ≥768, lg ≥992, xl ≥1200 and xxl ≥1600px. Configured values resolve downward from the largest matching breakpoint. SSR starts with xs and responds to the viewport after mounting. Grid collapsing and dynamic ordering are calculated after mounting. These layout containers add no keyboard shortcuts; callers supply content semantics and focusable elements. There are no public methods or dedicated theme tokens.

## GridItem

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| span | Grid span | number / ResponsiveValue | 1 |
| offset | Empty tracks before the item | number / ResponsiveValue | 0 |
| suffix | Suffix at the end of the row | boolean | false |

The default slot receives `{ overflow: boolean }`, indicating whether collapsing hides content. No custom events or public methods.

## Imports

Grid contains only Grid.Item. Row and Col are independent components with their own source, styles, navigation, documentation and demos. Grid.Row/Grid.Col, Row/Col re-exports from Grid and GridRowInstance/GridColInstance are removed. Import them from the library root or separate row/col entries. Installing Grid no longer registers Row/Col automatically.

---

Document: llms/en-US/components/hover.md

<!-- Source: src/hover/README.en-US.md; locale: en-US; page: /en/components/hover/ -->

# Hover

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

Preview configuration: `:hovering="hovering"`, `:focusing="focusing"`.

Example source: src/hover/__demos__/basic.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { Hover, useHoverOverlay } from '@cedar-design/ui'
import '@cedar-design/ui/hover/style'

const vHover = Hover
const { hovering, handleHovering } = useHoverOverlay()
const focusing = ref(false)
</script>

<template>
  <c-space direction="column">
    <c-button v-hover="handleHovering" class="hover-example-target" @focus="focusing = true" @blur="focusing = false">
      将鼠标移入，或用 Tab 聚焦
      <c-hover-overlay :hovering="hovering" :focusing="focusing" />
    </c-button>
    <span role="status">悬停：{{ hovering ? '是' : '否' }}；焦点：{{ focusing ? '是' : '否' }}</span>
  </c-space>
</template>

<style scoped>
.hover-example-target { position: relative; }
</style>
```

## API

### Directives

| Usage | Description |
| --- | --- |
| `v-hover="callback"` | Notifies `(hovering: boolean) => void` on mouse enter and leave |
| `v-hover="styleObject"` | Applies styles on mouse enter and restores them on leave |
| `v-hover:desktop` / `v-hover:mobile` | Enabled according to the directive's platform detection; this does not imply real touchscreen hover support |

### HoverOverlay Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| hovering | boolean | false | Hover decoration state |
| focusing | boolean | false | Focus decoration state |

`useHoverOverlay()` returns `hovering` and `handleHovering` for connection to directive callbacks. The overlay is absolutely positioned, so its host must establish a positioning context. For independent use, import `@cedar-design/ui/hover/style`.

---

Document: llms/en-US/components/icon.md

<!-- Source: src/icon/README.en-US.md; locale: en-US; page: /en/components/icon/ -->

# Icon

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic Usage

- `size`: Controls the component size.
- `color`: Overrides the color.

Example source: src/icon/__demos__/basic-usage.vue

```vue
<script setup lang="ts">
import { IconCheckCircleFill } from "@cedar-design/icons-vue";
</script>
<template>
  <div class="icon-demo-row">
    <div>
      <p>Resolver 自动按需导入</p>
      <c-icon size="40" color="red"><c-icon-check-circle-fill /></c-icon>
    </div>
    <div>
      <p>手动按需导入</p>
      <c-icon size="40" color="red"><IconCheckCircleFill /></c-icon>
    </div>
  </div>
</template>
<style scoped>
.icon-demo-row {
  display: flex;
  flex-wrap: wrap;
  align-items: center;
  gap: 32px;
}
p {
  margin: 0 0 12px;
  font-size: 14px;
}
</style>
```

## Appearance and states

### Icon size and color

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `size` | `inherit` | Icon size and color |
| `color` | Icon color | Icon size and color |
<!-- demo-config-notes:end -->


Compare size and color independently of rotation, animation and click handling.

Example source: src/icon/__demos__/appearance-comparison.vue

```vue
<script setup lang="ts">


</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="size">
    <h4><span lang="zh-CN">图标尺寸</span><span lang="en-US">size</span></h4>
    <c-space wrap align="center" :size="24">
        <c-icon size="20"><c-icon-check-circle /></c-icon>
        <c-icon size="28"><c-icon-check-circle /></c-icon>
        <c-icon size="36"><c-icon-check-circle /></c-icon>
      </c-space>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="color">
    <h4><span lang="zh-CN">图标颜色</span><span lang="en-US">color</span></h4>
    <c-space wrap :size="24">
        <c-icon size="28" color="rgb(var(--c-primary-6))"
          ><c-icon-check-circle
        /></c-icon>
        <c-icon size="28" color="rgb(var(--c-success-6))"
          ><c-icon-check-circle
        /></c-icon>
      </c-space>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

## Content and presentation

### Rotate Spin

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `size` | `inherit` | Rotate Spin |
| `rotate` | Rotation angle | Rotate Spin |
| `spin` | Whether to rotate continuously | Rotate Spin |
<!-- demo-config-notes:end -->


- `size`: Controls the component size.

Example source: src/icon/__demos__/rotate-spin.vue

```vue
<template>
  <c-space wrap align="center" :size="32">
    <div class="demo-item">
      <c-icon size="32" :rotate="90"><c-icon-arrow-right /></c-icon>
      <span>rotate="90"</span>
    </div>
    <div class="demo-item">
      <c-icon size="32" spin><c-icon-refresh /></c-icon>
      <span>spin</span>
    </div>
    <div class="demo-item">
      <c-icon-refresh :size="32" :rotate="45" spin />
      <span>独立 SVG：rotate + spin</span>
    </div>
  </c-space>
</template>
<style scoped>
.demo-item {
  display: inline-flex;
  align-items: center;
  gap: 8px;
}
</style>
```

### Catalog

Preview configuration: `clearable`, `placeholder="搜索图标名称"`.

Example source: src/icon/__demos__/catalog.vue

```vue
<script setup lang="ts">
import { computed, ref } from "vue";
import { iconNames } from "@cedar-design/icons-vue";
import * as CedarIcons from "@cedar-design/icons-vue";
import { Message } from "../../message";

const keyword = ref("");
const filteredIcons = computed(() =>
  keyword.value
    ? iconNames.filter((name) =>
        name.includes(keyword.value.trim().toLowerCase()),
      )
    : iconNames,
);

const groupRules = [
  [
    "方向",
    /(^|-)(arrow|caret|chevron|left|right|up|down|expand|shrink|swap|rotate|fullscreen|backward|forward)(-|$)/,
  ],
  [
    "状态与反馈",
    /(^|-)(alert|check|close|error|exclamation|info|question|success|warning|empty|stop)(-|$)/,
  ],
  [
    "编辑",
    /(^|-)(align|attachment|bold|brush|copy|delete|edit|eraser|filter|font|formula|italic|link|list|paste|quote|redo|scissor|sort|underline|undo|zoom)(-|$)/,
  ],
  ["文件", /(^|-)(archive|book|bookmark|drive|file|folder|save|storage)(-|$)/],
  [
    "媒体",
    /(^|-)(camera|image|live|music|mute|pause|play|record|skip|sound|video|voice)(-|$)/,
  ],
  [
    "通信与用户",
    /(^|-)(email|message|notification|phone|send|share|subscribe|user|robot)(-|$)/,
  ],
  [
    "品牌",
    /(alipay|bytedance|codepen|facebook|github|gitlab|google|lark|qq|tiktok|twitter|wechat|weibo|xigua)/,
  ],
  ["天气", /(^|-)weather-|(^|-)sun(-|$)|(^|-)moon(-|$)/],
  ["商业", /(^|-)(barcode|cart|gift|shopping|tag)(-|$)/],
] as const;

const iconGroups = computed(() => {
  const groups = new Map<string, string[]>();
  for (const name of filteredIcons.value) {
    const label = groupRules.find(([, rule]) => rule.test(name))?.[0] ?? "通用";
    if (!groups.has(label)) groups.set(label, []);
    groups.get(label)?.push(name);
  }
  return [...groupRules.map(([label]) => label), "通用"].flatMap((label) => {
    const names = groups.get(label);
    return names?.length ? [[label, names.sort()] as const] : [];
  });
});

function pascalCase(name: string) {
  return name
    .split("-")
    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
    .join("");
}

function resolveIcon(name: string) {
  return CedarIcons[`Icon${pascalCase(name)}` as keyof typeof CedarIcons];
}

async function copyIcon(name: string) {
  const markup = `<c-icon-${name} />`;
  try {
    await navigator.clipboard.writeText(markup);
    Message.success(`已复制 ${markup}`);
  } catch {
    Message.error("复制失败，请检查浏览器剪贴板权限");
  }
}
</script>

<template>
  <c-input v-model="keyword" clearable placeholder="搜索图标名称">
    <template #prefix><c-icon-search /></template>
  </c-input>
  <section v-for="[group, names] in iconGroups" :key="group" class="icon-group">
    <h3>
      {{ group }} <small>{{ names.length }}</small>
    </h3>
    <div class="icon-catalog">
      <c-button
        v-for="name in names"
        :key="name"
        class="icon-card"
        variant="outline"
        @click="copyIcon(name)"
      >
        <span class="icon-card-content">
          <component :is="resolveIcon(name)" :size="40" />
          <span class="icon-name">{{ name }}</span>
        </span>
      </c-button>
    </div>
  </section>
</template>

<style scoped>
.icon-catalog {
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(min(100%, 168px), 1fr));
  gap: 16px;
  margin-top: 12px;
}

.icon-group {
  margin-top: 24px;
}
.icon-group h3 {
  margin: 0;
  font-size: 16px;
}
.icon-group small {
  margin-left: 6px;
  color: var(--color-text-3);
  font-weight: normal;
}

.icon-card {
  min-height: 132px;
  height: auto;
  justify-content: center;
  font: inherit;
  line-height: 1.5;
  display: flex;
  min-width: 0;
  flex-direction: column;
  align-items: center;
  gap: 12px;
  padding: 20px 14px;
  color: var(--color-text-1);
  background: var(--color-bg-2);
  border: 1px solid var(--color-border-2);
  border-radius: 8px;
  cursor: pointer;
}

.icon-card:hover {
  color: rgb(var(--c-primary-6));
  border-color: rgb(var(--c-primary-6));
}
.icon-card-content {
  display: flex;
  flex-direction: column;
  align-items: center;
  gap: 12px;
}
.icon-name {
  width: 100%;
  text-align: center;
  font-size: 13px;
  overflow-wrap: anywhere;
  white-space: normal;
}
</style>
```

## Customization and slots

### Custom

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `size` | `inherit` | Custom |
| `color` | Icon color | Custom |
<!-- demo-config-notes:end -->


- `size`: Controls the component size.
- `color`: Overrides the color.

Example source: src/icon/__demos__/custom.vue

```vue
<template>
  <c-icon size="40" color="currentColor">
    <svg
      viewBox="0 0 24 24"
      fill="none"
      stroke="currentColor"
      stroke-width="2"
      role="img"
      aria-label="自定义菱形图标"
    >
      <path d="M12 2 22 12 12 22 2 12Z" />
      <path d="M8 12h8M12 8v8" />
    </svg>
  </c-icon>
</template>
```

### IconPark custom projects

You can use the **SVG Symbol JS** or **Web Component JS** generated by an IconPark custom project directly. Exporting individual SVG files or generating a Vue component for every icon is optional. These are SVG resource mechanisms, separate from loading text fonts with `@font-face`.

The public `@icon-park/vue-next` component package and your custom project's JS are separate resource sources. Installing the public package does not automatically include your team's uploaded or maintained icons.

| Approach | Resource source | Rendering | Loading unit |
| --- | --- | --- | --- |
| SVG Symbol JS | Custom project script | `svg` / `use` in the default slot | The icon collection in that file |
| Web Component JS | Custom project script | A custom element in the default slot | Depends on the generated implementation; do not assume individual icon loading |
| Individual SVG Vue components | Local files or a component package | Vue components in the default slot | Imported modules, subject to build configuration |

SVG Symbol is a suitable starting point: it reuses the Icon container without configuring Vue custom element recognition.

**Current API:** `CIcon` does not have a `symbol` prop and does not download, register or inject IconPark resources. The examples below use the existing default slot. `name` only resolves icon components registered in the current Vue application; it does not resolve Symbol IDs or Web Component icon names. Default slot content takes precedence over `name`.

#### SVG Symbol: load the project script

Copy the **SVG Symbol** script URL from your custom project and load it once in the application's HTML entry, such as `index.html` in a Vite application:

```html
<!-- Example path: replace with your project URL or a locally deployed copy -->
<script src="/icons/project-symbol.js" defer></script>
```

After execution, the script should inject an SVG collection containing `symbol` nodes into the page. The application owns the resource URL and decides whether to use a remote URL or a deployed static file. The component library does not embed business project URLs. Load the script type you chose; using the same collection does not require loading both script variants.

#### SVG Symbol: reference an icon

Suppose the script injects `<symbol id="project-home" viewBox="0 0 48 48">`. You can render it as follows. Paths and IDs in these examples are placeholders; use the values in your generated output.

```vue
<script setup lang="ts">
import { Icon as CIcon } from '@cedar-design/ui'
import '@cedar-design/ui/icon/style'
</script>

<template>
  <c-icon :size="24" color="#1677ff">
    <svg width="1em" height="1em" aria-hidden="true">
      <use href="#project-home" />
    </svg>
  </c-icon>
</template>
```

`href` uses the complete Symbol ID with a leading `#`. Display names, the library's `name` prop and IconPark icon names may differ from the Symbol ID. Do not invent or strip prefixes; inspect `symbol[id]` in developer tools. This references resources injected into the current page: do not use `href="project.js#project-home"`.

`size` sets the container's font size, and the inner SVG follows it through `1em`. `rotate` and `spin` affect the entire container. Without an explicit `size`, normal Icon size inheritance applies. Preserve the generated Symbol's `viewBox` to avoid clipping or incorrect scaling.

#### An application wrapper for shorter usage

Create an application component named `ProjectIcon.vue` if you want to pass an ID as a prop. This requires neither a library API change nor a generated Vue file for each icon:

```vue
<script setup lang="ts">
import { Icon as CIcon } from '@cedar-design/ui'
import '@cedar-design/ui/icon/style'

defineProps<{ symbol: string }>()
</script>

<template>
  <c-icon>
    <svg width="1em" height="1em" aria-hidden="true">
      <use :href="`#${symbol}`" />
    </svg>
  </c-icon>
</template>
```

Use it in the application:

```vue
<script setup lang="ts">
import ProjectIcon from './ProjectIcon.vue'
</script>

<template>
  <ProjectIcon symbol="project-home" :size="24" color="#1677ff" />
</template>
```

Here, `symbol` belongs to the application wrapper and excludes `#`. Undeclared attributes such as `size`, `color`, `rotate` and `spin` fall through to the single `CIcon` root. Forward `$attrs` explicitly if you add multiple roots or disable `inheritAttrs`. The existing `transition` prop only animates `CIcon`'s `name` changes; it does not animate Symbol reference changes inside the slot.

#### Web Component: script and compiler configuration

Alternatively, load your project's **Web Component JS** and place its registered element in the slot. The following assumes the generated element is named `iconpark-icon` and uses a `name` attribute. Confirm element names, attributes and theme support against your project's generated usage instructions.

```html
<!-- Application HTML entry; use the Web Component variant here -->
<script src="/icons/project-web-component.js" defer></script>
```

Configure the build that compiles Vue SFCs containing this tag to recognize the custom element. For Vite:

```ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [
    vue({
      template: {
        compilerOptions: {
          isCustomElement: (tag) => tag === 'iconpark-icon',
        },
      },
    }),
  ],
})
```

Merge this into the existing Vue plugin configuration instead of adding a duplicate plugin. `isCustomElement` is a compile-time setting; setting only `app.config.compilerOptions` does not replace this configuration when using a build tool. Configure the library build when the tag is wrapped inside library source, or the application build when application source uses the tag directly.

```vue
<template>
  <c-icon :size="24" color="#1677ff">
    <iconpark-icon name="project-home" size="1em"></iconpark-icon>
  </c-icon>
</template>
```

This example uses the application's existing `c-icon` import or registration. The outer `CIcon` does not automatically forward theme, stroke width or other attributes to slot content. Set supported attributes directly on the custom element. If it uses Shadow DOM, external `.c-icon svg` rules cannot directly style its inner SVG; use the element's supported attributes, inherited styles or CSS variables.

#### Size, color and multicolor icons

| Setting | Behavior and limitations |
| --- | --- |
| `size` | Symbol examples inherit through `1em`; check the Web Component's own sizing API |
| `color` | Works only when the graphic uses `currentColor` or supports corresponding inheritance |
| Fixed `fill` / `stroke` | Colors embedded in the graphic are not automatically overridden by the container's `color` |
| Multicolor icons | Preserve their colors; avoid forcing a single `fill` or `stroke` across all paths |
| Themes and stroke width | Depend on generated output; public Vue icon package props do not automatically apply to project scripts |

#### On-demand loading and bundle size

Importing components on demand and loading icon resources are independent. Slot usage does not make `CIcon` depend on the entire IconPark package, and existing Resolver imports still work. The Resolver does not load resources based on a `use` ID.

A Symbol script that injects a collection loads that entire file. If it contains 200 icons and a page references three, all 200 are still downloaded and injected. `href="#project-home"` selects a graphic; it does not request an individual icon. A static script is outside the application's module tree-shaking analysis, and string IDs do not automatically remove unused Symbols.

| Goal | Approach |
| --- | --- |
| Small collection reused across pages | Load once at application entry and reuse the browser cache by file version |
| Large collection with distinct business modules | Split resources into shared and module collections; load each when its route or module needs it |
| Render the page before loading icons | Manage loading, failure and placeholder states in the application; show icons when resources are ready |
| Require individual icons to participate in tree shaking | Use separate SVG modules or Vue components and verify package exports and actual build output |

Remote JS is outside the library's npm package but still contributes to application download size. Updating the project requires updating generated resources and their cache versions. The component library's build size alone does not describe page cost.

#### Loading order, SSR and accessibility

- Make static resources available when icons are needed. For dynamic loading, wait for successful script execution. For Web Components, `customElements.whenDefined('iconpark-icon')` can additionally wait for registration; it neither downloads the script nor automatically settles on a resource loading failure.
- Load each resource once per application instead of inserting a script on every component mount. Keep Symbol IDs unique across collections to avoid conflicting references.
- Do not execute scripts requiring `window`, `document` or `customElements` on the server. Use HTML scripts or client lifecycle loading. When rendering conditionally, keep server and initial client placeholders consistent. Icons remain invisible until their resources exist; strict first-paint requirements need server-inlined Symbols or individual SVGs.
- Use `aria-hidden="true"` for decorative SVGs. Give standalone informative SVGs `role="img"` and an accessible name. Give icon-only buttons an `aria-label` on the button itself.

#### Troubleshooting

| Symptom | Check |
| --- | --- |
| Blank icon | Successful script execution, correct script variant, exact ID and nonzero container size |
| `Failed to resolve component: iconpark-icon` | Compile-time `isCustomElement` configuration for the source containing the tag |
| Color does not change | Fixed graphic colors or the Web Component's supported color interface |
| Size does not follow `CIcon` | Inner SVG / element sizing through `1em` and any fixed pixel dimensions |
| Old icon after a project update | Current script version and browser / CDN caching |
| Works locally but fails after deployment | Resource base paths, network requests, CSP `script-src` and script execution errors |
| Wrong icon with multiple collections | Symbol ID collisions, duplicate scripts and the unique IDs in actual output |

References: [Vue and Web Components](https://vuejs.org/guide/extras/web-components), [SVG use element](https://developer.mozilla.org/en-US/docs/Web/SVG/Reference/Element/use).

## Interaction and control

### Click

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `size` | `inherit` | Click, Dynamic Name |
| `color` | Icon color | Click |
| `name` | Explicitly registered icon name | Dynamic Name |
| `transition` | Name-change animation duration in ms | Dynamic Name |
<!-- demo-config-notes:end -->


- `size`: Controls the component size.
- `color`: Overrides the color.

Example source: src/icon/__demos__/click.vue

```vue
<script setup lang="ts">
import { Message } from "@cedar-design/ui";
</script>
<template>
  <c-button
    variant="text"
    round
    aria-label="确认操作"
    @click="Message.success('点击成功')"
  >
    <template #icon><c-icon-check-circle /></template>
  </c-button>
</template>
```

### Dynamic Name

- `size`: Controls the component size.

Example source: src/icon/__demos__/dynamic-name.vue

```vue
<script setup lang="ts">
import { getCurrentInstance, ref } from "vue";
import {
  IconArrowLeft,
  IconArrowRight,
  IconCheckCircle,
  IconInfoCircle,
  IconRefresh,
  IconSearch,
} from "@cedar-design/icons-vue";
const iconName = ref("arrow-left");
const app = getCurrentInstance()?.appContext.app;
const icons = {
  IconArrowLeft,
  IconArrowRight,
  IconCheckCircle,
  IconInfoCircle,
  IconRefresh,
  IconSearch,
};
for (const [name, component] of Object.entries(icons)) {
  if (app && !app.component(name)) {
    app.component(name, component);
  }
}
function toggle() {
  iconName.value =
    iconName.value === "arrow-left" ? "arrow-right" : "arrow-left";
}
</script>
<template>
  <p>
    name 是已注册图标的名称。本例提供
    arrow-left、arrow-right、check-circle、info-circle、refresh、search；默认插槽存在时优先显示插槽内容。
  </p>
  <div class="icon-name-demo">
    <c-space wrap align="center" :size="24">
      <c-button @click="toggle">切换图标</c-button>
      <c-icon :name="iconName" :size="32" :transition="300" />
    </c-space>
  </div>
</template>
```

## Lifecycle and edge cases

### Lifecycle

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `name` | Explicitly registered icon name | Lifecycle |
| `transition` | Name-change animation duration in ms | Lifecycle |
| `size` | `inherit` | Lifecycle |
<!-- demo-config-notes:end -->


- `size`: Controls the component size.

Example source: src/icon/__demos__/lifecycle.vue

```vue
<script setup lang="ts">
import { computed, getCurrentInstance, KeepAlive, ref } from "vue";
import { IconArrowLeft, IconArrowRight } from "@cedar-design/icons-vue";

const language = ref("zh-CN");
const english = computed(() => language.value === "en-US");

const active = ref(true),
  iconName = ref("arrow-left"),
  duration = ref(300);
const app = getCurrentInstance()?.appContext.app;
if (app && !app.component("IconArrowLeft")) {
  app.component("IconArrowLeft", IconArrowLeft);
}
if (app && !app.component("IconArrowRight")) {
  app.component("IconArrowRight", IconArrowRight);
}
function toggleName() {
  iconName.value =
    iconName.value === "arrow-left" ? "arrow-right" : "arrow-left";
}
</script>
<template>
  <c-space wrap>
    <c-button @click="toggleName">{{
      english ? "Switch name" : "切换名称"
    }}</c-button>
    <c-button @click="active = !active">{{
      english ? "Toggle active" : "切换激活"
    }}</c-button>
    <c-button @click="duration = duration ? 0 : 300"
      >{{ english ? "Toggle duration" : "切换时长" }} {{ duration }}ms</c-button
    >
    <KeepAlive
      ><c-icon v-if="active" :name="iconName" :transition="duration" :size="32"
    /></KeepAlive>
  </c-space>
  <p>
    {{
      english
        ? "Inactive changes commit on activation without replay. Duration changes cancel the old phase; zero shows the latest name immediately."
        : "停用后切换名称，激活直接显示最新图标，不重放旧动画；时长变更取消旧阶段，0立即显示最新名称。"
    }}
  </p>
</template>
```

## API

### Icon Props

| Prop | Description | Type | Default |
| --------------- | ---------------------- | ---------------- | ------ |
| name | Explicitly registered icon name | string | - |
| size | `inherit` | number \| string | - |
| color | Icon color | string | - |
| rotate | Rotation angle | number | - |
| spin | Whether to rotate continuously | boolean | false |
| transition | Name-change animation duration in ms | number \| string | 0 |
| animation-class | Custom transition animation class | string | - |

### Icon-xxx Props

| Prop | Description | Type | Default |
| --------------- | ---------- | ------------------------------------------ | ------- |
| size | `inherit` | number \| string | - |
| color | Icon color | string | - |
| rotate | Rotation angle | number | - |
| spin | Whether to rotate | boolean | false |
| title | Accessible title | string | - |
| stroke-width | Stroke width | number | 4 |
| stroke-linecap | Stroke line cap | 'butt' \| 'round' \| 'square' | 'butt' |
| stroke-linejoin | Stroke line join | 'bevel' \| 'inherit' \| 'miter' \| 'round' | 'miter' |

### Icon Events

| Event | Description | Arguments |
| ------ | -------------- | --------------------------- |
| click | Click event | (event: MouseEvent) => void |

### Icon Slots

| Slot | Description |
| ------- | -------------- |
| default | Custom default content |

### Type definitions

The component exports the following types

```ts
import type { IconProps } from "@cedar-design/ui";
```

## Shared implementation and platform boundaries

Each platform maintains a complete local implementation. They do not import a common core or share component instances or reactive state. Changes must update both implementations. Component bodies, props, key styles and paired tests have read-only source consistency checks; theme tokens and installation entries remain local to each library.

Only icons registered in the current application are resolved. Repeated name changes cancel stale timers; no changes run after unmount. Each library locally adapts its registration prefix and legacy spin class; icon resources are not imported across libraries.

Icons inherit the host font size on both platforms. For a fixed 20px icon, set size="20" or icon-size explicitly. The size prop overrides the variable; color inherits from the host by default.

### Motion variables

| Token | Default |
| --- | --- |
| `--c-icon-spin-duration` | `1s` |

Built-in motion follows prefers-reduced-motion: reduce: content and state feedback remain, while decorative spinning, shimmer and ripples stop. Icon name changes display the latest value immediately and cancel unfinished phases, keeping CSS and JS durations aligned. Callers must adapt custom animation classes. Ripple duration/cleanup follows Ripple documentation; its historical 250ms rule is not an Icon duration limit.

---

Document: llms/en-US/components/image.md

<!-- Source: src/image/README.en-US.md; locale: en-US; page: /en/components/image/ -->

# Image

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

- `width`: Sets the configured width.

Example source: src/image/__demos__/basic.vue

```vue
<template>
  <c-image width="200" src="/cat.jpg" />
</template>
```

## Image presentation and states

### Fit Mode

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `width` | Displayed image width | Fit Mode, Captions and additional content, Error |
| `src` | Image source URL | Fit Mode, Captions and additional content, Error |
| `height` | Displayed image height | Fit Mode, Error, Loader |
| `preview-disabled` | Whether click preview is disabled | Fit Mode, Loader, Lazy |
| `object-fit` | How the image fits its container | Fit Mode, Lazy |
| `title` | Title | Captions and additional content |
<!-- demo-config-notes:end -->


- `width`: Sets the configured width.
- `height`: Constrains the component height.

Example source: src/image/__demos__/fit-mode.vue

```vue
<script setup lang="ts">
const fits = ['fill', 'contain', 'cover', 'none', 'scale-down'] as const
</script>

<template>
  <c-space :size="16" wrap>
    <c-space v-for="fit in fits" :key="fit" direction="column" align="center" :size="8">
      <c-image width="120" height="120" :object-fit="fit" preview-disabled src="/cat.jpg" />
      <span class="label">{{ fit }}</span>
    </c-space>
  </c-space>
</template>

<style scoped>
.label {
  color: var(--c-color-text-3);
  font-size: 12px;
}
</style>
```

### Captions and additional content

Compare caption and extra-slot placement independently of previews, loading and failures.

Example source: src/image/__demos__/content-comparison.vue

```vue
<script setup lang="ts">


</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="caption">
    <h4><span lang="zh-CN">标题与描述</span><span lang="en-US">caption</span></h4>
    <c-space :size="24" wrap>
        <c-image width="200" src="/cat.jpg" title="一只猫" description="页脚在图片内侧" />
        <c-image width="200" src="/cat2.jpg" title="一只猫" description="页脚在图片外侧" footer-position="outer" />
      </c-space>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="extra">
    <h4><span lang="zh-CN">底部额外内容</span><span lang="en-US">extra</span></h4>
    <c-space :size="24" wrap>
        <c-image width="200" src="/cat.jpg" title="一只猫" description="内侧额外内容">
          <template #extra>
            <span class="extra">Extra</span>
          </template>
        </c-image>
        <c-image width="200" src="/cat.jpg" title="一只猫" description="外侧额外内容" footer-position="outer">
          <template #extra>
            <span class="extra extra--outer">Extra</span>
          </template>
        </c-image>
      </c-space>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }
.demo-comparison-case--2 {

.extra {
  padding: 2px 8px;
  color: #fff;
  font-size: 12px;
  background: rgb(0 0 0 / 45%);
  border-radius: 10px;
}

.extra--outer {
  color: currentColor;
  background: var(--c-color-fill-2);
}

}
</style>
```

### Error

- `width`: Sets the configured width.
- `height`: Constrains the component height.

Example source: src/image/__demos__/error.vue

```vue
<template>
  <c-space :size="16" wrap>
    <c-image width="160" height="120" src="data:image/png;base64,AA==" />
    <c-image width="160" height="120" src="data:image/png;base64,AA==" alt="自定义错误内容">
      <template #error>
        <div class="error-slot">加载失败</div>
      </template>
    </c-image>
  </c-space>
</template>

<style scoped>
.error-slot {
  display: flex;
  align-items: center;
  justify-content: center;
  width: 100%;
  height: 100%;
  color: var(--c-color-text-3);
  font-size: 12px;
}
</style>
```

### Loader

- `width`: Sets the configured width.
- `height`: Constrains the component height.

Example source: src/image/__demos__/loader.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'

const timestamp = ref('')

function reload() {
  timestamp.value = String(Date.now())
}
</script>

<template>
  <c-space direction="column" :size="16">
    <c-button status="primary" size="sm" @click="reload">重新加载</c-button>
    <c-space :size="16" wrap>
      <c-image width="160" height="160" show-loader :src="`/cat.jpg?reload=${timestamp}`" preview-disabled />
      <c-image width="160" height="160" :src="`/cat.jpg?reload=${timestamp}`" preview-disabled>
        <template #loader>
          <div class="loader-animate" />
        </template>
      </c-image>
      <c-image width="160" height="160" :src="`/cat.jpg?reload=${timestamp}`" preview-disabled>
        <template #loader>
          <img class="progressive" src="/cat2.jpg" alt="" />
        </template>
      </c-image>
    </c-space>
  </c-space>
</template>

<style scoped>
.loader-animate {
  width: 100%;
  height: 100%;
  background: linear-gradient(
    -60deg,
    var(--c-color-fill-2) 25%,
    var(--c-color-fill-3) 40%,
    var(--c-color-fill-2) 55%
  );
  background-size: 400% 100%;
  animation: loop-circle 1.5s cubic-bezier(0.34, 0.69, 0.1, 1) infinite;
}

.progressive {
  width: 100%;
  height: 100%;
  object-fit: cover;
  filter: blur(5px);
}

@keyframes loop-circle {
  0% {
    background-position: 100% 50%;
  }

  100% {
    background-position: 0 50%;
  }
}
</style>
```

### Lazy

- `width`: Sets the configured width.
- `height`: Constrains the component height.

Example source: src/image/__demos__/lazy.vue

```vue
<template>
  <c-space :size="16" wrap>
    <c-image width="160" height="120" object-fit="cover" lazy src="/cat.jpg" preview-disabled />
    <c-image width="160" height="120" object-fit="cover" src="data:image/png;base64,AA==" fallback-src="/cat2.jpg" preview-disabled />
  </c-space>
</template>
```

## Preview entries and groups

### Disable Preview

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `width` | Displayed image width | Disable Preview, Preview Entry, Preview Group |
| `src` | Image source URL | Disable Preview, Preview Entry, Preview Group |
| `height` | Displayed image height | Preview Entry, Preview Group |
| `object-fit` | How the image fits its container | Preview Entry, Preview Group |
| `preview-disabled` | Whether click preview is disabled | Disable Preview |
| `preview-props` | Preview options | Preview Entry |
<!-- demo-config-notes:end -->


- `width`: Sets the configured width.

Example source: src/image/__demos__/disable-preview.vue

```vue
<template>
  <c-image preview-disabled width="200" src="/cat.jpg" />
</template>
```

### Preview Entry

- `width`: Sets the configured width.
- `height`: Constrains the component height.

Example source: src/image/__demos__/preview-entry.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'

const previewOpen = ref(false)
</script>

<template>
  <c-space direction="column" :size="16">
    <c-image width="160" height="120" object-fit="cover" src="/cat.jpg" preview-src="/cat2.jpg" />
    <c-button status="primary" size="sm" @click="previewOpen = true">打开预览</c-button>
    <c-image
      v-model:open="previewOpen"
      width="160"
      height="120"
      object-fit="cover"
      src="/cat.jpg"
      :preview-props="{ scaleStep: 1 }"
    />
  </c-space>
</template>
```

### Component Preview

Preview configuration: `v-model:open="open"`, `src="/cat.jpg"`.

Example source: src/image/__demos__/component-preview.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'

const open = ref(false)
</script>

<template>
  <c-space direction="column" :size="16">
    <c-button status="primary" size="sm" @click="open = true">打开单图预览</c-button>
    <c-image-preview v-model:open="open" src="/cat.jpg" />
  </c-space>
</template>
```

### Imperative Preview

Example source: src/image/__demos__/imperative-preview.vue

```vue
<script setup lang="ts">
const images = ['/cat.jpg', '/cat2.jpg']
let handle: { next: () => void; close: () => void } | undefined

function previewSingle() {
  imagePreview(images[0])
}

function previewMultiple() {
  handle = imagePreview({ images, modelValue: 1 })
}

function next() {
  handle?.next()
}

function close() {
  handle?.close()
}
</script>

<template>
  <c-space :size="12" wrap>
    <c-button status="primary" size="sm" @click="previewSingle">预览单图</c-button>
    <c-button status="primary" size="sm" @click="previewMultiple">预览多图</c-button>
    <c-button size="sm" @click="next">下一张</c-button>
    <c-button size="sm" @click="close">关闭</c-button>
  </c-space>
</template>
```

### Preview Group

- `width`: Sets the configured width.
- `height`: Constrains the component height.

Example source: src/image/__demos__/preview-group.vue

```vue
<template>
  <c-image-preview-group loop>
    <c-space :size="16" wrap>
      <c-image src="/cat.jpg" width="120" height="120" object-fit="cover" />
      <c-image src="/cat2.jpg" width="120" height="120" object-fit="cover" />
    </c-space>
  </c-image-preview-group>
</template>
```

### Component Preview Group

Preview configuration: `v-model:open="open"`, `:images="images"`, `:loop="false"`.

Example source: src/image/__demos__/component-preview-group.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'

const open = ref(false)
const current = ref(2)
const images = ['/cat.jpg', '/cat2.jpg']
</script>

<template>
  <c-space direction="column" :size="16">
    <p>默认在 body 全屏预览；切换缓存图片不重复等待加载。</p>
    <c-button status="primary" size="sm" @click="open = true">打开预览组</c-button>
    <c-image-preview-group v-model:open="open" v-model="current" :images="images" :loop="false" />
  </c-space>
</template>
```

## Preview customization and interaction

### Ripple

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `width` | Displayed image width | Ripple, Overlay Closable, Hide Footer Never |
| `src` | Image source URL | Ripple, Overlay Closable, Hide Footer Never |
| `height` | Displayed image height | Ripple, Overlay Closable, Presentation |
| `object-fit` | How the image fits its container | Ripple, Overlay Closable, Presentation |
| `preview-disabled` | Whether click preview is disabled | Ripple, Hide Footer Never, Presentation |
| `preview-props` | Preview options | Overlay Closable, Preview Popup Container |
<!-- demo-config-notes:end -->


- `width`: Sets the configured width.
- `height`: Constrains the component height.

Example source: src/image/__demos__/ripple.vue

```vue
<template>
  <c-space :size="16" wrap>
    <c-image width="120" height="120" object-fit="cover" ripple preview-disabled src="/cat.jpg" />
    <c-image :block="false" width="120" height="120" object-fit="cover" preview-disabled src="/cat.jpg" />
    <c-image :block="false" width="120" height="120" object-fit="cover" preview-disabled src="/cat2.jpg" />
  </c-space>
</template>
```

### Overlay Closable

- `width`: Sets the configured width.
- `height`: Constrains the component height.

Example source: src/image/__demos__/overlay-closable.vue

```vue
<template>
  <c-space :size="16" wrap>
    <c-image
      width="120"
      height="120"
      object-fit="cover"
      src="/cat.jpg"
      :preview-props="{ overlayClosable: true }"
    />
    <c-image
      width="120"
      height="120"
      object-fit="cover"
      src="/cat2.jpg"
      :preview-props="{ overlayClosable: false }"
    />
  </c-space>
</template>
```

### Hide Footer Never

- `width`: Sets the configured width.

Example source: src/image/__demos__/hide-footer-never.vue

```vue
<template>
  <c-image
    width="200"
    src="data:image/png;base64,AA=="
    title="一只猫"
    description="错误时仍显示底部信息"
    hide-footer="never"
    preview-disabled
  />
</template>
```

### Preview Features

Preview configuration: `v-model:open="open"`, `:images="images"`, `:loop="false"`, `name="切换"`.

Example source: src/image/__demos__/preview-features.vue

```vue
<script setup lang="ts">
import { ImagePreviewAction as CImagePreviewAction } from '../index'

import { ref } from 'vue'

const open = ref(false)
const current = ref(1)
const images = ['/cat.jpg', '/cat2.jpg']

function onAction() {
  current.value = current.value === 0 ? 1 : 0
}
</script>

<template>
  <c-space direction="column" :size="16">
    <c-button status="primary" size="sm" @click="open = true">打开自定义预览</c-button>
    <c-image-preview-group v-model:open="open" v-model="current" :images="images" :loop="false">
      <template #close-icon>
        <span class="close-icon">×</span>
      </template>
      <template #indicator="{ imageNumber, length }">
        <span class="indicator">{{ imageNumber }} / {{ length }}</span>
      </template>
      <template #actions>
        <c-image-preview-action name="切换" @click="onAction">+</c-image-preview-action>
      </template>
    </c-image-preview-group>
  </c-space>
</template>

<style scoped>
.close-icon {
  font-size: 24px;
  color: #fff;
}

.indicator {
  position: absolute;
  top: 16px;
  left: 50%;
  padding: 4px 12px;
  color: #fff;
  font-size: 12px;
  background: rgb(0 0 0 / 45%);
  border-radius: 12px;
  transform: translateX(-50%);
}
</style>
```

### Presentation

- `width`: Sets the configured width.
- `height`: Constrains the component height.

Example source: src/image/__demos__/presentation.vue

```vue
<template>
  <c-space :size="16" wrap>
    <c-space direction="column" align="center" :size="8">
      <c-image width="160" height="100" object-fit="cover" object-position="left top" preview-disabled src="/cat.jpg" />
      <span class="label">160×100 · left top</span>
    </c-space>
    <c-space direction="column" align="center" :size="8">
      <c-image width="100" height="100" object-fit="cover" :radius="12" preview-disabled src="/cat.jpg" />
      <span class="label">radius 12</span>
    </c-space>
    <c-space direction="column" align="center" :size="8">
      <c-image width="100" height="100" object-fit="cover" radius="50%" preview-disabled src="/cat.jpg" />
      <span class="label">radius 50%</span>
    </c-space>
  </c-space>
</template>

<style scoped>
.label {
  color: var(--c-color-text-3);
  font-size: 12px;
}
</style>
```

### Preview Popup Container

- `width`: Sets the configured width.

Example source: src/image/__demos__/preview-popup-container.vue

```vue
<template>
  <div id="image-demo-preview-popup-container" class="popup-container">
    <c-image
      width="160"
      src="/cat.jpg"
      :preview-props="{
        popupContainer: '#image-demo-preview-popup-container',
        closable: false,
      }"
    />
  </div>
</template>

<style scoped>
.popup-container {
  position: relative;
  height: 220px;
  padding: 16px;
  overflow: hidden;
  background: var(--c-color-fill-2);
}
</style>
```

## Lifecycle

### Track Lifecycle

Preview configuration: `v-model:open="open"`, `:images="images"`, `:loop="loop"`, `name="Replace images / 换图"`.

Example source: src/image/__demos__/track-lifecycle.vue

```vue
<script setup lang="ts">
import { ImagePreviewAction as CImagePreviewAction } from '../index'

import { ref } from 'vue'
const active = ref(true)
const open = ref(false)
const current = ref(1)
const loop = ref(true)
const images = ref(['/cat.jpg', '/cat2.jpg'])
function replaceImages() { images.value = [...images.value].reverse() }
</script>
<template>
  <div>
    <c-button @click="open = true">Open / 打开</c-button>
    <c-button @click="active = !active">Activate / 停用与激活</c-button>
    <c-button @click="loop = !loop">Loop / 循环</c-button>
    <c-button @click="replaceImages">Replace images / 等长换图</c-button>
    <p>Current / 当前: {{ current }}. Navigate across the loop edge; deactivate, close or replace images. Old work must not replay.</p>
    <KeepAlive>
      <c-image-preview-group v-if="active" v-model:open="open" v-model="current" :images="images" :loop="loop">
        <template #actions>
          <c-image-preview-action name="Replace images / 换图" @click="replaceImages">换图</c-image-preview-action>
          <c-image-preview-action name="Deactivate / 停用" @click="active = false">停用</c-image-preview-action>
        </template>
      </c-image-preview-group>
    </KeepAlive>
  </div>
</template>
```

### Controller Lifecycle

Preview configuration: `v-model:open="open"`, `:src="source"`, `interaction="touch"`, `:keyboard="true"`.

Example source: src/image/__demos__/controller-lifecycle.vue

```vue
<script setup lang="ts">
import { ImagePreviewAction as CImagePreviewAction } from '../index'

import { ref } from "vue";
const open = ref(false);
const active = ref(true);
const source = ref("/cat.jpg");
const presses = ref(0);
const switchSource = () => {
  source.value = source.value === "/cat.jpg" ? "/cat2.jpg" : "/cat.jpg";
};
</script>
<template>
  <div>
    <c-button @click="open = true">Open / 打开预览</c-button>
    <c-button @click="active = !active">Activate / 停用与激活</c-button>
    <p>
      Long presses / 长按通知: {{ presses }}. Cancel or deactivate; old input
      must not replay.
    </p>
    <KeepAlive>
      <c-image-preview
        v-if="active"
        v-model:open="open"
        :src="source"
        interaction="touch"
        :keyboard="true"
        @long-press="presses++"
      >
        <template #actions>
          <c-image-preview-action
            name="Switch source / 换图"
            @click="switchSource"
            >换图</c-image-preview-action
          >
          <c-image-preview-action
            name="Deactivate / 停用"
            @click="active = false"
            >停用</c-image-preview-action
          >
        </template>
      </c-image-preview>
    </KeepAlive>
  </div>
</template>
```

## Reading direction

Inherits the nearest `dir="ltr|rtl"` and supports runtime and nested overrides. Preview collection navigation, horizontal keys and swipes follow reading direction without reversing the image array. Direction changes cancel pending gestures while preserving the current image, scale and rotation. Images and zoomed pan coordinates are not mirrored. Numerical indicators remain LTR.

## API

ImagePreviewGroup binds a one-based image number through ordinary `v-model`; `defaultValue` initializes the uncontrolled index. Panel opening uses `v-model:open` and `defaultOpen` independently. Programmatic preview options also use modelValue/`defaultValue` and onUpdate:modelValue.

### `<image>` Props

| Parameter | Description | Type | Default | Version |
| -------------------------- | ------------------------------------------------------- | ---------------------------------------------------------- | :-------: | :----- |
| src | Image source URL | `string` | `-` |  |
| width | Displayed image width | `string \| number` | `-` |  |
| height | Displayed image height | `string \| number` | `-` |  |
| title | Title | `string` | `-` |  |
| description | Caption displayed at the bottom; also used as alt when alt is empty | `string` | `-` |  |
| object-fit | How the image fits its container | `'contain' \| 'cover' \| 'fill' \| 'none' \| 'scale-down'` | `-` |  |
| alt | Image text description | `string` | `-` |  |
| hide-footer | Whether to hide the footer; supports `'never'`, which retains the footer on error | `boolean \| 'never'` | `false` |  |
| footer-position | Footer region inside (inner) or outside (outer) the image, default inner; not four-side popup placement | `'inner' \| 'outer'` | `'inner'` |  |
| show-loader | Whether to show a loading effect | `boolean` | `false` |  |
| preview-disabled | Whether click preview is disabled | `boolean` | `false` |  |
| open **(v-model)** | Controlled preview open state | `boolean` | `-` |  |
| default-open | Default preview open state | `boolean` | `false` |  |
| preview-props | Preview options | `ImagePreviewProps` | `-` |  |
| footer-class | Footer-area class | `string\|array\|object` | `-` | 2.23.0 |
| popup-container | Preview mount container | `string \| HTMLElement \| false` | `-` |  |

### `<image>` Events

| Event | Description | Arguments |
| ------------------- | -------------------- | --------------- |
| open-change | Preview open/close event | open: `boolean` |

### `<image>` Slots

| Slot | Description | Arguments |
| --------------- | :------------------: | ---- |
| error | Custom error-state content | - |
| error-icon | Custom error-state icon | - |
| loader | Custom loading effect | - |
| extra | Additional footer content | - |
| preview-actions | Custom preview toolbar | - |

### `<image-preview>` Props

| Parameter | Description | Type | Default |
| ------------------ | ----------------------------------------------------------------- | ----------------------- | :----------------------------------------------------------------------------------------: |
| src | Image source URL | `string` | `-` |
| open **(v-model)** | Whether open | `boolean` | `-` |
| default-open | Default uncontrolled open state | `boolean` | `false` |
| overlay-closable | Whether clicking the overlay outside the image requests closing; clicking the image does not close it | `boolean` | `true` |
| closable | Show the close button | `boolean` | `true` |
| actions-layout | Action layout | `string[]` | `[  'fullScreen',  'rotateRight',  'rotateLeft',  'zoomIn',  'zoomOut',  'originalSize',]` |
| popup-container | Popup mount target, matching `teleport` `to`; defaults `to` document.body | `HTMLElement \| string \| false` | `-` |
| esc-to-close | Whether ESC closes the preview | `boolean` | `true` |
| wheel-zoom | Whether mouse-wheel zoom is enabled | `boolean` | `true` |
| keyboard | Whether keyboard controls are enabled | `boolean` | `true` |
| default-scale | Default zoom scale | `number` | `1` |
| scale-step | Zoom increment per action | `number` | `0.5` |

### `<image-preview>` Events

| Event | Description | Arguments |
| ----------- | ------------ | --------------- |
| close | Close event | - |
| open-change | Open-state change | open: `boolean` |

### `<image-preview>` Slots

| Slot | Description | Arguments | Version |
| ------- | :----------------: | ---- | :----- |
| actions | Additional custom actions | - | 2.17.0 |

### `<image-preview-group>` Props

| Parameter | Description | Type | Default |
| --------------------- | ----------------------------------------------------------------- | ----------------------- | :----------------------------------------------------------------------------------------: |
| images | Image list; providing it disables collection of child Image sources | `string[]` | `-` |
| model-value **(v-model)** | Index of the current image, starting at 1 | `number` | `-` |
| default-value | Initially displayed image index, starting at 1 | `number` | `1` |
| loop | Whether to loop indefinitely | `boolean` | `false` |
| open **(v-model)** | Controlled open state | `boolean` | `-` |
| default-open | Default uncontrolled open state | `boolean` | `false` |
| overlay-closable | Whether clicking the overlay outside the image requests closing; clicking the image does not close it | `boolean` | `true` |
| closable | Show the close button | `boolean` | `true` |
| actions-layout | Toolbar layout | `string[]` | `[  'fullScreen',  'rotateRight',  'rotateLeft',  'zoomIn',  'zoomOut',  'originalSize',]` |
| popup-container | Popup mount target, matching `teleport` `to`; defaults `to` document.body | `string \| HTMLElement \| false` | `-` |

### `<image-preview-group>` Events

| Event | Description | Arguments |
| ----------- | ---------------- | --------------- |
| change | Switch image | imageNumber: `number`，previousImageNumber: `number` |
| open-change | Preview open/close | open: `boolean` |

### `<image-preview-group>` Slots

| Slot | Description | Arguments | Version |
| ------- | :----------------: | ---- | :----- |
| actions | Additional custom actions | - | 2.46.0 |

### `<image-preview-action>` Props (2.17.0)

| Parameter | Description | Type | Default |
| -------- | -------- | --------- | :-----: |
| name | Name | `string` | `-` |
| disabled | Whether disabled | `boolean` | `false` |

### Type definitions

```ts
import type { ImageInstance } from "@cedar-design/ui";
import { imagePreview } from "@cedar-design/ui";
```

### `imagePreview` methods

Replacing an imperative preview disposes the previous instance and invokes its `onClosed` once, just like normal closure. Use this callback to release owned resources such as Object URLs. Old handles never close newer previews. If `onClosed` synchronously opens a new preview, that newer call wins and the interrupted outer call returns `undefined`.

| Method | Description | Arguments |
| ---------------------------------- | ------------ | ------------------------------------- |
| `imagePreview` | Open the image preview | `url \| url[] \| ImagePreviewOptions` |
| `imagePreview.close` | Close the preview | `-` |
| `imagePreview.setDefaultOptions` | Set default configuration | `ImagePreviewOptions` |
| `imagePreview.resetDefaultOptions` | Reset default configuration | `-` |

## FAQ

### `image-preview` prop notes

1. With `keyboard` set to `true`, shortcuts are enabled according to `actions-layout`.

- `esc`: close the preview
- `left`: previous image
- `right`: next image
- `up`: zoom in
- `down`: zoom out
- `space`: restore original size

2. `defaultScale` sets the initial zoom ratio. For example, 1.5 initially displays the image at 1.5 times its original size.

3. `scaleStep` sets the zoom increment for wheel, double-click and toolbar actions.

### Variable consumption boundaries

`--c-image-preview-arrow-font-size` controls preview-group arrows. DOM for old actions-item, trigger, scale-value dimensions and simple-toolbar variables no longer exists; these ineffective entries are removed. The toolbar uses preview-color-action-* and preview-padding-action-content; the footer uses existing footer variables. Error/loading layers fill the image without an extra 100px minimum height. Zoom/track transitions use system motion and stop under reduced motion.

### Image-preview group numbering

`modelValue/defaultValue` start at `1`. `open(imageNumber = 1)` and `to(imageNumber)` use the same numbering; invalid/noninteger values are ignored. `prev()/next()` retain this numbering at loop boundaries. Model events are `update:modelValue(imageNumber)`; navigation emits `change(imageNumber, previousImageNumber)`, while external assignments do not. Long press emits `long-press(imageNumber)`; the indicator slot receives `{ imageNumber, length }`. Internal array indices remain zero-based.

Root `class` and `style` merge with the Image wrapper. Use `img-props.class/style` to style the inner image. Preview `open-change` is a Vue notification event: each state transition emits once, `.once` uses Vue event semantics, and returned Promises do not control loading. The typed `onOpenChange` listener uses this same event path.

---

Document: llms/en-US/components/infinite-scroll.md

<!-- Source: src/infinite-scroll/README.en-US.md; locale: en-US; page: /en/components/infinite-scroll/ -->

# Infinite Scroll

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### List

- `status`: Selects the semantic state.

Example source: src/infinite-scroll/__demos__/list.vue

```vue
<template>
  <div ref="scroller" class="infinite-scroll-demo">
    <c-infinite-scroll
      v-model:status="status"
      :target="scroller"
      :bottom-offset="32"
      @load="fetchData"
    >
      <c-list :data="data" :scrollbar="false">
        <template #header>Infinite list</template>
        <template #item="{ item }">
          <c-list-item>{{ item }}</c-list-item>
        </template>
      </c-list>
    </c-infinite-scroll>
  </div>
</template>

<script lang="ts" setup>
import { onBeforeUnmount, onDeactivated, ref } from "vue";
import type { InfiniteScrollStatus } from "@cedar-design/ui";

const scroller = ref<HTMLElement>();
const page = ref(0);
const data = ref<string[]>([]);
const status = ref<InfiniteScrollStatus>("idle");
let timer: ReturnType<typeof window.setTimeout> | undefined;

const fetchData = () => {
  window.clearTimeout(timer);
  timer = window.setTimeout(() => {
    timer = undefined;
    const start = data.value.length;
    data.value.push(
      ...Array.from(
        { length: 8 },
        (_, index) => `Cedar list item ${start + index + 1}`,
      ),
    );
    page.value += 1;
    status.value = page.value >= 5 ? "finished" : "idle";
  }, 600);
};
onBeforeUnmount(() => window.clearTimeout(timer));
onDeactivated(() => {
  window.clearTimeout(timer);
  timer = undefined;
  if (status.value === "loading") {
    status.value = "idle";
  }
});
</script>

<style scoped>
.infinite-scroll-demo {
  max-height: 320px;
  overflow-y: auto;
}
</style>
```

## Content and presentation

### Error

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `status` | Pagination state; supports `v-model:status` | Error |
| `target` | Scroll container; defaults to the nearest scrolling ancestor | Error |
<!-- demo-config-notes:end -->


- `status`: Selects the semantic state.

Example source: src/infinite-scroll/__demos__/error.vue

```vue
<template>
  <div ref="scroller" class="infinite-scroll-demo">
    <c-infinite-scroll
      v-model:status="status"
      :target="scroller"
      @load="fetchData"
      @retry="fetchData"
    >
      <c-list :data="data" :scrollbar="false">
        <template #item="{ item }">
          <c-list-item>{{ item }}</c-list-item>
        </template>
      </c-list>

      <template #error="{ retry }">
        加载失败，<c-button
          variant="text"
          size="sm"
          status="primary"
          @click="retry"
          >点击重试</c-button
        >
      </template>
    </c-infinite-scroll>
  </div>
</template>

<script lang="ts" setup>
import { onBeforeUnmount, onDeactivated, ref } from "vue";
import type { InfiniteScrollStatus } from "@cedar-design/ui";

const scroller = ref<HTMLElement>();
const data = ref<string[]>([]);
const status = ref<InfiniteScrollStatus>("idle");
let failedOnce = false;
let timer: ReturnType<typeof window.setTimeout> | undefined;

const fetchData = () => {
  window.clearTimeout(timer);
  timer = window.setTimeout(() => {
    timer = undefined;
    if (!failedOnce && data.value.length === 8) {
      failedOnce = true;
      status.value = "error";
      return;
    }

    const start = data.value.length;
    data.value.push(
      ...Array.from(
        { length: 8 },
        (_, index) => `Cedar list item ${start + index + 1}`,
      ),
    );
    status.value = data.value.length >= 32 ? "finished" : "idle";
  }, 600);
};
onBeforeUnmount(() => window.clearTimeout(timer));
onDeactivated(() => {
  window.clearTimeout(timer);
  timer = undefined;
  if (status.value === "loading") {
    status.value = "idle";
  }
});
</script>

<style scoped>
.infinite-scroll-demo {
  max-height: 320px;
  overflow-y: auto;
}
</style>
```

## Customization and slots

### Custom Status

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `status` | Pagination state; supports `v-model:status` | Custom Status |
| `target` | Scroll container; defaults to the nearest scrolling ancestor | Custom Status |
| `bottom-offset` | Distance-to-bottom threshold; numbers are px, strings are CSS lengths | Custom Status |
<!-- demo-config-notes:end -->


- `status`: Selects the semantic state.

Example source: src/infinite-scroll/__demos__/custom-status.vue

```vue
<template>
  <div ref="scroller" class="infinite-scroll-demo">
    <c-infinite-scroll
      v-model:status="status"
      :target="scroller"
      bottom-offset="2rem"
      @load="fetchData"
    >
      <c-list :data="data" :scrollbar="false">
        <template #item="{ item }">
          <c-list-item>{{ item }}</c-list-item>
        </template>
      </c-list>

      <template #loading>
        <c-space align="center">
          <c-loading />
          正在加载下一页
        </c-space>
      </template>
      <template #finished>全部数据加载完成</template>
    </c-infinite-scroll>
  </div>
</template>

<script lang="ts" setup>
import { onBeforeUnmount, onDeactivated, ref } from "vue";
import type { InfiniteScrollStatus } from "@cedar-design/ui";

const scroller = ref<HTMLElement>();
const data = ref<string[]>([]);
const status = ref<InfiniteScrollStatus>("idle");
let timer: ReturnType<typeof window.setTimeout> | undefined;

const fetchData = () => {
  window.clearTimeout(timer);
  timer = window.setTimeout(() => {
    timer = undefined;
    const start = data.value.length;
    data.value.push(
      ...Array.from(
        { length: 8 },
        (_, index) => `Cedar list item ${start + index + 1}`,
      ),
    );
    status.value = data.value.length >= 32 ? "finished" : "idle";
  }, 600);
};
onBeforeUnmount(() => window.clearTimeout(timer));
onDeactivated(() => {
  window.clearTimeout(timer);
  timer = undefined;
  if (status.value === "loading") {
    status.value = "idle";
  }
});
</script>

<style scoped>
.infinite-scroll-demo {
  max-height: 320px;
  overflow-y: auto;
}
</style>
```

## Lifecycle and edge cases

### Scheduler Lifecycle

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `status` | Pagination state; supports `v-model:status` | Scheduler Lifecycle |
| `target` | Scroll container; defaults to the nearest scrolling ancestor | Scheduler Lifecycle |
| `immediate` | Whether to check immediately after mounting and resolving the scroll container | Scheduler Lifecycle |
<!-- demo-config-notes:end -->


- `status`: Selects the semantic state.

Example source: src/infinite-scroll/__demos__/scheduler-lifecycle.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import type { InfiniteScrollStatus } from "@cedar-design/ui";
const first = ref<HTMLElement>();
const second = ref<HTMLElement>();
const alternate = ref(false);
const active = ref(true);
const status = ref<InfiniteScrollStatus>("idle");
const loads = ref(0);
const load = () => {
  loads.value++;
  status.value = "finished";
};
</script>
<template>
  <div>
    <c-button @click="alternate = !alternate"
      >Switch target / 切换目标</c-button
    >
    <c-button @click="active = !active">Activate / 停用与激活</c-button>
    <c-button @click="status = 'idle'">New status cycle / 新状态循环</c-button>
    <p>
      Loads / 加载次数: {{ loads }}. Old checks must not replay /
      旧检查不能重放。
    </p>
    <div ref="first" style="height: 100px; overflow: auto">
      <div style="height: 300px">Target A</div>
    </div>
    <div ref="second" style="height: 100px; overflow: auto">
      <div style="height: 300px">Target B</div>
    </div>
    <KeepAlive>
      <c-infinite-scroll
        v-if="active"
        v-model:status="status"
        :target="alternate ? second : first"
        :immediate="false"
        @load="load"
      >
        <div>Detector / 触底检测</div>
      </c-infinite-scroll>
    </KeepAlive>
  </div>
</template>
```

## API

### `<infinite-scroll>` Props

| Parameter | Description | Type | Default |
| ------------- | -------------------------------------------------- | ---------------------------------------------- | -------- |
| status | Pagination state; supports `v-model:status` | `'idle' \| 'loading' \| 'error' \| 'finished'` | `'idle'` |
| bottom-offset | Distance-to-bottom threshold; numbers are px, strings are CSS lengths | `string \| number` | `0` |
| immediate | Whether to check immediately after mounting and resolving the scroll container | `boolean` | `true` |
| disabled | Pause loading and retry | `boolean` | `false` |
| target | Scroll container; defaults to the nearest scrolling ancestor | `string \| HTMLElement` | `-` |

### `<infinite-scroll>` Events

| Event | Description | Arguments |
| ------------- | -------------------------- | --------- |
| update:status | Requests pagination status `loading` | `loading` |
| load | Emitted when idle and the threshold is reached | - |
| retry | Emitted when retry is invoked in the error state | - |

`retry` does not also emit `load`. Both events may call the same business request function.

### `<infinite-scroll>` Methods

| Method | Description |
| ------ | ---------------------------- |
| check | Immediately check whether the loading threshold is reached |
| retry | Request a retry in the `error` state |

### `<infinite-scroll>` Slots

| Slot | Description | Arguments |
| -------- | ---------------- | ------------------- |
| default | Observed content | - |
| loading | Pagination loading state | - |
| error | Pagination error state | `retry: () => void` |
| finished | All-pages-loaded state | - |

The default error area retries on click. `finished` is terminal; detection resumes only when the parent resets `status` to `idle`.

### Type definitions

```ts
import type {
  InfiniteScrollInstance,
  InfiniteScrollMethods,
  InfiniteScrollProps,
  InfiniteScrollStatus,
} from "@cedar-design/ui";
```

### Style variables

| Variable | Default |
| ----------------------------------------------- | ----------------------- |
| `--c-infinite-scroll-status-min-height` | `50px` |
| `--c-infinite-scroll-status-padding` | `12px 0` |
| `--c-infinite-scroll-status-color` | `var(--c-color-text-3)` |
| `--c-infinite-scroll-status-font-size` | `var(--c-font-size-md)` |
| `--c-infinite-scroll-loading-gap` | `8px` |
| `--c-infinite-scroll-error-color` | `var(--c-color-danger)` |

---

Document: llms/en-US/components/input-number.md

<!-- Source: src/input-number/README.en-US.md; locale: en-US; page: /en/components/input-number/ -->

# InputNumber

Numeric editing with bounds and formatting.

## Reading direction

The numeric input inherits its source `dir`; step buttons follow reading order. Values, precision and vertical keys retain their meaning: ArrowUp increases and ArrowDown decreases. Neither values nor display strings are reversed.

## Basic examples

### Basic usage

Example source: src/input-number/__demos__/field-basic.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
const value = ref<number | undefined>(12);
const disabled = ref(false);
const readonly = ref(false);
const clearable = ref(true);
const hint = ref(false);
</script>
<template>
  <div class="number-demo">
    <div class="number-demo__options">
      <c-checkbox v-model="disabled" edit-mode="direct">禁用</c-checkbox>
      <c-checkbox v-model="readonly" edit-mode="direct">只读</c-checkbox>
      <c-checkbox v-model="clearable" edit-mode="direct">可清空</c-checkbox>
      <c-checkbox v-model="hint" edit-mode="direct">浮动提示</c-checkbox>
    </div>
    <c-input-number
      v-model="value"
      :disabled="disabled"
      :readonly="readonly"
      :clearable="clearable"
      :hint="hint"
      placeholder="数量"
    />
    <output>业务数值：{{ value ?? "空值" }}</output>
  </div>
</template>
<style scoped>
.number-demo {
  display: flex;
  flex-direction: column;
  gap: 12px;
}
.number-demo__options {
  display: flex;
  flex-wrap: wrap;
  gap: 12px;
}
</style>
```

## Appearance and layout

### Appearance Lab

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration | Purpose                                 | Related examples             |
| ------------- | --------------------------------------- | ---------------------------- |
| `size`        | All five sizes implemented; inheritable | Control Sizes, Field Options |
| `variant`     | Field variant; inherits InputGroup      | Control Sizes, Field Options |
| `placeholder` | Placeholder                             | Control Sizes, Field Options |
| `min`         | Minimum                                 | Appearance Lab               |
| `max`         | Maximum                                 | Appearance Lab               |
| `mode`        | Step-button layout                      | Field Modes                  |

<!-- demo-config-notes:end -->

- `min`: Sets the lower bound.
- `max`: Sets the upper bound.

Example source: src/input-number/__demos__/appearance-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref(3);
const __demoAppearance = __demoReactive({ variant: "filled", size: "md" });

import { computed as demoComputed, ref as demoRef } from 'vue'
const demoCompareFields = [{"name":"variant","values":["filled","outline","standard"]},{"name":"size","values":["xs","sm","md","lg","xl"]}]
const demoCompareAxis = demoRef("variant")
const demoComparedOptions = demoComputed(() => demoCompareFields.find(field => field.name === demoCompareAxis.value)?.values ?? [])
</script>
<template>
  <c-space direction="column" :size="16">
    <c-form layout="vertical">
      <c-form-item layout="vertical" size="sm" label="variant">
        <c-radio-group
          v-model="__demoAppearance['variant']"
          aria-label="variant"
          :options="[
            { label: 'filled', value: 'filled' },
            { label: 'outline', value: 'outline' },
            { label: 'standard', value: 'standard' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
      <c-form-item layout="vertical" size="sm" label="size">
        <c-radio-group
          v-model="__demoAppearance['size']"
          aria-label="size"
          :options="[
            { label: 'xs', value: 'xs' },
            { label: 'sm', value: 'sm' },
            { label: 'md', value: 'md' },
            { label: 'lg', value: 'lg' },
            { label: 'xl', value: 'xl' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
    </c-form>
    <p class="demo-config-comparison-hint"><span lang="zh-CN">选择一个对比维度；其他配置和内容保持一致。输入类示例共享同一个值，便于比较外观。</span><span lang="en-US">Compare one dimension while keeping the other settings and content identical. Input specimens share the same value.</span></p>
<c-radio-group v-model="demoCompareAxis" aria-label="Compare configuration" :options="demoCompareFields.map(field => ({ label: field.name, value: field.name }))" />
<div class="demo-config-comparison">
<section v-for="sample in demoComparedOptions" :key="String(sample)">
<p><code>{{ demoCompareAxis }}={{ sample }}</code></p>
<c-input-number
      v-model="value"
      :min="0"
      :max="10"
      v-bind="{ ...__demoAppearance, [demoCompareAxis]: sample }"
    ></c-input-number>
</section>
</div>
  </c-space>
</template>

<style scoped>
.demo-config-comparison { display: grid; grid-template-columns: repeat(auto-fit, minmax(min(100%, 220px), 1fr)); gap: 20px; min-width: 0; max-width: 100%; }
.demo-config-comparison > section { min-width: 0; }
.demo-config-comparison p { margin: 0 0 8px; }
html:not([lang='en-US']) .demo-config-comparison-hint > [lang='en-US'],
html[lang='en-US'] .demo-config-comparison-hint > [lang='zh-CN'] { display: none; }
</style>
```

### Control Sizes

- `size`: Controls the component size.
- `variant`: Selects the visual variant.

Example source: src/field-decorator/__demos__/control-sizes.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
const sizes = ["xs", "sm", "md", "lg", "xl"] as const;
const variants = ["outline", "filled", "standard"] as const;
const size = ref<(typeof sizes)[number]>("md");
const variant = ref<(typeof variants)[number]>("outline");
const options = [
  { value: "beijing", label: "Beijing" },
  { value: "shanghai", label: "Shanghai" },
];
const cascaderOptions = [{ value: "china", label: "China", children: options }];

const inputValue = ref("Beijing");
const selectValue = ref("beijing");
const cascaderValue = ref("beijing");
const selectMultiple = ref(["beijing", "shanghai"]);
const cascaderMultiple = ref(["beijing", "shanghai"]);
const selectOverflow = ref(["long", "beijing", "shanghai"]);
const cascaderOverflow = ref(["long", "beijing", "shanghai"]);
const selectedOptions = [
  ...options,
  {
    value: "long",
    label:
      "A very long selected option label for overflow comparison — full text preview keeps the selected value unchanged.",
  },
];
const selectedCascaderOptions = [
  { value: "china", label: "China", children: selectedOptions },
];
function resetSelections() {
  inputValue.value = "Beijing";
  selectValue.value = "beijing";
  cascaderValue.value = "beijing";
  selectMultiple.value = ["beijing", "shanghai"];
  cascaderMultiple.value = ["beijing", "shanghai"];
  selectOverflow.value = ["long", "beijing", "shanghai"];
  cascaderOverflow.value = ["long", "beijing", "shanghai"];
}
</script>
<template>
  <section
    aria-label="Form control size comparison"
    class="control-size-comparison"
  >
    <c-space wrap :size="12">
      <c-radio-group v-model="size" aria-label="Comparison size">
        <c-radio v-for="item in sizes" :key="item" :value="item">{{
          item
        }}</c-radio>
      </c-radio-group>
      <c-radio-group v-model="variant" aria-label="Comparison variant">
        <c-radio v-for="item in variants" :key="item" :value="item">{{
          item
        }}</c-radio>
      </c-radio-group>
    </c-space>
    <div class="control-size-comparison__grid">
      <div data-control="Input">
        <p>Input</p>
        <c-input :size="size" :variant="variant" placeholder="Input" />
      </div>
      <div data-control="Button">
        <p>Button</p>
        <c-button :size="size" variant="outline">Button</c-button>
      </div>
      <div data-control="Select">
        <p>Select</p>
        <c-select
          :size="size"
          :variant="variant"
          :options="options"
          placeholder="Select"
        />
      </div>
      <div data-control="Date">
        <p>Date</p>
        <c-date :size="size" :variant="variant" placeholder="Date" />
      </div>
      <div data-control="Time">
        <p>Time</p>
        <c-time :size="size" :variant="variant" placeholder="Time" />
      </div>
      <div data-control="InputNumber">
        <p>InputNumber</p>
        <c-input-number :size="size" :variant="variant" placeholder="Number" />
      </div>
      <div data-control="AutoComplete">
        <p>AutoComplete</p>
        <c-auto-complete
          :size="size"
          :variant="variant"
          :options="options"
          placeholder="AutoComplete"
        />
      </div>
      <div data-control="Cascader">
        <p>Cascader</p>
        <c-cascader
          :size="size"
          :variant="variant"
          :options="cascaderOptions"
          placeholder="Cascader"
        />
      </div>
      <div data-control="DateRange">
        <p>DateRange</p>
        <c-date-range
          :size="size"
          :variant="variant"
          :placeholder="['Start', 'End']"
        />
      </div>
      <div data-control="TimeRange">
        <p>TimeRange</p>
        <c-time-range
          :size="size"
          :variant="variant"
          :placeholder="['Start', 'End']"
        />
      </div>
    </div>

    <section
      aria-label="Selected control size comparison"
      class="control-size-comparison__states"
    >
      <c-space wrap align="center" :size="12">
        <span>Selected / Clearable / Multiple — 有值、可清空与多选不换行</span>
        <span
          >Hover or focus truncated text; tap on touch screens /
          悬停或聚焦省略正文查看全文；触屏点按查看，点外部关闭</span
        >
        <c-button size="sm" variant="outline" @click="resetSelections"
          >Reset / 恢复选中值</c-button
        >
      </c-space>
      <div class="control-size-comparison__grid">
        <div data-control="InputValue">
          <p>Input · clearable</p>
          <c-input
            v-model="inputValue"
            :size="size"
            :variant="variant"
            clearable
            placeholder="Input value"
          />
        </div>
        <div data-control="ButtonReference">
          <p>Button · reference</p>
          <c-button :size="size" variant="outline">Button</c-button>
        </div>
        <div data-control="SelectValue">
          <p>Select · clearable</p>
          <c-select
            v-model="selectValue"
            :size="size"
            :variant="variant"
            :options="selectedOptions"
            clearable
            placeholder="Select value"
          />
        </div>
        <div data-control="CascaderValue">
          <p>Cascader · clearable</p>
          <c-cascader
            v-model="cascaderValue"
            :size="size"
            :variant="variant"
            :options="selectedCascaderOptions"
            clearable
            placeholder="Cascader value"
          />
        </div>
        <div data-control="SelectMultiple">
          <p>Select · multiple / nowrap</p>
          <c-select
            v-model="selectMultiple"
            :size="size"
            :variant="variant"
            :options="selectedOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Select multiple"
          />
        </div>
        <div data-control="CascaderMultiple">
          <p>Cascader · multiple / nowrap</p>
          <c-cascader
            v-model="cascaderMultiple"
            :size="size"
            :variant="variant"
            :options="selectedCascaderOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Cascader multiple"
          />
        </div>
        <div data-control="SelectOverflow">
          <p>Select · long values / nowrap</p>
          <c-select
            v-model="selectOverflow"
            edit-mode="direct"
            :size="size"
            :variant="variant"
            :options="selectedOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Select long values"
          />
        </div>
        <div data-control="CascaderOverflow">
          <p>Cascader · long values / nowrap</p>
          <c-cascader
            v-model="cascaderOverflow"
            edit-mode="direct"
            :size="size"
            :variant="variant"
            :options="selectedCascaderOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Cascader long values"
          />
        </div>
      </div>
    </section>
  </section>
</template>
<style scoped>
.control-size-comparison,
.control-size-comparison__states {
  display: grid;
  gap: 24px;
}
.control-size-comparison__grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
  align-items: start;
  gap: 24px 16px;
}
.control-size-comparison__grid > div {
  min-width: 0;
}
.control-size-comparison__grid p {
  margin: 0 0 12px;
  font-size: 14px;
  line-height: 20px;
}
.control-size-comparison__grid :deep(.c-input-number),
.control-size-comparison__grid :deep(.c-auto-complete) {
  width: 100%;
}
</style>
```

### Field Modes

Example source: src/input-number/__demos__/field-modes.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const embed = ref(1)
const button = ref(1)
const input = ref(1)
</script>
<template>
  <div class="number-demo">
    <label>内嵌步进<c-input-number v-model="embed" mode="embed" /></label>
    <label>左右按钮（便于触控）<c-input-number v-model="button" mode="button" /></label>
    <label>纯输入<c-input-number v-model="input" mode="input" /></label>
    <p>按钮可长按；输入框内使用 ↑ / ↓ 步进，Enter 或失焦提交。</p>
  </div>
</template>
<style scoped>
.number-demo, .number-demo label { display: flex; flex-direction: column; gap: 12px; }
</style>
```

### Field Options

- `size`: Controls the component size.
- `variant`: Selects the visual variant.

Example source: src/input-number/__demos__/field-options.vue

```vue
<script setup lang="ts">
const sizes = ['xs', 'sm', 'md', 'lg', 'xl'] as const
const variants = ['outline', 'filled', 'standard'] as const
</script>
<template>
  <div class="number-demo">
    <label v-for="size in sizes" :key="size">{{ size }}<c-input-number :size="size" :default-value="12" /></label>
    <label v-for="variant in variants" :key="variant">{{ variant }}<c-input-number :variant="variant" hint placeholder="金额" :default-value="12" /></label>
  </div>
</template>
<style scoped>
.number-demo, .number-demo label { display: flex; flex-direction: column; gap: 12px; }
</style>
```

## Numeric input and formatting

### Quantity Controls

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration | Purpose                                             | Related examples                                   |
| ------------- | --------------------------------------------------- | -------------------------------------------------- |
| `clearable`   | Allow clearing an editable field                    | Quantity Controls, Format Slots, Number Boundaries |
| `mode`        | Step-button layout                                  | Quantity Controls, Format Slots                    |
| `min`         | Minimum                                             | Quantity Controls, Number Boundaries               |
| `max`         | Maximum                                             | Quantity Controls, Number Boundaries               |
| `step`        | Positive finite step; scientific notation supported | Quantity Controls, Number Boundaries               |
| `formatter`   | Display formatting only; does not change the number | Format Slots, Number Boundaries                    |

<!-- demo-config-notes:end -->

- `min`: Sets the lower bound.
- `max`: Sets the upper bound.
- `step`: Controls the allowed increment.
- `disabled`: Prevents user interaction.

Example source: src/input-number/__demos__/quantity-controls.vue

```vue
<script setup lang="ts">
import { onBeforeUnmount, ref, shallowRef } from "vue";

const props = defineProps<{ english?: boolean }>();
const value = ref<number | undefined>(2);
const disableInput = ref(true);
const disableIncrement = ref(false);
const disableDecrement = ref(false);
const incrementButton = ref(true);
const decrementButton = ref(true);
const press = ref(true);
const lastStep = ref("—");
const approved = ref<number | undefined>(2);
const blocked = ref(false);
const pending = ref(false);
const status = ref("—");
const decision = shallowRef<((allowed: boolean) => void) | undefined>();
const fail = shallowRef<(() => void) | undefined>();
function beforeCommit(
  { value: next }: { value: unknown },
  _done: (allow?: boolean) => void,
  { signal }: { signal: AbortSignal },
) {
  pending.value = true;
  status.value = props.english
    ? `Waiting to commit ${next ?? "empty"}`
    : `等待提交 ${next ?? "空值"}`;
  return new Promise<void | false>((resolve, reject) => {
    const cleanup = () => {
      signal.removeEventListener("abort", cancel);
      pending.value = false;
      decision.value = undefined;
      fail.value = undefined;
    };
    const cancel = () => {
      cleanup();
      status.value = props.english
        ? "Cancelled; old result ignored"
        : "已取消，旧结果不再生效";
      resolve(false);
    };
    signal.addEventListener("abort", cancel, { once: true });
    decision.value = (allowed) => {
      cleanup();
      status.value = allowed
        ? props.english
          ? "Approved"
          : "已允许"
        : props.english
          ? "Rejected"
          : "已拒绝";
      resolve(allowed ? undefined : false);
    };
    fail.value = () => {
      cleanup();
      status.value = props.english
        ? "Request failed; value preserved"
        : "请求失败，保留原值";
      reject(
        new Error(props.english ? "Quantity request failed" : "数量提交失败"),
      );
    };
  });
}
onBeforeUnmount(() => decision.value?.(false));
</script>

<template>
  <div class="quantity-controls-demo">
    <h4>
      {{
        english ? "Quantity controls and step direction" : "数量控制与步进方向"
      }}
    </h4>
    <c-space wrap>
      <c-checkbox v-model="disableInput" edit-mode="direct">{{
        english ? "Buttons only" : "禁止手输"
      }}</c-checkbox>
      <c-checkbox v-model="disableIncrement" edit-mode="direct">{{
        english ? "Disable increase" : "禁用增加"
      }}</c-checkbox>
      <c-checkbox v-model="disableDecrement" edit-mode="direct">{{
        english ? "Disable decrease" : "禁用减少"
      }}</c-checkbox>
      <c-checkbox v-model="incrementButton" edit-mode="direct">{{
        english ? "Show increase" : "显示增加"
      }}</c-checkbox>
      <c-checkbox v-model="decrementButton" edit-mode="direct">{{
        english ? "Show decrease" : "显示减少"
      }}</c-checkbox>
      <c-checkbox v-model="press" edit-mode="direct">{{
        english ? "Long press" : "开启长按"
      }}</c-checkbox>
    </c-space>
    <c-input-number
      v-model="value"
      edit-mode="direct"
      mode="button"
      aria-label="数量控制示例"
      :disable-input="disableInput"
      :disable-increment="disableIncrement"
      :disable-decrement="disableDecrement"
      :increment-button="incrementButton"
      :decrement-button="decrementButton"
      :press="press"
      :min="0"
      :max="10"
      @step="(next, direction) => (lastStep = `${direction}: ${next}`)"
    />
    <p role="status">
      {{ english ? "Accepted step" : "已接受的步进" }}：{{ lastStep }}
    </p>
    <h4>
      {{
        english
          ? "Approve, reject or cancel an asynchronous commit"
          : "异步允许、拒绝与取消提交"
      }}
    </h4>
    <p>
      {{
        english
          ? "Step, type or clear the value, then choose an approval result below. Pending operations cannot overlap. External updates and disabling cancel the old request."
          : "加减、输入或清空后，在下方手动选择审批结果。等待时不能重复提交；外部回填或禁用会取消旧请求。"
      }}
    </p>
    <c-input-number
      v-model="approved"
      edit-mode="direct"
      mode="button"
      clearable
      aria-label="异步数量示例"
      :before-commit="beforeCommit"
      loading-mode="line"
      :disabled="blocked"
    />
    <c-space wrap>
      <c-button :disabled="!pending" @click="decision?.(true)">{{
        english ? "Approve" : "允许本次变更"
      }}</c-button>
      <c-button :disabled="!pending" @click="decision?.(false)">{{
        english ? "Reject" : "拒绝本次变更"
      }}</c-button>
      <c-button :disabled="!pending" @click="fail?.()">{{
        english ? "Simulate failure" : "模拟失败"
      }}</c-button>
      <c-button @click="approved = 10">{{
        english ? "Set external value to 10" : "外部回填 10"
      }}</c-button>
      <c-button @click="blocked = !blocked">{{
        blocked
          ? english
            ? "Enable"
            : "恢复可用"
          : english
            ? "Disable"
            : "禁用控件"
      }}</c-button>
    </c-space>
    <p role="status">
      {{ status }}；{{ english ? "Committed value" : "已提交值" }}：{{
        approved ?? "—"
      }}
    </p>
  </div>
</template>
```

### Format Slots

Example source: src/input-number/__demos__/format-slots.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
const value = ref(12);
const formatter = (text: string) => text.replace(/\B(?=(\d{3})+(?!\d))/g, ",");
const parser = (text: string) => text.replace(/,/g, "");
</script>
<template>
  <c-input-number
    v-model="value"
    :formatter="formatter"
    :parser="parser"
    clearable
    mode="button"
  >
    <template #prepend>预算</template>
    <template #prefix>¥</template>
    <template #suffix>元</template>
    <template #append>含税</template>
    <template #plus>＋</template>
    <template #minus>－</template>
    <template #clear-icon="{ clear }"
      ><c-button html-type="button" aria-label="清空金额" @click="clear"
        >×</c-button
      ></template
    >
  </c-input-number>
</template>
```

### Number Boundaries

- `step`: Controls the allowed increment.
- `max`: Sets the upper bound.
- `min`: Sets the lower bound.

Example source: src/input-number/__demos__/number-boundaries.vue

```vue
<script setup lang="ts">
import { ref } from "vue";

const tiny = ref(0);
const negative = ref<number>();
const bounded = ref(0.1);
const amount = ref(12);
const formatter = (value: string) => "$" + value;
const parser = (value: string) => value.replace(/^\$/, "");
</script>

<template>
  <div class="number-boundaries-demo">
    <label>
      <span>科学计数法步长：1e-7</span>
      <c-input-number v-model="tiny" :step="1e-7" :precision="0" />
      <output>{{ tiny }}</output>
    </label>
    <label>
      <span>空值开始，最大值为 -1</span>
      <c-input-number v-model="negative" :max="-1" clearable />
      <output>{{ negative ?? "空值" }}</output>
    </label>
    <label>
      <span>边界优先：最大值 0.15，精度 1</span>
      <c-input-number
        v-model="bounded"
        :min="0"
        :max="0.15"
        :step="0.1"
        :precision="1"
      />
      <output>{{ bounded }}</output>
    </label>
    <label>
      <span>格式化展示与业务数字分离</span>
      <c-input-number
        v-model="amount"
        :formatter="formatter"
        :parser="parser"
        model-event="input"
      />
      <output>{{ amount }}</output>
    </label>
  </div>
</template>

<style scoped>
.number-boundaries-demo {
  display: flex;
  flex-direction: column;
  gap: 16px;
}
.number-boundaries-demo label {
  display: flex;
  flex-direction: column;
  gap: 6px;
}
.number-boundaries-demo output {
  font-variant-numeric: tabular-nums;
}
</style>
```

### Empty markers and valid zero

Configure empty-values and empty-value when an API uses -1 for missing data. Initially the input is blank while the model remains -1. Set it to 0 to see a valid zero; clearing returns -1. A second field clears to a valid 0, showing that clear output need not mean missing data.

Example source: src/input-number/__demos__/en-US/empty-value.vue

```vue
<script setup lang="ts">
import { reactive, ref } from "vue";
const model = reactive({ quantity: -1 as number | null | undefined });
const restored = ref<number | null | undefined>(12);
</script>
<template>
  <c-space direction="column">
    <p>
      -1 means missing and renders blank; 0 remains a valid number. Clearing
      produces -1.
    </p>
    <c-form :model="model" layout="vertical">
      <c-form-item field="quantity" label="Quantity">
        <c-input-number
          v-model="model.quantity"
          edit-mode="direct"
          clearable
          :empty-values="[null, undefined, -1]"
          :empty-value="-1"
        />
      </c-form-item>
    </c-form>
    <c-space wrap>
      <c-button @click="model.quantity = 0">Set to 0</c-button>
      <c-button @click="model.quantity = -1">Set to -1</c-button>
    </c-space>
    <p>
      Current model: <output>{{ String(model.quantity) }}</output>
    </p>
    <p>This field clears to 0 without treating 0 as missing.</p>
    <c-form layout="vertical">
      <c-form-item label="Clear restores valid zero">
        <c-input-number
          v-model="restored"
          edit-mode="direct"
          clearable
          :empty-value="0"
        />
        <output>{{ String(restored) }}</output>
      </c-form-item>
    </c-form>
  </c-space>
</template>
```

## Interaction and forms

### State Lab

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration | Purpose                                       | Related examples                    |
| ------------- | --------------------------------------------- | ----------------------------------- |
| `disabled`    | Disabled; inherits when omitted               | State Lab, Form Inheritance         |
| `readonly`    | Read-only; allows focus/copy but no mutations | State Lab, Form Inheritance         |
| `clearable`   | Allow clearing an editable field              | Controlled Events, Form Inheritance |
| `min`         | Minimum                                       | State Lab                           |
| `max`         | Maximum                                       | State Lab                           |
| `error`       | Error state; inherits FormItem when omitted   | State Lab                           |

<!-- demo-config-notes:end -->

- `min`: Sets the lower bound.
- `max`: Sets the upper bound.

Example source: src/input-number/__demos__/state-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref(3);
const __demoState = __demoReactive({
  disabled: false,
  readonly: false,
  error: false,
});
</script>
<template>
  <c-space direction="column" :size="16">
    <c-space wrap>
      <c-checkbox v-model="__demoState['disabled']">disabled</c-checkbox>
      <c-checkbox v-model="__demoState['readonly']">readonly</c-checkbox>
      <c-checkbox v-model="__demoState['error']">error</c-checkbox>
    </c-space>
    <c-input-number
      v-model="value"
      :min="0"
      :max="10"
      v-bind="__demoState"
    ></c-input-number>
  </c-space>
</template>
```

### Controlled Events

Example source: src/input-number/__demos__/controlled-events.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const value = ref<number | undefined>(1)
const logs = ref<string[]>([])
function log(name: string, next?: number) {
  logs.value = [name + ': ' + (next ?? '空值'), ...logs.value].slice(0, 6)
}
</script>
<template>
  <div class="number-demo">
    <label>父组件接受更新
      <c-input-number v-model="value" clearable model-event="input" @input="(next: number | undefined) => log('input', next)" @update:model-value="(next: number | undefined) => log('update', next)" @change="(next: number | undefined) => log('change', next)" @clear="() => log('clear')" />
    </label>
    <label>固定受控值，父组件不接受更新
      <c-input-number :model-value="5" @update:model-value="(next: number | undefined) => log('rejected', next)" />
    </label>
    <p>第二个输入框允许编辑草稿，提交后恢复为 5。外部回填不会触发用户 change。</p>
    <ol aria-live="polite"><li v-for="(entry, index) in logs" :key="index">{{ entry }}</li></ol>
  </div>
</template>
<style scoped>
.number-demo, .number-demo label { display: flex; flex-direction: column; gap: 12px; }
</style>
```

### Form Inheritance

- `disabled`: Prevents user interaction.
- `readonly`: Displays the current value without allowing edits.
- `size`: Controls the component size.

Example source: src/input-number/__demos__/form-inheritance.vue

```vue
<script setup lang="ts">
import { reactive, ref } from "vue";
const model = reactive({ quantity: 2, editable: 3 });
const disabled = ref(false);
const readonly = ref(false);
</script>
<template>
  <div class="number-demo">
    <c-checkbox v-model="disabled">表单禁用</c-checkbox>
    <c-checkbox v-model="readonly">表单只读</c-checkbox>
    <c-form :model="model" :disabled="disabled" :readonly="readonly" size="lg">
      <c-form-item field="quantity" label="继承状态">
        <c-input-number v-model="model.quantity" clearable />
      </c-form-item>
      <c-form-item field="editable" label="显式覆盖">
        <c-input-number
          v-model="model.editable"
          :disabled="false"
          :readonly="false"
          size="sm"
        />
      </c-form-item>
    </c-form>
  </div>
</template>
<style scoped>
.number-demo {
  display: flex;
  flex-direction: column;
  gap: 12px;
}
</style>
```

### Shared field loading

`loading` displays the shared field indicator. `loading-mode` is `default` (indicator) or `line` (an indeterminate bottom line); it defaults to `default`. Rendering belongs to FieldDecorator. Loading does not implicitly disable editing or change readonly. Set those states separately.

## API

### Empty values and reading placeholders

`empty-values` recognizes empty data; `empty-value` keeps existing clear output. `empty-text` defaults to `'-'` under `read-pretty`, with Field > FormItem > Form precedence and custom read slots first. With explicit empty-values, built-in required uses the policy; custom validators receive original data. See the [shared guide](llms/en-US/guide/empty-values.md).

| Prop         | Type               | Default and scope                                                           |
| ------------ | ------------------ | --------------------------------------------------------------------------- |
| empty-values | readonly unknown[] | Field > FormItem > Form > component-family default; replaces the whole list |
| empty-text   | string             | Field > FormItem > Form > '-'; explicit '' is valid                         |

These props belong to field presentation; pure panels do not gain reading mode. Form and FormItem provide inherited settings. The existing empty-value type and clear fallback remain component-specific.

### Clear output

`empty-value` / `emptyValue` sets the model value produced by clearing. It accepts a value in the component model type or a zero-argument factory. Omission preserves the existing default; use `() => undefined` to distinguish omission from returning undefined. Arrays are shallow-copied on every clear; selected items that cannot be cleared remain. It does not redefine emptiness, alter Form reset defaults or treat 0/false as universally empty.

`empty-value` accepts explicit `null` (or `() => null`). Clearing publishes `null` unchanged; omitted values preserve the existing default. Editors render `null` as blank without converting ordinary empty-string input to `null`. In popup editing, clearing changes the draft; confirm commits it and cancel preserves the original model.

### Props

| Prop          | Description                                                      | Type                            | Default                    |
| ------------- | ---------------------------------------------------------------- | ------------------------------- | -------------------------- |
| model-value   | Controlled number; undefined denotes an empty/uncontrolled value | `number`                        | —                          |
| default-value | Initial uncontrolled value                                       | `number`                        | —                          |
| mode          | Step-button layout                                               | `embed \| button \| input`      | `embed`                    |
| precision     | Decimal places (0–100), at least the step precision              | `number`                        | —                          |
| step          | Positive finite step; scientific notation supported              | `number`                        | `1`                        |
| disabled      | Disabled; inherits when omitted                                  | `boolean`                       | Inherited, otherwise false |
| error         | Error state; inherits FormItem when omitted                      | `boolean`                       | Inherited, otherwise false |
| max           | Maximum                                                          | `number`                        | `Infinity`                 |
| min           | Minimum                                                          | `number`                        | `-Infinity`                |
| formatter     | Display formatting only; does not change the number              | `(text: string) => string`      | —                          |
| parser        | Parse the original text once per edit                            | `(text: string) => string`      | —                          |
| placeholder   | Placeholder                                                      | `string`                        | —                          |
| size          | All five sizes implemented; inheritable                          | `xs \| sm \| md \| lg \| xl`    | Inherited, otherwise md    |
| variant       | Field variant; inherits InputGroup                               | `outline \| filled \| standard` | `outline`                  |
| hint          | Floating hint; inherits InputGroup / FieldDecorator              | `boolean`                       | Library default            |
| clearable     | Allow clearing an editable field                                 | `boolean`                       | `false`                    |
| model-event   | Model update timing; change only reports commits                 | `change \| input`               | `change`                   |
| readonly      | Read-only; allows focus/copy but no mutations                    | `boolean`                       | Inherited, otherwise false |
| input-attrs   | Additional native input attributes                               | `Record<string, unknown>`       | —                          |

### Events

| Event              | Arguments                                                  | Description                                                      |
| ------------------ | ---------------------------------------------------------- | ---------------------------------------------------------------- |
| input              | `(value: number \| undefined, text: string, event: Event)` | Parsed value and display text while editing                      |
| update:model-value | `(value: number \| undefined)`                             | Proposed model update                                            |
| change             | `(value: number \| undefined, event: Event)`               | Commit, step or clear                                            |
| clear              | `(event: Event)`                                           | Explicit clear                                                   |
| focus              | `(event: FocusEvent)`                                      | Focus                                                            |
| blur               | `(event: FocusEvent)`                                      | Blur                                                             |
| keydown            | `(event: KeyboardEvent)`                                   | Native keyboard event; preventDefault intercepts default actions |

### Slots

| Slot             | Arguments                            | Description         |
| ---------------- | ------------------------------------ | ------------------- |
| prefix / suffix  | —                                    | Inside the field    |
| prepend / append | —                                    | Outside the field   |
| plus / minus     | —                                    | Step-button icons   |
| clear-icon       | `{ clear: (event?: Event) => void }` | Custom clear button |

### Methods

| Method / property | Type                               | Description                       |
| ----------------- | ---------------------------------- | --------------------------------- |
| focus             | `(options?: FocusOptions) => void` | Focus; ineffective while disabled |
| blur              | `() => void`                       | Blur                              |
| select            | `() => void`                       | Select all text                   |
| inputRef          | `HTMLInputElement \| undefined`    | Native input element              |

## Type definitions / Types

```ts
import type {
  InputNumberProps,
  InputNumberInstance,
  InputNumberMode,
  InputNumberModelEvent,
  InputNumberSize,
  InputNumberVariant,
  InputNumberFormatter,
  InputNumberParser,
} from "@cedar-design/ui";
```

## Style variables

| Token                                              | Default                                |
| -------------------------------------------------- | -------------------------------------- |
| `--c-input-number-step-button-width`               | `var(--c-sys-control-height-md)`       |
| `--c-input-number-step-button-color`               | `var(--c-sys-color-content-secondary)` |
| `--c-input-number-step-button-disabled-color`      | `var(--c-sys-color-content-disabled)`  |
| `--c-input-number-step-button-border-color`        | `var(--c-sys-color-border-subtle)`     |
| `--c-input-number-step-button-background`          | `var(--c-sys-color-surface-muted)`     |
| `--c-input-number-step-button-hover-background`    | `var(--c-sys-color-state-hover)`       |
| `--c-input-number-step-button-active-background`   | `var(--c-sys-color-state-selected)`    |
| `--c-input-number-step-button-icon-size`           | `14px`                                 |
| `--c-input-number-step-button-transition-duration` | `0.2s`                                 |
| `--c-input-number-addon-background`                | `var(--c-sys-color-surface-muted)`     |
| `--c-input-number-addon-color`                     | `var(--c-sys-color-content-primary)`   |
| `--c-input-number-addon-border-color`              | `var(--c-sys-color-border-default)`    |
| `--c-input-number-border-width`                    | `1px`                                  |
| `--c-input-number-border-radius`                   | `var(--c-field-border-radius)`         |
| `--c-input-number-size-xs-step-button-width`       | `var(--c-sys-control-height-xs)`       |
| `--c-input-number-size-sm-step-button-width`       | `var(--c-sys-control-height-sm)`       |
| `--c-input-number-size-md-step-button-width`       | `var(--c-sys-control-height-md)`       |
| `--c-input-number-size-lg-step-button-width`       | `var(--c-sys-control-height-lg)`       |
| `--c-input-number-size-xl-step-button-width`       | `var(--c-sys-control-height-xl)`       |

Old `--c-field-number-*` tokens are removed in favor of `--c-input-number-*`, without aliases. Shared field appearance still uses FieldDecorator `--c-field-*` tokens.

### Form field presentation and confirmation

This component supports `edit-mode` with field > FormItem > Form precedence. When unset, it defaults to `direct` and preserves `direct` editing. Supported values: `direct / click / dblclick`. Non-`direct` modes open the editor through the field value trigger and keep one draft; v-model updates only after confirmation. Cancel, reset or enabling readPretty discards the draft.

Cedar uses edit-mode="click" / "dblclick" to open an editor popup near the field. Enter/F2 also opens it; cancel/Escape discards the draft, and confirmation commits it. readPretty is an independent reading setting, separate from readonly and disabled.

`before-commit(value, { previousValue, signal })` can reject an overlay save. FormItem validates the candidate first and keeps the editor open on failure. `open / default-open / update:open` control the editor. Use `#read="{ value, text }"` to customize display. See the full field comparison in Form.

`read-pretty` is an independent boolean alongside `readonly` and `disabled`. It inherits from field to FormItem to Form; explicit `false` overrides the parent. The default is `false`. Reading mode renders no editor.

`--c-field-caret-color` sets the shared caret color, defaulting to `currentColor`. `--c-input-number-caret-color` overrides this component and defaults to `var(--c-field-caret-color)`.

An explicit beforeCommit wait uses the existing loadingMode indicator and native aria-busy. Manual loading remains independent and does not implicitly make the input readonly; the beforeCommit guard owns its existing input lock. Returned change/step notification Promises do not control waiting.

---

Document: llms/en-US/components/input-tag.md

<!-- Source: src/input-tag/README.en-US.md; locale: en-US; page: /en/components/input-tag/ -->

# InputTag

Editable tag values with controlled array models.

## Reading direction

Tags follow reading order while their source array stays unchanged. With empty input, Backspace removes the last closable value; Enter adds a tag. Composition does not submit or delete tags.

## Basic examples

### Basic usage

Example source: src/input-tag/__demos__/basic.vue

```vue
<template>
  <c-input-tag :default-value="['test']" placeholder="Please Enter" clearable />
</template>
```

## Appearance and states

### Tag input size and state

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration   | Purpose                            | Related examples         |
| --------------- | ---------------------------------- | ------------------------ |
| `default-value` | Default value (uncontrolled state) | Tag input size and state |
| `placeholder`   | Placeholder                        | Tag input size and state |
| `size`          | The size of the input              | Tag input size and state |
| `clearable`     | Enables the clear action           | Tag input size and state |
| `disabled`      | Whether disabled                   | Tag input size and state |
| `readonly`      | Whether it is read-only mode       | Tag input size and state |

<!-- demo-config-notes:end -->

Compare sizes and disabled, read-only or error appearance while keeping the empty-value protocol separate.

Example source: src/input-tag/__demos__/appearance-state-comparison.vue

```vue
<script setup lang="ts">
import { ref } from "vue"
import { proxyRefs as demoProxyRefs } from 'vue'

const scene1 = demoProxyRefs((() => {


const size = ref('md')
return { size }
})())
</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="size">
    <h4><span lang="zh-CN">输入框尺寸</span><span lang="en-US">size</span></h4>
    <c-space direction="column" size="lg">
        <c-radio-group type="button" v-model="scene1.size">
          <c-radio value="xs">xs</c-radio>
          <c-radio value="sm">sm</c-radio>
          <c-radio value="md">md</c-radio>
          <c-radio value="lg">lg</c-radio>
          <c-radio value="xl">xl</c-radio>
        </c-radio-group>
        <c-input-tag :default-value="['one']" placeholder="Please enter something" :size="scene1.size" clearable />
      </c-space>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="status">
    <h4><span lang="zh-CN">输入框状态</span><span lang="en-US">status</span></h4>
    <c-space direction="column" size="lg">
        <c-input-tag :default-value="['test']" placeholder="Please Enter" disabled />
        <c-input-tag :default-value="['test']" placeholder="Please Enter" readonly />
        <c-input-tag :default-value="['test']" placeholder="Please Enter" error />
      </c-space>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

## Content and presentation

### Max

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration   | Purpose                                                   | Related examples |
| --------------- | --------------------------------------------------------- | ---------------- |
| `default-value` | Default value (uncontrolled state)                        | Max              |
| `placeholder`   | Placeholder                                               | Max              |
| `max-tag-count` | The maximum number of tags displayed, `0` means unlimited | Max              |
| `clearable`     | Enables the clear action                                  | Max              |

<!-- demo-config-notes:end -->

- `default-value`: Default value (uncontrolled state)
- `placeholder`: Placeholder
- `max-tag-count`: The maximum number of tags displayed, `0` means unlimited
- `clearable`: Whether to allow clear

Example source: src/input-tag/__demos__/max.vue

```vue
<template>
  <c-input-tag
    :default-value="['one', 'two', 'three', 'four']"
    placeholder="Please Enter"
    :max-tag-count="3"
    clearable
  />
</template>
```

## Loading and waiting

### Controlled loading

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| `loading` | Explicit business loading state | `boolean` | `false` |


Set loading explicitly to display feedback. Ordinary event return values do not drive loading. Before hooks retain their documented pending behavior.

Example source: src/input-tag/__demos__/loading.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const loading = ref(true)
</script>
<template>
  <c-space direction="column" style="width: 100%" :size="16">
    <c-form layout="vertical"><c-form-item label="加载状态 / Loading"><c-switch v-model="loading" /></c-form-item></c-form>
    <c-input-tag :loading="loading" :default-value="['示例 / Example']" />
    <p>通过 loading 显式控制等待展示，普通事件返回 Promise 不会自动加载。Loading is controlled by business state.</p>
  </c-space>
</template>
```

## API

### Empty values and reading placeholders

`empty-values` recognizes empty data; `empty-value` keeps existing clear output. `empty-text` defaults to `'-'` under `read-pretty`, with Field > FormItem > Form precedence and custom read slots first. With explicit empty-values, built-in required uses the policy; custom validators receive original data. See the [shared guide](llms/en-US/guide/empty-values.md).

| Prop         | Type               | Default and scope                                                           |
| ------------ | ------------------ | --------------------------------------------------------------------------- |
| empty-values | readonly unknown[] | Field > FormItem > Form > component-family default; replaces the whole list |
| empty-text   | string             | Field > FormItem > Form > '-'; explicit '' is valid                         |

These props belong to field presentation; pure panels do not gain reading mode. Form and FormItem provide inherited settings. The existing empty-value type and clear fallback remain component-specific.

### `<input-tag>` Props

| Parameter                 | Description                                               | Type                                              |  Default   |
| ------------------------- | --------------------------------------------------------- | ------------------------------------------------- | :--------: |
| model-value **(v-model)** | Bound value                                               | `(string \| number \| TagData)[]`                 |    `-`     |
| default-value             | Default value (uncontrolled state)                        | `(string \| number \| TagData)[]`                 |    `[]`    |
| input-value **(v-model)** | The value of the input                                    | `string`                                          |    `-`     |
| default-input-value       | The default value of the input (uncontrolled state)       | `string`                                          |    `''`    |
| placeholder               | Placeholder                                               | `string`                                          |    `-`     |
| disabled                  | Whether disabled                                          | `boolean`                                         |  `false`   |
| error                     | Whether it is an error state                              | `boolean`                                         |  `false`   |
| readonly                  | Whether it is read-only mode                              | `boolean`                                         |  `false`   |
| clearable                 | Enables the clear action                                  | `boolean`                                         |  `false`   |
| size                      | The size of the input                                     | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'`            |   `'md'`   |
| variant                   | The variant of the input                                  | `'filled' \| 'outline' \| 'standard'`             | `'filled'` |
| max-tag-count             | The maximum number of tags displayed, `0` means unlimited | `number`                                          |    `0`     |
| retain-input-value        | Whether to keep the content of the input box              | `boolean \| { create?: boolean; blur?: boolean }` |  `false`   |
| format-tag                | Format tag content                                        | `(data: TagData) => string`                       |    `-`     |
| unique-value              | Whether to create only unique values                      | `boolean`                                         |  `false`   |
| field-names               | Customize fields in `TagData`                             | `InputTagFieldNames`                              |    `-`     |
| tag-nowrap                | Tag content does not wrap                                 | `boolean`                                         |  `false`   |

### `<input-tag>` Events

| Event              | Description                                   | Arguments                                               |
| ------------------ | --------------------------------------------- | ------------------------------------------------------- |
| change             | Emitted when the value changes                | value: `(string \| number \| TagData)[]`<br>ev: `Event` |
| input-value-change | Emitted when the input value changes          | inputValue: `string`<br>ev: `Event`                     |
| press-enter        | Emitted when Enter is pressed                 | inputValue: `string`<br>ev: `KeyboardEvent`             |
| remove             | Emitted when a tag's remove button is clicked | removed: `string \| number`<br>ev: `Event`              |
| clear              | Emitted when the clear button is clicked      | ev: `MouseEvent`                                        |
| focus              | Emitted when the input gains focus            | ev: `FocusEvent`                                        |
| blur               | Emitted when the input loses focus            | ev: `FocusEvent`                                        |

### `<input-tag>` Methods

| Method | Description     | Arguments | Returns |
| ------ | --------------- | --------- | ------- |
| focus  | Focus the input | -         | -       |
| blur   | Blur the input  | -         | -       |

### `<input-tag>` Slots

| Slot   |         Description         | Arguments       |
| ------ | :-------------------------: | --------------- |
| tag    | Displayed input-tag content | data: `TagData` |
| prefix |       Prefix content        | -               |
| suffix |       Suffix content        | -               |

### TagData

| Parameter | Description      | Type               | Default |
| --------- | ---------------- | ------------------ | :-----: |
| value     | Tag value        | `string \| number` |   `-`   |
| label     | Tag content      | `string`           |   `-`   |
| closable  | Whether closable | `boolean`          | `false` |
| tagProps  | Tag props        | `TagProps`         |   `-`   |

### Type definitions

The component exports the following types

```ts
import type { InputTagInstance } from "@cedar-design/ui";
```

## Removing legacy InputTag icon references

Cedar InputTag embeds Tag's actual close-btn and renders no old c-icon-hover pseudo-element. The old mixin import, default/focus pseudo-element backgrounds and duplicate custom Tag text rules are removed; Tag owns its text. Existing close-button appearance, click removal and readonly/disabled behavior remain, without a new hover background.

Both libraries remove tag-custom-icon-bg-hover; Cedar also removes input-tag-tag-remove-icon-color-bg / input-tag-tag-remove-icon-color-bg-focus. Unused variables have no replacements; remove ineffective overrides. No aliases remain. Maple has no InputTag component and only synchronizes shared Tag-variable cleanup.

The former cross-component exemptions are closed. check:token-consumers checks 414 Badge/Tag declarations without exemptions and compiles InputTag to prevent legacy icon selectors/variables returning. Integration tests cover actual DOM, close interactions and custom colors. The 553 shared defaults are unchanged because removed shared variables previously registered names only. This does not claim complete InputTag token, browser-visual or keyboard governance.

## InputTag wrapper and content responsibilities

FieldDecorator owns InputTag outline / filled / standard wrappers. Form must not redraw backgrounds, borders or focus shadows; old Form overrides for obsolete InputTag state classes are removed, while validation messages remain. filled default/hover/focus still use FieldDecorator fill-1 / fill-2 / fill-3.

input-tag-* controls content density, default tag backgrounds and disabled text. Selectors match actual c-field-decorator--size-* / --focus / --disabled classes rather than nonexistent old InputTag classes; disabled overrides focus. All xs/sm/md/lg/xl sizes are covered. xl uses 32px tags, 16px input text and 4px vertical padding.

Removed 33 unused wrapper variables: size-{xs,sm,md,lg}-height; color-text-error; color-placeholder, color-icon-clear, color-icon-clear-bg-hover; color-border-{default,error,disabled} and -hover/-focus forms; color-bg-{default,error}, their -hover/-focus forms, color-bg-disabled and its -hover form; color-shadow-{default,error}-focus; size-shadow-{default,error}-focus; border-radius, border-width, size-icon-clear and size-icon-clear-hover. All use --c-input-tag-. No compatibility aliases remain.

Migrate by responsibility: field-variant-{variant}-background for wrapper backgrounds; field-border-radius for corners; field-placeholder-text-color for placeholders; field-clear-icon-color / field-clear-icon-size for clear icons. Prefer size for geometry; do not override internal variables. Unused legacy variables have no one-to-one replacement. Tag content uses the InputTag variables below.

InputTag retains 27 content variables in unused-consumer checks. Both libraries’ Badge/Tag plus Cedar InputTag cover 441 declarations and 80 size/focus/disabled cascades. The shared-default contract remains 553 entries; Cedar-only InputTag is not a cross-platform shared component. Default text, disabled text, tag backgrounds and focused backgrounds use content-primary, content-disabled, surface-default and state-hover. Disabled restyles neutral tags only, preserving explicit color/status; business themes own custom-color contrast. Parent disabled/readonly overrides tagProps.closable/checkable. Loading or explicitly nonclosable tags cannot be removed with Backspace. Cedar spot checks cover five sizes, xl input/keyboard removal, light/dark modes and disabled custom colors, not a complete visual audit.

### Current content variables

| Variable                                  | Default                               |
| ----------------------------------------- | ------------------------------------- |
| `--c-input-tag-size-xs-tag-height`        | `20px`                                |
| `--c-input-tag-size-sm-tag-height`        | `20px`                                |
| `--c-input-tag-size-md-tag-height`        | `24px`                                |
| `--c-input-tag-size-lg-tag-height`        | `28px`                                |
| `--c-input-tag-size-xl-tag-height`        | `32px`                                |
| `--c-input-tag-size-xs-font-size`         | `12px`                                |
| `--c-input-tag-size-sm-font-size`         | `14px`                                |
| `--c-input-tag-size-md-font-size`         | `14px`                                |
| `--c-input-tag-size-lg-font-size`         | `14px`                                |
| `--c-input-tag-size-xl-font-size`         | `16px`                                |
| `--c-input-tag-color-text-default`        | `var(--c-sys-color-content-primary)`  |
| `--c-input-tag-color-text-disabled`       | `var(--c-sys-color-content-disabled)` |
| `--c-input-tag-tag-margin-right`          | `4px`                                 |
| `--c-input-tag-tag-margin-y`              | `2px`                                 |
| `--c-input-tag-padding-x`                 | `4px`                                 |
| `--c-input-tag-size-xs-padding-y`         | `0px`                                 |
| `--c-input-tag-size-sm-padding-y`         | `2px`                                 |
| `--c-input-tag-size-md-padding-y`         | `2px`                                 |
| `--c-input-tag-size-lg-padding-y`         | `2px`                                 |
| `--c-input-tag-size-xl-padding-y`         | `4px`                                 |
| `--c-input-tag-tag-font-size`             | `12px`                                |
| `--c-input-tag-tag-color-bg`              | `var(--c-sys-color-surface-default)`  |
| `--c-input-tag-tag-color-bg-focus`        | `var(--c-sys-color-state-hover)`      |
| `--c-input-tag-tag-color-bg-disabled`     | `var(--c-sys-color-state-hover)`      |
| `--c-input-tag-tag-color-border`          | `var(--c-color-fill-3)`               |
| `--c-input-tag-tag-color-border-disabled` | `var(--c-color-fill-3)`               |
| `--c-input-tag-tag-color-border-focus`    | `var(--c-sys-color-state-hover)`      |

### Form field presentation and confirmation

This component supports `edit-mode` with field > FormItem > Form precedence. When unset, it defaults to `direct` and preserves `direct` editing. Supported values: `direct / click / dblclick`. Non-`direct` modes open the editor through the field value trigger and keep one draft; v-model updates only after confirmation. Cancel, reset or enabling readPretty discards the draft.

Cedar uses edit-mode="click" / "dblclick" to open an editor popup near the field. Enter/F2 also opens it; cancel/Escape discards the draft, and confirmation commits it. readPretty is an independent reading setting, separate from readonly and disabled.

`before-commit(value, { previousValue, signal })` can reject an overlay save. FormItem validates the candidate first and keeps the editor open on failure. `open / default-open / update:open` control the editor. Use `#read="{ value, text }"` to customize display. See the full field comparison in Form.

`read-pretty` is an independent boolean alongside `readonly` and `disabled`. It inherits from field to FormItem to Form; explicit `false` overrides the parent. The default is `false`. Reading mode renders no editor.

## Configuring the cleared value

`empty-value` / `emptyValue` sets the model value produced by clearing. It accepts a value in the component model type or a zero-argument factory. Omission preserves the existing default; use `() => undefined` to distinguish omission from returning undefined. Arrays are shallow-copied on every clear; selected items that cannot be cleared remain. It does not redefine emptiness, alter Form reset defaults or treat 0/false as universally empty.

`empty-value` accepts explicit `null` (or `() => null`). Clearing publishes `null` unchanged; omitted values preserve the existing default. Editors render `null` as blank without converting ordinary empty-string input to `null`. In popup editing, clearing changes the draft; confirm commits it and cancel preserves the original model.

---

Document: llms/en-US/components/input.md

<!-- Source: src/input/README.en-US.md; locale: en-US; page: /en/components/input/ -->

# Input

Text input with controlled and uncontrolled values.

## Reading direction

The input inherits `dir` from its page or local scope. Affixes, clear actions and input groups follow reading order. Runtime changes retain the native editor, focus and selection; the browser handles caret movement, mixed text and composition without swapping editing keys. Parent rerenders preserve the native composition buffer; older selection-restoration tasks do not overwrite a newer composition.

## Basic examples

### Control Sizes

- `size`: Controls the component size.
- `variant`: Selects the visual variant.

Example source: src/field-decorator/__demos__/control-sizes.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
const sizes = ["xs", "sm", "md", "lg", "xl"] as const;
const variants = ["outline", "filled", "standard"] as const;
const size = ref<(typeof sizes)[number]>("md");
const variant = ref<(typeof variants)[number]>("outline");
const options = [
  { value: "beijing", label: "Beijing" },
  { value: "shanghai", label: "Shanghai" },
];
const cascaderOptions = [{ value: "china", label: "China", children: options }];

const inputValue = ref("Beijing");
const selectValue = ref("beijing");
const cascaderValue = ref("beijing");
const selectMultiple = ref(["beijing", "shanghai"]);
const cascaderMultiple = ref(["beijing", "shanghai"]);
const selectOverflow = ref(["long", "beijing", "shanghai"]);
const cascaderOverflow = ref(["long", "beijing", "shanghai"]);
const selectedOptions = [
  ...options,
  {
    value: "long",
    label:
      "A very long selected option label for overflow comparison — full text preview keeps the selected value unchanged.",
  },
];
const selectedCascaderOptions = [
  { value: "china", label: "China", children: selectedOptions },
];
function resetSelections() {
  inputValue.value = "Beijing";
  selectValue.value = "beijing";
  cascaderValue.value = "beijing";
  selectMultiple.value = ["beijing", "shanghai"];
  cascaderMultiple.value = ["beijing", "shanghai"];
  selectOverflow.value = ["long", "beijing", "shanghai"];
  cascaderOverflow.value = ["long", "beijing", "shanghai"];
}
</script>
<template>
  <section
    aria-label="Form control size comparison"
    class="control-size-comparison"
  >
    <c-space wrap :size="12">
      <c-radio-group v-model="size" aria-label="Comparison size">
        <c-radio v-for="item in sizes" :key="item" :value="item">{{
          item
        }}</c-radio>
      </c-radio-group>
      <c-radio-group v-model="variant" aria-label="Comparison variant">
        <c-radio v-for="item in variants" :key="item" :value="item">{{
          item
        }}</c-radio>
      </c-radio-group>
    </c-space>
    <div class="control-size-comparison__grid">
      <div data-control="Input">
        <p>Input</p>
        <c-input :size="size" :variant="variant" placeholder="Input" />
      </div>
      <div data-control="Button">
        <p>Button</p>
        <c-button :size="size" variant="outline">Button</c-button>
      </div>
      <div data-control="Select">
        <p>Select</p>
        <c-select
          :size="size"
          :variant="variant"
          :options="options"
          placeholder="Select"
        />
      </div>
      <div data-control="Date">
        <p>Date</p>
        <c-date :size="size" :variant="variant" placeholder="Date" />
      </div>
      <div data-control="Time">
        <p>Time</p>
        <c-time :size="size" :variant="variant" placeholder="Time" />
      </div>
      <div data-control="InputNumber">
        <p>InputNumber</p>
        <c-input-number :size="size" :variant="variant" placeholder="Number" />
      </div>
      <div data-control="AutoComplete">
        <p>AutoComplete</p>
        <c-auto-complete
          :size="size"
          :variant="variant"
          :options="options"
          placeholder="AutoComplete"
        />
      </div>
      <div data-control="Cascader">
        <p>Cascader</p>
        <c-cascader
          :size="size"
          :variant="variant"
          :options="cascaderOptions"
          placeholder="Cascader"
        />
      </div>
      <div data-control="DateRange">
        <p>DateRange</p>
        <c-date-range
          :size="size"
          :variant="variant"
          :placeholder="['Start', 'End']"
        />
      </div>
      <div data-control="TimeRange">
        <p>TimeRange</p>
        <c-time-range
          :size="size"
          :variant="variant"
          :placeholder="['Start', 'End']"
        />
      </div>
    </div>

    <section
      aria-label="Selected control size comparison"
      class="control-size-comparison__states"
    >
      <c-space wrap align="center" :size="12">
        <span>Selected / Clearable / Multiple — 有值、可清空与多选不换行</span>
        <span
          >Hover or focus truncated text; tap on touch screens /
          悬停或聚焦省略正文查看全文；触屏点按查看，点外部关闭</span
        >
        <c-button size="sm" variant="outline" @click="resetSelections"
          >Reset / 恢复选中值</c-button
        >
      </c-space>
      <div class="control-size-comparison__grid">
        <div data-control="InputValue">
          <p>Input · clearable</p>
          <c-input
            v-model="inputValue"
            :size="size"
            :variant="variant"
            clearable
            placeholder="Input value"
          />
        </div>
        <div data-control="ButtonReference">
          <p>Button · reference</p>
          <c-button :size="size" variant="outline">Button</c-button>
        </div>
        <div data-control="SelectValue">
          <p>Select · clearable</p>
          <c-select
            v-model="selectValue"
            :size="size"
            :variant="variant"
            :options="selectedOptions"
            clearable
            placeholder="Select value"
          />
        </div>
        <div data-control="CascaderValue">
          <p>Cascader · clearable</p>
          <c-cascader
            v-model="cascaderValue"
            :size="size"
            :variant="variant"
            :options="selectedCascaderOptions"
            clearable
            placeholder="Cascader value"
          />
        </div>
        <div data-control="SelectMultiple">
          <p>Select · multiple / nowrap</p>
          <c-select
            v-model="selectMultiple"
            :size="size"
            :variant="variant"
            :options="selectedOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Select multiple"
          />
        </div>
        <div data-control="CascaderMultiple">
          <p>Cascader · multiple / nowrap</p>
          <c-cascader
            v-model="cascaderMultiple"
            :size="size"
            :variant="variant"
            :options="selectedCascaderOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Cascader multiple"
          />
        </div>
        <div data-control="SelectOverflow">
          <p>Select · long values / nowrap</p>
          <c-select
            v-model="selectOverflow"
            edit-mode="direct"
            :size="size"
            :variant="variant"
            :options="selectedOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Select long values"
          />
        </div>
        <div data-control="CascaderOverflow">
          <p>Cascader · long values / nowrap</p>
          <c-cascader
            v-model="cascaderOverflow"
            edit-mode="direct"
            :size="size"
            :variant="variant"
            :options="selectedCascaderOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Cascader long values"
          />
        </div>
      </div>
    </section>
  </section>
</template>
<style scoped>
.control-size-comparison,
.control-size-comparison__states {
  display: grid;
  gap: 24px;
}
.control-size-comparison__grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
  align-items: start;
  gap: 24px 16px;
}
.control-size-comparison__grid > div {
  min-width: 0;
}
.control-size-comparison__grid p {
  margin: 0 0 12px;
  font-size: 14px;
  line-height: 20px;
}
.control-size-comparison__grid :deep(.c-input-number),
.control-size-comparison__grid :deep(.c-auto-complete) {
  width: 100%;
}
</style>
```

Example source: src/input/__demos__/basic.vue

```vue
<template>
  <c-space direction="column">
    <c-input placeholder="请输入1" clearable variant="outline" />
    <c-input placeholder="请输入1" clearable variant="filled" />
  </c-space>
</template>
```

## Appearance and states

### Appearance configuration comparison

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration | Purpose                                  | Related examples             |
| ------------- | ---------------------------------------- | ---------------------------- |
| `placeholder` | Hint text                                | Form Feedback, Floating Hint |
| `hint`        | Whether hint text floats                 | Form Feedback, Floating Hint |
| `clearable`   | Whether to allow the input to be cleared | Form Feedback, Floating Hint |
| `variant`     | Field appearance                         | Floating Hint                |

<!-- demo-config-notes:end -->

Choose an axis to compare its available values with the same content and model. Other settings remain unchanged while comparing.

Example source: src/input/__demos__/appearance-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref("示例内容");
const __demoAppearance = __demoReactive({ variant: "filled", size: "md" });

import { computed as demoComputed, ref as demoRef } from 'vue'
const demoCompareFields = [{"name":"variant","values":["filled","outline","standard"]},{"name":"size","values":["xs","sm","md","lg","xl"]}]
const demoCompareAxis = demoRef("variant")
const demoComparedOptions = demoComputed(() => demoCompareFields.find(field => field.name === demoCompareAxis.value)?.values ?? [])
</script>
<template>
  <c-space direction="column" :size="16">
    <c-form layout="vertical">
      <c-form-item layout="vertical" size="sm" label="variant">
        <c-radio-group
          v-model="__demoAppearance['variant']"
          aria-label="variant"
          :options="[
            { label: 'filled', value: 'filled' },
            { label: 'outline', value: 'outline' },
            { label: 'standard', value: 'standard' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
      <c-form-item layout="vertical" size="sm" label="size">
        <c-radio-group
          v-model="__demoAppearance['size']"
          aria-label="size"
          :options="[
            { label: 'xs', value: 'xs' },
            { label: 'sm', value: 'sm' },
            { label: 'md', value: 'md' },
            { label: 'lg', value: 'lg' },
            { label: 'xl', value: 'xl' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
    </c-form>
    <p class="demo-config-comparison-hint"><span lang="zh-CN">选择一个对比维度；其他配置和内容保持一致。输入类示例共享同一个值，便于比较外观。</span><span lang="en-US">Compare one dimension while keeping the other settings and content identical. Input specimens share the same value.</span></p>
<c-radio-group v-model="demoCompareAxis" aria-label="Compare configuration" :options="demoCompareFields.map(field => ({ label: field.name, value: field.name }))" />
<div class="demo-config-comparison">
<section v-for="sample in demoComparedOptions" :key="String(sample)">
<p><code>{{ demoCompareAxis }}={{ sample }}</code></p>
<c-input v-model="value" v-bind="{ ...__demoAppearance, [demoCompareAxis]: sample }"></c-input>
</section>
</div>
  </c-space>
</template>

<style scoped>
.demo-config-comparison { display: grid; grid-template-columns: repeat(auto-fit, minmax(min(100%, 220px), 1fr)); gap: 20px; min-width: 0; max-width: 100%; }
.demo-config-comparison > section { min-width: 0; }
.demo-config-comparison p { margin: 0 0 8px; }
html:not([lang='en-US']) .demo-config-comparison-hint > [lang='en-US'],
html[lang='en-US'] .demo-config-comparison-hint > [lang='zh-CN'] { display: none; }
</style>
```

### Form Feedback

Example source: src/input/__demos__/form-feedback.vue

```vue
<template>
  <c-form :model="model">
    <c-form-item field="account" label="账户" feedback :validate-status="status" :help="status === 'error' ? '请输入账户后重试' : undefined">
      <c-input v-model="model.account" placeholder="外置标签会关闭内部浮动提示" hint clearable />
    </c-form-item>
    <c-button status="primary" :loading="status === 'validating'" @click="validate">模拟异步校验</c-button>
  </c-form>
</template>

<script setup lang="ts">
import { reactive, ref } from 'vue'

const model = reactive({ account: '' })
const status = ref<'validating' | 'success' | 'error'>()
let request = 0
async function validate() {
  const current = ++request
  const value = model.account
  status.value = 'validating'
  await new Promise((resolve) => setTimeout(resolve, 500))
  if (current === request) status.value = value.trim() ? 'success' : 'error'
}
</script>
```

### Floating Hint

- `variant`: Selects the visual variant.

Example source: src/input/__demos__/floating-hint.vue

```vue
<template>
  <c-space direction="column" style="width: 100%">
    <c-input v-model="name" hint placeholder="姓名" clearable />
    <c-input v-model="email" hint variant="standard" placeholder="邮箱" />
    <c-input v-model="phone" hint placeholder="带前缀的电话" clearable><template #prefix>+86</template></c-input>
  </c-space>
</template>

<script setup lang="ts">
import { ref } from 'vue'

const name = ref('')
const email = ref('')
const phone = ref('')
</script>
```

## Input content and layout

### Word Limit

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration     | Purpose                                                                          | Related examples                |
| ----------------- | -------------------------------------------------------------------------------- | ------------------------------- |
| `placeholder`     | Hint text                                                                        | Word Limit, Prefix, Group       |
| `clearable`       | Whether to allow the input to be cleared                                         | Word Limit, Prefix, Group State |
| `max-length`      | Maximum input length                                                             | Word Limit                      |
| `show-word-limit` | Show the character counter                                                       | Word Limit                      |
| `default-value`   | Uncontrolled initial value; read only at creation, never written into the parent | Group State                     |
| `disabled`        | Disabled state; can inherit from Form                                            | Group State                     |

<!-- demo-config-notes:end -->

Example source: src/input/__demos__/word-limit.vue

```vue
<template>
  <c-space direction="column">
    <c-input v-model="normalValue" :max-length="10" clearable show-word-limit placeholder="超出后截断" />
    <c-input
      v-model="errorOnlyValue"
      :max-length="{ length: 6, errorOnly: true }"
      show-word-limit
      placeholder="允许超出，但标记错误"
    />
  </c-space>
</template>

<script setup lang="ts">
import { ref } from 'vue'

const normalValue = ref('Cedar')
const errorOnlyValue = ref('超过六个字符后显示错误')
</script>
```

### Password

Example source: src/input/__demos__/password.vue

```vue
<template>
  <c-space direction="column">
    <c-input-password />
  </c-space>
</template>
```

### Prefix

Example source: src/input/__demos__/prefix.vue

```vue
<template>
  <c-space direction="column">
    <c-input :style="{ width: '320px' }" placeholder="请输入">
      <template #prefix> +86 </template>
    </c-input>
    <c-input :style="{ width: '320px' }" placeholder="请输入">
      <template #suffix> RMB </template>
    </c-input>
    <c-input
      v-model="clearableValue"
      :style="{ width: '320px' }"
      clearable
      placeholder="自定义清除图标"
    >
      <template #clear-icon="{ clear }">
        <c-button
          html-type="button"
          class="prefix-demo__clear"
          aria-label="清空"
          @click="clear"
          >清空</c-button
        >
      </template>
    </c-input>
  </c-space>
</template>

<script setup lang="ts">
import { ref } from "vue";

const clearableValue = ref("Cedar");
</script>

<style scoped>
.prefix-demo__clear {
  border: 0;
  background: transparent;
  color: var(--color-text-2);
  cursor: pointer;
  font-size: 12px;
}
</style>
```

### Group

Example source: src/input/__demos__/group.vue

```vue
<template>
  <c-space direction="column">
    <c-radio-group v-model="variant">
      <c-radio value="filled">filled</c-radio>
      <c-radio value="outline">outline</c-radio>
      <c-radio value="standard">standard</c-radio>
    </c-radio-group>
    <c-input-group :variant="variant">
      <c-input :style="{ width: '160px' }" placeholder="first" />
      <c-input :style="{ width: '320px' }" placeholder="second" />
    </c-input-group>
    <c-input-group :variant="variant">
      <c-select :options="['Option1', 'Option2', 'Option3']" :style="{ width: '160px' }" placeholder="first" />
      <c-input :style="{ width: '320px' }" placeholder="second" />
    </c-input-group>

    <c-input-group :variant="variant">
      <c-select :options="['Option1', 'Option2', 'Option3']" :style="{ width: '160px' }" placeholder="first" />
      <c-auto-complete :style="{ width: '320px' }" placeholder="second" />
    </c-input-group>
    <c-input-group :variant="variant">
      <c-input-group-label>text</c-input-group-label>
      <c-input :style="{ width: '320px' }" placeholder="second" />
      <c-button status="primary">label</c-button>
    </c-input-group>
  </c-space>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
const variant = ref('filled')
</script>
```

### Group State

- `disabled`: Prevents user interaction.
- `readonly`: Displays the current value without allowing edits.

Example source: src/input/__demos__/group-state.vue

```vue
<template>
  <c-space direction="column" style="width: 100%">
    <c-space>
      <c-button variant="outline" @click="disabled = !disabled">{{ disabled ? '启用组合' : '禁用组合' }}</c-button>
      <c-button variant="outline" @click="readonly = !readonly">{{ readonly ? '允许编辑' : '组合只读' }}</c-button>
    </c-space>
    <c-input-group variant="outline" :disabled="disabled" :readonly="readonly" :hint="false">
      <c-input-group-label>https://</c-input-group-label>
      <c-input v-model="domain" placeholder="输入域名" clearable />
      <c-input-group-label>.com</c-input-group-label>
    </c-input-group>
    <c-input-group variant="filled" :disabled="disabled" :readonly="readonly" :hint="false">
      <c-input v-model="first" placeholder="继承组合状态" clearable />
      <c-input default-value="可独立编辑" :disabled="false" :readonly="false" clearable />
    </c-input-group>
    <c-input-group size="lg" variant="outline" :disabled="disabled" :readonly="readonly" :hint="false">
      <c-input-group-label>密码</c-input-group-label>
      <c-input-password v-model="password" placeholder="密码切换继承禁用状态" clearable />
    </c-input-group>
  </c-space>
</template>

<script setup lang="ts">
import { ref } from 'vue'

const disabled = ref(false)
const readonly = ref(false)
const domain = ref('example')
const first = ref('继承状态')
const password = ref('CedarMaple')
</script>
```

## Value model and interaction

### Default Value

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration   | Purpose                                                                          | Related examples             |
| --------------- | -------------------------------------------------------------------------------- | ---------------------------- |
| `clearable`     | Whether to allow the input to be cleared                                         | Event Pipeline, TypeScript   |
| `default-value` | Uncontrolled initial value; read only at creation, never written into the parent | Default Value                |
| `aria-label`    | Native input accessible label                                                    | Default Value                |
| `disabled`      | Disabled state; can inherit from Form                                            | Interaction state comparison |
| `readonly`      | Readonly state; can inherit from Form                                            | Interaction state comparison |
| `error`         | Error state; can inherit from FormItem                                           | Interaction state comparison |

<!-- demo-config-notes:end -->

Example source: src/input/__demos__/default-value.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'

withDefaults(defineProps<{ english?: boolean }>(), { english: false })
const seed = ref('A: initial text')
const instanceKey = ref(0)
const lastUpdate = ref<string | null>(null)
const updateCount = ref(0)
const controlled = ref('')
function record(value: string) {
  lastUpdate.value = value
  updateCount.value += 1
}
function remount() {
  instanceKey.value += 1
  lastUpdate.value = null
  updateCount.value = 0
}
</script>

<template>
  <div>
    <p>
      {{
        english
          ? '1. Uncontrolled: defaultValue supplies the initial text. Typing updates the component itself; the seed below stays unchanged.'
          : '1. 非受控：defaultValue 提供初始文字。输入后由组件自己保存新值，下方的默认值变量不会随之变化。'
      }}
    </p>
    <c-input :key="instanceKey" :default-value="seed" aria-label="Uncontrolled input" @update:model-value="record" />
    <p>
      defaultValue = <code>{{ seed }}</code>
    </p>
    <p role="status">
      update:modelValue × {{ updateCount }}; {{ english ? 'last emitted value' : '最近一次用户更新' }} =
      <code>{{ lastUpdate === null ? (english ? '(none)' : '（尚未触发）') : JSON.stringify(lastUpdate) }}</code>
    </p>
    <c-space wrap>
      <c-button @click="seed = seed.startsWith('A:') ? 'B: new default' : 'A: initial text'">{{
        english ? 'Change defaultValue only' : '仅修改 defaultValue'
      }}</c-button>
      <c-button @click="remount">{{ english ? 'Remount input' : '重新挂载输入框' }}</c-button>
    </c-space>
    <p>
      {{
        english
          ? 'Try typing, then change defaultValue: the current text stays. Remount to read the latest defaultValue. Initialization never emits update:modelValue.'
          : '操作顺序：先输入，再修改 defaultValue，当前文字不会被覆盖；点击重新挂载后，才读取最新的默认值。初始化不会触发 update:modelValue。'
      }}
    </p>
    <p>
      {{
        english
          ? '2. Controlled: v-model is the source of truth. Its initial empty string takes precedence over defaultValue.'
          : '2. 受控：v-model 是数据来源。这里初始值为空字符串，仍优先于 defaultValue，不会自动填入默认文字。'
      }}
    </p>
    <c-input v-model="controlled" default-value="This default is ignored" aria-label="Controlled input" />
    <p role="status">
      v-model = <code>{{ JSON.stringify(controlled) }}</code>
    </p>
    <c-space wrap>
      <c-button @click="controlled = 'Parent supplied text'">{{
        english ? 'Update parent value' : '从父级设置值'
      }}</c-button>
      <c-button @click="controlled = ''">{{ english ? 'Clear parent value' : '清空父级值' }}</c-button>
    </c-space>
    <p>
      {{
        english
          ? 'For a form, initialize the bound field in the parent. defaultValue does not write an initial value into the parent form.'
          : '表单需要初始值时，请初始化父级绑定字段。defaultValue 不会把初始值写入父级表单。'
      }}
    </p>
  </div>
</template>
```

### Clear icon and manual deletion

Set clear output to null. Clear with the icon, restore the initial value, then delete all text with Backspace. The model shows null for the icon and an empty string for manual deletion.

Example source: src/input/__demos__/en-US/empty-value.vue

```vue
<script setup lang="ts">
import { reactive } from "vue";
const model = reactive({ text: "Hello" as string | null });
</script>
<template>
  <c-space direction="column">
    <p>
      The clear icon produces null; Backspace to empty produces an empty string.
    </p>
    <c-form :model="model" layout="vertical">
      <c-form-item field="text" label="Keyword">
        <c-input
          v-model="model.text"
          edit-mode="direct"
          clearable
          :empty-value="null"
        />
      </c-form-item>
    </c-form>
    <c-button @click="model.text = 'Hello'">Restore initial value</c-button>
    <p>
      Current model: <output>{{ JSON.stringify(model.text) }}</output>
    </p>
  </c-space>
</template>
```

### Interaction state comparison

Toggle the state, interact with the component, and restore editing using the controls outside the specimen. Error appearance alone does not run validation.

Example source: src/input/__demos__/state-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref("示例内容");
const __demoState = __demoReactive({
  disabled: false,
  readonly: false,
  error: false,
});
</script>
<template>
  <c-space direction="column" :size="16">
    <c-space wrap>
      <c-checkbox v-model="__demoState['disabled']">disabled</c-checkbox>
      <c-checkbox v-model="__demoState['readonly']">readonly</c-checkbox>
      <c-checkbox v-model="__demoState['error']">error</c-checkbox>
    </c-space>
    <c-input v-model="value" v-bind="__demoState"></c-input>
  </c-space>
</template>
```

### Event Pipeline

Example source: src/input/__demos__/event-pipeline.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const value = ref('可编辑内容')
const events = ref<string[]>([])
const record = (name: string) => { events.value = [...events.value.slice(-7), name] }
</script>
<template>
  <div class="input-pipeline-demo">
    <c-input v-model="value" clearable placeholder="输入后尝试清空" @clear="record('clear')" @input="record('input')" @update:model-value="record('update:modelValue')" @change="record('change')" />
    <p>输入：input → update；清空：clear → input → update → change。</p>
    <output>{{ events.join(' → ') || '等待操作' }}</output>
  </div>
</template>
<style scoped>
.input-pipeline-demo { display: flex; flex-direction: column; gap: 12px; }
.input-pipeline-demo p { margin: 0; }
</style>
```

### Commit approval

`empty-value` accepts explicit `null` (or `() => null`). Clearing publishes null unchanged; omitted values preserve the existing default. Editors render null as blank without converting ordinary empty-string input to null. In popup editing, clearing changes the draft; confirm commits it and cancel preserves the original model.

Cancellable hooks use `(payload, done, context)`: closure payloads contain `{ action }`, change/commit payloads contain `{ value, previousValue }`, and Popup uses `{ reason }`. Context provides `signal` and an optional original `event`. Return a boolean/Promise, or call done()/done(false). Synchronous void waits for done; Promise&lt;void&gt; allows the operation. First completion wins. Pending state controls loading/disabled automatically. Cancellation invalidates stale results. Button refs are not exposed.

Example source: src/input/__demos__/en-US/commit-protocol.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
const value = ref<string | null>("Project A");
const message = ref("");
async function beforeCommit(
  { value: next, previousValue }: { value: unknown; previousValue: unknown },
  _done: (allow?: boolean) => void,
  { signal }: { signal: AbortSignal },
) {
  if (next === previousValue) return true;
  await new Promise((resolve) => setTimeout(resolve, 500));
  if (signal.aborted) return false;
  message.value = `Saved: ${String(next)}`;
  return true;
}
</script>
<template>
  <c-space direction="column">
    <c-input
      v-model="value"
      edit-mode="click"
      clearable
      :empty-value="null"
      :before-commit="beforeCommit"
    />
    <p role="status">{{ message }}</p>
  </c-space>
</template>
```

### Shared field loading

`loading` displays the shared field indicator. `loading-mode` is `default` (indicator) or `line` (an indeterminate bottom line); it defaults to `default`. Rendering belongs to FieldDecorator. Loading does not implicitly disable editing or change readonly. Set those states separately.

## Loading and waiting

### Loading

Toggle loading to compare the default indicator and bottom line. The input remains editable while loading.

Example source: src/input/__demos__/loading.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const busy = ref(true)
const value = ref('加载时仍可编辑')
</script>
<template>
  <c-space direction="column" :size="16" style="width: 100%">
    <c-form layout="vertical">
      <c-form-item label="加载状态 / Loading"><c-switch v-model="busy" /></c-form-item>
      <c-form-item label="默认指示器 / Default"><c-input v-model="value" :loading="busy" placeholder="加载时仍可编辑 / Editable while loading" loading-mode="default" /></c-form-item>
      <c-form-item label="底部加载线 / Line"><c-input v-model="value" :loading="busy" placeholder="加载时仍可编辑 / Editable while loading" loading-mode="line" /></c-form-item>
    </c-form>
    <p>切换加载状态；加载时仍可输入和清空。Loading keeps the input editable.</p>
  </c-space>
</template>
```

## API

### Empty values and reading placeholders

`empty-values` recognizes empty data; `empty-value` keeps existing clear output. `empty-text` defaults to `'-'` under `read-pretty`, with Field > FormItem > Form precedence and custom read slots first. With explicit empty-values, built-in required uses the policy; custom validators receive original data. See the [shared guide](llms/en-US/guide/empty-values.md).

| Prop         | Type               | Default and scope                                                           |
| ------------ | ------------------ | --------------------------------------------------------------------------- |
| empty-values | readonly unknown[] | Field > FormItem > Form > component-family default; replaces the whole list |
| empty-text   | string             | Field > FormItem > Form > '-'; explicit '' is valid                         |

These props belong to field presentation; pure panels do not gain reading mode. Form and FormItem provide inherited settings. The existing empty-value type and clear fallback remain component-specific.

### `<Input>` Props

| Parameter                 | Description                                                                       | Type                                                |   Default   |
| ------------------------- | --------------------------------------------------------------------------------- | --------------------------------------------------- | :---------: |
| model-value **(v-model)** | Bound value                                                                       | `string \| null`                                    |     `-`     |
| `loading` | Loading presentation; keeps the input editable | `boolean` | `false` |
| `loading-mode` | Loading layout: default indicator or bottom line | `default / line` | `default` |
| model-modifiers           | `v-model` modifiers; supports `trim`                                              | `{ trim?: boolean }`                                |    `{}`     |
| default-value             | Uncontrolled initial value; read only at creation, never written into the parent  | `string`                                            |    `''`     |
| variant                   | Field appearance                                                                  | `'filled' \| 'outline' \| 'standard'`               | `'outline'` |
| size                      | Input size                                                                        | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'`              |   `'md'`    |
| clearable                 | Whether to allow the input to be cleared                                          | `boolean`                                           |   `false`   |
| empty-value               | Clear output; omission clears to an empty string and manual deletion is unchanged | `string \| null \| (() => string \| null)`          | `undefined` |
| disabled                  | Disabled state; can inherit from Form                                             | `boolean`                                           |     `-`     |
| readonly                  | Readonly state; can inherit from Form                                             | `boolean`                                           |     `-`     |
| error                     | Error state; can inherit from FormItem                                            | `boolean`                                           |     `-`     |
| placeholder               | Hint text                                                                         | `string`                                            |     `-`     |
| hint                      | Whether hint text floats                                                          | `boolean`                                           |   `false`   |
| line                      | Whether to draw a border or underline                                             | `boolean`                                           |   `true`    |
| text-color                | Input text color                                                                  | `string`                                            |     `-`     |
| focus-color               | Focused hint and supported border colors; does not control the caret              | `string`                                            |     `-`     |
| blur-color                | Unfocused hint color                                                              | `string`                                            |     `-`     |
| aria-label                | Native input accessible label                                                     | `string`                                            |     `-`     |
| autofocus                 | Focus automatically after mount                                                   | `boolean`                                           |   `false`   |
| enterkeyhint              | Mobile virtual-keyboard enter-key hint                                            | `string`                                            |     `-`     |
| max-length                | Maximum input length                                                              | `number \| { length: number; errorOnly?: boolean }` |     `0`     |
| show-word-limit           | Show the character counter                                                        | `boolean`                                           |   `false`   |
| word-length               | Length-counting function                                                          | `(value: string) => number`                         |     `-`     |
| word-slice                | Text-slicing function, used with wordLength                                       | `(value: string, maxLength: number) => string`      |     `-`     |
| input-attrs               | Attributes for the internal input element                                         | `object`                                            |     `-`     |

`disabled / readonly / size` resolve from child → InputGroup → FormItem/Form → library defaults; Cedar size also supports ConfigProvider. `clearable` applies only to nonempty editable inputs: PC shows it on hover/focus, while touch devices and Maple keep it visible. Native name/id/aria-_/data-_ reach the input; class/style stay on the wrapper. `input-attrs` cannot override controlled value, type, disabled/readonly state or length policy.

### `<Input>` Events

| Event       | Description                                   | Arguments                      |
| ----------- | --------------------------------------------- | ------------------------------ |
| input       | Emitted on user input                         | value: `string`<br>ev: `Event` |
| change      | Emitted on blur, Enter submission or clearing | value: `string`<br>ev: `Event` |
| press-enter | Emitted when the user presses Enter           | ev: `KeyboardEvent`            |
| clear       | Emitted when the user clicks the clear button | ev: `MouseEvent`               |
| focus       | Emitted when the input gains focus            | ev: `FocusEvent`               |
| blur        | Emitted when the input loses focus            | ev: `FocusEvent`               |

### `<Input>` Methods

| Method | Description     | Arguments | Returns |
| ------ | --------------- | --------- | ------- |
| focus  | Focus the input | -         | -       |
| blur   | Blur the input  | -         | -       |
| select | Select all text | -         | -       |

### `<input>` Slots

| Slot       |     Description     | Arguments              |
| ---------- | :-----------------: | ---------------------- |
| suffix     |   Suffix content    | -                      |
| prefix     |   Prefix content    | -                      |
| clear-icon | Custom clear button | `clear(event?: Event)` |

### `<InputPassword>` Props

| Parameter          | Description                                                 | Type      | Default |
| ------------------ | ----------------------------------------------------------- | --------- | :-----: |
| visibility-toggle  | Whether to show the password-visibility toggle              | `boolean` | `true`  |
| default-visibility | Default uncontrolled visibility                             | `boolean` | `false` |
| visibility         | Controlled password visibility; supports v-model:visibility | `boolean` |   `-`   |

InputPassword supports all Input props, events, slots and methods.

### `<InputGroup>` Props

| Parameter | Description                      | Type                            | Default                                     |
| --------- | -------------------------------- | ------------------------------- | ------------------------------------------- |
| size      | Default size within the group    | `ComponentSize`                 | Inherited from Form/ConfigProvider, or `md` |
| variant   | Default variant within the group | `filled \| outline \| standard` | `filled`                                    |
| disabled  | Group disabled state             | `boolean`                       | Inherited from Form, or `false`             |
| readonly  | Group readonly state             | `boolean`                       | Inherited from Form, or `false`             |
| hint      | Group floating hint              | `boolean`                       | Library default                             |

### `<InputPassword>` Events

| Parameter         | Description                     | Arguments         |
| ----------------- | ------------------------------- | ----------------- |
| visibility-change | Emitted when visibility changes | `visible:boolean` |

## Type definitions

The component exports the following types

```ts
import type { InputProps } from "@cedar-design/ui";
```

Public types: `InputEmits`, `InputSlots`, `InputExpose`, `InputGroupSlots`, `InputPasswordEmits`, `InputPasswordSlots`, `InputPasswordExpose`.

### Form presentation inheritance

Supports `edit-mode`: `direct / click / dblclick`. Inherits FormItem/Form when unset; standalone usage defaults to direct. readPretty displays plain text; popup editing updates v-model after confirmation by default. Optional before-commit can intercept saving after candidate validation. See the Form documentation for usage and comparison demos.

### Input caret theme

| CSS variable            | Default        | Description                                            |
| ----------------------- | -------------- | ------------------------------------------------------ |
| `--c-input-caret-color` | `currentColor` | Caret color, independently overridable from text color |

`--c-field-caret-color` sets the shared caret color, defaulting to `currentColor`. `--c-input-caret-color` overrides this component and defaults to `var(--c-field-caret-color)`.

---

Document: llms/en-US/components/layout.md

<!-- Source: src/layout/README.en-US.md; locale: en-US; page: /en/components/layout/ -->

# Layout

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

Example source: src/layout/__demos__/basic.vue

```vue
<template>
  <c-layout style="height: 300px">
    <c-layout-header class="layout-header">Header</c-layout-header>
    <c-layout-content class="layout-content">Content</c-layout-content>
    <c-layout-footer class="layout-footer">Footer</c-layout-footer>
  </c-layout>
  <br />
  <c-layout style="height: 300px">
    <c-layout-header class="layout-header">Header</c-layout-header>
    <c-layout>
      <c-layout-sider class="layout-sider">Sider</c-layout-sider>
      <c-layout-content class="layout-content">Content</c-layout-content>
    </c-layout>
    <c-layout-footer class="layout-footer">Footer</c-layout-footer>
  </c-layout>
  <br />
  <c-layout style="height: 300px">
    <c-layout-header class="layout-header">Header</c-layout-header>
    <c-layout>
      <c-layout-content class="layout-content">Content</c-layout-content>
      <c-layout-sider class="layout-sider">Sider</c-layout-sider>
    </c-layout>
    <c-layout-footer class="layout-footer">Footer</c-layout-footer>
  </c-layout>
  <br />
  <c-layout style="height: 300px">
    <c-layout-header class="layout-header">Header</c-layout-header>
    <c-layout>
      <c-layout-sider class="layout-sider" style="width: 64px">Sider</c-layout-sider>
      <c-layout-sider class="layout-sider" style="width: 206px; margin-left: 1px">Sider </c-layout-sider>
      <c-layout-content class="layout-content">Content</c-layout-content>
    </c-layout>
    <c-layout-footer class="layout-footer">Footer</c-layout-footer>
  </c-layout>
</template>

<style scoped lang="less">
.layout-header {
  height: 100px;
  display: flex;
  justify-content: center;
  align-items: center;
  background-color: var(--c-color-primary-light-3);
  color: var(--c-color-text-1);
}

.layout-content {
  height: 100px;
  display: flex;
  justify-content: center;
  align-items: center;
  background-color: var(--c-color-primary-light-4);
  color: var(--c-color-text-1);
}

.layout-sider {
  min-height: 100px;
  background-color: var(--c-color-primary);

  :deep(.c-layout-sider-children) {
    display: flex;
    justify-content: center;
    align-items: center;
    color: var(--c-color-text-1);
  }
}

.layout-footer {
  height: 100px;
  display: flex;
  justify-content: center;
  align-items: center;
  background-color: var(--c-color-primary);
  color: var(--c-color-text-1);
}
</style>
```

## Layout and arrangement

### Scroll

Preview configuration: `bordered`, `scrollable`.

Example source: src/layout/__demos__/scroll.vue

```vue
<template>
  <c-layout class="scroll-layout">
    <c-layout-header bordered class="bar">
      固定头部
      <c-button
        size="sm"
        @click="content?.scrollTo({ top: 0, behavior: 'smooth' })"
        >回到顶部</c-button
      >
    </c-layout-header>
    <c-layout-content ref="content" scrollable @scroll="onScroll">
      <div v-for="item in 30" :key="item" class="row">
        内容 {{ item }} · 只有内容区域滚动
      </div>
    </c-layout-content>
    <c-layout-footer bordered class="bar"
      >固定底部 · 已滚动 {{ offset }}px</c-layout-footer
    >
  </c-layout>
</template>
<script setup lang="ts">
import { ref } from "vue";
import type { LayoutContentInstance } from "../index";
const content = ref<LayoutContentInstance>();
const offset = ref(0);
const onScroll = (event: Event) => {
  offset.value = Math.round((event.target as HTMLElement).scrollTop);
};
</script>
<style scoped>
.scroll-layout {
  height: 320px;
  background: var(--c-color-bg-2);
}
.bar {
  padding: 12px 16px;
  display: flex;
  align-items: center;
  justify-content: space-between;
}
.row {
  padding: 16px;
  border-bottom: 1px solid var(--c-color-border-2);
}
</style>
```

### Sider Options

- `has-sider`: Indicates that there is a Sider in the sub-element, which generally does not need to be specified. Used to avoid style flicker when rendering on the server side.

Example source: src/layout/__demos__/sider-options.vue

```vue
<template>
  <div class="controls">
    <c-radio-group v-model="placement"
      ><c-radio value="left">左侧</c-radio
      ><c-radio value="right">右侧</c-radio></c-radio-group
    >
    <c-radio-group v-model="mode"
      ><c-radio value="width">宽度折叠</c-radio
      ><c-radio value="transform">位移折叠</c-radio></c-radio-group
    >
    <label>完全收起 <c-switch v-model="zero" /></label>
    <c-button size="sm" @click="collapsed = !collapsed">{{
      collapsed ? "展开" : "收起"
    }}</c-button>
  </div>
  <c-layout has-sider class="options-layout">
    <c-layout-sider
      v-model:collapsed="collapsed"
      :placement="placement"
      :collapse-mode="mode"
      :collapsed-width="zero ? 0 : 48"
      :width="200"
      bordered
      collapsible
    >
      <div v-for="item in 12" :key="item" class="item">
        {{ item }} · 项目导航和工作空间
      </div>
    </c-layout-sider>
    <c-layout-content scrollable class="content">
      <h4>内容区域</h4>
      <p>切换左右位置和折叠方式。完全收起后仍可通过边缘按钮展开。</p>
      <p>Tab 可聚焦折叠按钮，Enter 或空格可切换状态。</p>
    </c-layout-content>
  </c-layout>
</template>
<script setup lang="ts">
import { ref } from "vue";
const placement = ref<"left" | "right">("left");
const mode = ref<"width" | "transform">("width");
const collapsed = ref(false);
const zero = ref(false);
</script>
<style scoped>
.controls {
  display: flex;
  gap: 16px;
  flex-wrap: wrap;
  margin-bottom: 16px;
  align-items: center;
}
.controls label {
  display: flex;
  align-items: center;
  gap: 8px;
}
.options-layout {
  height: 300px;
  background: var(--c-color-bg-2);
}
.item {
  padding: 16px;
}
.content {
  padding: 16px;
}
</style>
```

## Content and presentation

### Resize

Preview configuration: `:resize-directions="['right']"`.

Example source: src/layout/__demos__/resize.vue

```vue
<template>
  <c-layout>
    <c-layout-header class="layout-header">Header</c-layout-header>
    <c-layout>
      <c-layout-sider class="layout-sider" :resize-directions="['right']"> Sider </c-layout-sider>
      <c-layout-content class="layout-content">Content</c-layout-content>
    </c-layout>
    <c-layout-footer class="layout-footer">Footer</c-layout-footer>
  </c-layout>
</template>

<style scoped lang="less">
.layout-header {
  height: 100px;
  display: flex;
  justify-content: center;
  align-items: center;
  background-color: var(--c-color-primary-light-3);
  color: var(--c-color-text-1);
}

.layout-content {
  height: 100px;
  display: flex;
  justify-content: center;
  align-items: center;
  background-color: var(--c-color-primary-light-4);
  color: var(--c-color-text-1);
}

.layout-sider {
  min-height: 100px;
  background-color: var(--c-color-primary);

  :deep(.c-layout-sider-children) {
    display: flex;
    justify-content: center;
    align-items: center;
    color: var(--c-color-text-1);
  }
}

.layout-footer {
  height: 100px;
  display: flex;
  justify-content: center;
  align-items: center;
  background-color: var(--c-color-primary);
  color: var(--c-color-text-1);
}
</style>
```

### Collapse

- `has-sider`: Indicates that there is a Sider in the sub-element, which generally does not need to be specified. Used to avoid style flicker when rendering on the server side.

Example source: src/layout/__demos__/collapse.vue

```vue
<template>
  <c-layout class="collapse-layout" has-sider>
    <c-layout-sider v-model:collapsed="collapsed" collapsible>
      <div class="sider-content">{{ collapsed ? '导航' : '侧栏导航区域' }}</div>
    </c-layout-sider>
    <c-layout>
      <c-layout-header class="header">可折叠侧栏</c-layout-header>
      <c-layout-content class="content">
        <c-button @click="collapsed = !collapsed">{{ collapsed ? '展开侧栏' : '收起侧栏' }}</c-button>
        <p>侧栏和内容区共享可用高度，底部触发器保持在侧栏底部。</p>
      </c-layout-content>
    </c-layout>
  </c-layout>
</template>

<script setup lang="ts">
import { ref } from 'vue'
const collapsed = ref(false)
</script>

<style scoped>
.collapse-layout { height: 300px; background: var(--c-color-bg-2); }
.sider-content, .header, .content { padding: 16px; }
.header { background: var(--c-color-bg-3); }
</style>
```

## Reading direction

Inherits the nearest `dir="ltr|rtl"` and supports runtime and nested overrides. Content inherits reading direction. Sider placement=left/right and physical ResizeBox handles keep their physical-side semantics. Nested headings and content may override dir locally.

## API

### Layout Props

| Parameter | Description | Type | Default |
| --------- | ------------------------------------------------------------------ | ------- | :----: |
| scrollable | Enable native scrolling on this element; requires constrained height | boolean | false |
| has-sider | Indicates that there is a Sider in the sub-element, which generally does not need to be specified. Used to avoid style flicker when rendering on the server side. | boolean | false |

### Layout-Header Slots

| Slot | Description | Arguments |
| ------- | :--: | ---- |
| default | Content | - |

### Layout-content Slots

| Slot | Description | Arguments |
| ------- | :--: | ---- |
| default | Content | - |

### Layout-Footer Slots

| Slot | Description | Arguments |
| ------- | :--: | ---- |
| default | Content | - |

### Layout-Sider Props

| Parameter | Description | Type | Default |
| ----------------- | ---------------------------------------------------------------------------------------------------- | --------------------------------------------- | :-----: |
| theme | Theme color | 'dark' \| 'light' | 'light' |
| collapsed | Current collapsed state | boolean | - |
| default-collapsed | Default collapsed state | boolean | false |
| collapsible | Whether collapsing is enabled | boolean | false |
| width | Width | number \| string | 200 |
| collapsed-width | Collapsed width | number | 48 |
| reverse-arrow | Reverse the collapse arrow; useful for a right-side Sider | boolean | false |
| breakpoint | Responsive breakpoint; see responsive Grid | 'xxl' \| 'xl' \| 'lg' \| 'md' \| 'sm' \| 'xs' | - |
| resize-directions | Replace the native aside with ResizeBox; this is the ResizeBox directions parameter. See ResizeBox | Array<'left' \| 'right' \| 'top' \| 'bottom'> | - |
| hide-trigger | Hide the bottom collapse trigger | boolean | false |

### Layout-Sider Events

| Event | Description | Arguments |
| ---------- | ---------------------------------------------------------------- | -------------------------------------------------------- |
| collapse | Expand/collapse event, from the collapse control or responsive changes | collapsed: boolean<br>type: 'clickTrigger'\|'responsive' |
| breakpoint | Responsive-breakpoint event | collapsed: boolean |

### Layout-Sider Slots

| Slot | Description | Arguments |
| ------- | :------------------: | ------------------ |
| trigger | Custom bottom collapse trigger | collapsed: boolean |

## Type definitions

The component exports the following types

```ts
import type { LayoutProps } from '@cedar-design/ui'
```

### Additional layout capabilities

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Content | scrollable | boolean | false | Use this element as a native scroll container |
| Header / Footer / Sider | bordered | boolean | false | Show a border adjacent to the content |
| Sider | placement | 'left' / 'right' | 'left' | Sidebar placement; handles arrows automatically, while reverse-arrow remains supported |
| Sider | collapse-mode | 'width' / 'transform' | 'width' | Resize or translate content while collapsing |

Layout, Content and Sider emit `scroll`(event: Event) and expose `scrollTo(options: ScrollToOptions)` / `scrollTo(x: number, y: number)`. Sider scrolls its internal content node by default. `width` accepts numeric px or CSS lengths. Percentage widths with transform mode are discouraged; use definite lengths such as px/rem.

The collapse control is a native button supporting Tab, Enter and Space. With `collapsed-width="0"`, the hidden region is inert and the expansion entry stays at the sidebar edge. A custom trigger slot should contain display content without nested buttons.

---

Document: llms/en-US/components/link.md

<!-- Source: src/link/README.en-US.md; locale: en-US; page: /en/components/link/ -->

# Link

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

Example source: src/link/__demos__/basic.vue

```vue
<template>
  <c-link href="https://example.com/" target="_blank" rel="noopener noreferrer"
    >访问示例网站</c-link
  >
</template>
```

## Appearance and states

### Link sizes and semantic colors

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `status` | Link status | Link sizes and semantic colors, Link Mode, Link Underline |
| `href` | Link URL | Link Mode, Hoverable |
| `size` | Text, icon and loading-icon size | Link sizes and semantic colors |
| `icon` | Icon | Link sizes and semantic colors |
| `loading` | Whether the link is loading | Link sizes and semantic colors |
| `target` | Native link target | Link Mode |
<!-- demo-config-notes:end -->


Compare sizes and semantic colors independently of navigation, disabled interception and loading.

Example source: src/link/__demos__/appearance-comparison.vue

```vue
<script setup lang="ts">
import { proxyRefs as demoProxyRefs } from 'vue'

const scene1 = demoProxyRefs((() => {

const sizes = ['xs', 'sm', 'md', 'lg', 'xl'] as const
return { sizes }
})())
</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="size">
    <h4><span lang="zh-CN">五种尺寸</span><span lang="en-US">size</span></h4>
    <c-space direction="column" size="md">
        <c-space v-for="size in scene1.sizes" :key="size" wrap size="md" align="center">
          <c-link :size="size" status="primary">{{ size }} 链接</c-link>
          <c-link :size="size" status="primary" icon>{{ size }} 图标</c-link>
          <c-link :size="size" loading>{{ size }} 加载中</c-link>
        </c-space>
      </c-space>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="link-status">
    <h4><span lang="zh-CN">链接状态</span><span lang="en-US">link status</span></h4>
    <c-space wrap size="sm">
        <c-link status="default">默认链接</c-link>
        <c-link status="primary">主要链接</c-link>
        <c-link status="secondary">次要链接</c-link>
        <c-link status="tertiary">三级链接</c-link>
        <c-link status="info">信息链接</c-link>
        <c-link status="success">成功链接</c-link>
        <c-link status="warning">警告链接</c-link>
        <c-link status="danger">危险链接</c-link>
      </c-space>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

### Link Mode

- `status`: Selects the semantic state.

Example source: src/link/__demos__/link-mode.vue

```vue
<template>
  <c-space size="sm">
    <c-link
      status="primary"
      href="https://example.com/"
      target="_blank"
      rel="noopener noreferrer"
    >
      href 链接
    </c-link>
  </c-space>
</template>
```

### Link Underline

- `status`: Selects the semantic state.

Example source: src/link/__demos__/link-underline.vue

```vue
<template>
  <c-space size="sm">
    <c-link status="primary" underline="always">始终显示</c-link>
    <c-link status="primary" underline="hover">悬停显示</c-link>
    <c-link status="primary" underline="none">不显示</c-link>
  </c-space>
</template>
```

### Link Disabled

- `disabled`: Prevents user interaction.

Example source: src/link/__demos__/link-disabled.vue

```vue
<template>
  <c-link disabled>禁用状态</c-link>
</template>
```

### Hoverable

Preview configuration: `hoverable`, `href="#link"`.

Example source: src/link/__demos__/hoverable.vue

```vue
<template>
  <c-space size="sm">
    <c-link hoverable href="#link">悬浮态底色</c-link>
    <c-link href="#link">Tab 键聚焦</c-link>
  </c-space>
</template>
```

## Content and presentation

### Link Icon

Preview configuration: `icon`.

Example source: src/link/__demos__/link-icon.vue

```vue
<template>
  <c-space size="sm">
    <c-link icon>默认图标</c-link>
    <c-link>
      <template #icon><c-icon-edit /></template>
      自定义图标
    </c-link>
  </c-space>
</template>
```

## Interaction and control

### Link Loading

Preview configuration: `loading`, `:loading="loading"`.

Example source: src/link/__demos__/link-loading.vue

```vue
<script setup lang="ts">
import { onBeforeUnmount, ref } from "vue";

const loading = ref(false);
const ready = ref(false);
const href =
  "data:text/plain;charset=utf-8," + encodeURIComponent("示例报告：准备完成。");
let timer: ReturnType<typeof setTimeout> | undefined;

function prepareDownload(event: MouseEvent) {
  if (ready.value) {
    return;
  }
  event.preventDefault();
  loading.value = true;
  // 模拟业务准备；完成后再次激活链接，交给浏览器原生下载。
  timer = setTimeout(() => {
    ready.value = true;
    loading.value = false;
    timer = undefined;
  }, 1000);
}
onBeforeUnmount(() => clearTimeout(timer));
</script>
<template>
  <c-space size="sm">
    <c-link :href="href" download="report.txt" loading>加载中</c-link>
    <c-link
      :href="href"
      download="report.txt"
      :loading="loading"
      @click="prepareDownload"
    >
      {{ loading ? "准备中" : ready ? "下载示例报告" : "准备下载报告" }}
    </c-link>
  </c-space>
  <p>
    首次点击或按 Enter 准备报告；完成后再次激活链接，浏览器下载文本文件。loading
    由业务手动控制。
  </p>
</template>
```

## API

### Native links and controlled loading

Provide href for navigation. Disabled/loading links retain their link role when an href was provided, remove navigation attributes and leave the Tab order. Native download, hreflang, referrerpolicy and ARIA attributes pass through. Loading replaces the icon slot. click is a MouseEvent notification with Vue once semantics; returned promises do not manage loading. Use Button for operations without a navigation target.

The loading example prepares a report on the first activation, then uses the browser's native download on the next activation. Preparation is canceled when unmounted.


### `<Link>` Props

| Property | Description | Type | Default |
| --- | --- | --- | --- |
| `size` | Five text, icon and spinner sizes | 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' | 'md' |
| `href` | Native link destination | string | - |
| `target` | Native target | string | - |
| `rel` | Native rel | string | - |
| `status` | Semantic status | SemanticStatus | 'default' |
| `underline` | Underline policy | 'always' \| 'hover' \| 'none' | 'none' |
| `hoverable` | Padded hover/active backgrounds | boolean | false |
| `icon` | Show the leading icon; icon slot takes priority | boolean | false |
| `loading` | Show spinner and block navigation/click | boolean | false |
| `disabled` | Disable the link | boolean | false |


### `<Link>` Events

| Event | Description | Arguments |
| ------ | -------------- | ----------------------------- |
| click | Click event | `(event: MouseEvent) => void` |

### Slots

| Slot | Description |
| --- | --- |
| default | Link content |
| icon | Custom icon; replaced by the loading icon while loading |

### Type definitions

The component exports the following types

```ts
import type { LinkProps, LinkSize, LinkUnderline, LinkInstance } from '@cedar-design/ui'
```

### Style migration

Internal classes use `c-link--status-*`, `c-link--underline-*`, `c-link--disabled`, `c-link--loading` and `c-link__icon`. Migrate old single-hyphen selectors and prefer `--c-link-*` CSS variables. Focus supports `--c-link-focus-width` (2px), `--c-link-focus-offset` (2px), `--c-link-focus-color` (currentColor) and `--c-link-focus-opacity` (0.8). Reduced motion disables loading rotation and transitions.

Text colors match Button text variants: default uses content-primary; secondary/tertiary use content-secondary; colored statuses use their semantic content colors; disabled/loading use content-disabled. Both brands inherit these in light/dark modes.

Size variables: `--c-link-size-xs-font-size`, `--c-link-size-sm-font-size`, `--c-link-size-md-font-size`, `--c-link-size-lg-font-size`, `--c-link-size-xl-font-size`. Defaults are 12 / 13 / 14 / 16 / 18px. md references `--c-link-font-size`; icons/loading icons use 1em.

---

Document: llms/en-US/components/list.md

<!-- Source: src/list/README.en-US.md; locale: en-US; page: /en/components/list/ -->

# List

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

Example source: src/list/__demos__/basic.vue

```vue
<template>
  <c-list>
    <template #header> List title </template>
    <c-list-item>Beijing Bytedance Technology Co., Ltd.</c-list-item>
    <c-list-item>Bytedance Technology Co., Ltd.</c-list-item>
    <c-list-item>Beijing Toutiao Technology Co., Ltd.</c-list-item>
    <c-list-item>Beijing Volcengine Technology Co., Ltd.</c-list-item>
    <c-list-item>China Beijing Bytedance Technology Co., Ltd.</c-list-item>
  </c-list>
</template>
<script lang="ts" setup>
</script>
```

## Appearance and states

### Size

- `size`: Controls the component size.

Example source: src/list/__demos__/size.vue

```vue
<template>
  <c-space direction="column" size="lg">
    <c-radio-group v-model="size" type="button">
      <c-radio value="sm">sm</c-radio>
      <c-radio value="md">md</c-radio>
      <c-radio value="lg">lg</c-radio>
    </c-radio-group>
    <c-list :size="size">
      <template #header> List title </template>
      <c-list-item>Beijing Bytedance Technology Co., Ltd.</c-list-item>
      <c-list-item>Bytedance Technology Co., Ltd.</c-list-item>
      <c-list-item>Beijing Toutiao Technology Co., Ltd.</c-list-item>
      <c-list-item>Beijing Volcengine Technology Co., Ltd.</c-list-item>
      <c-list-item>China Beijing Bytedance Technology Co., Ltd.</c-list-item>
    </c-list>
  </c-space>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
const size = ref('md')
</script>
```

## Content and layout

### Prefix Suffix

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `bordered` | Outer border | Actions Layout |
| `data` | Data consumed by item slot | Actions Layout |
<!-- demo-config-notes:end -->


Preview configuration: `shape="square"`.

Example source: src/list/__demos__/prefix-suffix.vue

```vue
<template>
  <c-list>
    <c-list-item v-for="item in items" :key="item.title">
      <template #prefix>
        <c-avatar shape="square">{{ item.initial }}</c-avatar>
      </template>
      <template #suffix>
        <c-button size="sm">编辑</c-button>
      </template>
      <div class="list-item-title">{{ item.title }}</div>
      <div class="list-item-description">{{ item.description }}</div>
    </c-list-item>
  </c-list>
</template>

<script lang="ts" setup>
const items = [
  {
    initial: 'B',
    title: 'Beijing Bytedance Technology Co., Ltd.',
    description: 'Beijing ByteDance Technology Co., Ltd. is an enterprise located in China.',
  },
  {
    initial: 'T',
    title: 'Beijing Toutiao Technology Co., Ltd.',
    description: 'Toutiao is a content platform under ByteDance.',
  },
  {
    initial: 'V',
    title: 'Beijing Volcengine Technology Co., Ltd.',
    description: 'Volcengine provides cloud and AI infrastructure.',
  },
]
</script>

<style scoped>
.list-item-title {
  font-weight: var(--c-font-weight-500);
}

.list-item-description {
  margin-top: 4px;
  color: var(--c-color-text-2);
}
</style>
```

### Actions Layout

- `data`: Supplies the example data.

Example source: src/list/__demos__/actions-layout.vue

```vue
<template>
  <c-list :bordered="false" :data="dataSource">
    <template #item="{ item }">
      <c-list-item>
        <template #prefix>
          <c-avatar shape="square">
            <img alt="avatar" :src="item.avatar" />
          </c-avatar>
        </template>
        <template #suffix>
          <img class="list-demo-cover" alt="cover" :src="item.imageSrc" />
        </template>
        <div class="list-item-title">{{ item.title }}</div>
        <div class="list-item-description">{{ item.description }}</div>
      </c-list-item>
    </template>
  </c-list>
</template>

<script lang="ts" setup>
const names = ['Socrates', 'Balzac', 'Plato']
const avatarSrc = [
  '//p1-arco.byteimg.com/tos-cn-i-uwbnlip3yd/a8c8cdb109cb051163646151a4a5083b.png~tplv-uwbnlip3yd-webp.webp',
  '//p1-arco.byteimg.com/tos-cn-i-uwbnlip3yd/e278888093bef8910e829486fb45dd69.png~tplv-uwbnlip3yd-webp.webp',
  '//p1-arco.byteimg.com/tos-cn-i-uwbnlip3yd/9eeb1800d9b78349b24682c3518ac4a3.png~tplv-uwbnlip3yd-webp.webp',
]
const imageSrc = [
  '//p1-arco.byteimg.com/tos-cn-i-uwbnlip3yd/29c1f9d7d17c503c5d7bf4e538cb7c4f.png~tplv-uwbnlip3yd-webp.webp',
  '//p1-arco.byteimg.com/tos-cn-i-uwbnlip3yd/04d7bc31dd67dcdf380bc3f6aa07599f.png~tplv-uwbnlip3yd-webp.webp',
  '//p1-arco.byteimg.com/tos-cn-i-uwbnlip3yd/1f61854a849a076318ed527c8fca1bbf.png~tplv-uwbnlip3yd-webp.webp',
]
const dataSource = names.map((title, index) => ({
  avatar: avatarSrc[index],
  title,
  description:
    'Beijing ByteDance Technology Co., Ltd. is an enterprise located in China. ByteDance has products such as TikTok, Toutiao, volcano video and Douyin (the Chinese version of TikTok).',
  imageSrc: imageSrc[index],
}))
</script>

<style scoped>
.list-item-title {
  font-weight: var(--c-font-weight-500);
}

.list-item-description {
  margin-top: 4px;
  color: var(--c-color-text-2);
}

.list-demo-cover {
  display: block;
  width: 120px;
  height: 80px;
  object-fit: cover;
  border-radius: var(--c-border-radius-md);
}
</style>
```

## Scrolling and virtualization

### Bounded Scroll

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `data` | Data consumed by item slot | Bounded Scroll, Virtual List, Virtual Navigation |
| `virtual-list-props` | Data virtualization; ignored when default slot exists | Virtual List, Virtual Navigation |
| `max-height` | Maximum ordinary viewport height; number in px or CSS length, zero means unlimited | Bounded Scroll |
| `scrollbar` | Ordinary viewport custom scrollbar; false uses native scrolling | Bounded Scroll |
| `size` | Implemented sizes only; xs/xl are not supported | Bounded Scroll |
| `split` | Item/header/footer separators, independent of border | Bounded Scroll |
<!-- demo-config-notes:end -->


- `data`: Supplies the example data.
- `size`: Controls the component size.

Example source: src/list/__demos__/bounded-scroll.vue

```vue
<script setup>
const rows = Array.from({ length: 20 }, (_, index) => ({ id: index, name: '记录 ' + (index + 1) }))
</script>
<template>
  <c-space direction="column" style="width: 100%">
    <c-list :data="rows" :max-height="180" :scrollbar="false">
      <template #header>原生滚动条</template>
      <template #item="{ item }"><c-list-item>{{ item.name }}</c-list-item></template>
    </c-list>
    <c-list :data="rows" max-height="12rem" :scrollbar="{ type: 'track' }" size="sm" :split="false">
      <template #header>自定义滚动条，无分隔线</template>
      <template #item="{ item }"><c-list-item>{{ item.name }}</c-list-item></template>
    </c-list>
  </c-space>
</template>
```

### Virtual List

- `data`: Supplies the example data.

Example source: src/list/__demos__/virtual-list.vue

```vue
<template>
  <h3 :style="{ color: 'var(--c-color-text-2)' }">10000 items</h3>
  <c-list
    :style="{ width: `600px` }"
    :virtualListProps="{
      height: 560,
    }"
    :data="list"
  >
    <template #item="{ item, index }">
      <c-list-item :key="index">
        <template #prefix>
          <c-avatar shape="square">A</c-avatar>
        </template>
        <div>{{ item.title }}</div>
        <div class="list-item-description">{{ item.description }}</div>
      </c-list-item>
    </template>
  </c-list>
</template>

<script lang="ts" setup>
import { reactive } from 'vue'

const list = reactive(
  Array(10000)
    .fill(null)
    .map((_, index) => {
      const prefix = `0000${index}`.slice(-5)
      return {
        title: 'Beijing Bytedance Technology Co., Ltd.',
        description: `(${prefix}) Beijing ByteDance Technology Co., Ltd. is an enterprise located in China.`,
      }
    }),
)
</script>

<style scoped>
.list-item-description {
  margin-top: 4px;
  color: var(--c-color-text-2);
}
</style>
```

### Virtual Navigation

- `data`: Supplies the example data.

Example source: src/list/__demos__/virtual-navigation.vue

```vue
<script setup>
import { ref } from 'vue'
const list = ref()
const rows = Array.from({ length: 1000 }, (_, id) => ({ id, name: '记录 ' + (id + 1) }))
</script>
<template>
  <c-space direction="column" style="width: 100%">
    <c-space wrap>
      <c-button @click="list.scrollIntoView({ key: 499, align: 'top' })">第 500 项置顶</c-button>
      <c-button @click="list.scrollIntoView({ key: 499, align: 'bottom' })">第 500 项置底</c-button>
      <c-button @click="list.scrollIntoView({ key: 499, align: 'auto' })">仅滚动到可见</c-button>
    </c-space>
    <c-list ref="list" :data="rows" :virtual-list-props="{ height: 240, itemKey: 'id', estimatedSize: 48, buffer: 10 }">
      <template #item="{ item, index }"><c-list-item><template #prefix>{{ index + 1 }}</template>{{ item.name }}</c-list-item></template>
    </c-list>
  </c-space>
</template>
```

## Lifecycle

### Virtual Lifecycle

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `data` | Data consumed by item slot | Virtual Lifecycle |
| `virtual-list-props` | Data virtualization; ignored when default slot exists | Virtual Lifecycle |
<!-- demo-config-notes:end -->


- `data`: Supplies the example data.

Example source: src/list/__demos__/virtual-lifecycle.vue

```vue
<script setup lang="ts">
import { ref } from "vue";

const active = ref(true);
const mounted = ref(true);
const rows = Array.from({ length: 100 }, (_, key) => ({ key }));
let retained:
  | { scrollIntoView: (options: { key: number; align: "top" }) => void }
  | undefined;
const capture = (instance: typeof retained) => {
  if (instance) retained = instance;
};
const jump = () => retained?.scrollIntoView({ key: 50, align: "top" });
</script>

<template>
  <div>
    <c-button @click="active = !active">Activate / deactivate</c-button>
    <c-button @click="mounted = !mounted">Mount / dispose cache</c-button>
    <c-button @click="jump">Retained command: row 51</c-button>
    <p>Inactive/disposed commands do nothing. Activation never replays them.</p>
    <KeepAlive v-if="mounted">
      <c-list
        v-if="active"
        :ref="capture"
        :data="rows"
        :virtual-list-props="{
          height: 100,
          fixedSize: true,
          estimatedSize: 20,
          buffer: 2,
          itemKey: 'key',
        }"
      >
        <template #item="{ item }"
          ><div style="height: 20px">{{ item.key + 1 }}</div></template
        >
      </c-list>
    </KeepAlive>
  </div>
</template>
```

## API

### List Props

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| data | Data consumed by item slot | unknown[] | undefined |
| size | Implemented sizes only; xs/xl are not supported | 'sm' \| 'md' \| 'lg' | md |
| bordered | Outer border | boolean | true |
| split | Item/header/footer separators, independent of border | boolean | true |
| loading | Initial loading/refresh feedback, not pagination state | boolean | false |
| max-height | Maximum ordinary viewport height; number in px or CSS length, zero means unlimited | number \| string | 0 |
| virtual-list-props | Data virtualization; ignored when default slot exists | ListVirtualListProps | undefined |
| scrollbar | Ordinary viewport custom scrollbar; false uses native scrolling | boolean \| ListScrollbarProps | true |

Virtual lists use a dedicated viewport without nesting a custom scrollbar. virtualListProps.height overrides maxHeight; with neither, height defaults to 200px. Numeric and unit-bearing CSS lengths are accepted. Invalid/nonpositive max-height does not constrain height.

ListVirtualListProps supports height, threshold, fixedSize, estimatedSize, buffer, itemKey and component. Removed isStaticItemHeight is unsupported; List.data supplies data. Counts at or below threshold render all items. Variable heights use measurements and estimatedSize; buffer controls overscan rows.

ListScrollbarProps supports type: 'track'|'embed', outerClass, outerStyle, hide, disableHorizontal and disableVertical. JavaScript object fields use camelCase.

### Events / Methods

- scroll(event: Event): one notification per real scroll event.
- scrollIntoView({ index?, key?, align }): virtual-list positioning. index overrides key; align is top/bottom/auto. auto does nothing for a fully visible item, otherwise scrolls the minimum distance required. Invalid targets or nonvirtual mode do nothing.

### Slots

List slots: default (overrides data), item({ item, index }), header, footer, empty. Empty state appears only without a default slot/data and while not loading. ListItem prefix/default/suffix retain list-item semantics without managing buttons/business interactions.

### Types

ListProps、ListSize、ListVirtualListProps、ListScrollbarProps、ListExpose、ListSlots、ListEmits、ListInstance、ListItemInstance。

List handles display and an optional virtual viewport. Compose InfiniteScroll status/target behavior for pagination rather than duplicating its loading state machine inside List.

## Style variables

| Token | Default |
| --- | --- |
| `--c-list-background` | `transparent` |
| `--c-list-empty-padding` | `16px` |
| `--c-list-empty-color` | `var(--c-list-text-color)` |
| `--c-list-loading-padding` | `0px` |
| `--c-list-border-width` | `1px` |
| `--c-list-border-color` | `var(--c-color-neutral-3)` |
| `--c-list-border-radius` | `var(--c-border-radius-md)` |
| `--c-list-text-color` | `var(--c-color-text-1)` |
| `--c-list-font-size` | `var(--c-font-size-body-3)` |
| `--c-list-line-height` | `var(--c-line-height)` |
| `--c-list-text-color-header` | `var(--c-color-text-1)` |
| `--c-list-font-size-header` | `var(--c-font-size-title-1)` |
| `--c-list-font-weight-header` | `var(--c-font-weight-500)` |
| `--c-list-line-height-header` | `1.5` |
| `--c-list-size-sm-padding-vertical-header` | `var(--c-spacing-4)` |
| `--c-list-size-sm-padding-horizontal-header` | `var(--c-spacing-8)` |
| `--c-list-size-sm-padding-vertical-item` | `9px` |
| `--c-list-size-sm-padding-horizontal-item` | `var(--c-spacing-8)` |
| `--c-list-size-md-padding-vertical-header` | `var(--c-spacing-6)` |
| `--c-list-size-md-padding-horizontal-header` | `var(--c-spacing-8)` |
| `--c-list-size-md-padding-vertical-item` | `13px` |
| `--c-list-size-md-padding-horizontal-item` | `var(--c-spacing-8)` |
| `--c-list-size-lg-padding-vertical-header` | `var(--c-spacing-7)` |
| `--c-list-size-lg-padding-horizontal-header` | `var(--c-spacing-8)` |
| `--c-list-size-lg-padding-vertical-item` | `17px` |
| `--c-list-size-lg-padding-horizontal-item` | `var(--c-spacing-8)` |
| `--c-list-item-prefix-margin-right` | `var(--c-spacing-8)` |
| `--c-list-item-suffix-margin-left` | `var(--c-spacing-8)` |
| `--c-list-size-sm-padding-vertical-footer` | `var(--c-list-size-sm-padding-vertical-item)` |
| `--c-list-size-sm-padding-horizontal-footer` | `var(--c-list-size-sm-padding-horizontal-item)` |
| `--c-list-size-md-padding-vertical-footer` | `var(--c-list-size-md-padding-vertical-item)` |
| `--c-list-size-md-padding-horizontal-footer` | `var(--c-list-size-md-padding-horizontal-item)` |
| `--c-list-size-lg-padding-vertical-footer` | `var(--c-list-size-lg-padding-vertical-item)` |
| `--c-list-size-lg-padding-horizontal-footer` | `var(--c-list-size-lg-padding-horizontal-item)` |

---

Document: llms/en-US/components/loading.md

<!-- Source: src/loading/README.en-US.md; locale: en-US; page: /en/components/loading/ -->

# Loading

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

Preview configuration: `tip="加载中"`.

Example source: src/loading/__demos__/basic.vue

```vue
<template>
  <c-loading tip="加载中" />
</template>
```

## Appearance and states

### Loading shape, size and color

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `size` | Loading-indicator size; numbers are px | Loading shape, size and color |
| `type` | Loading animation type | Loading shape, size and color |
| `color` | Indicator and hint-text color | Loading shape, size and color |
<!-- demo-config-notes:end -->


Compare the shape, size and color of loading indicators. Container masks and directives remain separate.

Example source: src/loading/__demos__/appearance-comparison.vue

```vue
<script setup lang="ts">


</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="size">
    <h4><span lang="zh-CN">大小</span><span lang="en-US">size</span></h4>
    <c-space align="center" justify="space-between">
        <c-loading size="sm" />
        <c-loading type="cube" size="sm" />
        <c-loading type="wave" size="sm" />
        <c-loading type="rect" size="sm" />
        <c-loading type="disappear" size="sm" />
        <c-loading :size="32" />
      </c-space>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="color">
    <h4><span lang="zh-CN">颜色</span><span lang="en-US">color</span></h4>
    <c-space align="center" justify="space-between">
        <c-loading color="var(--c-color-info)" />
        <c-loading type="cube" color="var(--c-color-success)" />
        <c-loading type="wave" color="var(--c-color-warning)" />
        <c-loading type="rect" color="var(--c-color-danger)" />
        <c-loading type="disappear" color="var(--c-color-text-disabled)" />
      </c-space>
  </section>

  <section class="demo-comparison-case demo-comparison-case--3" data-comparison-scene="type">
    <h4><span lang="zh-CN">类型</span><span lang="en-US">type</span></h4>
    <c-space align="center" justify="space-between">
        <c-loading />
        <c-loading type="cube" />
        <c-loading type="wave" />
        <c-loading type="rect" />
        <c-loading type="disappear" />
      </c-space>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

## Layout and arrangement

### Wrap

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `tip` | Prompt copy | Wrap |
| `loading` | Whether loading; effective only when wrapping content | Wrap |
<!-- demo-config-notes:end -->


Preview configuration: `tip="LOADING"`, `:loading="loading"`, `title="介绍"`, `description="Cedar 是一个基于 Vue 3 的企业级桌面端组件库。"`.

Example source: src/loading/__demos__/wrap.vue

```vue
<template>
  <c-button style="margin-bottom: 8px" @click="loading = !loading">
    {{ loading ? "关闭" : "打开" }}
  </c-button>
  <c-loading tip="LOADING" :loading="loading">
    <c-card
      title="介绍"
      description="Cedar 是一个基于 Vue 3 的企业级桌面端组件库。"
    />
  </c-loading>
</template>

<script lang="ts" setup>
import { ref } from "vue";

const loading = ref(false);
</script>
```

## Content and presentation

### Directive

Preview configuration: `title="介绍"`, `description="v-c-loading 会在当前容器内渲染 Loading 遮罩，不会改变内容结构。"`.

Example source: src/loading/__demos__/directive.vue

```vue
<template>
  <c-space direction="column">
    <h4>简单用法</h4>
    <c-switch v-model="simpleLoading" />
    <c-card
      v-c-loading="simpleLoading"
      title="介绍"
      description="v-c-loading 会在当前容器内渲染 Loading 遮罩，不会改变内容结构。"
    />

    <h4>复杂配置</h4>
    <c-switch v-model="configuredLoading" />
    <c-card
      v-c-loading="{
        loading: configuredLoading,
        tip: '加载中...',
        color: 'var(--c-color-primary)',
        background: 'color-mix(in srgb, var(--c-color-bg-1) 72%, transparent)',
      }"
      title="介绍"
      description="v-c-loading 会在当前容器内渲染 Loading 遮罩，不会改变内容结构。"
    />
  </c-space>
</template>

<script lang="ts" setup>
import { ref } from "vue";

const simpleLoading = ref(false);
const configuredLoading = ref(false);
</script>
```

## API

### `<Loading>` Props

| Prop | Description | Type | Default |
| --------- | -------------------------------------- | --------------------------------------------- | -------- |
| type | Loading animation type | `circle \| wave \| cube \| rect \| disappear` | `circle` |
| size | Loading-indicator size; numbers are px | `xs \| sm \| md \| lg \| xl \| number` | `md` |
| radius | Radius for `circle` indicators | `string \| number` | - |
| color | Indicator and hint-text color | `string` | - |
| loading | Whether loading; effective only when wrapping content | `boolean` | `false` |
| tip | Prompt copy | `string` | - |
| hide-icon | Whether to hide the loading indicator | `boolean` | `false` |

`v-c-loading` accepts boolean shorthand or `{ loading, tip, type, size, radius, color, hideIcon, fullscreen, background }`. The object's `loading` field controls state; other props match `Loading`.

#### Registration

`v-c-loading` renders Cedar's built-in `Loading` component. The `c-` prefix avoids collisions with other libraries’ directives. Register it in any of the following ways.

```ts
// 1. Full installation: registers Loading and v-c-loading automatically
import CedarVue from "@cedar-design/ui";

app.use(CedarVue);
```

```ts
// 2. Install Loading on demand: registers the component and directive
import { Loading } from "@cedar-design/ui";

app.use(Loading);
```

```ts
// 3. Register only the directive manually
import { vLoading } from "@cedar-design/ui";

app.directive("c-loading", vLoading);
```

With `CedarResolver()`, `unplugin-vue-components` resolves template `v-c-loading` automatically. `directives: false` disables directive resolution.

### `<Loading>` Slots

| Slot | Description |
| ------- | ---------------------- |
| default | Content covered by the loading mask |
| tip | Custom hint content |
| icon | Custom loading indicator |

The `icon` slot replaces every built-in `type` animation. Without it, the ConfigProvider `loading` slot takes precedence over built-in animations. `hide-icon=true` hides all indicators while allowing tip content to remain visible.

## Type definitions

The component exports the following types:

```ts
import type { LoadingProps } from "@cedar-design/ui";
```

The loading-directive mask prevents default click behavior and propagation. Clicking it does not activate Card or ordinary parent click handlers. Normal clicking resumes after loading. It does not disable keyboard access to underlying controls; set those controls’ `disabled` props to block all interaction.

### Overlay styles

| Variable | Description |
| --- | --- |
| `--c-loading-overlay-background` | Directive overlay background; the background option overrides this value. |

Content-overlay class: `.c-loading__content-overlay`.

Each directive update replaces the complete configuration; omitted options and boolean `true` use defaults. Changing `fullscreen` while loading moves the overlay between the host and its owner document body. Host children stay in place. Multiple fullscreen instances share a counted scroll lock: closing a local instance does not unlock fullscreen instances, and the final fullscreen instance preserves an existing external lock class.

---

Document: llms/en-US/components/map.md

<!-- Source: src/map/README.en-US.md; locale: en-US; page: /en/components/map/ -->

# Map

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

Preview configuration: `map-type="amaps"`.

Example source: src/map/__demos__/basic.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const location = ref({ longitude: 116.397, latitude: 39.908, address: '北京示例位置' })
function reset() { location.value = { longitude: 116.397, latitude: 39.908, address: '北京示例位置' } }
</script>
<template>
  <c-space direction="column">
    <p>未接入地图 SDK 时显示降级状态，不请求定位权限、不发送真实接口请求。按钮只演示本地位置模型。</p>
    <c-space wrap>
      <c-button @click="location = { longitude: 121.4737, latitude: 31.2304, address: '上海示例位置' }">使用上海示例位置</c-button>
      <c-button @click="reset">重置位置</c-button>
    </c-space>
    <p role="status">当前位置：{{ location.address }}（{{ location.longitude }}, {{ location.latitude }}）</p>
    <c-map v-model="location" map-type="amaps" style="height: 300px" />
  </c-space>
</template>
```

## Content and presentation

### Auth

Example source: src/map/__demos__/auth.vue

```vue
<template>
  <c-alert status="info" title="地图 SDK 接入">
    本地示例不需要登录、令牌或外部图片。生产应用须自行接入地图 SDK 适配器、配置服务与授权域名，再验证搜索、选点和定位；当前降级展示不代表 SDK 已接入成功。
  </c-alert>
</template>
```

## Data and options

### Google

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `map-type` | Map type | Google |
| `is-international` | Whether this is a Google map | Google |
<!-- demo-config-notes:end -->


Preview configuration: `map-type="google"`, `is-international`, `map-type="amaps"`.

Example source: src/map/__demos__/google.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const location = ref({ longitude: -0.1276, latitude: 51.5072, address: 'London sample location' })
</script>
<template>
  <c-space direction="column">
    <p>国际地图使用 is-international 和 map-type="google"。未配置 SDK 时保留降级展示，应用须自行接入适配器和地图服务；示例不保存密钥或 token。</p>
    <c-map v-model="location" map-type="google" is-international style="height: 300px" />
    <p role="status">{{ location.address }}</p>
  </c-space>
</template>
```

Example source: src/map/__demos__/use-vmodel.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const location = ref({ longitude: 116.397, latitude: 39.908, address: '北京示例位置' })
</script>
<template>
  <c-space direction="column">
    <c-map v-model="location" map-type="amaps" style="height: 300px" />
    <p role="status">{{ location.address }}（{{ location.longitude }}, {{ location.latitude }}）</p>
  </c-space>
</template>
```

## API

### Map Props

| Prop | Description | Type | Default |
| ----------------------- | -------------------------------------------- | -------------------------------------------- | ---------------- |
| model-value(**v-model**) | Initial map value representing the selected location | `Object` | - |
| default-value | Default map center | `{ [key in valueKeyAlias[keys]]: any }` | - |
| driver | Return value of `Fetch.genDriiver` | `Driver` | `-` |
| fetch | Return value of `Fetch.genFetch` | `CoreService` | `-` |
| geocoder-url | Geocoder endpoint URL | `string` | `-` |
| geocoder-handler | Processes geocoding-service responses | `(longitude: number, latitude: number)=>{})` | - |
| base-path | Base URL for map data | `String` | `'/pe/powerpro'` |
| is-international | Whether this is a Google map | `Boolean` | - |
| show-name | Whether to show the floating location name | `boolean` | `false` |
| show-locate-me-button | Whether to show the current-location button | `boolean` | `false` |
| show-edit-address-button | Whether to show the floating change-location button | `boolean` | `false` |
| show-map-tips | Whether to show tips above the map | `boolean` | `false` |
| map-type | Map type | `'qqmaps'\|'bmapGL'\|'amaps'` | `'amaps'` |
| enable-gis-search | Whether to enable GIS search; `fetch` is required when enabled | `boolean` | `false` |
| value-key-scope | String array of values displayed on the map | `Array` | `valueKeyScope` |
| value-key-alias | Mapping from map keys to values | `Object` | `valueKeyAlias` |

### MapSelect Props

| map-style | Styles applied directly to the map; can set map height | `object` | `{ height: '300px'}` |

### Map Events

| Event | Description | Arguments |
| --------------- | -------------------------- | ------------------------- |
| change | Emitted when the address changes | `(value: ModelValueType)` |
| init | Emitted after map initialization | `(value: ModelValueType)` |
| loading:address | Emitted while resolving the selected location's address | `-` |
| loaded:address | Emitted after resolving the selected location's address | `-` |

## Type definitions

### valueKeyAlias

```ts
{
  longitude: 'longitude',
  latitude: 'latitude',
  address: 'address',
  name: 'name',
  adcode: 'adcode',
  city: 'city',
  countryCode: 'countryCode',
  country: 'country',
}
```

### valueKeyScope

```ts
;['longitude', 'latitude', 'address', 'name', 'adcode', 'city', 'country', 'countryCode']
```

### ModelValueType

ModelValueType keys depend on valueKeyAlias

```ts
interface ModelValueType {
  adcode?: string
  city?: string
  country?: string
  countryCode?: string
  address?: string
  latitude?: number
  longitude?: number
  name?: string
}
```

The component exports the following types

```ts
import type { MapProps } from '@cedar-design/ui'
```

---

Document: llms/en-US/components/mention.md

<!-- Source: src/mention/README.en-US.md; locale: en-US; page: /en/components/mention/ -->

# Mention

Text input with mention suggestions supplied by the application.

## Basic examples

### Basic usage

Example source: src/mention/__demos__/basic.vue

```vue
<template>
  <c-space direction="column" size="lg" style="width: 100%">
    <c-mention v-model="value" :data="['Bytedance', 'Bytedesign', 'Bytenumner']" placeholder="enter something" />
    <c-mention
      v-model="text"
      :data="['Bytedance', 'Bytedesign', 'Bytenumner']"
      type="textarea"
      placeholder="enter something" />
  </c-space>
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const value = ref('')
const text = ref('')
</script>
```

## Customization and slots

### Prefix

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration | Purpose                               | Related examples |
| ------------- | ------------------------------------- | ---------------- |
| `data`        | Data for automatic completion         | Prefix           |
| `prefix`      | Keywords that trigger auto-completion | Prefix           |

<!-- demo-config-notes:end -->

- `data`: Data for automatic completion
- `prefix`: Keywords that trigger auto-completion

Example source: src/mention/__demos__/prefix.vue

```vue
<template>
  <c-space direction="column" size="lg" style="width: 100%">
    <c-mention :data="['Bytedance', 'Bytedesign', 'Bytenumner']" placeholder="input @" />
    <c-mention :data="['Bytedance', 'Bytedesign', 'Bytenumner']" prefix="#" placeholder="input #" />
    <c-mention :data="['Bytedance', 'Bytedesign', 'Bytenumner']" prefix="$" placeholder="input $" />
  </c-space>
</template>

<script lang="ts" setup>
</script>
```

## Lifecycle and edge cases

### Mirror Lifecycle

Example source: src/mention/__demos__/mirror-lifecycle.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import Mention from "../index";

const active = ref(true);
const mounted = ref(true);
const disabled = ref(false);
const searches = ref(0);
const value = ref("第一行\n第二行\n第三行\n@al");
</script>

<template>
  <div>
    <c-button html-type="button" @click="active = !active"
      >切换 KeepAlive</c-button
    >
    <c-button html-type="button" @click="mounted = !mounted"
      >卸载／挂载</c-button
    >
    <c-button html-type="button" @click="disabled = !disabled"
      >切换禁用</c-button
    >
    <p>
      搜索通知：{{ searches }}。在文本域滚动后输入
      @al，停用再激活，继续输入检查镜像定位。
    </p>
    <KeepAlive v-if="mounted">
      <Mention
        v-if="active"
        v-model="value"
        type="textarea"
        :disabled="disabled"
        :data="['alice', 'alex']"
        :rows="3"
        @search="searches++"
      />
    </KeepAlive>
  </div>
</template>
```

## Loading and waiting

### Controlled loading

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| `loading` | Explicit business loading state | `boolean` | `false` |


Set loading explicitly to display feedback. Ordinary event return values do not drive loading. Before hooks retain their documented pending behavior.

Example source: src/mention/__demos__/loading.vue

```vue
<script setup lang="ts">
import { onBeforeUnmount, ref } from 'vue'
import type { OptionsLoader } from '../../_hooks/use-option-request'
const loading = ref(true)
const requests = new Set<(failed?: boolean) => void>()
const pending = ref(0)
const status = ref('等待数据 / Waiting for data')
const load: OptionsLoader<string> = (query, { signal }) => new Promise((resolve, reject) => {
  const finish = (failed = false) => {
    requests.delete(finish)
    pending.value = requests.size
    signal.removeEventListener('abort', cancel)
    if (failed) reject(new Error('Candidate request failed'))
    else resolve(['Alice', 'Bob'].filter(name => name.toLowerCase().includes(query.toLowerCase())))
  }
  const cancel = () => finish()
  requests.add(finish)
  pending.value = requests.size
  signal.addEventListener('abort', cancel, { once: true })
})
function settle(failed = false) {
  status.value = failed ? '请求失败，可继续输入重试 / Failed; type to retry' : '数据已返回 / Data received'
  ;[...requests].forEach(finish => finish(failed))
}
onBeforeUnmount(() => settle())
</script>
<template>
  <c-space direction="column" style="width: 100%" :size="16">
    <h4>业务控制 / Manual loading</h4>
    <c-switch v-model="loading" aria-label="业务加载状态 / Manual loading" />
    <c-mention edit-mode="direct" :loading="loading" :data="['Alice', 'Bob']" placeholder="单行输入 @ / Single line" />
    <c-mention edit-mode="direct" type="textarea" :loading="loading" :data="['Alice', 'Bob']" placeholder="多行输入 @ / Multiple lines" />
    <p>loading 只控制显示，两种输入框均可继续编辑。普通事件返回 Promise 不会触发等待。Loading does not disable editing or await notification handlers.</p>
    <h4>数据源等待 / Remote candidates</h4>
    <c-mention edit-mode="direct" :data="load" placeholder="输入 @a，手动返回候选数据 / Type @a" @load-error="() => {}" />
    <c-space>
      <c-button :disabled="!pending" @click="settle()">返回数据 / Resolve</c-button>
      <c-button :disabled="!pending" @click="settle(true)">模拟失败 / Reject</c-button>
    </c-space>
    <p role="status">{{ pending ? '请求中，仍可输入 / Pending; editing remains available' : status }}</p>
  </c-space>
</template>
```

## API

### Empty values and reading placeholders

`empty-values` recognizes empty data; `empty-value` keeps existing clear output. `empty-text` defaults to `'-'` under `read-pretty`, with Field > FormItem > Form precedence and custom read slots first. With explicit empty-values, built-in required uses the policy; custom validators receive original data. See the [shared guide](llms/en-US/guide/empty-values.md).

| Prop         | Type               | Default and scope                                                           |
| ------------ | ------------------ | --------------------------------------------------------------------------- |
| empty-values | readonly unknown[] | Field > FormItem > Form > component-family default; replaces the whole list |
| empty-text   | string             | Field > FormItem > Form > '-'; explicit '' is valid                         |

These props belong to field presentation; pure panels do not gain reading mode. Form and FormItem provide inherited settings. The existing empty-value type and clear fallback remain component-specific.

### `<mention>` Props

| Parameter                 | Description                                  | Type                                                                                                       |   Default   | Version |
| ------------------------- | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | :---------: | :------ |
| model-value **(v-model)** | Bound value                                  | `string`                                                                                                   |     `-`     |         |
| default-value             | Default value (uncontrolled state)           | `string`                                                                                                   |    `''`     |         |
| data                      | Data for automatic completion                | `(string \| number \| SelectOptionData \| SelectOptionGroup)[]` / `(query, { signal }) => Array / Promise` | `undefined` |         |
| prefix                    | Keywords that trigger auto-completion        | `string \| string[]`                                                                                       |    `'@'`    |         |
| split                     | Before and after the selected item separator | `string`                                                                                                   |    `' '`    |         |
| type                      | default input or textarea                    | `'input' \| 'textarea'`                                                                                    |  `'input'`  |         |
| disabled                  | Whether disabled                             | `boolean`                                                                                                  |   `false`   |         |
| clearable                 | Whether to allow the input to be cleared     | `boolean`                                                                                                  |   `false`   | 2.23.0  |

### `<mention>` Events

| Event  | Description                                               | Arguments                                                     | Version |
| ------ | --------------------------------------------------------- | ------------------------------------------------------------- | :------ |
| change | Emitted when the value changes                            | value: `string`                                               |         |
| search | Emitted during dynamic search; prefix was added in 2.47.0 | value: `string`<br>prefix: `string`                           |         |
| select | Emitted when a dropdown option is selected                | value: `string \| number \| Record<string, any> \| undefined` |         |
| clear  | Emitted when the user clicks the clear button             | -                                                             | 2.23.0  |
| focus  | Emitted when the text input gains focus                   | ev: `FocusEvent`                                              | 2.42.0  |
| blur   | Emitted when the text input loses focus                   | ev: `FocusEvent`                                              | 2.42.0  |

### `<mention>` Methods

| Method | Description     | Arguments | Returns | Version |
| ------ | --------------- | --------- | ------- | :------ |
| focus  | Focus the input | -         | -       | 2.24.0  |
| blur   | Blur the input  | -         | -       | 2.24.0  |

### `<mention>` Slots

| Slot   |  Description   | Arguments          | Version |
| ------ | :------------: | ------------------ | :------ |
| option | Option content | data: `OptionInfo` | 2.13.0  |

### Type definitions

The component exports the following types

```ts
import type { MentionInstance } from "@cedar-design/ui";
```

Mention reuses Input/Textarea typography and spacing; its measurement mirror copies computed native input styles. Override the corresponding input variables. Ineffective mention-font-size, mention-line-height and mention-padding-* variables are removed.

### Form field presentation and confirmation

Cedar uses edit-mode="click" / "dblclick" to open an editor popup near the field. Enter/F2 also opens it; cancel/Escape discards the draft, and confirmation commits it. readPretty is an independent reading setting, separate from readonly and disabled.

## Configuring the cleared value

`empty-value` / `emptyValue` sets the model value produced by clearing. It accepts a value in the component model type or a zero-argument factory. Omission preserves the existing default; use `() => undefined` to distinguish omission from returning undefined. Arrays are shallow-copied on every clear; selected items that cannot be cleared remain. It does not redefine emptiness, alter Form reset defaults or treat 0/false as universally empty.
Text and person-ID models remain strings; use an empty string or a business-defined string sentinel.

`empty-value` accepts explicit `null` (or `() => null`). Clearing publishes `null` unchanged; omitted values preserve the existing default. Editors render `null` as blank without converting ordinary empty-string input to `null`. In popup editing, clearing changes the draft; confirm commits it and cancel preserves the original model.

`data` accepts an array or (query, { signal }) => array/Promise. The component manages loading, cancellation and stale-result isolation; failures emit load-error. Single/multiple groups initialize with an empty query; searchable fields reload when queries change. Tree root loading is independent of existing load-more child loading.

Both input and textarea show manual loading and the current explicit data-loader wait. Loading feedback does not implicitly disable editing; search notification return Promises do not start tasks. Old data requests cannot clear the current request indicator, and load-error retains its original error payload.

---

Document: llms/en-US/components/menu.md

<!-- Source: src/menu/README.en-US.md; locale: en-US; page: /en/components/menu/ -->

# Menu

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

- `options`: Supplies the available options.

Example source: src/menu/__demos__/basic.vue

```vue
<template>
  <c-menu :options="options">
    <c-button variant="tonal" :elevation="false" aria-label="更多操作"><template #icon><c-icon-more /></template></c-button>
  </c-menu>
</template>

<script setup lang="ts">
const options = [
  { label: '编辑', value: 'edit' },
  { label: '复制', value: 'copy' },
  { type: 'divider' },
  { label: '删除', value: 'delete' },
]
</script>
```

## Appearance and states

### Disabled

- `disabled`: Prevents user interaction.

Example source: src/menu/__demos__/disabled.vue

```vue
<template>
  <c-space wrap>
    <c-menu disabled>
      <c-button disabled>菜单禁用</c-button>
      <template #content><c-menu-option label="Option 1" /></template>
    </c-menu>
    <c-menu>
      <c-button>选项禁用</c-button>
      <template #content>
        <c-menu-option label="可用选项" />
        <c-menu-option label="禁用选项" disabled />
        <c-menu-option label="另一个可用选项" />
      </template>
    </c-menu>
  </c-space>
</template>
```

## Options and hierarchy

### Groups, submenus and option content

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `options` | Command tree | Groups, submenus and option content, Active Rendering |
| `hide-on-select` | Close the popup after activating a command | Active Rendering |
| `submenu-trigger` | How every submenu level expands | Active Rendering |
<!-- demo-config-notes:end -->


Compare flat groups, nested menus and option content. Expand or select options to inspect their hierarchy.

Example source: src/menu/__demos__/structure-comparison.vue

```vue
<script setup lang="ts">
import { h } from "vue"
import { proxyRefs as demoProxyRefs } from 'vue'

const scene1 = demoProxyRefs((() => {

const options = [
  { type: 'group', label: '文件操作', children: [{ label: '新建', value: 'new' }, { label: '打开', value: 'open' }] },
  { type: 'group', label: '编辑操作', children: [{ label: '复制', value: 'copy' }, { label: '粘贴', value: 'paste' }] },
]
return { options }
})())

const scene2 = demoProxyRefs((() => {

const options = [
  { label: '首页', value: 'home' },
  { label: '产品', children: [
    { label: '产品概览', value: 'overview' },
    { label: '解决方案', children: [{ label: '企业版', value: 'enterprise' }, { label: '团队版', value: 'team' }] },
  ] },
  { label: '关于我们', value: 'about' },
]
return { options }
})())

const scene3 = demoProxyRefs((() => {


const icon = (text: string) => h('span', { 'aria-hidden': 'true' }, text)

const options = [
  { label: '编辑', value: 'edit', icon: icon('✎'), extra: '⌘ E' },
  { label: ({ active }: { active: boolean }) => h('strong', active ? '已选中复制' : '复制'), value: 'copy', icon: icon('⧉'), extra: '⌘ C' },
  { label: '删除', value: 'delete', icon: icon('⌫'), extra: '⌫', disabled: true },
]
return { icon, options }
})())
</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="group">
    <h4><span lang="zh-CN">选项分组</span><span lang="en-US">group</span></h4>
    <c-menu :options="scene1.options">
        <c-button>选项分组</c-button>
      </c-menu>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="submenu">
    <h4><span lang="zh-CN">多级菜单</span><span lang="en-US">submenu</span></h4>
    <c-menu :options="scene2.options">
        <c-button>多级菜单</c-button>
      </c-menu>
  </section>

  <section class="demo-comparison-case demo-comparison-case--3" data-comparison-scene="option-content">
    <h4><span lang="zh-CN">自定义选项内容</span><span lang="en-US">option content</span></h4>
    <c-menu :options="scene3.options">
        <c-button>自定义选项内容</c-button>
      </c-menu>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

### Active Rendering

- `options`: Supplies the available options.

Example source: src/menu/__demos__/active-rendering.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
import type { MenuRenderContext } from '@cedar-design/ui'

const selectedValue = ref('account')
const status = ({ active }: MenuRenderContext) => active ? '当前项已选中' : '当前项未选中'
const options = [
  { label: '设置', value: 'settings', extra: status, children: [
    { label: '账户', value: 'account', extra: status },
    { label: '通知', value: 'notifications', extra: status },
  ] },
  { label: '帮助', value: 'help', extra: status },
]
const helpLabel = ({ active }: MenuRenderContext) => active ? '帮助（已选中）' : '帮助（未选中，仅视觉强调）'
</script>

<template>
  <p>当前值：{{ selectedValue }}。默认选中“账户”；父分支“设置”处于选中路径，但 active=false。</p>
  <c-space wrap>
    <c-menu v-model="selectedValue" :options="options" :hide-on-select="false" submenu-trigger="click">
      <c-button>渲染函数中的 active</c-button>
    </c-menu>
    <c-menu v-model="selectedValue" :options="options" :hide-on-select="false" submenu-trigger="click">
      <c-button>作用域插槽中的 active</c-button>
      <template #option-extra="{ active }">
        <c-tag :status="active ? 'primary' : 'default'">{{ active ? '当前项已选中' : '当前项未选中' }}</c-tag>
      </template>
    </c-menu>
    <c-menu v-model="selectedValue" :hide-on-select="false">
      <c-button>自定义子项与 highlight</c-button>
      <template #content>
        <c-menu-option value="account">
          <template #default="{ active }">账户：{{ active ? '已选中' : '未选中' }}</template>
        </c-menu-option>
        <c-menu-option value="help" :label="helpLabel" highlight />
      </template>
    </c-menu>
  </c-space>
</template>
```

## Triggers and positioning

### Context Menu

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `trigger` | Root menu trigger | Context Menu, Trigger |
| `options` | Command tree | Context Menu, Positioning |
| `align-point` | Align to the pointer position at activation; stays in place until the next context menu activation | Context Menu |
| `placement` | Preferred popup side relative to the trigger, default bottom. With the default auto-fit-position enabled, Trigger may flip and constrain it to the viewport when space is limited; this is not a fixed final position | Placement |
| `strategy` | Positioning strategy inherited by every submenu | Positioning |
| `submenu-trigger` | How every submenu level expands | Positioning |
<!-- demo-config-notes:end -->


- `options`: Supplies the available options.

Example source: src/menu/__demos__/context-menu.vue

```vue
<script setup lang="ts">
const options = [
  { label: 'Option 1', value: 'option-1' },
  { label: 'Option 2', value: 'option-2' },
  { label: 'Option 3', value: 'option-3' },
]
</script>

<template>
  <c-menu trigger="contextMenu" align-point :options="options" style="display: block">
    <div class="c-menu-context-target">右键点击</div>
  </c-menu>
</template>

<style scoped>
.c-menu-context-target {
  display: flex;
  align-items: center;
  justify-content: center;
  height: 160px;
  background-color: var(--c-sys-color-surface-muted);
}
</style>
```

### Trigger

Preview configuration: `trigger="click"`, `label="Option 1"`, `label="Option 2"`, `trigger="hover"`.

Example source: src/menu/__demos__/trigger.vue

```vue
<template>
  <c-space wrap>
    <c-menu trigger="click">
      <c-button>点击触发</c-button>
      <template #content>
        <c-menu-option label="Option 1" />
        <c-menu-option label="Option 2" />
      </template>
    </c-menu>
    <c-menu trigger="hover">
      <c-button>悬浮触发</c-button>
      <template #content>
        <c-menu-option label="Option 1" />
        <c-menu-option label="Option 2" />
      </template>
    </c-menu>
  </c-space>
</template>
```

### Placement

- `placement`: Chooses the position relative to the trigger.

Example source: src/menu/__demos__/placement.vue

```vue
<template>
  <c-space wrap>
    <c-menu placement="bottom-start">
      <c-button>Bottom Left</c-button>
      <template #content>
        <c-menu-option>Option 1</c-menu-option>
        <c-menu-option>Option 2</c-menu-option>
        <c-menu-option>Option 3</c-menu-option>
      </template>
    </c-menu>

    <c-menu placement="bottom">
      <c-button>Bottom</c-button>
      <template #content>
        <c-menu-option>Option 1</c-menu-option>
        <c-menu-option>Option 2</c-menu-option>
        <c-menu-option>Option 3</c-menu-option>
      </template>
    </c-menu>

    <c-menu placement="bottom-end">
      <c-button>Bottom Right</c-button>
      <template #content>
        <c-menu-option>Option 1</c-menu-option>
        <c-menu-option>Option 2</c-menu-option>
        <c-menu-option>Option 3</c-menu-option>
      </template>
    </c-menu>

    <c-menu placement="top-start">
      <c-button>Top Left</c-button>
      <template #content>
        <c-menu-option>Option 1</c-menu-option>
        <c-menu-option>Option 2</c-menu-option>
        <c-menu-option>Option 3</c-menu-option>
      </template>
    </c-menu>

    <c-menu placement="top">
      <c-button>Top</c-button>
      <template #content>
        <c-menu-option>Option 1</c-menu-option>
        <c-menu-option>Option 2</c-menu-option>
        <c-menu-option>Option 3</c-menu-option>
      </template>
    </c-menu>

    <c-menu placement="top-end">
      <c-button>Top Right</c-button>
      <template #content>
        <c-menu-option>Option 1</c-menu-option>
        <c-menu-option>Option 2</c-menu-option>
        <c-menu-option>Option 3</c-menu-option>
      </template>
    </c-menu>
  </c-space>
</template>
```

### Positioning

- `options`: Supplies the available options.

Example source: src/menu/__demos__/positioning.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
import type { MenuStrategy } from '@cedar-design/ui'

const strategy = ref<MenuStrategy>('fixed')
const options = [
  { label: '操作', children: [
    { label: '导出', children: [
      { label: 'CSV', value: 'csv' },
      { label: 'JSON', value: 'json' },
    ] },
    { label: '复制', value: 'copy' },
  ] },
]
</script>

<template>
  <c-space direction="column">
    <c-button @click="strategy = strategy === 'fixed' ? 'absolute' : 'fixed'">
      切换定位：{{ strategy }}
    </c-button>
    <c-menu :strategy="strategy" :options="options" submenu-trigger="click">
      <c-button>打开三级菜单</c-button>
      <template #footer>
        <c-button variant="text" @click.stop="strategy = strategy === 'fixed' ? 'absolute' : 'fixed'">
          展开时切换：{{ strategy }}
        </c-button>
      </template>
    </c-menu>
    <small>所有层级继承同一定位策略；挂载容器仍由 popup-container 单独控制。</small>
  </c-space>
</template>
```

### Popup Height

Preview configuration: `:popup-max-height="120"`, `:label="item"`, `:popup-max-height="false"`.

Example source: src/menu/__demos__/popup-height.vue

```vue
<template>
  <c-space wrap>
    <c-menu :popup-max-height="120">
      <c-button>限制为 120px</c-button>
      <template #content>
        <c-menu-option v-for="item in options" :key="item" :label="item" />
      </template>
    </c-menu>
    <c-menu :popup-max-height="false">
      <c-button>不限制高度</c-button>
      <template #content>
        <c-menu-option v-for="item in options" :key="item" :label="item" />
      </template>
    </c-menu>
  </c-space>
</template>

<script lang="ts" setup>
const options = Array.from({ length: 8 }, (_, index) => `Option ${index + 1}`);
</script>
```

## State and content customization

### Selection

- `options`: Supplies the available options.

Example source: src/menu/__demos__/selection.vue

```vue
<template>
  <c-space direction="column">
    <c-menu v-model="active" :options="options" @select="handleSelect">
      <c-button>{{ selectedLabel || "请选择操作" }}</c-button>
    </c-menu>
    <span
      >当前值：{{ active || "-" }}，最近选择：{{ selectedLabel || "-" }}</span
    >
  </c-space>
</template>

<script lang="ts" setup>
import { ref } from "vue";

const active = ref("edit");
const selectedLabel = ref("编辑");
const options = [
  { label: '编辑', value: 'edit' },
  { label: '复制', value: 'copy' },
  { label: '删除', value: 'delete' },
]

const handleSelect = (_value: unknown, option: { label?: string | number }) => {
  selectedLabel.value = String(option.label ?? "");
};
</script>
```

### Controlled

Preview configuration: `v-model:open="open"`, `label="Option 1"`, `label="Option 2"`.

Example source: src/menu/__demos__/controlled.vue

```vue
<template>
  <c-space direction="column">
    <c-button @mousedown.stop @click.stop="open = !open">{{
      open ? "关闭菜单" : "打开菜单"
    }}</c-button>
    <c-menu v-model:open="open">
      <c-button>菜单触发器</c-button>
      <template #content>
        <c-menu-option label="Option 1" />
        <c-menu-option label="Option 2" />
      </template>
    </c-menu>
  </c-space>
</template>

<script lang="ts" setup>
import { ref } from "vue";

const open = ref(false);
</script>
```

### Footer

Example source: src/menu/__demos__/footer.vue

```vue
<template>
  <c-menu>
    <c-button>页脚</c-button>
    <template #content>
      <c-menu-option>Option 1</c-menu-option>
      <c-menu-option>Option 2</c-menu-option>
    </template>
    <template #footer>
      <div style="padding: 8px 12px">自定义页脚</div>
    </template>
  </c-menu>
</template>
```

## Reading direction

Inherits the nearest `dir="ltr|rtl"` and supports runtime and nested overrides. Submenus and horizontal parent/child navigation follow the current reading direction. Vertical and boundary navigation keeps item order and skips disabled items. Portals inherit their source direction; switching direction preserves selection.

## API

### Value and default value

Use ordinary `v-model`. `modelValue` is the selected option value; `defaultValue` initializes uncontrolled state once, and later changes do not reset it. Explicit binding takes precedence. Initialization emits no `update:modelValue`.

### `<Menu>` Props

| Parameter | Description | Type | Default |
| --- | --- | --- | :---: |
| options | Command tree | `MenuOptionData[]` | `[]` |
| field-names | `label/value/children/disabled` field mapping | `MenuFieldNames` | `-` |
| model-value **(v-model)** | Current active value for controlled highlighting | `MenuValue` | `-` |
| open **(v-model)** | Whether the popup is visible | `boolean` | `-` |
| default-open | Uncontrolled default visibility | `boolean` | `false` |
| trigger | Root menu trigger | `'hover' \| 'click' \| 'focus' \| 'contextMenu'` | `'click'` |
| submenu-trigger | How every submenu level expands | `'hover' \| 'click'` | `'hover'` |
| placement | Preferred popup side relative to the trigger, default bottom. With the default auto-fit-position enabled, Trigger may flip and constrain it to the viewport when space is limited; this is not a fixed final position | `MenuPlacement` | `'bottom'` |
| `strategy` | Positioning strategy inherited by every submenu | `'absolute' \| 'fixed'` | `'absolute'` |
| popup-container | Popup mount container | `string \| HTMLElement \| false` | `-` |
| popup-max-height | Default limit, pixel height, or unlimited | `boolean \| number` | `true` |
| hide-on-select | Close the popup after activating a command | `boolean` | `true` |
| auto-fit-popup-width | Match popup width to the trigger | `boolean` | `false` |
| disabled | Disable the menu | `boolean` | `false` |
| align-point | Align to the pointer position at activation; stays in place until the next context menu activation | `boolean` | `false` |

### `MenuOptionData`

| Field | Description | Type |
| --- | --- | --- |
| type | Plain command, group or divider | `'item' \| 'group' \| 'divider'` |
| label | Main content | `VNodeChild \| (context) => VNodeChild` |
| icon | Leading icon | `VNodeChild \| (context) => VNodeChild` |
| extra | Trailing content such as a shortcut | `VNodeChild \| (context) => VNodeChild` |
| value | Value passed to events on activation | `any` |
| children | Child commands; a plain option with children becomes a submenu | `MenuOptionData[]` |
| disabled | Disable this item and its descendants | `boolean` |
| show | Whether to render | `boolean` |
| ripple | Whether to show the click ripple | `boolean` |
| props | HTML attributes forwarded to the row element | `HTMLAttributes` |

The render context is `{ option, active, level }`. `type: 'group'` is visual only and does not add a level; `type: 'divider'` is neither focusable nor activatable.

### Events

| Event | Description | Arguments |
| --- | --- | --- |
| update:model-value | Active value update request | `value: MenuValue` |
| open-change | Visibility update request | `open: boolean` |
| select | A menu item was activated | `value, option, event` |

### Slots

| Slot | Description | Arguments |
| --- | --- | --- |
| default | Trigger element | - |
| content | Hand-written content, pairs with `MenuOption` | - |
| footer | Footer | - |
| option-label | Render every option's main content | `{ option, active, level }` |
| option-icon | Render every option's icon | `{ option, active, level }` |
| option-extra | Render every option's trailing content | `{ option, active, level }` |

### `<MenuOption>`

Retained for SplitButton and a few handwritten `content` cases. Props are `label`, `value`, `disabled`, `ripple` and `highlight`. The `label` render function and `default`/`icon`/`suffix` slots receive `{ option, active, level }`. Clicking emits `click`. `highlight` controls visual emphasis without committing selection. Groups/submenus are described only through `options`; `MenuGroup` and `MenuSubmenu` are no longer exported.

### Instance methods and keyboard

The instance exposes `open()`, `close()`, `resize()` and `setReference(reference?)`. Root menus support Up/Down, Home/End and Enter. Right enters submenus; Left/Escape returns. Each Escape closes only the topmost layer and restores focus.

Classes, CSS variables and internal DOM markers consistently use `c-menu-*`, `--c-menu-*` and `data-menu-*`.

### State and duration variables

Disabled overrides selection, pointer hover and keyboard focus. Selected hover uses a separate role, inheriting the selected background by default; override it for additional feedback. Both platforms paint selected backgrounds directly on options.

| Token | Default |
| --- | --- |
| `--c-menu-option-bg-selected-hover` | `var(--c-menu-option-bg-selected)` |

### Data identity and trigger switching

Reorderable items should provide stable unique values; internal Vue keys derive from business values. Numeric `0`, string `'0'` and boolean `false` remain distinct. Groups, separators and display items without values retain identity through their original option objects; no public key alias is added. Clicking another sibling trigger that is already hover-open closes the previous menu. Clicking inside a submenu does not incorrectly close its parent.


### Placement semantics and configuration

MenuPlacement uses the twelve-value TriggerPlacement domain. Both prop and type describe the preferred popup side relative to its trigger. The old MenuPosition export has been removed.

---

Document: llms/en-US/components/message.md

<!-- Source: src/message/README.en-US.md; locale: en-US; page: /en/components/message/ -->

# Message

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

Example source: src/message/__demos__/basic.vue

```vue
<template>
  <c-button @click="handleClick">Info Message</c-button>
</template>
<script lang="ts">
import { defineComponent } from "vue";
import { Message } from "@cedar-design/ui";

export default defineComponent({
  setup() {
    return {
      handleClick() {
        Message.info("This is an info message");
      },
    };
  },
});
</script>
```

## Appearance and states

### Type

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `status` | Semantic status | Appearance Lab |
| `position` | Region of the message itself in the viewport: top/center/bottom, default top. Not positioned relative to a trigger | Appearance Lab |
| `closable` | Show the close button | Appearance Lab |
| `duration` | Auto-close duration in ms; `0` disables automatic closing | Appearance Lab |
| `variant` | Visual emphasis | Appearance Lab |
<!-- demo-config-notes:end -->


Example source: src/message/__demos__/type.vue

```vue
<template>
  <div>
    <c-space>
      <c-button @click="() => Message.info('This is an info message!')"
        >Info Message</c-button
      >
      <c-button
        @click="() => Message.success('This is a success message!')"
        status="success"
        >Success Message
      </c-button>
      <c-button
        @click="() => Message.warning('This is a warning message!')"
        status="warning"
        >Warning Message
      </c-button>
      <c-button
        @click="() => Message.error('This is an error message!')"
        status="danger"
        >Error Message</c-button
      >
    </c-space>
  </div>
  <div style="margin-top: 20px">
    <c-space>
      <c-button @click="() => Message('This is a default message!')"
        >Default Message</c-button
      >
      <c-button
        @click="
          () =>
            Message({
              content: 'This is a default message!',
              icon: renderIcon,
            })
        "
        >Default Message With Icon
      </c-button>
      <c-button @click="handleLoading" status="primary"
        >Loading Message
      </c-button>
    </c-space>
  </div>
</template>

<script lang="ts">
import { defineComponent, h } from "vue";
import { IconExclamationCircleFill } from "@cedar-design/icons-vue";
import { Message } from "@cedar-design/ui";

export default defineComponent({
  setup() {
    const renderIcon = () => h(IconExclamationCircleFill);

    const handleLoading = () => {
      const message = Message.loading("This is a loading message!");
      setTimeout(() => {
        message.close();
        Message.success("Loaded");
      }, 2000);
    };

    return {
      renderIcon,
      handleLoading,
      Message,
    };
  },
});
</script>
```

### Variant

Example source: src/message/__demos__/variant.vue

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

const variants = ["neutral", "tonal", "solid"] as const;
</script>

<template>
  <c-space wrap>
    <c-button
      @click="Message.success({ content: 'neutral (default)', closable: true })"
      >neutral (default)</c-button
    >
    <c-button
      v-for="variant in variants"
      :key="variant"
      @click="Message.success({ content: variant, variant, closable: true })"
      >{{ variant }}</c-button
    >
  </c-space>
</template>
```

### Appearance Lab

- `status`: Selects the semantic state.

Example source: src/message/__demos__/appearance-lab.vue

```vue
<script setup lang="ts">
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const open = ref(false);
const __demoAppearance = __demoReactive({
  variant: "neutral",
  status: "default",
});

import { computed as demoComputed, ref as demoRef } from 'vue'
const demoCompareFields = [{"name":"variant","values":["neutral","tonal","solid"]},{"name":"status","values":["default","info","success","warning","danger","loading"]}]
const demoCompareAxis = demoRef("variant")
const demoComparedOptions = demoComputed(() => demoCompareFields.find(field => field.name === demoCompareAxis.value)?.values ?? [])
</script>
<template>
  <c-space direction="column" :size="16">
    <c-form layout="vertical">
      <c-form-item layout="vertical" size="sm" label="variant">
        <c-radio-group
          v-model="__demoAppearance['variant']"
          aria-label="variant"
          :options="[
            { label: 'neutral', value: 'neutral' },
            { label: 'tonal', value: 'tonal' },
            { label: 'solid', value: 'solid' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
      <c-form-item layout="vertical" size="sm" label="status">
        <c-select
          v-model="__demoAppearance['status']"
          :clearable="false"
          :options="[
            { label: 'default', value: 'default' },
            { label: 'info', value: 'info' },
            { label: 'success', value: 'success' },
            { label: 'warning', value: 'warning' },
            { label: 'danger', value: 'danger' },
            { label: 'loading', value: 'loading' },
          ]"
          aria-label="status"
        />
      </c-form-item>
    </c-form>
    <p class="demo-config-comparison-hint"><span lang="zh-CN">选择一个对比维度；其他配置和内容保持一致。输入类示例共享同一个值，便于比较外观。</span><span lang="en-US">Compare one dimension while keeping the other settings and content identical. Input specimens share the same value.</span></p>
<c-radio-group v-model="demoCompareAxis" aria-label="Compare configuration" :options="demoCompareFields.map(field => ({ label: field.name, value: field.name }))" />
<c-space wrap><c-button v-for="sample in demoComparedOptions" :key="String(sample)" @click="() => { __demoAppearance[demoCompareAxis] = sample; open = true }">{{ demoCompareAxis }}={{ sample }}</c-button></c-space>
<c-message
      v-model:open="open"
      status="success"
      position="center"
      closable
      :duration="0"
      v-bind="__demoAppearance"
    >
      Declarative message
      <template #action>
        <c-button size="sm" variant="text" @click="open = false"
          >Close</c-button
        >
      </template>
    </c-message>
  </c-space>
</template>

<style scoped>
.demo-config-comparison { display: grid; grid-template-columns: repeat(auto-fit, minmax(min(100%, 220px), 1fr)); gap: 20px; min-width: 0; max-width: 100%; }
.demo-config-comparison > section { min-width: 0; }
.demo-config-comparison p { margin: 0 0 8px; }
html:not([lang='en-US']) .demo-config-comparison-hint > [lang='en-US'],
html[lang='en-US'] .demo-config-comparison-hint > [lang='zh-CN'] { display: none; }
</style>
```

## Layout and arrangement

### Location

Example source: src/message/__demos__/location.vue

```vue
<template>
  <c-space>
    <c-button
      @click="() => Message.info({ content: 'This is an info message!' })"
      >Top Message</c-button
    >
    <c-button
      @click="
        () =>
          Message.info({
            content: 'This is an info message!',
            position: 'bottom',
          })
      "
      >Bottom Message</c-button
    >
    <c-button
      @click="
        () =>
          Message.info({
            content: 'This is an info message!',
            position: 'center',
          })
      "
      >Center Message</c-button
    >
  </c-space>
</template>
<script lang="ts">
import { defineComponent } from "vue";
import { Message } from "@cedar-design/ui";

export default defineComponent({
  setup() {
    return {
      Message,
    };
  },
});
</script>
```

## Content and presentation

### Time

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `status` | Semantic status | Component |
| `position` | Region of the message itself in the viewport: top/center/bottom, default top. Not positioned relative to a trigger | Component |
| `closable` | Show the close button | Component |
| `duration` | Auto-close duration in ms; `0` disables automatic closing | Component |
<!-- demo-config-notes:end -->


Example source: src/message/__demos__/time.vue

```vue
<template>
  <c-button @click="handleClick">Duration 1000ms</c-button>
</template>
<script lang="ts">
import { defineComponent } from "vue";
import { Message } from "@cedar-design/ui";

export default defineComponent({
  setup() {
    const handleClick = () => {
      Message.info({
        content: "This is an info message!",
        duration: 1000,
      });
    };
    return {
      handleClick,
    };
  },
});
</script>
```

### Update

Example source: src/message/__demos__/update.vue

```vue
<template>
  <c-button @click="handleClick">Update Info Message</c-button>
</template>
<script lang="ts">
import { defineComponent, ref } from "vue";
import { Message } from "@cedar-design/ui";

export default defineComponent({
  setup() {
    const index = ref(0);
    const handleClick = () => {
      Message.info({
        id: "myInfo",
        content: `This is an info message ${index.value++}`,
        duration: 2000,
        resetOnUpdate: true,
      });
    };
    return {
      index,
      handleClick,
    };
  },
});
</script>
```

### Pause On Hover

Example source: src/message/__demos__/pause-on-hover.vue

```vue
<template>
  <c-button @click="handleClick">Reset On Hover</c-button>
</template>
<script lang="ts">
import { defineComponent } from "vue";
import { Message } from "@cedar-design/ui";

export default defineComponent({
  setup() {
    const handleClick = () => {
      Message.info({
        content: "Hover to pause auto close",
        duration: 3000,
        pauseOnHover: true,
      });
    };
    return {
      handleClick,
    };
  },
});
</script>
```

### Component

- `status`: Selects the semantic state.

Example source: src/message/__demos__/component.vue

```vue
<script setup lang="ts">
import { ref } from "vue";

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

<template>
  <c-button status="primary" @click="open = true">Open Message</c-button>
  <c-message
    v-model:open="open"
    status="success"
    position="center"
    closable
    :duration="0"
  >
    Declarative message
    <template #action>
      <c-button size="sm" variant="text" @click="open = false">Close</c-button>
    </template>
  </c-message>
</template>
```

## Customization and slots

### Custom Icon

Example source: src/message/__demos__/custom-icon.vue

```vue
<template>
  <c-button @click="handleClick">Info Message</c-button>
</template>

<script lang="ts">
import { defineComponent, h } from "vue";
import { IconFaceSmileFill } from "@cedar-design/icons-vue";
import { Message } from "@cedar-design/ui";

export default defineComponent({
  setup() {
    const handleClick = () => {
      Message.info({
        content: "This is an info message!",
        icon: () => h(IconFaceSmileFill),
      });
    };
    return {
      handleClick,
    };
  },
});
</script>
```

## Interaction and control

### Closable

Example source: src/message/__demos__/closable.vue

```vue
<template>
  <c-button @click="handleClick">Closeable Message</c-button>
</template>
<script lang="ts">
import { defineComponent } from "vue";
import { Message } from "@cedar-design/ui";

export default defineComponent({
  setup() {
    const handleClick = () => {
      Message.info({
        content: "This is an info message!",
        closable: true,
      });
    };
    return {
      handleClick,
    };
  },
});
</script>
```

### Loading

Example source: src/message/__demos__/loading.vue

```vue
<template>
  <c-space>
    <c-button status="primary" @click="handleLoading">Loading</c-button>
  </c-space>
</template>

<script lang="ts">
import { defineComponent } from "vue";
import { Message } from "@cedar-design/ui";

export default defineComponent({
  setup() {
    const handleLoading = () => {
      const message = Message.loading("This is a loading message");
      setTimeout(() => {
        message.close();
        Message.success("Loaded");
      }, 2000);
    };

    return {
      handleLoading,
    };
  },
});
</script>
```

Example source: src/message/__demos__/multiple.vue

```vue
<template>
  <c-button @click="handleClick">Multiple Messages</c-button>
</template>
<script lang="ts">
import { defineComponent } from "vue";
import { Message } from "@cedar-design/ui";

export default defineComponent({
  setup() {
    const handleClick = () => {
      const message1 = Message.info("Message 1");
      Message.success("Message 2");
      Message.warning("Message 3");
      setTimeout(() => {
        message1.close();
      }, 1000);
    };
    return {
      handleClick,
    };
  },
});
</script>
```

## Reading direction

Inherits the nearest `dir="ltr|rtl"` and supports runtime and nested overrides. Content, icon and close gaps follow reading direction. Direction changes preserve message type, timing and close semantics. Imperative calls use explicit or document direction.

## API

### Props / MessageOptions

| Prop | Description | Type | Default |
| --------------------- | -------------------------------------- | ------------------------------------------------------------ | --------------- |
| open / `v-model:open` | Controlled visibility | `boolean` | `false` |
| id | Unique queue identifier; the same id updates the existing instance | `string \| number` | Automatically generated |
| status | Semantic status | `default \| info \| success \| warning \| danger \| loading` | `default` |
| variant | Visual emphasis | `neutral \| tonal \| solid` | `neutral` |
| position | Region of the message itself in the viewport: top/center/bottom, default top. Not positioned relative to a trigger | `top \| center \| bottom` | `top` |
| content | Content | `MessageContent` | - |
| icon | Custom icon | `MessageContent` | - |
| action | Action-area content | `MessageContent` | - |
| duration | Auto-close duration in ms; `0` disables automatic closing | `number` | `3000` |
| showIcon | Whether to show the status icon | `boolean` | `true` |
| closable | Show the close button | `boolean` | `false` |
| pauseOnHover | Pause while hovered | `boolean` | `false` |
| resetOnUpdate | Whether same-id updates reset the complete duration | `boolean` | `false` |
| closeButtonAriaLabel | Close button label | `string` | `Close message` |
| popupContainer | Mount container; function-call queues are isolated by container and position | `string \| HTMLElement \| false` | `body` |

Function options additionally accept `onOpen / onOpened / onClose / onClosed`. Close callbacks receive the current `id`.

### Events

`update:open`, `open`, `opened`, `close`, and `closed`, emitted once per visibility cycle.

### Methods

| Method | Description |
| ------------------------------------------------- | ------------------------ |
| `Message(options \| string)` | Open a default message |
| `Message.info/success/warning/error/loading(...)` | Open a message with the corresponding status |
| `Message.clear(position?)` | Clear all messages or a specified position |
| `Message.setDefaultOptions(options)` | Set defaults for subsequent calls |
| `Message.resetDefaultOptions()` | Restore defaults |

Returns `{ close() }`. Repeated `close()` calls do not duplicate closing lifecycle events.

### Slots

`default`、`icon`、`action`。

## Public CSS variables

Visual variant is independent of status. neutral uses a neutral popup and status icon; tonal uses a low-emphasis status background with dark content; solid uses a high-emphasis fill and matching foreground. Cedar/Maple both default to neutral; explicit solid/tonal have matching visual semantics. default/loading solid retains a dark background, with the loading icon indicating progress. Both export MessageVariant; function calls, setDefaultOptions and same-id updates support variant.

Colors use `--c-message-{variant}-{status}-{bg|content-color|icon-color|border-color|close-color}`. bg sets the panel background; content-color sets body/action text unless separately styled; icon-color sets status icons; border-color sets borders; close-color sets close controls. With a custom background, verify all three foregrounds. Geometry retains platform density rather than forcing equal defaults. Variables must affect actual Teleport-container ancestors.

| Variable | Default |
| --- | --- |
| `--c-message-neutral-default-bg` | `var(--c-sys-color-surface-overlay)` |
| `--c-message-neutral-default-content-color` | `var(--c-sys-color-content-primary)` |
| `--c-message-neutral-default-icon-color` | `var(--c-sys-color-content-primary)` |
| `--c-message-neutral-default-border-color` | `var(--c-sys-color-border-default)` |
| `--c-message-neutral-default-close-color` | `var(--c-sys-color-content-secondary)` |
| `--c-message-neutral-info-bg` | `var(--c-sys-color-surface-overlay)` |
| `--c-message-neutral-info-content-color` | `var(--c-sys-color-content-primary)` |
| `--c-message-neutral-info-icon-color` | `var(--c-sys-color-content-info)` |
| `--c-message-neutral-info-border-color` | `var(--c-sys-color-border-default)` |
| `--c-message-neutral-info-close-color` | `var(--c-sys-color-content-secondary)` |
| `--c-message-neutral-success-bg` | `var(--c-sys-color-surface-overlay)` |
| `--c-message-neutral-success-content-color` | `var(--c-sys-color-content-primary)` |
| `--c-message-neutral-success-icon-color` | `var(--c-sys-color-content-success)` |
| `--c-message-neutral-success-border-color` | `var(--c-sys-color-border-default)` |
| `--c-message-neutral-success-close-color` | `var(--c-sys-color-content-secondary)` |
| `--c-message-neutral-warning-bg` | `var(--c-sys-color-surface-overlay)` |
| `--c-message-neutral-warning-content-color` | `var(--c-sys-color-content-primary)` |
| `--c-message-neutral-warning-icon-color` | `var(--c-sys-color-content-warning)` |
| `--c-message-neutral-warning-border-color` | `var(--c-sys-color-border-default)` |
| `--c-message-neutral-warning-close-color` | `var(--c-sys-color-content-secondary)` |
| `--c-message-neutral-danger-bg` | `var(--c-sys-color-surface-overlay)` |
| `--c-message-neutral-danger-content-color` | `var(--c-sys-color-content-primary)` |
| `--c-message-neutral-danger-icon-color` | `var(--c-sys-color-content-danger)` |
| `--c-message-neutral-danger-border-color` | `var(--c-sys-color-border-default)` |
| `--c-message-neutral-danger-close-color` | `var(--c-sys-color-content-secondary)` |
| `--c-message-neutral-loading-bg` | `var(--c-sys-color-surface-overlay)` |
| `--c-message-neutral-loading-content-color` | `var(--c-sys-color-content-primary)` |
| `--c-message-neutral-loading-icon-color` | `var(--c-sys-color-content-brand)` |
| `--c-message-neutral-loading-border-color` | `var(--c-sys-color-border-default)` |
| `--c-message-neutral-loading-close-color` | `var(--c-sys-color-content-secondary)` |
| `--c-message-tonal-default-bg` | `var(--c-sys-color-surface-muted)` |
| `--c-message-tonal-default-content-color` | `var(--c-sys-color-content-primary)` |
| `--c-message-tonal-default-icon-color` | `var(--c-sys-color-content-primary)` |
| `--c-message-tonal-default-border-color` | `transparent` |
| `--c-message-tonal-default-close-color` | `var(--c-sys-color-content-primary)` |
| `--c-message-tonal-info-bg` | `rgba(var(--c-blue-6), 0.12)` |
| `--c-message-tonal-info-content-color` | `var(--c-sys-color-content-primary)` |
| `--c-message-tonal-info-icon-color` | `var(--c-sys-color-content-info)` |
| `--c-message-tonal-info-border-color` | `transparent` |
| `--c-message-tonal-info-close-color` | `var(--c-sys-color-content-primary)` |
| `--c-message-tonal-success-bg` | `var(--c-color-success-light-1)` |
| `--c-message-tonal-success-content-color` | `var(--c-sys-color-content-primary)` |
| `--c-message-tonal-success-icon-color` | `var(--c-sys-color-content-success)` |
| `--c-message-tonal-success-border-color` | `transparent` |
| `--c-message-tonal-success-close-color` | `var(--c-sys-color-content-primary)` |
| `--c-message-tonal-warning-bg` | `var(--c-color-warning-light-1)` |
| `--c-message-tonal-warning-content-color` | `var(--c-sys-color-content-primary)` |
| `--c-message-tonal-warning-icon-color` | `var(--c-sys-color-content-warning)` |
| `--c-message-tonal-warning-border-color` | `transparent` |
| `--c-message-tonal-warning-close-color` | `var(--c-sys-color-content-primary)` |
| `--c-message-tonal-danger-bg` | `var(--c-color-danger-light-1)` |
| `--c-message-tonal-danger-content-color` | `var(--c-sys-color-content-primary)` |
| `--c-message-tonal-danger-icon-color` | `var(--c-sys-color-content-danger)` |
| `--c-message-tonal-danger-border-color` | `transparent` |
| `--c-message-tonal-danger-close-color` | `var(--c-sys-color-content-primary)` |
| `--c-message-tonal-loading-bg` | `var(--c-color-primary-light-1)` |
| `--c-message-tonal-loading-content-color` | `var(--c-sys-color-content-primary)` |
| `--c-message-tonal-loading-icon-color` | `var(--c-sys-color-content-brand)` |
| `--c-message-tonal-loading-border-color` | `transparent` |
| `--c-message-tonal-loading-close-color` | `var(--c-sys-color-content-primary)` |
| `--c-message-solid-default-bg` | `#333` |
| `--c-message-solid-default-content-color` | `var(--c-sys-color-content-on-dark)` |
| `--c-message-solid-default-icon-color` | `var(--c-sys-color-content-on-dark)` |
| `--c-message-solid-default-border-color` | `transparent` |
| `--c-message-solid-default-close-color` | `var(--c-sys-color-content-on-dark)` |
| `--c-message-solid-info-bg` | `var(--c-sys-color-status-info)` |
| `--c-message-solid-info-content-color` | `var(--c-sys-color-content-on-bright)` |
| `--c-message-solid-info-icon-color` | `var(--c-sys-color-content-on-bright)` |
| `--c-message-solid-info-border-color` | `transparent` |
| `--c-message-solid-info-close-color` | `var(--c-sys-color-content-on-bright)` |
| `--c-message-solid-success-bg` | `var(--c-sys-color-status-success)` |
| `--c-message-solid-success-content-color` | `var(--c-sys-color-content-on-bright)` |
| `--c-message-solid-success-icon-color` | `var(--c-sys-color-content-on-bright)` |
| `--c-message-solid-success-border-color` | `transparent` |
| `--c-message-solid-success-close-color` | `var(--c-sys-color-content-on-bright)` |
| `--c-message-solid-warning-bg` | `var(--c-sys-color-status-warning)` |
| `--c-message-solid-warning-content-color` | `var(--c-sys-color-content-on-bright)` |
| `--c-message-solid-warning-icon-color` | `var(--c-sys-color-content-on-bright)` |
| `--c-message-solid-warning-border-color` | `transparent` |
| `--c-message-solid-warning-close-color` | `var(--c-sys-color-content-on-bright)` |
| `--c-message-solid-danger-bg` | `var(--c-sys-color-status-danger)` |
| `--c-message-solid-danger-content-color` | `var(--c-sys-color-content-on-bright)` |
| `--c-message-solid-danger-icon-color` | `var(--c-sys-color-content-on-bright)` |
| `--c-message-solid-danger-border-color` | `transparent` |
| `--c-message-solid-danger-close-color` | `var(--c-sys-color-content-on-bright)` |
| `--c-message-solid-loading-bg` | `#333` |
| `--c-message-solid-loading-content-color` | `var(--c-sys-color-content-on-dark)` |
| `--c-message-solid-loading-icon-color` | `var(--c-sys-color-content-on-dark)` |
| `--c-message-solid-loading-border-color` | `transparent` |
| `--c-message-solid-loading-close-color` | `var(--c-sys-color-content-on-dark)` |
| `--c-message-wrapper-margin-top` | `var(--c-spacing-12)` |
| `--c-message-wrapper-margin-bottom` | `var(--c-spacing-12)` |
| `--c-message-wrapper-padding-horizontal` | `var(--c-spacing-5)` |
| `--c-message-z-index` | `var(--c-z-index-message)` |
| `--c-message-padding-top` | `var(--c-spacing-5)` |
| `--c-message-padding-bottom` | `var(--c-spacing-5)` |
| `--c-message-padding-left` | `var(--c-spacing-7)` |
| `--c-message-padding-right` | `var(--c-spacing-7)` |
| `--c-message-margin-bottom` | `var(--c-spacing-7)` |
| `--c-message-border-radius` | `var(--c-border-radius-sm)` |
| `--c-message-icon-font-size` | `20px` |
| `--c-message-content-font-size` | `var(--c-font-size-body-3)` |
| `--c-message-icon-margin-right` | `var(--c-spacing-4)` |
| `--c-message-box-shadow` | `var(--c-shadow2-down)` |
| `--c-message-border-width` | `1px` |
| `--c-message-border-style` | `solid` |
| `--c-message-close-icon-font-size` | `12px` |
| `--c-message-close-btn-margin-left` | `var(--c-spacing-4)` |
| `--c-message-close-icon-hover-size` | `20px` |
| `--c-message-close-icon-hover-opacity` | `0.08` |
| `--c-message-transition-duration` | `var(--c-transition-duration-1)` |
| `--c-message-transition-duration-icon` | `var(--c-transition-duration-4)` |
| `--c-message-transition-timing-function` | `var( --c-transition-timing-function-linear )` |
| `--c-message-transition-timing-function-icon` | `var( --c-transition-timing-function-overshoot )` |

A throwing close/closed notification cannot retain the closed item or its empty manager host. Resources are released independently of notification callbacks.

---

Document: llms/en-US/components/nav-menu.md

<!-- Source: src/nav-menu/README.en-US.md; locale: en-US; page: /en/components/nav-menu/ -->

# Nav Menu

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

- `options`: Supplies the available options.

Example source: src/nav-menu/__demos__/basic.vue

```vue
<template>
  <div class="nav-menu-demo">
    <c-nav-menu v-model="selected" :options="options" />
    <p>当前页面：{{ selected }}</p>
  </div>
</template>

<script setup lang="ts">
import { ref } from "vue";
import { options } from "./data";

const selected = ref<string | number | null>(0);
</script>

<style scoped>
.nav-menu-demo {
  width: 240px;
  max-width: 100%;
}
</style>
```

Example source: src/nav-menu/__demos__/horizontal-sub-menu.vue

```vue
<template>
  <div class="nav-menu-demo">
    <c-nav-menu v-model="selected" mode="horizontal" :options="options" />
    <p>当前页面：{{ selected }}</p>
  </div>
</template>

<script setup lang="ts">
import { ref } from "vue";
import { options } from "./data";

const selected = ref<string | number | null>("cloud");
</script>

<style scoped>
.nav-menu-demo {
  min-height: 180px;
}
</style>
```

## Appearance and layout

### Size

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `options` | Navigation tree | Size |
| `size` | Size | Size |
| `mode` | Navigation orientation | Size |
<!-- demo-config-notes:end -->


- `options`: Supplies the available options.
- `size`: Controls the component size.

Example source: src/nav-menu/__demos__/size.vue

```vue
<template>
  <div v-for="size in sizes" :key="size" style="margin-bottom: 16px">
    <p>尺寸：{{ size }}</p>
    <c-nav-menu :options="options" :size="size" mode="horizontal" />
  </div>
</template>
<script setup lang="ts">
import { options } from './data'
const sizes = ['xs', 'sm', 'md', 'lg', 'xl'] as const
</script>
```

## Hierarchy and responsive layout

### Sub Menu

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `options` | Navigation tree | Sub Menu |
| `accordion` | Expand only one branch per level | Sub Menu |
| `default-value` | Initial uncontrolled selected value | Sub Menu |
| `collapsed` | Collapsed state; supports v-model:collapsed | Sub Menu |
| `mode` | Navigation orientation | Sub Menu |
<!-- demo-config-notes:end -->


- `options`: Supplies the available options.

Example source: src/nav-menu/__demos__/sub-menu.vue

```vue
<template>
  <c-nav-menu :options="options" accordion default-value="compute" />
</template>
<script setup lang="ts">
import { options } from './data'

</script>
```

Example source: src/nav-menu/__demos__/collapsed.vue

```vue
<template>
  <div class="nav-menu-demo">
    <c-button @click="collapsed = !collapsed">{{
      collapsed ? "展开菜单" : "折叠菜单"
    }}</c-button>
    <c-nav-menu
      :options="options"
      :collapsed="collapsed"
      default-value="cloud"
    />
  </div>
</template>

<script setup lang="ts">
import { ref } from "vue";
import { options } from "./data";

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

<style scoped>
.nav-menu-demo {
  display: grid;
  justify-items: start;
  gap: 12px;
  width: 240px;
  max-width: 100%;
}

.nav-menu-demo :deep(.c-nav-menu) {
  width: 100%;
}
</style>
```

Example source: src/nav-menu/__demos__/breakpoint.vue

```vue
<template>
  <div class="nav-menu-demo">
    <p>拖动虚线容器右下角，观察菜单项收入“更多”。</p>
    <div class="nav-menu-demo__resizable">
      <c-nav-menu :options="options" mode="horizontal" />
    </div>
  </div>
</template>

<script setup lang="ts">
import { options } from "./data";
</script>

<style scoped>
.nav-menu-demo p {
  margin-top: 0;
}

.nav-menu-demo__resizable {
  width: 520px;
  max-width: 100%;
  min-width: 240px;
  min-height: 180px;
  overflow: auto;
  resize: horizontal;
  border-right: 1px dashed var(--c-color-border-2);
  border-bottom: 1px dashed var(--c-color-border-2);
}
</style>
```

## Entries and panels

### Items Horizontal

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `mode` | Navigation orientation | Items Horizontal |
| `active-item` | Controlled named NavMenu.Item activation; supports v-model:active-item | Items Horizontal |
<!-- demo-config-notes:end -->


Preview configuration: `mode="horizontal"`, `label="分类"`, `:options="categories"`, `label="地区"`.

Example source: src/nav-menu/__demos__/items-horizontal.vue

```vue
<script setup lang="ts">
import { computed, ref } from 'vue'
import type { NavMenuKey, NavMenuOption } from '..'

const category = ref<NavMenuKey | null>(null)
const region = ref<NavMenuKey | null>(null)
const keyword = ref('')
const appliedKeyword = ref('')
const categories: NavMenuOption[] = [
  { key: 'all', label: '全部分类' },
  { key: 'design', label: '设计资源' },
  { key: 'development', label: '开发工具' },
]
const regions: NavMenuOption[] = [
  { key: 'all', label: '全部地区' },
  { key: 'east', label: '华东' },
  { key: 'south', label: '华南' },
  { key: 'north', label: '华北' },
]
const categoryLabel = computed(() => categories.find((item) => item.key === category.value)?.label ?? '未选择')
const regionLabel = computed(() => regions.find((item) => item.key === region.value)?.label ?? '未选择')
function resetFilters(close: () => void) {
  keyword.value = ''
  appliedKeyword.value = ''
  close()
}
function applyFilters(close: () => void) {
  appliedKeyword.value = keyword.value.trim()
  close()
}
</script>
<template>
  <div>
    <c-nav-menu mode="horizontal">
      <c-nav-menu-item v-model="category" label="分类" :options="categories" />
      <c-nav-menu-item
        v-model="region"
        label="地区"
        :options="regions"
        options-mode="horizontal"
        popup-layout="full-width"
      />
      <c-nav-menu-item label="更多筛选" :highlight="!!appliedKeyword" popup-layout="full" :hide-on-select="false">
        <template #content="{ close }">
          <div style="height: 100%; display: flex; flex-direction: column; gap: 16px">
            <div style="flex: 1; min-height: 0; overflow-y: auto">
              <c-space direction="column" style="width: 100%">
                <strong>按关键词筛选</strong>
                <c-input v-model="keyword" placeholder="输入资源名称" aria-label="资源名称" />
              </c-space>
            </div>
            <c-space>
              <c-button @click="resetFilters(close)">重置</c-button>
              <c-button @click="applyFilters(close)">应用</c-button>
            </c-space>
          </div>
        </template>
      </c-nav-menu-item>
    </c-nav-menu>
    <p aria-live="polite">分类：{{ categoryLabel }}；地区：{{ regionLabel }}；关键词：{{ appliedKeyword || '不限' }}</p>
  </div>
</template>
```

Example source: src/nav-menu/__demos__/items-vertical.vue

```vue
<script setup lang="ts">
import { computed, ref } from 'vue'
import type { NavMenuKey, NavMenuOption } from '../types'

const section = ref<NavMenuKey | null>('overview')
const project = ref<NavMenuKey | null>(null)
const keyword = ref('')
const appliedKeyword = ref('')
const projects: NavMenuOption[] = [
  { key: 'website', label: '官网改版' },
  { key: 'dashboard', label: '数据平台' },
  { key: 'archived', label: '已归档项目', disabled: true },
]
const projectLabel = computed(() => projects.find(item => item.key === project.value)?.label ?? '未选择')
</script>

<template>
  <div class="vertical-items-demo">
    <c-nav-menu v-model:active-item="section" mode="vertical" class="vertical-items-demo__menu">
      <c-nav-menu-item label="工作概览" name="overview" />
      <c-nav-menu-item label="我的任务" name="tasks" />
      <c-nav-menu-item
        v-model="project"
        label="选择项目"
        :options="projects"
        options-mode="vertical"
        placement="right-start"
      />
      <c-nav-menu-item
        label="高级筛选"
        :highlight="!!appliedKeyword"
        popup-layout="full-height"
        placement="right-start"
        :popup-style="{ width: 'min(360px, 100vw)' }"
      >
        <template #content="{ close }">
          <c-space direction="column" style="width: 100%; height: 100%">
            <h3>任务筛选</h3>
            <p>应用后高亮入口，保留“高级筛选”标题。</p>
            <c-input v-model="keyword" placeholder="输入任务关键词" aria-label="任务关键词" />
            <c-space>
              <c-button @click="appliedKeyword = keyword.trim(); close()">应用</c-button>
              <c-button @click="keyword = ''; appliedKeyword = ''; close()">重置</c-button>
              <c-button @click="close()">关闭</c-button>
            </c-space>
          </c-space>
        </template>
      </c-nav-menu-item>
    </c-nav-menu>
    <div aria-live="polite">
      <h3>{{ section === 'overview' ? '工作概览' : '我的任务' }}</h3>
      <p>当前项目：{{ projectLabel }}</p>
      <p>关键词：{{ appliedKeyword || '不限' }}</p>
      <p>页面入口互斥选中，项目和高级筛选独立控制。</p>
    </div>
  </div>
</template>

<style scoped>
.vertical-items-demo { display: flex; flex-wrap: wrap; gap: 24px; align-items: flex-start; }
.vertical-items-demo__menu { width: 200px; max-width: 100%; flex: none; }
</style>
```

Example source: src/nav-menu/__demos__/entry-state.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
import type { NavMenuKey } from '..'

const value = ref<NavMenuKey | null>(null)
const activeItem = ref<NavMenuKey | null>(null)
const highlight = ref<boolean | undefined>(undefined)
const options = [{ key: 0, label: '数字零' }, { key: '', label: '空字符串' }, { key: 'account', label: '账户' }]
const highlightText = () => highlight.value === undefined ? '跟随业务 active' : String(highlight.value)
</script>

<template>
  <c-space direction="column">
    <c-space wrap>
      <c-button @click="highlight = undefined">跟随业务状态</c-button>
      <c-button @click="highlight = true">强制强调</c-button>
      <c-button @click="highlight = false">取消强调</c-button>
      <c-button @click="value = null">清空主值</c-button>
      <c-button @click="value = 'missing'">设为未匹配值</c-button>
    </c-space>
    <p>独立入口主值：{{ JSON.stringify(value) }}；highlight：{{ highlightText() }}。</p>
    <c-nav-menu mode="horizontal" class="entry-state-menu">
      <c-nav-menu-item v-model="value" :options="options" :highlight="highlight">
        <template #label="{ active, open }">独立入口 active={{ active }} / open={{ open }}</template>
      </c-nav-menu-item>
    </c-nav-menu>
    <p>具名当前入口：{{ activeItem ?? '无' }}。只打开面板不会改变 activeItem；选择叶子项后才切换。</p>
    <c-nav-menu v-model:active-item="activeItem" mode="horizontal" class="entry-state-menu">
      <c-nav-menu-item name="first" :options="options">
        <template #label="{ active, open }">入口一 active={{ active }} / open={{ open }}</template>
      </c-nav-menu-item>
      <c-nav-menu-item name="second" :options="options">
        <template #label="{ active, open }">入口二 active={{ active }} / open={{ open }}</template>
      </c-nav-menu-item>
    </c-nav-menu>
  </c-space>
</template>

<style scoped>
.entry-state-menu {
  width: 100%;
  min-width: 0;
}
</style>
```

Example source: src/nav-menu/__demos__/item-label.vue

```vue
<script setup lang="ts">
import { computed, ref } from "vue";
import type { NavMenuKey } from "../types";

const options = [
  { key: 0, label: "全部分类" },
  { key: "design", label: "设计" },
  { key: "development", label: "开发" },
];
const activeItem = ref<NavMenuKey | null>(null);
const automatic = ref<NavMenuKey | null>(null);
const fixed = ref<NavMenuKey | null>(null);
const manual = ref<NavMenuKey | null>(null);
const manualLabel = ref("手动标题");
const appliedValue = ref<NavMenuKey | null>(null);
const automaticLabel = computed(
  () =>
    options.find((option) => option.key === automatic.value)?.label ?? "未选择",
);
const fixedLabel = computed(
  () => options.find((option) => option.key === fixed.value)?.label ?? "未选择",
);
const selectedLabel = computed(
  () =>
    options.find((option) => option.key === manual.value)?.label ?? "未选择",
);
const pending = computed(() => manual.value !== appliedValue.value);

function applyLabel() {
  if (manual.value === null) return;
  manualLabel.value = `当前：${selectedLabel.value}`;
  appliedValue.value = manual.value;
}

function reset() {
  manual.value = appliedValue.value = null;
  manualLabel.value = "手动标题";
}
</script>

<template>
  <div class="item-label-demo">
    <c-nav-menu v-model:active-item="activeItem" mode="horizontal">
      <c-nav-menu-item
        v-model="automatic"
        name="automatic"
        label="自动标题"
        :options="options"
      />
      <c-nav-menu-item v-model="fixed" name="fixed" :options="options">
        <template #label>固定标题</template>
      </c-nav-menu-item>
      <c-nav-menu-item v-model="manual" name="manual" :options="options">
        <template #label>{{ manualLabel }}</template>
      </c-nav-menu-item>
    </c-nav-menu>

    <div class="item-label-demo__status" aria-live="polite">
      <p>
        <strong>自动标题：</strong>选择后入口直接显示“{{ automaticLabel }}”。
      </p>
      <p>
        <strong>固定标题：</strong>入口始终显示“固定标题”，当前选择“{{
          fixedLabel
        }}”。
      </p>
      <p>
        <strong>手动标题：</strong>当前选择“{{ selectedLabel }}”，入口显示“{{
          manualLabel
        }}”。
        <span v-if="pending">选择尚未应用到标题。</span>
      </p>
    </div>

    <c-space wrap>
      <c-button :disabled="!pending || manual === null" @click="applyLabel">
        {{ pending ? `应用手动标题：${selectedLabel}` : "手动标题已同步" }}
      </c-button>
      <c-button @click="reset">重置手动标题</c-button>
    </c-space>

    <p class="item-label-demo__tip">
      当前激活入口：{{ activeItem ?? "暂无" }}。打开入口不会激活，选择叶子节点后才会统一切换高亮；各面板内部数据仍各自保留。
    </p>
  </div>
</template>

<style scoped>
.item-label-demo {
  display: grid;
  grid-template-columns: minmax(0, 1fr);
  min-width: 0;
  gap: 16px;
  min-height: 220px;
}

.item-label-demo__status {
  display: grid;
  gap: 8px;
}

.item-label-demo__status p,
.item-label-demo__tip {
  margin: 0;
}

.item-label-demo__tip {
  color: var(--c-color-text-3);
}
</style>
```

Example source: src/nav-menu/__demos__/item-label-independent.vue

```vue
<script setup lang="ts">
import { computed, ref } from 'vue'
import type { NavMenuKey, NavMenuOption } from '..'

const categories: NavMenuOption[] = [
  { key: 'design', label: '设计资源' },
  { key: 'development', label: '开发工具' },
  { key: 'document', label: '文档资料' },
]
const regions: NavMenuOption[] = [
  { key: 'east', label: '华东' },
  { key: 'south', label: '华南' },
  { key: 'north', label: '华北' },
]

const category = ref<NavMenuKey | null>('design')
const region = ref<NavMenuKey | null>('east')
const categoryLabel = computed(
  () => categories.find(option => option.key === category.value)?.label ?? '未选择',
)
const regionLabel = computed(
  () => regions.find(option => option.key === region.value)?.label ?? '未选择',
)
</script>

<template>
  <div class="item-label-independent-demo">
    <c-nav-menu mode="horizontal">
      <c-nav-menu-item v-model="category" label="选择分类" :options="categories" />
      <c-nav-menu-item v-model="region" label="选择地区" :options="regions" />
    </c-nav-menu>

    <div class="item-label-independent-demo__status" aria-live="polite">
      <p><strong>分类：</strong>{{ categoryLabel }}</p>
      <p><strong>地区：</strong>{{ regionLabel }}</p>
    </div>

    <c-space>
      <c-button :disabled="category === null" @click="category = null">清空分类</c-button>
      <c-button :disabled="region === null" @click="region = null">清空地区</c-button>
    </c-space>

    <p class="item-label-independent-demo__tip">
      两个 Item 未设置 name，各自根据选中值更新标题和高亮，互不清除；面板仍互斥展开。
    </p>
  </div>
</template>

<style scoped>
.item-label-independent-demo {
  display: grid;
  gap: 16px;
  min-height: 180px;
}

.item-label-independent-demo__status {
  display: flex;
  flex-wrap: wrap;
  gap: 8px 24px;
}

.item-label-independent-demo__status p,
.item-label-independent-demo__tip {
  margin: 0;
}

.item-label-independent-demo__tip {
  color: var(--c-color-text-3);
}
</style>
```

## Data and state control

### Controlled

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `options` | Navigation tree | Controlled |
| `model-value` | Current selected key; supports v-model. null means no selection | Controlled |
| `expanded-keys` | Controlled expanded branches | Controlled |
| `field-names` | Field mapping for key/label/children/disabled | Controlled |
| `disabled` | Globally disable selection/user expansion | Controlled |
| `default-value` | Initial uncontrolled selected value | Controlled |
<!-- demo-config-notes:end -->


- `options`: Supplies the available options.
- `disabled`: Prevents user interaction.

Example source: src/nav-menu/__demos__/controlled.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
import type { NavMenuKey } from '../types'
import { options } from './data'
const selected = ref<NavMenuKey | null>(0)
const expanded = ref<NavMenuKey[]>([])
const acceptUpdates = ref(true)
const lastRequest = ref('尚未操作')
function select(key: NavMenuKey | null) {
  lastRequest.value = `请求选择：${key}`
  if (acceptUpdates.value) selected.value = key
}
function expand(keys: NavMenuKey[]) {
  lastRequest.value = `请求展开：${keys.join('、') || '无'}`
  if (acceptUpdates.value) expanded.value = keys
}
</script>
<template>
  <div>
    <c-button @click="acceptUpdates = !acceptUpdates">{{ acceptUpdates ? '当前接受更新，点击拒绝' : '当前拒绝更新，点击接受' }}</c-button>
    <c-nav-menu :options="options" :model-value="selected" :expanded-keys="expanded" @update:model-value="select" @update:expanded-keys="expand" />
    <p aria-live="polite">{{ lastRequest }}；实际选中：{{ selected }}；实际展开：{{ expanded.join('、') || '无' }}</p>
  </div>
</template>
```

Example source: src/nav-menu/__demos__/item-controlled.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'

const accepted = ref(true)
const open = ref(false)
const value = ref<string | number | null>(null)
const options = [
  { key: 0, label: '不限' },
  { key: 'design', label: '设计' },
  { key: 'disabled', label: '禁用选项', disabled: true },
]
function updateOpen(next: boolean) {
  if (accepted.value) {
    open.value = next
  }
}
function updateValue(next: string | number | null) {
  if (accepted.value) {
    value.value = next
  }
}
</script>
<template>
  <c-button @click="accepted = !accepted">{{
    accepted ? '当前接受更新，点击拒绝' : '当前拒绝更新，点击接受'
  }}</c-button>
  <c-nav-menu>
    <c-nav-menu-item
      :open="open"
      :model-value="value"
      :options="options"
      label="受控筛选"
      @update:open="updateOpen"
      @update:model-value="updateValue"
    />
    <c-nav-menu-item label="禁用入口" disabled :options="options" />
  </c-nav-menu>
  <p>选中：{{ value ?? '未选择' }}；展开：{{ open }}</p>
</template>
```

Example source: src/nav-menu/__demos__/panel-state.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
import type { NavMenuInstance } from '..'

const menu = ref<NavMenuInstance>()
const unmountOnClose = ref(false)
const options = [{ key: 0, label: '不限' }, { key: 'design', label: '设计资源' }]
</script>
<template>
  <c-space direction="column" style="width: 100%">
    <c-space>
      <span>关闭后卸载</span>
      <c-switch v-model="unmountOnClose" />
      <c-button @click="menu?.close()">关闭当前面板</c-button>
    </c-space>
    <c-nav-menu ref="menu" mode="horizontal">
      <c-nav-menu-item label="草稿表单" :unmount-on-close="unmountOnClose">
        <template #content="{ close }">
          <c-space direction="column" style="width: 100%">
            <c-input default-value="" placeholder="输入后关闭，再打开查看草稿" aria-label="面板内部草稿" />
            <c-button @click="close">关闭并返回入口</c-button>
          </c-space>
        </template>
      </c-nav-menu-item>
      <c-nav-menu-item label="分类" :options="options" />
    </c-nav-menu>
    <p>默认保留面板内部草稿；开启卸载后再次展开会重新创建。关闭面板不会提交或重置业务筛选值。</p>
  </c-space>
</template>
```

Example source: src/nav-menu/__demos__/field-names.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
import type { NavMenuOption } from '../types'
const disabled = ref(false)
const fieldNames = { key: 'id', label: 'name', children: 'items', disabled: 'unavailable' }
const options: NavMenuOption[] = [
  { type: 'group', name: '工作空间', items: [
    { id: 0, name: '概览' },
    { id: 'projects', name: '项目', items: [{ id: 'active', name: '进行中' }, { id: 'archived', name: '已归档', unavailable: true }] },
  ] },
  { type: 'divider' },
  { id: 'settings', name: '设置' },
  { id: 'hidden', name: '隐藏入口', show: false },
]
</script>
<template>
  <div>
    <c-button @click="disabled = !disabled">{{ disabled ? '启用菜单' : '禁用整个菜单' }}</c-button>
    <c-nav-menu :options="options" :field-names="fieldNames" :disabled="disabled" :default-value="0" default-expand-all />
  </div>
</template>
```

Example source: src/nav-menu/__demos__/custom-content.vue

```vue
<template>
  <c-nav-menu :options="options">
    <template #label="{ option, active }"><strong :style="{ fontWeight: active ? 700 : 400 }">{{ option.label }}</strong></template>
    <template #extra="{ option }"><c-tag v-if="option.key === 'inbox'">3</c-tag></template>
  </c-nav-menu>
</template>
<script setup lang="ts">
import { h } from 'vue'
import type { NavMenuOption } from '..'
const options: NavMenuOption[] = [
  { key: 'workspace', type: 'group', label: '工作空间', children: [
    { key: 'inbox', label: '收件箱' }, { key: 'docs', label: '文档', icon: h('span', '文') },
  ] },
  { type: 'divider' }, { key: 'settings', label: '设置' },
]
</script>
```

## NavMenu API

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| options | Navigation tree | NavMenuOption[] | [] |
| model-value | Current selected key; supports v-model. null means no selection | string / number / null | undefined |
| default-value | Initial uncontrolled selected value | string / number / null | null |
| active-item | Controlled named NavMenu.Item activation; supports v-model:active-item | string / number / null | undefined |
| default-active-item | Initial uncontrolled named NavMenu.Item activation | string / number / null | null |
| expanded-keys | Controlled expanded branches | (string / number)[] | undefined |
| default-expanded-keys | Initial uncontrolled expanded branches | (string / number)[] | [] |
| default-expand-all | Initially expand every branch | boolean | false |
| auto-expand-selected | Expand selected-item ancestors in vertical noncollapsed mode; controlled mode requests updates | boolean | true |
| accordion | Expand only one branch per level | boolean | false |
| mode | Navigation orientation | vertical / horizontal | vertical |
| collapsed | Collapsed state; supports v-model:collapsed | boolean | undefined |
| default-collapsed | Initial uncontrolled collapsed state | boolean | false |
| theme | Code Theme | light / dark | Inherit Sider, otherwise light |
| size | Size | xs / sm / md / lg / xl | md |
| disabled | Globally disable selection/user expansion | boolean | false |
| field-names | Field mapping for key/label/children/disabled | NavMenuFieldNames | Same-name fields by default |
| responsive | Enable horizontal overflow collection | boolean | true |
| indent | Indent per level in px | number | 24 |
| root-indent | Root indent in px | number | 12 |
| collapsed-width | Collapsed width in px | number | 56 |
| icon-size | Icon size in px | number | 20 |
| popup-container | Popup mount container; false renders locally | Matching Trigger type | Inherits Trigger definition |
| popup-class | Additional popup class | string / array / object | — |
| overflow-label | Overflow-entry label | string | More |
| node-props | Node DOM attributes/events; internal selection, disabled and keyboard semantics remain | (context) => Record<string, unknown> | — |

Controlled props follow supplied values; update events are requests only. `default-*` initializes once, not on later changes. Selection and expansion are independent. `showOption` does not select.

### NavMenuOption

```ts
interface NavMenuOption {
  key?: string | number
  type?: 'item' | 'group' | 'divider'
  label?: VNodeChild | ((context: NavMenuRenderContext) => VNodeChild)
  icon?: VNodeChild | ((context: NavMenuRenderContext) => VNodeChild)
  extra?: VNodeChild | ((context: NavMenuRenderContext) => VNodeChild)
  children?: NavMenuOption[]
  disabled?: boolean
  show?: boolean
  props?: HTMLAttributes
}
```

Ordinary options require unique stable keys, using mapped keys when fieldNames is supplied. Numeric 0 is valid. Groups/dividers may omit keys, though explicit keys are recommended for dynamic reordering. Duplicate keys/missing ordinary-item keys throw to prevent ambiguous selection paths. show=false hides nodes/subtrees. Disabled branches propagate downward. Ordinary branches expand; leaves select.

### Events

| Event | Arguments |
| --- | --- |
| update:model-value | key / null |
| update:active-item | name / null |
| update:expanded-keys | keys |
| update:collapsed | collapsed |
| select | key, original option, original Event |

### Slots

The default slot contains independent `CNavMenuItem` entries. When present, horizontal menus scroll rather than using `responsive` overflow collection.

label/icon/extra render functions, same-name slots and nodeProps receive `{ option, active, expanded, level }`. `active` means this node itself matches modelValue; ancestor-path emphasis is internal. `expanded` describes branch expansion; level starts at 0.

### Cross-platform contract

Both libraries create panel content on first open and retain it when closed or switched, including local drafts and expanded branches. With `unmount-on-close`, content is destroyed after the closing transition and recreated on the next open; the Item's own selected value remains intact. Applications own draft submission, resets and filter application.

Root `close()` requests closing Item panels and restores entry focus without changing selected values, active-item or desktop tree expanded-keys. Controlled open values remain authoritative when closure is rejected. Entries with neither options nor a content slot never open; asynchronous options follow the current open state when they arrive. KeepAlive suspension hides panels and requests closure; controlled state remains authoritative on activation.

Item values, open state, events, slot contexts and `select/close/setOpen` methods share the same contract. Both roots expose `close/resize/setActiveItem`. Names must be unique within the menu; changing a name releases the previous one. Batched swaps and insertions validate the final rendered names. Vertical options expand enabled ancestors of the selected value on initialization and value/options updates. Users can still collapse branches manually.

| Capability | Cedar | Maple |
| --- | --- | --- |
| Root menu | options tree or Item entries; vertical by default | Item filter bar only; horizontal by default |
| popup-layout | dropdown (default) / full-width / full-height / full | full-width (default) / full |
| Panel origin | Individual entry bottom | Entire filter bar bottom; standalone Item uses its own bottom |
| Trigger and placement | trigger / placement | Click to open downward |
| Backdrop and scrolling | Non-modal; background scroll remains available | Root overlay / overlay-closable / lock-scroll / esc-to-close / z-index |
| Theme | theme override | Global theme; no theme prop |
| Tree-only methods | showOption / scrollTo / setCollapsed | — |

Each library exports `NavMenuPopupLayout` with its supported values. Maple's `NavMenuMode` is horizontal only; `options-mode` supports both orientations. The default entry slot replaces the entry's inner content. Maple renders it inside a native button: use non-interactive text/icons and place forms and action buttons in the content slot.

### Methods

| Method | Description |
| --- | --- |
| close() | Request closing Item panels and restore focus without changing tree expansion |
| showOption(key?) | Expand ancestors of the specified item, defaulting to current selection; does not select |
| scrollTo(key?) | Expand then scroll to an item; controlled expansion requires parent acceptance |
| resize() | Manually remeasure horizontal overflow |
| setCollapsed(value) | Update uncontrolled collapse or request a controlled update |
| setActiveItem(value) | Update uncontrolled named-Item activation or request a controlled update |

### Arrow direction

Horizontal dropdowns point down when closed/up when open. Vertical inline branches point right/down. Right-opening submenus point right/left. Independent Item arrows follow placement and reverse when open. Arrows follow actual open state, not unaccepted controlled proposals.

### Keyboard

Vertical Up/Down and horizontal Left/Right move focus; Home/End reach first/last. Right expands vertical branches, Down opens horizontal branches, Left returns to parents. Escape closes the current popup and restores reference focus. Enter/Space activates nodes. Disabled nodes are skipped; inputs retain native keys. If narrowing moves a focused item into overflow, focus moves to the overflow entry.

## NavMenu.Item API

Titles follow matching selected options by default. `label` slots take highest precedence: use `<template #label>Advanced filters</template>` for fixed titles or bind a separate reactive variable for manual titles. `update-label` is removed.

`v-model` stores panel selection. Slot `active` indicates business entry state: named entries in a root menu compare root activeItem with name; independent entries match their main value against ordinary options, including 0/empty string. Unknown values/groups/dividers do not activate independent entries. `highlight` overrides emphasis only: true forces it, false removes it, omission follows `active`. It changes neither `active` nor value. Opening a panel does not activate the entry.

`CNavMenuItem` (also `NavMenu.Item`) is an independent top-level entry outside root navigation-tree `modelValue`. Without `name`, each Item highlights from its own value, allowing simultaneous category/region filters. With unique names, root `activeItem/defaultActiveItem` maintains one highlighted entry. Both modes allow only one open Item panel without clearing other panels’ values. Ordinary root navigation uses `options + v-model`. Entries define their own `options` or replace panels through `content`. default customizes the entry; `label`/`icon` customize parts; `option-label`/`option-icon`/`option-extra` customize `options`.

Horizontal menus with default slots scroll rather than collecting entries into overflow, avoiding cloned form content. Pure `options` menus retain automatic overflow collection. New Item does not support legacy child collection. Item panels within one NavMenu are mutually exclusive. Clicking another entry requests closing the previous one; controlled open requires parent acceptance.

| Item prop | Description | Default |
| --- | --- | --- |
| name | Stable unique entry identifier; root activeItem makes named entries mutually exclusive. highlight separately overrides appearance | — |
| label | Entry title when unselected or selection does not match options; supports VNode/render functions | — |
| options / fieldNames | Same options/field mappings as NavMenu | `[]` |
| model-value / default-value | Independent controlled/initial value; string, number or null | `undefined` / `null` |
| highlight | Visual emphasis override without changing active/selection; defaults to active | — |
| hide-on-select | Close the panel after select | `true` |
| unmount-on-close | Destroy panel content after the closing transition; retain it by default | false |
| open / default-open | Controlled / initial panel state | `undefined` / `false` |
| disabled | Disable the entry, also respecting parent menu disabled | `undefined` |
| trigger | Trigger mode | `click` |
| placement | Ordinary dropdown placement; full-height right/left placements align to the corresponding entry edge | `bottom-start` |
| popup-layout | `dropdown`: standard `dropdown` / `full-width`: `full` width below the trigger / `full-height`: `full` height on the right / `full`: fills the available width and height below the trigger | `dropdown` |
| popup-style | Panel CSS; may override full-height width/direction/dimensions | — |
| popup-container / popup-class | Trigger container and popup class | Follow parent menu |
| options-mode | Horizontal/vertical default options-panel layout | `vertical` |

Entry/`content` slots receive `{ modelValue, selectedOption, active, open, select, close }`. select(key,event?) emits `update:modelValue` and select(key,option,event). Custom panels may select outside options, making option undefined and independent active false; use highlight if emphasis is needed. `close()` closes/restores entry focus. Controlled values affect titles/active only after acceptance. Entry-slot active is entry state, while label-render active compares its context option with the Item value. `hideOnSelect` is independent of acceptance; set false for manual confirmation.

Item also emits `update:open`/entry `click` and exposes `select`/`close`/`setOpen`. Full-width/full-height popups are nonmodal without scroll locks/focus traps. They default to body; custom containers must avoid ancestor transforms changing the fixed-position reference.

## Migrating from older versions

Legacy child collection and state aliases are removed. New `NavMenu.Item` is an independent top-level entry with different usage.

| Previous usage | Current usage |
| --- | --- |
| Legacy Item/SubMenu/ItemGroup components | Use options/children/type=group for navigation trees; new NavMenu.Item for custom top-level entries |
| selectedKeys/defaultSelectedKeys arrays | modelValue/defaultValue single key |
| openKeys/defaultOpenKeys | expandedKeys/defaultExpandedKeys |
| menu-item-click | select(key, option, event) |
| pop/popButton mode | vertical + collapsed; horizontal remains horizontal |
| Child title/icon slots | Root scoped label/icon/extra slots or option VNodes |
| Built-in collapse button/breakpoint | External buttons control collapsed; containers handle responsive layout |
| Unrestricted triggerProps/tooltipProps forwarding | Explicit popupContainer/popupClass props |

All library demos, exports, global types and resolver entries are migrated. Styles use BEM `c-nav-menu__*` / `c-nav-menu--*`; old selectors and unused tokens are removed.

## Design reference

The workspace Naive UI 2.44.1 Menu informed option trees, ancestor paths and content rendering. No Naive UI/TreeMate runtime dependency is introduced. Local Trigger provides popups; public APIs follow Cedar names.

## Style variables

| Variable | Default |
| --- | --- |
| --c-nav-menu-font-size | `var(~'--c-font-size-body-3')` |
| --c-nav-menu-border-radius | `var(~'--c-border-radius-sm')` |
| --c-nav-menu-light-bg | `var(~'--c-color-bg-2')` |
| --c-nav-menu-light-item-bg-hover | `var(~'--c-color-fill-2')` |
| --c-nav-menu-light-item-bg-selected | `var(~'--c-color-fill-2')` |
| --c-nav-menu-light-item-text-color | `var(~'--c-color-text-2')` |
| --c-nav-menu-light-item-text-color-selected | `rgb(var(~'--c-primary-6'))` |
| --c-nav-menu-light-item-text-color-disabled | `var(~'--c-color-text-4')` |
| --c-nav-menu-dark-bg | `var(~'--c-color-menu-dark-bg')` |
| --c-nav-menu-dark-item-bg-hover | `var(~'--c-color-menu-dark-hover')` |
| --c-nav-menu-dark-item-bg-selected | `var(~'--c-color-menu-dark-hover')` |
| --c-nav-menu-dark-item-text-color | `var(~'--c-color-text-4')` |
| --c-nav-menu-dark-item-text-color-selected | `var(~'--c-color-white')` |
| --c-nav-menu-dark-item-text-color-disabled | `var(~'--c-color-text-2')` |
| --c-nav-menu-row-height | `40px` |
| --c-nav-menu-row-height-xs | `28px` |
| --c-nav-menu-row-height-sm | `32px` |
| --c-nav-menu-row-height-lg | `48px` |
| --c-nav-menu-row-height-xl | `56px` |
| --c-nav-menu-content-gap | `8px` |
| --c-nav-menu-content-padding | `12px` |
| --c-nav-menu-icon-size | `20px` |
| --c-nav-menu-arrow-size | `12px` |
| --c-nav-menu-focus-width | `2px` |
| --c-nav-menu-focus-offset | `-2px` |
| --c-nav-menu-divider-width | `1px` |
| --c-nav-menu-divider-color | `var(--c-color-border-2)` |
| --c-nav-menu-popup-min-width | `180px` |
| --c-nav-menu-popup-max-height | `320px` |
| --c-nav-menu-popup-shadow | `0 6px 24px rgb(0 0 0 / 12%)` |
| --c-nav-menu-motion-duration | `150ms` |
| --c-nav-menu-panel-width | `min(400px, 100vw)` |

`popup-layout="full"` starts at the bottom edge of the trigger, spans the viewport width and fills the remaining viewport height below it. On Maple, the same layout starts below the entire filter bar. Mobile defaults to full-width; desktop defaults to dropdown.


## Reading direction and keyboard interaction

NavMenu inherits the nearest native `dir` and reacts to changes. Horizontal navigation follows reading direction; vertical up/down navigation stays unchanged. Data-menu branches mirror expand/parent keys and prefer the inline-end side for nested popups. Popups retain the source direction. Explicit Item placement remains physical; changing direction does not select an item or clear filters.

---

Document: llms/en-US/components/notification.md

<!-- Source: src/notification/README.en-US.md; locale: en-US; page: /en/components/notification/ -->

# Notification

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

Example source: src/notification/__demos__/basic.vue

```vue
<template>
  <c-space>
    <c-button @click="handleNotification"> Open Notification </c-button>
  </c-space>
</template>
<script lang="ts" setup>
import { Notification } from '@cedar-design/ui'

const handleNotification = () => {
  Notification.info({
    title: 'Notification',
    content: 'This is a notification!',
  })
}
</script>
```

## Reading direction

Inherits the nearest `dir="ltr|rtl"` and supports runtime and nested overrides. Explicit left/right notification corners remain physical. Icons, content, close actions and footers follow reading direction. Imperative calls use explicit or document direction rather than borrowing another app context.

## API

clear immediately releases entries and IDs. Re-adding the same ID, even in the same update cycle, creates an independent internal instance and a fresh complete display timer. Ordinary active-ID updates remain in place. Internal keys are not public API. clear still does not add business onClose calls. Reduced-motion component styles disable opacity, left/right enter, appear and leave transitions and initial displacement without a global tiny-duration fallback. Static layout/colors and business display deadlines remain unchanged. Real OS/browser matrices require separate validation.

duration (default 3000ms; 0 stays open) is a business display timer, not CSS animation duration. close notifies once per mounted instance and immediately cancels timers. Updates/repeated closing during leave do not reschedule auto-close. reset-on-update restarts only active, unclosed instances. KeepAlive deactivation cancels timing; reactivation restarts the full configured duration. Unmounting/stale callbacks emit no delayed close. TransitionGroup unmounts after actual leave completion, independently of duration. Six transition-* tokens control opacity/left/right enter/leave without changing auto-close deadlines. Normal override checks are not real OS reduced-motion validation.

### `Notification` global methods

`Notification` global methods can be used in three ways:

1. Call `this.$notification`
2. In Composition API, call `getCurrentInstance().appContext.config.globalProperties.$notification`
3. Import `Notification` and call its methods directly

Import-based calls cannot obtain the current Vue Context. AppContext injections such as i18n or route
must be supplied manually in the call, or by configuring a global AppContext for the component.

```ts
import { createApp } from 'vue'
import { Notification } from '@cedar-design/ui'

const app = createApp(App)
Notification._context = app._context
```

### NotificationMethod

| Parameter | Description | Type | Default |
| ------- | ---------------------- | ------------------------------------------------------------------------------------------------ | :----: |
| info | Show an information notification | `(    config: string \| NotificationConfig,    appContext?: AppContext  ) => NotificationReturn` | `-` |
| success | Show a success notification | `(    config: string \| NotificationConfig,    appContext?: AppContext  ) => NotificationReturn` | `-` |
| warning | Show a warning notification | `(    config: string \| NotificationConfig,    appContext?: AppContext  ) => NotificationReturn` | `-` |
| error | Show an error notification | `(    config: string \| NotificationConfig,    appContext?: AppContext  ) => NotificationReturn` | `-` |
| remove | Clear the notification with the specified `id` | `(id: string) => void` | `-` |
| clear | Clear all notifications | `(position?: NotificationPosition) => void` | `-` |

### NotificationConfig

| Parameter | Description | Type | Default | Version |
| ---------------- | --------------------------- | ---------------------------------------------------- | :-----: | :----- |
| content | Content | `RenderContent` | `-` |  |
| title | Title | `RenderContent` | `-` |  |
| icon | Icon | `RenderFunction` | `-` |  |
| id | Unique id | `string` | `-` |  |
| style | Style | `CSSProperties` | `-` |  |
| class | Class name | `ClassName` | `-` |  |
| position | Physical corner of the notification itself in the viewport, default top-right. Corner values use vertical-first kebab-case spelling | `'top-left'\|'top-right'\|'bottom-left'\|'bottom-right'` | `top-right` |  |
| showIcon | Whether to show the icon | `boolean` | `true` |  |
| closable | Whether closable | `boolean` | `false` |  |
| duration | Display duration in `ms` | `number` | `3000` |  |
| footer | Footer content | `RenderFunction` | `-` | 2.25.0 |
| closeIcon | Close-button icon | `RenderFunction` | `-` |  |
| closeIconElement | Close-button element | `RenderFunction` | `-` |  |
| onClose | Close callback | `(id: number \| string) => void` | `-` |  |

### NotificationReturn

| Parameter | Description | Type | Default |
| ------ | ------------------ | ------------ | :----: |
| close | Close the current notification | `() => void` | `-` |

### Type definitions

The component exports the following types

```ts
import type { NotificationInstance, NotificationConfig, NotificationReturn } from '@cedar-design/ui'
```

## Public CSS variables

Panels use surface-overlay; body/title use content-primary; close buttons use content-secondary; borders use border-default. Status icons use readable status content colors: info no longer uses brand fills, and loading uses content-brand. Colors are grouped by status. Custom backgrounds require checking content/icon/close contrast. Plain-text actions/footers inherit panel content color; applications own independently styled slots.

wrapper-* controls list position/spacing; padding-*/margin-* control panel layout; icon-*/title-*/content-* control typography; close-* controls close buttons; border-*/box-shadow control borders/shadows; transition-* controls motion; z-index controls stacking. Existing geometry/motion defaults remain. The table lists actual declarations, not a claim that every historical geometry variable has verified consumers.

| Variable | Default |
| --- | --- |
| `--c-notification-wrapper-margin-top` | `var(--c-spacing-8)` |
| `--c-notification-wrapper-margin-bottom` | `var(--c-spacing-8)` |
| `--c-notification-wrapper-margin-left` | `var(--c-spacing-8)` |
| `--c-notification-wrapper-margin-right` | `var(--c-spacing-8)` |
| `--c-notification-z-index` | `var(--c-z-index-notification)` |
| `--c-notification-border-radius` | `var(--c-border-radius-md)` |
| `--c-notification-margin-bottom` | `var(--c-spacing-8)` |
| `--c-notification-width` | `300px` |
| `--c-notification-padding-top` | `var(--c-spacing-8)` |
| `--c-notification-padding-bottom` | `var(--c-spacing-8)` |
| `--c-notification-padding-left` | `var(--c-spacing-8)` |
| `--c-notification-padding-right` | `var(--c-spacing-8)` |
| `--c-notification-icon-font-size` | `24px` |
| `--c-notification-title-font-size` | `var(--c-font-size-title-1)` |
| `--c-notification-title-font-weight` | `var(--c-font-weight-500)` |
| `--c-notification-content-font-size` | `var(--c-font-size-body-3)` |
| `--c-notification-icon-margin-right` | `var(--c-spacing-7)` |
| `--c-notification-title-margin-bottom` | `var(--c-spacing-2)` |
| `--c-notification-footer-margin-top` | `var(--c-spacing-7)` |
| `--c-notification-box-shadow` | `0 4px 12px rgba(0, 0, 0, 0.15)` |
| `--c-notification-border-width` | `1px` |
| `--c-notification-border-style` | `solid` |
| `--c-notification-close-icon-color` | `var(--c-sys-color-content-secondary)` |
| `--c-notification-close-icon-font-size` | `12px` |
| `--c-notification-close-icon-top` | `var(--c-spacing-6)` |
| `--c-notification-close-icon-right` | `var(--c-spacing-6)` |
| `--c-notification-close-icon-hover-size` | `20px` |
| `--c-notification-normal-bg` | `var(--c-sys-color-surface-overlay)` |
| `--c-notification-normal-icon-color` | `var(--c-sys-color-content-primary)` |
| `--c-notification-normal-title-color` | `var(--c-sys-color-content-primary)` |
| `--c-notification-normal-content-color` | `var(--c-sys-color-content-primary)` |
| `--c-notification-normal-border-color` | `var(--c-sys-color-border-default)` |
| `--c-notification-info-bg` | `var(--c-sys-color-surface-overlay)` |
| `--c-notification-info-icon-color` | `var(--c-sys-color-content-info)` |
| `--c-notification-info-title-color` | `var(--c-sys-color-content-primary)` |
| `--c-notification-info-content-color` | `var(--c-sys-color-content-primary)` |
| `--c-notification-info-border-color` | `var(--c-sys-color-border-default)` |
| `--c-notification-success-bg` | `var(--c-sys-color-surface-overlay)` |
| `--c-notification-success-icon-color` | `var(--c-sys-color-content-success)` |
| `--c-notification-success-title-color` | `var(--c-sys-color-content-primary)` |
| `--c-notification-success-content-color` | `var(--c-sys-color-content-primary)` |
| `--c-notification-success-border-color` | `var(--c-sys-color-border-default)` |
| `--c-notification-warning-bg` | `var(--c-sys-color-surface-overlay)` |
| `--c-notification-warning-icon-color` | `var(--c-sys-color-content-warning)` |
| `--c-notification-warning-title-color` | `var(--c-sys-color-content-primary)` |
| `--c-notification-warning-content-color` | `var(--c-sys-color-content-primary)` |
| `--c-notification-warning-border-color` | `var(--c-sys-color-border-default)` |
| `--c-notification-error-bg` | `var(--c-sys-color-surface-overlay)` |
| `--c-notification-error-icon-color` | `var(--c-sys-color-content-danger)` |
| `--c-notification-error-title-color` | `var(--c-sys-color-content-primary)` |
| `--c-notification-error-content-color` | `var(--c-sys-color-content-primary)` |
| `--c-notification-error-border-color` | `var(--c-sys-color-border-default)` |
| `--c-notification-transition-duration` | `var(--c-transition-duration-2)` |
| `--c-notification-transition-duration-enter` | `var(--c-transition-duration-4)` |
| `--c-notification-transition-duration-leave` | `var(--c-transition-duration-3)` |
| `--c-notification-transition-timing-function` | `var(--c-transition-timing-function-linear)` |
| `--c-notification-transition-timing-function-enter` | `var(--c-transition-timing-function-overshoot)` |
| `--c-notification-transition-timing-function-leave` | `var(--c-transition-timing-function-standard)` |

After Teleport, theme variables follow actual DOM ancestors. Variables inside content do not propagate upward to service-created containers.

A throwing close/closed notification cannot retain the closed item or its empty manager host. Resources are released independently of notification callbacks.

---

Document: llms/en-US/components/overflow-list.md

<!-- Source: src/overflow-list/README.en-US.md; locale: en-US; page: /en/components/overflow-list/ -->

# Overflow List

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

Preview configuration: `auto-label-width`, `:min="0"`, `:max="20"`, `:max="800"`.

Example source: src/overflow-list/__demos__/basic.vue

```vue
<template>
  <c-form auto-label-width>
    <c-form-item label="Tag Number">
      <c-input-number v-model="number" :min="0" :max="20" style="width: 200px" />
    </c-form-item>
    <c-form-item label="List Width">
      <c-slider v-model="width" :min="0" :max="800" />
    </c-form-item>
  </c-form>
  <div :style="{ width: `${width}px`, marginTop: '20px' }">
    <c-overflow-list>
      <div>DIV Element</div>
      <c-tag v-for="item of tags" :key="item">Tag{{ item }}</c-tag>
    </c-overflow-list>
  </div>
</template>

<script lang="ts" setup>
import { computed, ref } from 'vue'

const width = ref(500)
const number = ref(10)
const tags = computed(() => Array.from({ length: number.value }, (_, idx) => idx + 1))
</script>
```

## Layout and arrangement

### From

- `from`: Overflow From

Example source: src/overflow-list/__demos__/from.vue

```vue
<template>
  <c-form auto-label-width>
    <c-form-item label="Tag Number">
      <c-input-number v-model="number" :min="0" :max="20" style="width: 200px" />
    </c-form-item>
    <c-form-item label="List Width">
      <c-slider v-model="width" :min="0" :max="800" />
    </c-form-item>
  </c-form>
  <div :style="{ width: `${width}px`, marginTop: '20px' }">
    <c-overflow-list from="start">
      <div>DIV Element</div>
      <c-tag v-for="item of tags" :key="item">Tag{{ item }}</c-tag>
    </c-overflow-list>
  </div>
</template>

<script lang="ts" setup>
import { computed, ref } from 'vue'

const width = ref(500)
const number = ref(10)
const tags = computed(() => Array.from({ length: number.value }, (_, idx) => idx + 1))
</script>
```

## API

### `<overflow-list>` Props

| Parameter | Description | Type | Default |
| ------ | ------------------ | ------------------ | :-----: |
| min | Minimum number of elements to display | `number` | `0` |
| margin | Item Margin | `number` | `8` |
| from | Overflow From | `'start' \| 'end'` | `'end'` |

### `<overflow-list>` Events

| Event | Description | Arguments |
| ------ | ------------------ | --------------- |
| change | Emitted when the overflow count changes | value: `number` |

### `<overflow-list>` Slots

| Slot | Description | Arguments |
| -------- | :------: | ---------------- |
| overflow | Collapsed elements | number: `number` |

### Type definitions

The component exports the following types

```ts
import type { BadgeInstance } from '@cedar-design/ui'
```

---

Document: llms/en-US/components/overlay.md

<!-- Source: src/overlay/README.en-US.md; locale: en-US; page: /en/components/overlay/ -->

# Overlay

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

Preview configuration: `v-model:open="open"`.

Example source: src/overlay/__demos__/basic.vue

```vue
<template>
  <c-button status="primary" @click="open = true">打开背景层</c-button>
  <c-overlay v-model:open="open">
    <div class="overlay-demo-content">背景层内容</div>
  </c-overlay>
</template>

<script setup lang="ts">
import { ref } from "vue";

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

<style scoped>
.overlay-demo-content {
  padding: 24px;
  background: var(--c-color-bg-2);
  border-radius: var(--c-border-radius-md);
}
</style>
```

## API

### Props

| Arguments | Description | Type | Default |
| ------------------ | -------------------------------------------- | -------------------------------- | -------- |
| `v-model:open` | Visible state | `boolean` | `false` |
| `default-open` | Whether to display by default in uncontrolled mode | `boolean` | `false` |
| `overlay-closable` | Whether clicking the backdrop closes the Overlay | `boolean` | `true` |
| `lock-scroll` | Lock scrolling on the host | `boolean` | `true` |
| `unmount-on-close` | Whether to unmount slot content after closing | `boolean` | `true` |
| `esc-to-close` | Whether Escape closes the overlay | `boolean` | `true` |
| `popup-container` | Teleport target; `false` renders in place | `string \| HTMLElement \| false` | `'body'` |
| `z-index` | Custom z-index | `number` | `-` |

### Events

| Event | Description | Arguments |
| ------------- | ------------ | --------------- |
| `update:open` | Open state changed | `boolean` |
| `open` | Opening starts | `-` |
| `opened` | Opening transition completes | `-` |
| `close` | Closing starts | `-` |
| `closed` | Closing transition completes | `-` |
| `click` | Click on the background area | `MouseEvent` |
| `key-escape` | Escape was pressed | `KeyboardEvent` |

### Slots

| Slot | Description |
| --------- | ---------------- |
| `default` | Content above the background layer |

## Public CSS variables

These are actual :root defaults. Prefer component variables for business customization; internal positioning variables are not public API.

| Variable | Default | Meaning and use case |
| --- | --- | --- |
| `--c-overlay-background-color` | `var(--c-sys-color-scrim)` | Scrim background only; does not change foreground-content opacity |
| `--c-overlay-animation-duration` | `var(--c-sys-motion-duration-slow)` | Enter/leave duration; reduced motion may override it |
| `--c-overlay-content-z-index` | `var(--c-sys-layer-raised)` | Local stacking level of content above the scrim |

### Reduced motion

Built-in CSS transitions follow `prefers-reduced-motion: reduce`. Removing transitions does not change final visibility, selected/expanded state or event semantics. Applications control custom animations inside slots.

---

Document: llms/en-US/components/page-header.md

<!-- Source: src/page-header/README.en-US.md; locale: en-US; page: /en/components/page-header/ -->

# Page Header

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

- `show-back`: Whether to show the back button
- `title`: Main title
- `subtitle`: Subtitle

Example source: src/page-header/__demos__/basic.vue

```vue
<template>
  <c-card variant="outline" size="md">
    <c-page-header
      show-back
      title="设计系统"
      subtitle="项目概览"
      @back="onBack"
    >
      <template #extra>
        <c-space size="sm" wrap>
          <c-button @click="onFollow">关注</c-button>
          <c-button status="primary" @click="onCreate">创建任务</c-button>
        </c-space>
      </template>
    </c-page-header>
  </c-card>
</template>

<script setup lang="ts">
import { Message } from "@cedar-design/ui";

const onBack = () => Message.info("点击返回");
const onFollow = () => Message.success("已关注项目");
const onCreate = () => Message.info("点击创建任务");
</script>
```

## Content and presentation

### Breadcrumbs and transparent surfaces

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `title` | Main title | Breadcrumbs and transparent surfaces, Content |
| `subtitle` | Subtitle | Breadcrumbs and transparent surfaces, Content |
| `show-back` | Whether to show back | Content |
<!-- demo-config-notes:end -->


Compare breadcrumb navigation and title hierarchy on transparent surfaces.

Example source: src/page-header/__demos__/surface-comparison.vue

```vue
<script setup lang="ts">
import { Message } from "@cedar-design/ui"
import { proxyRefs as demoProxyRefs } from 'vue'

const scene2 = demoProxyRefs((() => {


const onFollow = () => Message.success("已关注项目");
return { onFollow }
})())
</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="breadcrumb">
    <h4><span lang="zh-CN">页头上方内容</span><span lang="en-US">breadcrumb</span></h4>
    <c-card variant="outline" size="md">
        <c-page-header title="设计系统" subtitle="项目概览">
          <template #header>
            <c-breadcrumb>
              <c-breadcrumb-item>工作台</c-breadcrumb-item>
              <c-breadcrumb-item>项目</c-breadcrumb-item>
              <c-breadcrumb-item>设计系统</c-breadcrumb-item>
            </c-breadcrumb>
          </template>
        </c-page-header>
      </c-card>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="transparent">
    <h4><span lang="zh-CN">透明底色</span><span lang="en-US">transparent</span></h4>
    <c-card variant="tonal" size="md">
        <c-page-header title="设计系统" subtitle="项目概览">
          <template #extra><c-button @click="scene2.onFollow">关注</c-button></template>
          <span>页头默认透明，可以融入页面背景。</span>
        </c-page-header>
      </c-card>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

### Content

- `show-back`: Whether to show the back button
- `title`: Main title
- `subtitle`: Subtitle

Example source: src/page-header/__demos__/content.vue

```vue
<template>
  <c-card variant="outline" size="md">
    <c-page-header
      show-back
      title="设计系统"
      subtitle="项目概览"
      @back="onBack"
    >
      <template #header>
        <c-breadcrumb>
          <c-breadcrumb-item>工作台</c-breadcrumb-item>
          <c-breadcrumb-item>项目</c-breadcrumb-item>
        </c-breadcrumb>
      </template>
      <template #avatar
        ><c-avatar shape="square" :size="40">D</c-avatar></template
      >
      <template #extra>
        <c-space size="sm" wrap>
          <c-button @click="onFollow">关注</c-button>
          <c-button status="primary" @click="onCreate">创建任务</c-button>
        </c-space>
      </template>
      <c-row :gutter="[24, 24]" align="center" justify="space-between">
        <c-col :xs="24" :lg="14">
          <c-space direction="column" size="lg">
            <span>统一设计规范与组件资源，帮助团队高效协作。</span>
            <c-descriptions :column="2" size="sm">
              <c-descriptions-item label="负责人">林晓</c-descriptions-item>
              <c-descriptions-item label="所属团队"
                >设计平台</c-descriptions-item
              >
            </c-descriptions>
          </c-space>
        </c-col>
        <c-col :xs="24" :lg="8">
          <c-grid :cols="3" :col-gap="24">
            <c-grid-item
              ><c-statistic title="组件" :value="48" tabular-nums
            /></c-grid-item>
            <c-grid-item
              ><c-statistic title="进行中" :value="12" tabular-nums
            /></c-grid-item>
            <c-grid-item
              ><c-statistic title="成员" :value="8" tabular-nums
            /></c-grid-item>
          </c-grid>
        </c-col>
      </c-row>
      <template #footer>
        <c-divider :spacing="[0, 16]" />
        <c-space justify="space-between" size="sm" wrap>
          <small>项目编号 DS-001</small>
          <small>最近更新：今天</small>
        </c-space>
      </template>
    </c-page-header>
  </c-card>
</template>

<script setup lang="ts">
import { Message } from "@cedar-design/ui";

const onBack = () => Message.info("点击返回");
const onFollow = () => Message.success("已关注项目");
const onCreate = () => Message.info("点击创建任务");
</script>
```

## Reading direction

Inherits the nearest `dir="ltr|rtl"` and supports runtime and nested overrides. The back action sits at reading start and its default icon points right in RTL. Titles and extras follow reading order. Custom back slots are not automatically mirrored.

## API

### PageHeader Props

| Prop | Description | Type | Default |
| -------- | ---------------- | --------- | ------- |
| show-back | Whether to show back | `boolean` | `false` |
| title | Main title | `string` | `-` |
| subtitle | Subtitle | `string` | `-` |
| extra | Extra content on the right | `string` | `-` |

### PageHeader Events

| Event | Description | Arguments |
| ------ | ------------------ | -------------- |
| back | Emitted when the back button is clicked | event: `Event` |

### PageHeader Slots

| Slot | Description | Arguments |
| -------- | -------------- | ---- |
| header | Content above the page header | - |
| back | Custom back icon | - |
| avatar | Avatar | - |
| title | Main title | - |
| subtitle | Subtitle | - |
| extra | Additional right-side content | - |
| default | Main page-header content | - |
| footer | Footer content | - |

## Type definitions

```ts
import type { PageHeaderProps } from '@cedar-design/ui'
```

## Shared implementation and platform boundaries

Each platform maintains a complete local implementation. They do not import a common core or share component instances or reactive state. Changes must update both implementations. Component bodies, props, key styles and paired tests have read-only source consistency checks; theme tokens and installation entries remain local to each library.

The back control is a native button with keyboard activation and back(MouseEvent). Cedar classes change from c-page-header-xxx to c-page-header__xxx. Icons remain locally supplied.

### Back-interaction variables

`--c-page-header-back-hover-size` (30px) sets the feedback-circle size without moving title layout. `--c-page-header-back-hover-bg` (`var(--c-sys-color-state-hover)`) sets its background. Hover applies only to hover-capable fine pointers; all input modes retain keyboard focus-visible feedback.

---

Document: llms/en-US/components/pagination.md

<!-- Source: src/pagination/README.en-US.md; locale: en-US; page: /en/components/pagination/ -->

# Pagination

Pagination with a shared API and container-responsive layout.

## Basic examples

### Basic and two-way binding

Example source: src/pagination/__demos__/basic.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const current = ref(1)
</script>
<template>
  <div class="pagination-demo">
    <c-pagination v-model="current" :total="50" />
    <span>Current: {{ current }}</span>
  </div>
</template>
<style scoped>
.pagination-demo { display: grid; gap: 16px; min-width: 0; }
.pagination-demo-controls { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; }
</style>
```

## Appearance and states

### Five sizes and elevation

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `total` | Total item count; required | Five sizes and elevation, Disabled and hide on single page |
| `show-page-size` | Show page size selector | Five sizes and elevation, Disabled and hide on single page |
| `show-jumper` | Show separate jumper in full mode; simple mode includes input | Five sizes and elevation, Disabled and hide on single page |
| `size` | Size of all controls | Five sizes and elevation |
| `elevation` | Page button shadow; true uses level 2 | Five sizes and elevation |
| `disabled` | Disable all interactions | Disabled and hide on single page |
<!-- demo-config-notes:end -->


Example source: src/pagination/__demos__/size.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const size = ref<'xs' | 'sm' | 'md' | 'lg' | 'xl'>('md')
const elevation = ref(false)
</script>
<template>
  <div class="pagination-demo">
    <c-radio-group v-model="size"><c-radio v-for="value in ['xs', 'sm', 'md', 'lg', 'xl']" :key="value" :value="value">{{ value }}</c-radio></c-radio-group>
    <div class="pagination-demo-controls"><c-switch v-model="elevation" /> Elevation</div>
    <c-pagination :size="size" :elevation="elevation" :total="50" show-page-size show-jumper />
  </div>
</template>
<style scoped>
.pagination-demo { display: grid; gap: 16px; min-width: 0; }
.pagination-demo-controls { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; }
</style>
```

### Disabled and hide on single page

Example source: src/pagination/__demos__/disabled.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const disabled = ref(true)
const single = ref(false)
</script>
<template>
  <div class="pagination-demo">
    <div class="pagination-demo-controls"><c-switch v-model="disabled" /> Disabled<c-switch v-model="single" /> Single page</div>
    <c-pagination :total="single ? 5 : 200" :disabled="disabled" hide-on-single-page show-jumper show-page-size show-total />
  </div>
</template>
<style scoped>
.pagination-demo { display: grid; gap: 16px; min-width: 0; }
.pagination-demo-controls { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; }
</style>
```

## Pagination modes and information

### Simple mode

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `total` | Total item count; required | Simple mode, Page window and ellipsis, Totals, page sizes and jumpers |
| `show-total` | Show total | Simple mode, Totals, page sizes and jumpers |
| `show-page-size` | Show page size selector | Simple mode, Totals, page sizes and jumpers |
| `responsive` | Automatically use simple mode by container width | Page window and ellipsis, Totals, page sizes and jumpers |
| `simple` | Explicit simple mode | Simple mode |
| `default-value` | Initial uncontrolled page | Page window and ellipsis |
<!-- demo-config-notes:end -->


Example source: src/pagination/__demos__/simple.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const current = ref(3)
</script>
<template>
  <div class="pagination-demo">
    <c-pagination v-model="current" :total="200" simple show-total show-page-size />
  </div>
</template>
<style scoped>
.pagination-demo { display: grid; gap: 16px; min-width: 0; }
.pagination-demo-controls { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; }
</style>
```

### Page window and ellipsis

Example source: src/pagination/__demos__/more-page-size.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const buffer = ref(2)
const more = ref(false)
</script>
<template>
  <div class="pagination-demo">
    <div class="pagination-demo-controls"><c-radio-group v-model="buffer"><c-radio v-for="value in [0, 1, 2]" :key="value" :value="value">Buffer {{ value }}</c-radio></c-radio-group><c-switch v-model="more" /> Show more</div>
    <c-pagination :total="500" :default-value="12" :buffer-size="buffer" :show-more="more" :responsive="false" />
  </div>
</template>
<style scoped>
.pagination-demo { display: grid; gap: 16px; min-width: 0; }
.pagination-demo-controls { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; }
</style>
```

### Totals, page sizes and jumpers

Compare total labels, page-size selection and page jumpers. Change the available controls and observe their output.

Example source: src/pagination/__demos__/auxiliary-controls-comparison.vue

```vue
<script setup lang="ts">
import { ref } from "vue"
import { proxyRefs as demoProxyRefs } from 'vue'

const scene2 = demoProxyRefs((() => {

const pageSize = ref(10)

const current = ref(5)
return { pageSize, current }
})())
</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="show-total">
    <h4><span lang="zh-CN">自定义总数插槽</span><span lang="en-US">Custom total slot</span></h4>
    <div class="pagination-demo">
        <c-pagination :total="200" show-total><template #total="{ total }">{{ total }} records</template></c-pagination>
      </div>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="show-page-size">
    <h4><span lang="zh-CN">每页条数与公共选择器配置</span><span lang="en-US">Page size and shared selector options</span></h4>
    <div class="pagination-demo">
        <c-pagination v-model="scene2.current" v-model:page-size="scene2.pageSize" :total="200" show-page-size :page-size-options="[10, 20, 50, 100]" :page-size-props="{
      placement: 'bottom-start'
    }" />
        <span>Current: {{ scene2.current }} · Page size: {{ scene2.pageSize }}</span>
      </div>
  </section>

  <section class="demo-comparison-case demo-comparison-case--3" data-comparison-scene="show-jumper">
    <h4><span lang="zh-CN">跳转与前后缀插槽</span><span lang="en-US">Jumper and prefix/suffix slots</span></h4>
    <div class="pagination-demo">
        <c-pagination :total="200" show-jumper :responsive="false">
          <template #jumper-prepend>Go to</template><template #jumper-append>page</template>
        </c-pagination>
      </div>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }
.demo-comparison-case--1 {

.pagination-demo { display: grid; gap: 16px; min-width: 0; }
.pagination-demo-controls { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; }

}
.demo-comparison-case--2 {

.pagination-demo { display: grid; gap: 16px; min-width: 0; }
.pagination-demo-controls { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; }

}
.demo-comparison-case--3 {

.pagination-demo { display: grid; gap: 16px; min-width: 0; }
.pagination-demo-controls { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; }

}
</style>
```

## Page size, navigation and buttons

### Custom page slots and styles

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `total` | Total item count; required | Custom page slots and styles |
| `default-value` | Initial uncontrolled page | Custom page slots and styles |
| `buffer-size` | Pages on either side of current page | Custom page slots and styles |
| `responsive` | Automatically use simple mode by container width | Custom page slots and styles |
| `page-item-style` | Base numeric page style | Custom page slots and styles |
| `active-page-item-style` | Additional active numeric page style | Custom page slots and styles |
<!-- demo-config-notes:end -->


Example source: src/pagination/__demos__/custom-page-button.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'

</script>
<template>
  <div class="pagination-demo">
    <c-pagination :total="300" :default-value="10" :buffer-size="0" :responsive="false" :page-item-style="{ borderRadius: '8px' }" :active-page-item-style="{ fontWeight: '700' }">
      <template #page-item="{ page }">{{ page }}</template>
      <template #page-item-step="{ type }">{{ type === 'previous' ? 'Prev' : 'Next' }}</template>
      <template #page-item-ellipsis>✦</template>
    </c-pagination>
  </div>
</template>
<style scoped>
.pagination-demo { display: grid; gap: 16px; min-width: 0; }
.pagination-demo-controls { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; }
</style>
```

## Responsive layout and data changes

### Container width and compact layout

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `total` | Total item count; required | Container width and compact layout, Data changes and auto adjustment, Full feature controls |
| `show-total` | Show total | Container width and compact layout, Data changes and auto adjustment, Full feature controls |
| `show-page-size` | Show page size selector | Container width and compact layout, Data changes and auto adjustment, Full feature controls |
| `show-jumper` | Show separate jumper in full mode; simple mode includes input | Container width and compact layout, Full feature controls |
| `responsive` | Automatically use simple mode by container width | Container width and compact layout |
| `auto-adjust` | Preserve first record on size change; clamp after total shrinks | Data changes and auto adjustment |
<!-- demo-config-notes:end -->


Example source: src/pagination/__demos__/responsive.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const width = ref(360)
const responsive = ref(true)
</script>
<template>
  <div class="pagination-demo">
    <c-radio-group v-model="width" wrap><c-radio v-for="value in [280, 360, 480, 640]" :key="value" :value="value">{{ value }}px</c-radio></c-radio-group>
    <div class="pagination-demo-controls"><c-switch v-model="responsive" /> Responsive</div>
    <div :style="{ width: width + 'px', maxWidth: '100%' }"><c-pagination :total="250" :responsive="responsive" show-total show-jumper show-page-size /></div>
  </div>
</template>
<style scoped>
.pagination-demo { display: grid; grid-template-columns: minmax(0, 1fr); gap: 16px; min-width: 0; }
.pagination-demo-controls { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; }
</style>
```

### Data changes and auto adjustment

Example source: src/pagination/__demos__/auto-adjust.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const total = ref(200)
const current = ref(18)
const autoAdjust = ref(true)
function reset() { total.value = 200; current.value = 18 }
</script>
<template>
  <div class="pagination-demo">
    <div class="pagination-demo-controls"><c-switch v-model="autoAdjust" /> Auto adjust<c-button @click="total = 25">Reduce total</c-button><c-button @click="reset">Reset</c-button></div>
    <c-pagination v-model="current" :total="total" :auto-adjust="autoAdjust" show-total show-page-size />
    <span>Current: {{ current }} · Total: {{ total }}</span>
  </div>
</template>
<style scoped>
.pagination-demo { display: grid; gap: 16px; min-width: 0; }
.pagination-demo-controls { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; }
</style>
```

### Full feature controls

Example source: src/pagination/__demos__/all.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const total = ref(true)
const jumper = ref(true)
const pageSize = ref(true)
</script>
<template>
  <div class="pagination-demo">
    <div class="pagination-demo-controls"><c-switch v-model="total" /> Total<c-switch v-model="jumper" /> Jumper<c-switch v-model="pageSize" /> Page size</div>
    <c-pagination :total="125" :show-total="total" :show-jumper="jumper" :show-page-size="pageSize" />
  </div>
</template>
<style scoped>
.pagination-demo { display: grid; gap: 16px; min-width: 0; }
.pagination-demo-controls { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; }
</style>
```

## Reading direction

Inherits the nearest `dir="ltr|rtl"` and supports runtime and nested overrides. Page numbers and previous/next semantics remain unchanged. Default navigation icons follow reading direction; page input, disabled boundaries and selection are preserved. Custom icon slots own their direction.

## API

Use ordinary `v-model`: `modelValue` is the current page, starting at 1; pageSize independently controls items per page. `defaultValue` initializes uncontrolled state once without later resets or initialization `update:modelValue`. When `modelValue` is supplied, the parent value controls the display.

<!-- same-source-api:start -->
### Props

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| total | Total item count; required | `number` | `—` |
| model-value | Current page; v-model | `number` | `—` |
| default-value | Initial uncontrolled page | `number` | `1` |
| page-size | Page size; v-model:page-size | `number` | `—` |
| default-page-size | Initial uncontrolled page size | `number` | `10` |
| disabled | Disable all interactions | `boolean` | `false` |
| hide-on-single-page | Hide with at most one page | `boolean` | `false` |
| simple | Explicit simple mode | `boolean` | `false` |
| show-total | Show total | `boolean` | `false` |
| show-more | Append forward jump in full mode | `boolean` | `false` |
| show-jumper | Show separate jumper in full mode; simple mode includes input | `boolean` | `false` |
| show-page-size | Show page size selector | `boolean` | `false` |
| page-size-options | Positive integer size options | `number[]` | `[10, 20, 30, 40, 50]` |
| page-size-props | Optional restricted configuration for the page-size Select. Placement defaults to bottom-start and reaches Trigger through Select.triggerProps for automatic positioning; cannot override pagination values, options or size | `PaginationPageSizeProps` | `—` |
| size | Size of all controls | `'xs' / 'sm' / 'md' / 'lg' / 'xl'` | `'md'` |
| page-item-style | Base numeric page style | `CSSProperties` | `—` |
| active-page-item-style | Additional active numeric page style | `CSSProperties` | `—` |
| base-size | Base threshold for ellipsis in full mode | `number` | `6` |
| buffer-size | Pages on either side of current page | `number` | `2` |
| elevation | Page button shadow; true uses level 2 | `boolean / number` | `false` |
| responsive | Automatically use simple mode by container width | `boolean` | `true` |
| compact-breakpoint | Maximum container width for compact mode, in px | `number` | `480` |
| auto-adjust | Preserve first record on size change; clamp after total shrinks | `boolean` | `true` |

### Events

| Event | Description | Arguments |
| --- | --- | --- |
| update:model-value | Request current page update | `number` |
| change | Committed page change; paired with update:modelValue | `number` |
| update:page-size | Request page size update | `number` |
| page-size-change | Committed size change; paired with update:page-size | `number` |

### Slots

| Slot | Description | Scope |
| --- | --- | --- |
| total | Total | `{ total: number }` |
| page-item | Numeric page | `{ page: number }` |
| page-item-step | Previous / next | `{ type: 'previous' / 'next' }` |
| page-item-ellipsis | Ellipsis jump | `—` |
| jumper-prepend | Separate jumper prefix | `—` |
| jumper-append | Separate jumper suffix | `—` |

### Methods

| Method | Description |
| --- | --- |

<!-- same-source-api:end -->

## Behavior

Containers at or below `compact-breakpoint` automatically use compact mode, consistently in desktop sidebars and mobile. Totals/page-size selectors remain; auxiliary controls wrap. Previous/next sizes follow size without forced narrow-screen enlargement (formerly 36px). `responsive=false` retains full page numbers; extremely narrow page lists scroll internally without widening the page.

The compact current-page input also serves as the jumper, so no duplicate jumper appears. `page-item`, `page-item-ellipsis`, `jumper-prepend` and `jumper-append` render only in their full-mode controls.

Page buttons support Tab/Enter/Space, with `aria-current=page` on the current page. The jumper requests a numeric keyboard and submits on Enter/blur. Empty, nonnumeric or fractional values do not navigate; out-of-range integers clamp to valid pages. Disabled blocks all commits.

`auto-adjust` tries to preserve the previous page's first item when page size changes, clamps to the last page after total reductions and returns to page 1 for zero items. Controlled mode proposes updates only; the parent decides the display. An explicit parent modelValue in the same update batch takes precedence.

Both full and compact jumper inputs show the current page. Navigation, external modelValue changes and page-size adjustments update them together. Invalid input restores the current page number.

### PaginationPageSizeProps

The page-size selector fits its selected text and arrow with only item spacing between them, updating on option/language changes. `--c-pagination-select-width` overrides its width. Popup menus size independently from option content.

Both platforms support `disabled?: boolean`, `placement?: 'top' | 'top-start' | 'top-end' | 'bottom' | 'bottom-start' | 'bottom-end'`, `popupContainer?: string | HTMLElement | false`, `class?: string` and `style?: CSSProperties`. Outer disabled takes precedence. Default placement is bottom-start.

This configuration no longer forwards arbitrary SelectProps/MenuProps. page-size, page-size-options and size control the pagination value, options and dimensions.

## Type definitions

```ts
import type { PaginationProps, PaginationInstance, PaginationPageSizeProps } from '@cedar-design/ui'
```

## Style variables

| Token | Default |
| --- | --- |
| `--c-pagination-text-color` | `var(--c-color-text-1)` |
| `--c-pagination-font-size` | `var(--c-sys-font-size-md)` |
| `--c-pagination-gap` | `var(--c-sys-space-5)` |
| `--c-pagination-item-gap` | `var(--c-sys-space-2)` |
| `--c-pagination-focus-space` | `3px` |
| `--c-pagination-size-xs` | `24px` |
| `--c-pagination-size-sm` | `28px` |
| `--c-pagination-size-md` | `36px` |
| `--c-pagination-size-lg` | `44px` |
| `--c-pagination-size-xl` | `52px` |
| `--c-pagination-item-padding` | `var(--c-sys-space-4)` |
| `--c-pagination-item-border-radius` | `var(--c-sys-radius-md)` |
| `--c-pagination-icon-size` | `16px` |
| `--c-pagination-input-width` | `32px` |
| `--c-pagination-select-width` | `max-content` |
| `--c-pagination-touch-size` | `44px` |
| `--c-pagination-focus-width` | `2px` |
| `--c-pagination-focus-offset` | `1px` |
| `--c-pagination-focus-color` | `var(--c-color-primary)` |
| `--c-pagination-item-background` | `transparent` |
| `--c-pagination-hover-background` | `var(--c-color-fill-1)` |
| `--c-pagination-active-background` | `var(--c-color-primary-light-1)` |
| `--c-pagination-active-color` | `var(--c-color-primary)` |
| `--c-pagination-disabled-color` | `var(--c-color-text-4)` |
| `--c-pagination-disabled-background` | `var(--c-color-fill-1)` |


### Placement semantics and configuration

No placement configuration is required for normal use: bottom-start is preferred and the underlying Trigger automatically flips/constrains the popup. pageSizeProps.placement is only a restricted override for the page-size Select: Pagination → Select.triggerProps.placement → Trigger. It does not position the pagination itself.

---

Document: llms/en-US/components/palette.md

<!-- Source: src/style/palette/README.en-US.md; locale: en-US; page: /en/components/palette/ -->

# Style Palette

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Colors

Example source: src/style/palette/__demos__/colors.vue

```vue
<template>
  <div class="palette-demo">
    <div class="section-title">功能色阶</div>
    <div class="hue-grid">
      <div v-for="hue in functionalHues" :key="hue.name" class="hue-block">
        <div class="hue-label">{{ hue.label }}</div>
        <div class="swatch-row">
          <div
            v-for="step in steps"
            :key="`${hue.name}-${step}`"
            class="swatch"
            :style="{
              background: `rgb(var(--c-${hue.name}-${step}))`,
              color: step > 5 ? '#fff' : '#000',
            }"
            :title="`--c-${hue.name}-${step}`"
          >
            <span class="swatch-name">{{ step }}</span>
          </div>
        </div>
      </div>
    </div>

    <div class="section-title">色相色阶</div>
    <div class="hue-grid">
      <div v-for="hue in chromaticHues" :key="hue.name" class="hue-block">
        <div class="hue-label">{{ hue.label }}</div>
        <div class="swatch-row">
          <div
            v-for="step in steps"
            :key="`${hue.name}-${step}`"
            class="swatch"
            :style="{
              background: `rgb(var(--c-${hue.name}-${step}))`,
              color: step > 5 ? '#fff' : '#000',
            }"
            :title="`--c-${hue.name}-${step}`"
          >
            <span class="swatch-name">{{ step }}</span>
          </div>
        </div>
      </div>
    </div>
  </div>
</template>

<script lang="ts" setup>
const steps = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];

const functionalHues = [
  { name: "primary", label: "Primary（主色）" },
  { name: "success", label: "Success" },
  { name: "warning", label: "Warning" },
  { name: "danger", label: "Danger" },
  { name: "link", label: "Link" },
  { name: "gray", label: "Gray" },
];

const chromaticHues = [
  { name: "brand", label: "Brand" },
  { name: "red", label: "Red" },
  { name: "orangered", label: "Orangered" },
  { name: "orange", label: "Orange" },
  { name: "gold", label: "Gold" },
  { name: "yellow", label: "Yellow" },
  { name: "lime", label: "Lime" },
  { name: "green", label: "Green" },
  { name: "cyan", label: "Cyan" },
  { name: "blue", label: "Blue" },
  { name: "purple", label: "Purple" },
  { name: "pinkpurple", label: "Pinkpurple" },
  { name: "magenta", label: "Magenta" },
];
</script>

<style lang="less" scoped>
.palette-demo {
  color: var(--c-color-text-1);
}

.section-title {
  margin: 16px 0 12px;
  font-size: 16px;
  font-weight: 600;
}

.hue-grid {
  display: grid;
  grid-template-columns: repeat(3, minmax(0, 1fr));
  gap: 16px 20px;
  margin-bottom: 8px;
}

.hue-block {
  min-width: 0;
}

.hue-label {
  margin-bottom: 6px;
  font-size: 13px;
  color: var(--c-color-text-3);
}

.swatch-row {
  display: flex;
  gap: 2px;
  overflow: hidden;
  border-radius: var(--c-border-radius-md, 4px);
}

.swatch {
  flex: 1;
  min-width: 0;
  height: 36px;
  display: flex;
  align-items: center;
  justify-content: center;
  font-size: 11px;
  font-variant-numeric: tabular-nums;
}

.swatch-name {
  overflow: hidden;
  text-overflow: ellipsis;
  white-space: nowrap;
  padding: 0 2px;
}

@media (max-width: 991px) {
  .hue-grid {
    grid-template-columns: repeat(2, minmax(0, 1fr));
  }
}

@media (max-width: 767px) {
  .hue-grid {
    grid-template-columns: 1fr;
  }
}
</style>
```

---

Document: llms/en-US/components/paper.md

<!-- Source: src/paper/README.en-US.md; locale: en-US; page: /en/components/paper/ -->

# Paper

Paper is a low-level surface with background, radius, optional border and elevation. It has no variant, status, structural slots or default padding. Use Card for structured content. Paper does not manage popup positioning, focus or button semantics.

## Basic examples

### Examples

Example source: src/paper/__demos__/basic.vue

```vue
<template>
  <c-space wrap>
    <c-paper :width="120" :height="80">Surface</c-paper>
    <c-paper bordered :width="120" :height="80">Border</c-paper>
    <c-paper bordered :elevation="2" style="padding: 16px">Border + shadow</c-paper>
    <c-paper :radius="12" :width="120" :height="80" :elevation="2">Radius</c-paper>
    <c-paper round :width="80" :height="80" bordered />
    <c-paper inline bordered>Inline</c-paper>
    <c-paper ripple bordered :width="120" :height="80">Ripple</c-paper>
  </c-space>
</template>
```

## Interaction and control

### Live properties

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `bordered` | Show a border independently of elevation | Live properties |
| `round` | 50% radius; a circle only with equal width and height | Live properties |
| `radius` | Explicit radius, taking priority over round | Live properties |
| `elevation` | false disables; true uses level 2; numeric levels 0–24 | Live properties |
| `width` | Width | Live properties |
| `height` | Surface height | Live properties |
<!-- demo-config-notes:end -->


Border and shadow are independent. An explicit radius overrides round; removing it restores round. The inner native button provides keyboard semantics, and its click bubbles to Paper to update parent-owned feedback.

Example source: src/paper/__demos__/live-properties.vue

```vue
<script setup>
import { ref } from "vue";

const bordered = ref(false);
const round = ref(false);
const explicitRadius = ref(false);
const elevated = ref(false);
const clicks = ref(0);
</script>

<template>
  <section class="paper-live-demo">
    <div class="controls">
      <c-checkbox v-model="bordered"> Paper border</c-checkbox>
      <c-checkbox v-model="round"> Round paper</c-checkbox>
      <c-checkbox v-model="explicitRadius"> Explicit radius</c-checkbox>
      <c-checkbox v-model="elevated"> Paper shadow</c-checkbox>
    </div>
    <p role="status">Surface clicks: {{ clicks }}</p>
    <c-paper
      data-testid="live-paper"
      :bordered="bordered"
      :round="round"
      :radius="explicitRadius ? '12' : undefined"
      :elevation="elevated ? 2 : false"
      width="160"
      :height="100"
      @click="clicks++"
    >
      <c-button html-type="button">Surface action</c-button>
    </c-paper>
  </section>
</template>

<style scoped>
.controls {
  display: flex;
  flex-wrap: wrap;
  gap: 12px;
}
.controls label {
  display: inline-flex;
  align-items: center;
  gap: 4px;
}
[data-testid="live-paper"] {
  display: flex;
  align-items: center;
  justify-content: center;
}
</style>
```

## API

### Props

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| bordered | Show a border independently of elevation | boolean | false |
| elevation | false disables; true uses level 2; numeric levels 0–24 | boolean / number | false |
| ripple | Opt-in ripple; does not add button semantics | boolean | false |
| radius | Explicit radius, taking priority over round | number / string | — |
| width | Width | number / string | — |
| height | Surface height | number / string | — |
| round | 50% radius; a circle only with equal width and height | boolean | false |
| inline | Use inline-flex | boolean | false |

Numbers and numeric strings for radius/width/height use px. Other strings pass through as CSS lengths, such as 1rem, 50% and calc(100% - 8px). Classes, native attributes and styles fall through to the root.

### Events

| Event | Description | Arguments |
| --- | --- | --- |
| click | Triggered when the paper is clicked | MouseEvent |

### Slots

| Slot | Description |
| --- | --- |
| default | Paper content |

### Style variables

| Variable | Default |
| --- | --- |
| --c-paper-background | `var(--c-sys-color-surface-default)` |
| --c-paper-border-radius | `4px` |
| --c-paper-border-width | `1px` |
| --c-paper-border-color | `var(--c-sys-color-border-default)` |
| --c-paper-transition-duration | `var(--c-sys-motion-duration-slow)` |

Built-in themes can override backgrounds/radii. bordered=false reserves no border space; enabled borders use border-box and count within fixed dimensions. Background, border and shadow are independent.

### Types

```ts
import type { PaperProps, PaperInstance } from '@cedar-design/ui'
```

## Independent source copies

Each platform maintains its own component body, props, styles, tokens and contract tests, adapting prefixes/local imports without a cross-library core or shared instances/state.

Maple migration: the default background becomes the theme surface, and the default pointer cursor is removed. The inline class becomes mp-paper--inline. Existing dimensions, radii, elevation and ripple APIs remain.

---

Document: llms/en-US/components/people-select.md

<!-- Source: src/people-select/README.en-US.md; locale: en-US; page: /en/components/people-select/ -->

# PeopleSelect

`options` accepts an array or a loader. Each component owns loading, cancellation and stale-result isolation. `fallback-option` synchronously reads independent reactive display data; update that data after a business request to refresh the label and avatar. Avatars come from `avatar`. Optional phone/chat buttons provide consistent presentation while all actions remain application functions.

## Global defaults and local overrides

```ts
import { PeopleSelect, type PeopleSelectProps } from "@cedar-design/ui";
PeopleSelect.setPropsDefaults({
  options: (query, { signal }) => peopleService.search(query, signal),
  fallbackOption: (id) => personCache.value[id] ?? { value: id, label: id },
  showPhone: true,
  showChat: true,
  call: (person) => businessPhone.call(person.mobile),
  chat: (person) => businessChat.open(person.value),
} satisfies PeopleSelectProps);
```

```vue
<c-people-select v-model="personId" />
<c-people-select
  v-model="personId"
  :options="loadMyTeam"
  :chat="openTeamChat"
  :show-phone="false"
  read-pretty
/>
<c-people-select v-model="personId" :options="[]" />
```

Local props override global defaults. Arrays, including [], replace a global loader. Phone/chat buttons appear only in read mode and are hidden by default. Without an action function, without a selected person, or when disabled, the action cannot run. Returned Promises drive button loading; rejection emits action-error(error, call|chat). The UI never opens tel: links or imports a chat SDK.

Configure setPropsDefaults once before mounting. It changes the component definition, not an app/tenant-isolated context. For SSR or dynamic tenant defaults, use an application wrapper and props.

## Custom actions

```vue
<c-people-select v-model="personId" read-pretty>
  <template #actions="{ person, disabled }">
    <business-person-actions :person="person" :disabled="disabled" />
  </template>
</c-people-select>
```

Priority: actions slot → render-actions → built-in phone/chat buttons. Actions do not open the field editor or change its model.

## Basic examples

### Complete example

Example source: src/people-select/__demos__/en-US/injected-services.vue

```vue
<script setup lang="ts">
import { onMounted, ref } from 'vue'
const personId = ref<string | null>('alice')
const log = ref('')
const people = [
 { value: 'alice', label: 'Alice', mobile: '13800000000', avatar: 'data:image/svg+xml,%3Csvg xmlns="http://www.w3.org/2000/svg" width="24" height="24"%3E%3Ccircle cx="12" cy="12" r="12" fill="%236579af"/%3E%3C/svg%3E' },
 { value: 'bob', label: 'Bob', mobile: '13900000000' },
]
const displayed = ref<Record<string, (typeof people)[number]>>({})
// Simulated detail request: update display data without changing candidates.
onMounted(() => { setTimeout(() => { displayed.value.alice = people[0] }, 600) })
const fallbackOption = (id: string) => displayed.value[id] ?? { value: id, label: id }
async function options(query: string, { signal }: { signal: AbortSignal }) {
 await new Promise(resolve => setTimeout(resolve, 200))
 if (signal.aborted) return []
 return people.filter(person => person.label.toLowerCase().includes(query.toLowerCase()))
}
async function call(person: { value: string; mobile?: string }) { log.value = `Call: ${person.mobile || person.value}` }
async function chat(person: { value: string }) { log.value = `Chat: ${person.value}` }
</script>
<template>
 <c-space direction="column">
  <c-people-select v-model="personId" :options="options" :fallback-option="fallbackOption" clearable :empty-value="null" />
  <c-people-select v-model="personId" :fallback-option="fallbackOption" show-phone show-chat :call="call" :chat="chat" read-pretty />
  <p role="status">{{ log }}</p>
 </c-space>
</template>
```

## API

### Empty values and reading placeholders

`empty-values` recognizes empty data; `empty-value` keeps existing clear output. `empty-text` defaults to `'-'` under `read-pretty`, with Field > FormItem > Form precedence and custom read slots first. With explicit empty-values, built-in required uses the policy; custom validators receive original data. See the [shared guide](llms/en-US/guide/empty-values.md).

| Prop         | Type               | Default and scope                                                           |
| ------------ | ------------------ | --------------------------------------------------------------------------- |
| empty-values | readonly unknown[] | Field > FormItem > Form > component-family default; replaces the whole list |
| empty-text   | string             | Field > FormItem > Form > '-'; explicit '' is valid                         |

These props belong to field presentation; pure panels do not gain reading mode. Form and FormItem provide inherited settings. The existing empty-value type and clear fallback remain component-specific.

| Prop                    | Description                                                  | Default |
| ----------------------- | ------------------------------------------------------------ | ------- |
| v-model / default-value | String ID; null explicitly clears the model                  | — / ''  |
| options                 | Array or (query, { signal }) => array/Promise                | —       |
| fallback-option         | boolean / (id) => PeopleSelectOption                         | true    |
| show-avatar             | Render avatar                                                | true    |
| show-phone / show-chat  | Read-mode phone/chat buttons                                 | false   |
| call / chat             | Application (person) => void/Promise                         | —       |
| render-actions          | ({ person, disabled }) => VNodeChild                         | —       |
| is-label / read-pretty  | Read mode; uses reactive fallback without loading candidates | false   |
| disabled / readonly     | Inherit form state when omitted                              | —       |
| empty-value             | Clear result; accepts null or a factory returning null       | ''      |

Person data is `{ value: string, label: string, avatar?: string, mobile?: string, disabled?: boolean }`.

Optionally pass signal to fetch to cancel stale requests. It is not an HTTP parameter and cannot roll back server operations. Even if signal is ignored, the component isolates stale results. Function results skip secondary local filtering by default; filter-option configures only local matching.

Events: update:model-value, change, clear, search, load-error(error, options), action-error(error, call|chat). Methods: refresh(), focus(), blur(). No separate request prop, external useAsyncData or special provider key is needed.

`empty-value` accepts explicit `null` (or `() => null`). Clearing publishes `null` unchanged; omitted values preserve the existing default. Editors render `null` as blank without converting ordinary empty-string input to `null`. In popup editing, clearing changes the draft; confirm commits it and cancel preserves the original model.

`fallback-option` is independent of options, returns no Promise and sends no requests. Display prefers a current option, then fallback; false disables display of unmatched values.

### Receiving cancellation signals in business requests

The component creates an AbortController per operation and passes signal to the loader. Business code must forward it through request layers. fetch supports AbortSignal natively; Axios 0.22+ supports signal; ofetch/Ky forward or merge it into fetch. Other wrappers must adapt abort events to their own cancellation methods. Client cancellation cannot undo completed server operations.

```ts
async function loadPeople(query, { signal }) {
  const response = await fetch(`/api/people?q=${encodeURIComponent(query)}`, {
    signal,
  });
  if (!response.ok) throw new Error("People request failed");
  return response.json();
}

// Axios: preserve signal through your service wrapper.
async function loadWithAxios(query, { signal }) {
  const { data } = await axios.get("/api/people", {
    params: { q: query },
    signal,
  });
  return data;
}

// Other fetch wrappers:
const loadWithOfetch = (query, { signal }) =>
  ofetch("/api/people", { query: { q: query }, signal });
const loadWithKy = (query, { signal }) =>
  ky.get("/api/people", { searchParams: { q: query }, signal }).json();
```

[AbortSignal](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) · [Axios cancellation](https://axios-http.com/docs/cancellation) · [ofetch](https://github.com/unjs/ofetch) · [Ky](https://github.com/sindresorhus/ky#cancellation)

---

Document: llms/en-US/components/popconfirm.md

<!-- Source: src/popconfirm/README.en-US.md; locale: en-US; page: /en/components/popconfirm/ -->

# Popconfirm

A confirmation popup with before-confirm and before-cancel hooks.

## Basic examples

### Basic

Example source: src/popconfirm/__demos__/basic.vue

```vue
<template>
  <c-popconfirm content="Are you sure you want to delete?">
    <c-button>Click To Delete</c-button>
  </c-popconfirm>
</template>

<script lang="ts" setup>
</script>
```

## Appearance and states

### Type

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `content` | Content | Type |
| `type` | Confirmation status type | Type |
<!-- demo-config-notes:end -->


Example source: src/popconfirm/__demos__/type.vue

```vue
<template>
  <c-space>
    <c-popconfirm content="Are you sure you want to delete?" type="info">
      <c-button>Click To Delete</c-button>
    </c-popconfirm>
    <c-popconfirm content="Are you sure you want to delete?" type="success">
      <c-button>Click To Delete</c-button>
    </c-popconfirm>
    <c-popconfirm content="Are you sure you want to delete?" type="warning">
      <c-button>Click To Delete</c-button>
    </c-popconfirm>
    <c-popconfirm content="Are you sure you want to delete?" type="error">
      <c-button>Click To Delete</c-button>
    </c-popconfirm>
  </c-space>
</template>

<script lang="ts" setup>
</script>
```

### Api Review

## Layout and arrangement

### Placement

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `content` | Content | Placement |
| `placement` | Preferred popup side relative to the trigger, default top. With the default auto-fit-position enabled, Trigger may flip and constrain it to the viewport when space is limited; this is not a fixed final position | Placement |
<!-- demo-config-notes:end -->


Example source: src/popconfirm/__demos__/placement.vue

```vue
<template>
  <div :style="{ position: 'relative', width: '440px', height: '280px' }">
    <c-popconfirm content="This is a Popconfirm" placement="top-start">
      <c-button class="button" :style="{ position: 'absolute', top: '0', left: '70px' }">TL</c-button>
    </c-popconfirm>
    <c-popconfirm content="This is a Popconfirm" placement="top">
      <c-button class="button" :style="{ position: 'absolute', top: '0', left: '180px' }">TOP</c-button>
    </c-popconfirm>
    <c-popconfirm content="This is a Popconfirm" placement="top-end">
      <c-button class="button" :style="{ position: 'absolute', top: '0', left: '290px' }">TR</c-button>
    </c-popconfirm>
    <c-popconfirm content="This is a Popconfirm" placement="bottom-start">
      <c-button class="button" :style="{ position: 'absolute', top: '240px', left: '70px' }">BL</c-button>
    </c-popconfirm>
    <c-popconfirm content="This is a Popconfirm" placement="bottom">
      <c-button class="button" :style="{ position: 'absolute', top: '240px', left: '180px' }">BOTTOM</c-button>
    </c-popconfirm>
    <c-popconfirm content="This is a Popconfirm" placement="bottom-end">
      <c-button class="button" :style="{ position: 'absolute', top: '240px', left: '290px' }">BR</c-button>
    </c-popconfirm>
    <c-popconfirm content="This is a Popconfirm" placement="left-start">
      <c-button class="button" :style="{ position: 'absolute', top: '60px', left: '10px' }">LT</c-button>
    </c-popconfirm>
    <c-popconfirm content="This is a Popconfirm" placement="left">
      <c-button class="button" :style="{ position: 'absolute', top: '120px', left: '10px' }">LEFT</c-button>
    </c-popconfirm>
    <c-popconfirm content="This is a Popconfirm" placement="left-end">
      <c-button class="button" :style="{ position: 'absolute', top: '180px', left: '10px' }">LB</c-button>
    </c-popconfirm>
    <c-popconfirm content="This is a Popconfirm" placement="right-start">
      <c-button class="button" :style="{ position: 'absolute', top: '60px', left: '350px' }">RT</c-button>
    </c-popconfirm>
    <c-popconfirm content="This is a Popconfirm" placement="right">
      <c-button class="button" :style="{ position: 'absolute', top: '120px', left: '350px' }">RIGHT</c-button>
    </c-popconfirm>
    <c-popconfirm content="This is a Popconfirm" placement="right-end">
      <c-button class="button" :style="{ position: 'absolute', top: '180px', left: '350px' }">RB</c-button>
    </c-popconfirm>
  </div>
</template>

<script lang="ts" setup>
</script>
```

## Content and presentation

### Guard Protocol

Example source: src/popconfirm/__demos__/en-US/guard-protocol.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import type { PopconfirmBeforeConfirm } from "@cedar-design/ui";
const open = ref(false);
const mode = ref("promise");
const allowed = ref(false);
const status = ref("");
const check: PopconfirmBeforeConfirm = (payload, done, { signal }) => {
  status.value = `Waiting: ${payload.action}`;
  if (mode.value === "done") {
    setTimeout(() => {
      status.value = allowed.value ? "Allowed" : "Rejected";
      done(!signal.aborted && allowed.value);
    }, 500);
    return;
  }
  return new Promise<boolean>((resolve) =>
    setTimeout(() => {
      status.value = allowed.value ? "Allowed" : "Rejected";
      resolve(!signal.aborted && allowed.value);
    }, 500),
  );
};
</script>
<template>
  <c-space direction="column" align="stretch">
    <c-switch v-model="allowed" />
    <c-form-item layout="vertical" size="sm" label="mode">
      <c-radio-group
        aria-label="mode"
        v-model="mode"
        :options="[
          { value: 'promise', label: 'Promise' },
          { value: 'done', label: 'done callback' },
        ]"
        variant="button"
        size="sm"
      />
    </c-form-item>
    <c-button @click="open = true">Open</c-button>
    <c-popconfirm
      v-model:open="open"
      :before-confirm="check"
      @guard-error="status = 'Error'"
    >
      <template #default
        ><c-button v-if="true" @click="open = true">Confirm action</c-button
        ><span v-else>Close with beforeClose</span></template
      >
    </c-popconfirm>
    <p role="status">{{ status }}</p>
  </c-space>
</template>
```

### `<popconfirm>` Props

| Name | Description | Type | Default |
| --------------------------- | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | :------: |
| content | Content | `string` | `-` |
| placement | Preferred popup side relative to the trigger, default top. Trigger may flip and constrain it to the viewport when space is limited; this is not a fixed final position | `'top' \| 'top-start' \| 'top-end' \| 'bottom' \| 'bottom-start' \| 'bottom-end' \| 'left' \| 'left-start' \| 'left-end' \| 'right' \| 'right-start' \| 'right-end'` | `'top'` |
| open **(v-model)** | Controlled confirmation popup visibility | `boolean` | `-` |
| default-open | Initial uncontrolled popup visibility | `boolean` | `false` |
| type | Confirmation status type | `'info' \| 'success' \| 'warning' \| 'error'` | `'info'` |
| confirm-button-text | Confirm button text | `string` | `-` |
| cancel-text | Cancel button text | `string` | `-` |
| confirm-button-loading | Confirm button loading state | `boolean` | `false` |
| confirm-button-props | Confirm button props | `ButtonProps` | `-` |
| cancel-button-props | Cancel button props | `ButtonProps` | `-` |
| content-class | Popup content class | `ClassName` | `-` |
| content-style | Popup content style | `CSSProperties` | `-` |
| arrow-class | Arrow class | `ClassName` | `-` |
| arrow-style | Arrow style | `CSSProperties` | `-` |
| popup-container | Portal container | `string \| HTMLElement \| false` | `-` |
| `before-confirm` | Return a boolean/Promise or call done; the first completion wins | `PopconfirmBeforeConfirm` | — |
| `before-cancel` | Return a boolean/Promise or call done; the first completion wins | `PopconfirmBeforeConfirm` | — |

### `<popconfirm>` Events

| Event | Description | Arguments |
| -------------------- | ------------------------------ | ------------------ |
| open-change | Popup visibility changes | open: `boolean` |
| confirm | Accepted confirm action | - |
| cancel | Accepted cancel action | - |

### `<popconfirm>` Slots

| Slot | Description | Arguments |
| ------- | :--: | ---- |
| icon | Icon | - |
| content | Content | - |


Promise and done share a single completion state: false/done(false) rejects; true/done() allows; a resolved Promise&lt;void&gt; allows. The first completion wins. Errors emit guard-error; cancellation/unmount invalidates late completion. Synchronous void retains the callback protocol and waits for done on these close/confirm guards.


Cancellable hooks use `(payload, done, context)`: closure payloads contain `{ action }`, change/commit payloads contain `{ value, previousValue }`, and Popup uses `{ reason }`. Context provides `signal` and an optional original `event`. Return a boolean/Promise, or call done()/done(false). Synchronous void waits for done; Promise&lt;void&gt; allows the operation. First completion wins. Pending state controls loading/disabled automatically. Cancellation invalidates stale results. Button refs are not exposed.

## Customization and slots

### Custom

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `content` | Content | Custom |
| `confirm-button-text` | Confirm button text | Custom |
| `cancel-text` | Cancel button text | Custom |
<!-- demo-config-notes:end -->


Example source: src/popconfirm/__demos__/custom.vue

```vue
<template>
  <c-popconfirm content="Do you want to discard the draft?" confirmButtonText="Discard" cancelText="No">
    <c-button>Discard</c-button>
  </c-popconfirm>
</template>

<script lang="ts" setup>
</script>
```

## Reading direction

Inherits the nearest `dir="ltr|rtl"` and supports runtime and nested overrides. Content and actions use logical alignment. Confirm/cancel actions follow reading order, and switching direction triggers neither action. Explicit popup placement retains its documented physical or logical meaning.

## API

### `<popconfirm>` Props

| Parameter | Description | Type | Default |
| --------------------------- | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | :------: |
| content | Content | `string` | `-` |
| placement | Preferred popup side relative to the trigger, default top. With the default auto-fit-position enabled, Trigger may flip and constrain it to the viewport when space is limited; this is not a fixed final position | `'top' \| 'top-start' \| 'top-end' \| 'bottom' \| 'bottom-start' \| 'bottom-end' \| 'left' \| 'left-start' \| 'left-end' \| 'right' \| 'right-start' \| 'right-end'` | `'top'` |
| open **(v-model)** | Controlled confirmation popup visibility | `boolean` | `-` |
| default-open | Initial uncontrolled popup visibility | `boolean` | `false` |
| type | Confirmation status type | `'info' \| 'success' \| 'warning' \| 'error'` | `'info'` |
| confirm-button-text | Confirm button text | `string` | `-` |
| cancel-text | Cancel button text | `string` | `-` |
| confirm-button-loading | Confirm button loading state | `boolean` | `false` |
| confirm-button-props | Confirm button props | `ButtonProps` | `-` |
| cancel-button-props | Cancel button props | `ButtonProps` | `-` |
| content-class | Popup content class | `ClassName` | `-` |
| content-style | Popup content style | `CSSProperties` | `-` |
| arrow-class | Arrow class | `ClassName` | `-` |
| arrow-style | Arrow style | `CSSProperties` | `-` |
| popup-container | Portal container | `string \| HTMLElement \| false` | `-` |
| `before-confirm` | Return a boolean/Promise or call done; the first completion wins | `PopconfirmBeforeConfirm` | — |
| `before-cancel` | Return a boolean/Promise or call done; the first completion wins | `PopconfirmBeforeConfirm` | — |

### `<popconfirm>` Events

| Event | Description | Arguments |
| -------------------- | ------------------------------ | ------------------ |
| open-change | Popup visibility changes | open: `boolean` |
| confirm | Accepted confirm action | - |
| cancel | Accepted cancel action | - |

### `<popconfirm>` Slots

| Slot | Description | Arguments |
| ------- | :--: | ---- |
| icon | Icon | - |
| content | Content | - |

### Type definitions

The component exports the following types

```ts
import type { PopconfirmInstance } from '@cedar-design/ui'
```


### Placement semantics and configuration

placement directly uses TriggerPlacement / triggerPlacements. Legacy TriggerPosition / TRIGGER_POSITIONS aliases have been removed; placement values are unchanged.

### Before-hook waiting feedback

Before-hook waits show visible feedback and aria-busy. Rejected or failed operations recover; duplicate submissions do not start another copy. Notification event Promises never drive loading.

---

Document: llms/en-US/components/popover.md

<!-- Source: src/popover/README.en-US.md; locale: en-US; page: /en/components/popover/ -->

# Popover

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

Preview configuration: `title="设备状态"`.

Example source: src/popover/__demos__/basic.vue

```vue
<template>
  <c-popover title="设备状态">
    <c-button>点击查看</c-button>
    <template #content>
      <p>设备：生产线 A-03</p>
      <p>状态：运行中</p>
    </template>
  </c-popover>
</template>
```

## Interaction and control

### Interactive

Preview configuration: `v-model:open="open"`, `title="快速备注"`, `placeholder="关闭后再次打开，草稿仍会保留"`.

Example source: src/popover/__demos__/interactive.vue

```vue
<template>
  <c-popover v-model:open="open" title="快速备注">
    <c-button>编辑备注</c-button>
    <template #content>
      <c-space direction="column">
        <c-input v-model="draft" placeholder="关闭后再次打开，草稿仍会保留" />
        <c-button status="primary" @click="open = false">完成</c-button>
      </c-space>
    </template>
  </c-popover>
</template>

<script setup lang="ts">
import { ref } from 'vue'

const open = ref(false)
const draft = ref('')
</script>
```

## Reading direction

Inherits the nearest `dir="ltr|rtl"` and supports runtime and nested overrides. Content defaults to reading start and portals inherit their source direction. Logical start/end alignment follows direction, while explicit left/right placement remains physical.

## API

Popover inherits Trigger positioning, containers, controlled state, close policies and public methods.

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| title | Title | `string` | — |
| content | Body | `string` | — |
| trigger | Interaction | `TriggerEvent \| TriggerEvent[]` | `click` |
| placement | Preferred popup side relative to the trigger, default bottom. With the default auto-fit-position enabled, Trigger may flip and constrain it to the viewport when space is limited; this is not a fixed final position | `TriggerPlacement` | `bottom` |
| show-arrow | Show the arrow | `boolean` | `true` |
| popup-offset | Main-axis distance | `number` | `10` |
| unmount-on-close | Unmount content after closing; interaction drafts are retained by default | `boolean` | `false` |
| close-on-click-reference | Close when the trigger is clicked again | `boolean` | `true` |

Events: `update:open`, `open-change`, `open`, `opened`, `close`, `closed`, `click-outside`. Slots: `default`, `title`, `content`. Slots override same-name `content` props.

Panels have consistent content/title/body layers. Triggers are associated through `aria-controls`/`aria-expanded`; external references and SVG are also supported.

## Shared-source contract

Cedar and Maple independently maintain the same component body, props, appearance mapping and structural styles. Use Trigger directly for unstyled positioning. Popover has no `defaultStyle`, `popoverClass` or `elevation`; customize appearance through component tokens, `content-class` or `content-style`.

## Public CSS variables

These are actual :root defaults. Prefer component variables for business customization; internal positioning variables are not public API.

| Variable | Default | Meaning and use case |
| --- | --- | --- |
| `--c-popover-background` | `var(--c-sys-color-surface-overlay)` | Content and arrow background |
| `--c-popover-text-color` | `var(--c-sys-color-content-secondary)` | Body foreground |
| `--c-popover-border-color` | `var(--c-sys-color-border-default)` | Content and arrow border color |
| `--c-popover-border-width` | `1px` | Content and arrow border width |
| `--c-popover-border-radius` | `var(--c-sys-radius-md)` | Content border radius |
| `--c-popover-box-shadow` | `var(--c-shadow2-down)` | Content shadow; retains platform differences |
| `--c-popover-arrow-z-index` | `1` | Arrow stacking within the current popup |
| `--c-popover-padding-horizontal` | `var(--c-sys-space-7)` | Horizontal content padding |
| `--c-popover-padding-vertical` | `var(--c-sys-space-6)` | Vertical content padding |
| `--c-popover-font-size` | `var(--c-sys-font-size-md)` | Content font size |
| `--c-popover-line-height` | `var(--c-line-height)` | Content line height |
| `--c-popover-title-text-color` | `var(--c-sys-color-content-primary)` | Title foreground |
| `--c-popover-title-font-size` | `var(--c-sys-font-size-lg)` | Title font size |
| `--c-popover-title-font-weight` | `var(--c-sys-font-weight-medium)` | Title font weight |
| `--c-popover-title-content-gap` | `var(--c-sys-space-2)` | Title-to-body gap |
| `--c-popover-animation-duration` | `var(--c-sys-motion-duration-standard)` | Enter/leave duration; reduced motion may override it |

Maple dark mode retains a 2px radius and platform-specific shadows. Content and arrows share background/border variables, independent of Trigger style-loading order.

With Teleport, variables must be in the actual popup scope, for example through `popup-style`. Trigger-button variables do not automatically inherit into popups.

---

Document: llms/en-US/components/progress-group.md

<!-- Source: src/progress-group/README.en-US.md; locale: en-US; page: /en/components/progress-group/ -->

# Progress Group

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

- `max`: Sets the upper bound.

Example source: src/progress-group/__demos__/basic.vue

```vue
<script setup lang="ts">
import type { ProgressGroupItem } from '@cedar-design/ui'

const items: ProgressGroupItem[] = [
  { label: '系统', value: 24, color: '#64748b' },
  { label: '应用', value: 8, color: '#f53f3f' },
  { label: '多媒体', value: 42, color: '#00b42a' },
]
</script>

<template>
  <c-progress-group :items="items" :max="128" show-text style="max-width: 520px" />
</template>
```

## Appearance and states

### Progress group sizes and colors

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `items` | Segment data | Progress group sizes and colors |
| `size` | Track size | Progress group sizes and colors |
| `color` | Default color for segments without their own color | Progress group sizes and colors |
| `show-text` | Show the summed percentage | Progress group sizes and colors |
<!-- demo-config-notes:end -->


Compare segment sizes and color overrides separately from orientation, circular layouts, overflow and keyboard interaction.

Example source: src/progress-group/__demos__/appearance-comparison.vue

```vue
<script setup lang="ts">
import { proxyRefs as demoProxyRefs } from 'vue'

const scene1 = demoProxyRefs((() => {

const items = [
  { value: 24 },
  { value: 18, color: "#722ed1" },
  { value: 30, color: "#0fc6c2" },
];

const sizes = ["xs", "sm", "md", "lg", "xl"] as const;
return { items, sizes }
})())

const scene2 = demoProxyRefs((() => {

const inheritedColorItems = [
  { label: "文档", value: 20 },
  { label: "测试", value: 35 },
];

const trackOnlyItems = [
  { value: 16 },
  { value: 22, color: "#722ed1" },
  { value: 28, color: "#0fc6c2" },
];
return { inheritedColorItems, trackOnlyItems }
})())
</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="sizes">
    <h4><span lang="zh-CN">尺寸</span><span lang="en-US">sizes</span></h4>
    <c-space direction="column" size="16px" style="max-width: 520px">
        <div
          v-for="size in scene1.sizes"
          :key="size"
          style="
            display: grid;
            grid-template-columns: 24px 1fr;
            align-items: center;
            gap: 12px;
          "
        >
          <span>{{ size }}</span>
          <c-progress-group :items="scene1.items" :size="size" />
        </div>
      </c-space>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="color">
    <h4><span lang="zh-CN">颜色与纯进度轨</span><span lang="en-US">color</span></h4>
    <c-space direction="column" size="24px" style="max-width: 520px">
        <c-progress-group :items="scene2.inheritedColorItems" color="#ff7d00" show-text />
        <c-progress-group :items="scene2.trackOnlyItems" size="lg" />
      </c-space>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

## Layout and arrangement

### Orientation

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `items` | Segment data | Orientation |
| `show-text` | Show the summed percentage | Orientation |
| `orientation` | Horizontal/vertical orientation of the linear progress track, default horizontal; only used for mode=line | Orientation |
| `size` | Track size | Orientation |
<!-- demo-config-notes:end -->


- `size`: Controls the component size.

Example source: src/progress-group/__demos__/orientation.vue

```vue
<script setup lang="ts">
const items = [
  { label: "系统", value: 24, color: "#64748b" },
  { label: "应用", value: 18, color: "#f53f3f" },
  { label: "媒体", value: 32, color: "#00b42a" },
];
</script>

<template>
  <c-space wrap size="64px" align="flex-start">
    <c-progress-group :items="items" show-text style="width: 420px" />
    <c-progress-group
      :items="items"
      orientation="vertical"
      size="lg"
      show-text
      style="height: 220px"
    />
  </c-space>
</template>
```

## Content and presentation

### Circle

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `mode` | Display mode | Circle |
| `items` | Segment data | Circle |
| `show-text` | Show the summed percentage | Circle |
| `circle-size` | Diameter in circle mode | Circle |
| `stroke-width` | Track width in circle mode | Circle |
<!-- demo-config-notes:end -->


Preview configuration: `mode="circle"`, `:items="items"`, `show-text`, `:circle-size="168"`.

Example source: src/progress-group/__demos__/circle.vue

```vue
<script setup lang="ts">
const items = [
  { label: "系统", value: 24, color: "#64748b" },
  { label: "应用", value: 18, color: "#f53f3f" },
  { label: "媒体", value: 32, color: "#00b42a" },
];
</script>

<template>
  <c-space wrap size="48px" align="flex-start">
    <c-progress-group mode="circle" :items="items" show-text />
    <c-progress-group
      mode="circle"
      :items="items"
      :circle-size="168"
      :stroke-width="12"
      show-text
    >
      <template #text="{ value, max }">
        <div style="text-align: center">
          <strong>{{ value }}</strong
          ><br /><small>/ {{ max }} GB</small>
        </div>
      </template>
    </c-progress-group>
  </c-space>
</template>
```

## Interaction and control

### Overflow Keyboard

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `items` | Segment data | Overflow Keyboard |
| `max` | Total used to calculate segment proportions | Overflow Keyboard |
| `tooltip` | Whether to show segment hover/focus hints | Overflow Keyboard |
| `show-text` | Show the summed percentage | Overflow Keyboard |
| `aria-label` | Accessible group name | Overflow Keyboard |
| `mode` | Display mode | Overflow Keyboard |
<!-- demo-config-notes:end -->


- `max`: Sets the upper bound.

Example source: src/progress-group/__demos__/overflow-keyboard.vue

```vue
<script setup>
import { ref } from "vue";

const initialItems = [
  { label: "A", value: 70 },
  { label: "B", value: 50, color: "#722ed1" },
  { label: "C", value: 10, color: "#0fc6c2" },
];
const items = ref(initialItems);
const max = ref(100);
const tooltip = ref(true);
</script>
<template>
  <c-space direction="column" size="24px" data-demo-capacity>
    <c-space wrap>
      <c-button @click="max = max === 100 ? 200 : 100"
        >Capacity: {{ max }}</c-button
      >
      <c-button @click="items = items.length ? [] : initialItems">{{
        items.length ? "Clear data" : "Restore data"
      }}</c-button>
      <c-button @click="tooltip = !tooltip"
        >Tooltips: {{ tooltip ? "on" : "off" }}</c-button
      >
    </c-space>
    <c-progress-group
      :items="items"
      :max="max"
      :tooltip="tooltip"
      show-text
      aria-label="Capacity line"
    />
    <c-progress-group
      mode="circle"
      :items="items"
      :max="max"
      :tooltip="tooltip"
      show-text
      aria-label="Capacity circle"
    />
    <p aria-live="polite">
      Items: {{ items.length }}; capacity: {{ max }}; tooltips:
      {{ tooltip ? "on" : "off" }}
    </p>
  </c-space>
</template>
```

Example source: src/progress-group/__demos__/slots.vue

```vue
<script setup lang="ts">
const items = [
  { label: '设计稿', value: 18, color: '#165dff', tip: '设计稿占用 18 GB' },
  { label: '组件', value: 36, color: '#722ed1' },
  { label: '测试', value: 20, color: '#0fc6c2' },
]
</script>

<template>
  <c-progress-group :items="items" show-text style="max-width: 520px">
    <template #text="{ value, max }">已使用 {{ value }} / {{ max }} GB</template>
    <template #item-trailing="{ item }">{{ item.value }} GB</template>
    <template #tooltip="{ item, percent }">{{ item.label }} · {{ item.value }} GB · {{ Math.round(percent) }}%</template>
  </c-progress-group>
</template>
```

## Reading direction

Horizontal segments, highlights and tooltips share a logical start. Vertical progress stays top to bottom; circular angles and data order are preserved.

## API

### Props

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| aria-label | Accessible group name | `string` | — |
| items | Segment data | `ProgressGroupItem[]` | `[]` |
| mode | Display mode | `'line' \| 'circle'` | `'line'` |
| max | Total used to calculate segment proportions | `number` | `100` |
| show-text | Show the summed percentage | `boolean` | `false` |
| size | Track size | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` |
| color | Default color for segments without their own color | `string` | `content-brand` |
| circle-size | Diameter in circle mode | `number \| string` | `120` |
| stroke-width | Track width in circle mode | `number` | `8` |
| tooltip | Whether to show segment hover/focus hints | `boolean` | `true` |
| orientation | Horizontal/vertical orientation of the linear progress track, default horizontal; only used for mode=line | `'horizontal' \| 'vertical'` | `'horizontal'` |

### Item

| Prop | Description | Type |
| --- | --- | --- |
| label | Legend label | `string` |
| value | Segment value | `number` |
| color | Segment color | `string` |
| icon | Legend icon component | `Component` |
| slot | Custom slot-name prefix | `string` |
| tip | Custom hint text | `string` |

### Slots

| Name | Slot arguments |
| --- | --- |
| text | `{ percent, value, max }` |
| tooltip | `{ item, index, percent }` |
| item / item-leading / item-label / item-trailing | `{ item, index, percent }` |

### Style variables

| Variable | Default |
| --- | --- |
| `--c-progress-group-gap` | `var(--c-sys-space-3)` |
| `--c-progress-group-item-gap` | `var(--c-sys-space-2)` |
| `--c-progress-group-dot-size` | `var(--c-sys-space-4)` |
| `--c-progress-group-radius` | `9999px` |
| `--c-progress-group-track-color` | `var(--c-sys-color-state-hover)` |
| `--c-progress-group-text-color` | `var(--c-sys-color-content-primary)` |
| `--c-progress-group-muted-color` | `var(--c-sys-color-content-secondary)` |
| `--c-progress-group-font-size` | `var(--c-sys-font-size-sm)` |
| `--c-progress-group-tooltip-bg` | `var(--c-sys-color-surface-tooltip)` |
| `--c-progress-group-tooltip-color` | `var(--c-sys-color-content-on-dark)` |

Graphic markers default to system content-brand. Color precedence: item.color → component color → default. Check custom-color contrast; geometry tokens retain platform differences.

### Geometry and motion variables

Built-in effects respect `prefers-reduced-motion: reduce`. Track thickness applies to both horizontal and vertical layouts; circle geometry remains prop-driven.

| Token | Default |
| --- | --- |
| `--c-progress-group-transition-duration` | `var(--c-sys-motion-duration-standard)` |
| `--c-progress-group-tooltip-duration` | `var(--c-sys-motion-duration-fast)` |
| `--c-progress-group-tooltip-max-width` | `240px` |
| `--c-progress-group-tooltip-padding` | `5px var(--c-sys-space-4)` |
| `--c-progress-group-tooltip-radius` | `var(--c-sys-radius-md)` |
| `--c-progress-group-tooltip-font-size` | `var(--c-sys-font-size-xs)` |
| `--c-progress-group-tooltip-line-height` | `1.4` |
| `--c-progress-group-tooltip-offset` | `var(--c-sys-space-4)` |
| `--c-progress-group-text-font-weight` | `var(--c-sys-font-weight-medium)` |
| `--c-progress-group-size-xs-thickness` | `2px` |
| `--c-progress-group-size-sm-thickness` | `4px` |
| `--c-progress-group-size-md-thickness` | `8px` |
| `--c-progress-group-size-lg-thickness` | `12px` |
| `--c-progress-group-size-xl-thickness` | `16px` |

---

Document: llms/en-US/components/progress.md

<!-- Source: src/progress/README.en-US.md; locale: en-US; page: /en/components/progress/ -->

# Progress

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

Preview configuration: `:percent="20"`, `:percent="30"`.

Example source: src/progress/__demos__/basic.vue

```vue
<template>
  <c-progress :percent="20" :style="{ width: '50%' }" />
  <br />
  <br />
  <c-progress :percent="30" :style="{ width: '50%' }">
    <template v-slot:text="scope">进度 {{ scope.percent }}%</template>
  </c-progress>
</template>
```

## Appearance and states

### Progress sizes and states

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `size` | xs/sm/md/lg/xl or CSS length; line thickness / circle diameter | Progress sizes and states |
| `percent` | Decimal 0–100; numeric strings supported; invalid values become zero, out-of-range values clamp | Progress sizes and states |
| `mode` | Line or circle | Progress sizes and states |
| `stroke-width` | Overrides thickness, numbers in px | Progress sizes and states |
| `status` | default/primary/secondary/tertiary/info/success/warning/danger; default becomes success at 100 unless indeterminate | Progress sizes and states |
<!-- demo-config-notes:end -->


Compare sizes and semantic states independently of circular, stepped and indeterminate models.

Example source: src/progress/__demos__/appearance-comparison.vue

```vue
<script setup lang="ts">
import { proxyRefs as demoProxyRefs } from 'vue'

const scene1 = demoProxyRefs((() => {

const sizes = ["xs", "sm", "md", "lg", "xl"] as const;
return { sizes }
})())

const scene2 = demoProxyRefs((() => {

const statuses = [
  "default",
  "primary",
  "secondary",
  "tertiary",
  "info",
  "success",
  "warning",
  "danger",
] as const;
return { statuses }
})())
</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="size">
    <h4><span lang="zh-CN">五档与自定义尺寸</span><span lang="en-US">size</span></h4>
    <c-space direction="column" size="16px">
        <c-space wrap size="16px" align="center" v-for="size in scene1.sizes" :key="size">
          <span>{{ size }}</span
          ><c-progress :size="size" :percent="42" /><c-progress
            mode="circle"
            :size="size"
            :percent="42"
          />
        </c-space>
        <c-progress :size="10" :percent="12.5" />
        <c-progress size="0.75rem" :stroke-width="6" :percent="60" />
        <c-progress mode="circle" size="6rem" :percent="75" />
      </c-space>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="status">
    <h4><span lang="zh-CN">八种状态</span><span lang="en-US">status</span></h4>
    <c-space direction="column" size="16px">
        <c-progress
          v-for="status in scene2.statuses"
          :key="status"
          :status="status"
          :percent="60"
          ><template #text>{{ status }}</template></c-progress
        >
        <c-progress :percent="100" />
      </c-space>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

## Content and presentation

### Circle

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `percent` | Decimal 0–100; numeric strings supported; invalid values become zero, out-of-range values clamp | Circle, Step, Loop |
| `mode` | Line or circle | Circle, Loop, Advanced |
| `status` | default/primary/secondary/tertiary/info/success/warning/danger; default becomes success at 100 unless indeterminate | Circle, Step |
| `steps` | Line segments, floored and clamped to 0–1000; ignored when indeterminate | Step |
| `size` | xs/sm/md/lg/xl or CSS length; line thickness / circle diameter | Step |
| `indeterminate` | Unknown progress; omits aria-valuenow | Loop |
<!-- demo-config-notes:end -->


- `status`: Selects the semantic state.

Example source: src/progress/__demos__/circle.vue

```vue
<template>
  <c-space wrap size="lg">
    <c-progress mode="circle" :percent="percent" />
    <c-progress mode="circle" status="warning" :percent="percent" />
    <c-progress mode="circle" status="danger" :percent="percent" />
    <c-progress mode="circle" status="success" :percent="percent" />
  </c-space>
  <div :style="{ marginTop: '20px' }">
    <c-slider v-model="percent" :max="100" :step="10" :style="{ width: '150px' }" />
  </div>
</template>
<script lang="ts" setup>
import { ref } from 'vue'
const percent = ref(20)
</script>
```

### Step

- `status`: Selects the semantic state.
- `size`: Controls the component size.

Example source: src/progress/__demos__/step.vue

```vue
<template>
  <c-space direction="column" size="16px">
    <c-progress :steps="5" :percent="40" />
    <c-progress :steps="10" :percent="75" status="warning" size="lg" />
    <c-progress :steps="5" :percent="100" />
  </c-space>
</template>
```

### Loop

Preview configuration: `indeterminate`, `aria-label="Loading"`, `mode="circle"`, `:percent="60"`.

Example source: src/progress/__demos__/loop.vue

```vue
<template>
  <c-space direction="column" size="16px">
    <c-progress indeterminate aria-label="Loading" />
    <c-progress mode="circle" indeterminate aria-label="Loading" />
    <c-progress :percent="60" animation />
  </c-space>
</template>
```

### Advanced

- `color`: Overrides the color.

Example source: src/progress/__demos__/advanced.vue

```vue
<script setup>
import { ref } from "vue";

const gradient = ref(false);
</script>
<template>
  <c-space direction="column" size="16px">
    <c-switch v-model="gradient" aria-label="Gradient" />
    <c-progress
      :percent="65"
      :color="gradient ? { '0%': '#722ed1', '100%': '#0fc6c2' } : '#722ed1'"
      buffer-color="#eee5ff"
    />
    <c-space wrap size="24px">
      <c-progress
        mode="circle"
        :percent="65"
        :rotate="90"
        :color="gradient ? { '0%': '#722ed1', '100%': '#0fc6c2' } : '#722ed1'"
      />
      <c-progress mode="circle" :percent="65" :track="false"
        ><template #text="{ percent }"
          >{{ percent }} / 100</template
        ></c-progress
      >
    </c-space>
  </c-space>
</template>
```

## Reading direction

Linear progress grows from reading start and activity motion follows reading direction. Values and circular angles remain unchanged, and reduced-motion settings still apply.

## API

### Props

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| mode | Line or circle | `line \| circle` | `line` |
| percent | Decimal 0–100; numeric strings supported; invalid values become zero, out-of-range values clamp | `number \| string` | `0` |
| size | xs/sm/md/lg/xl or CSS length; line thickness / circle diameter | `ProgressSize` | `md` |
| stroke-width | Overrides thickness, numbers in px | `number \| string` | Follows size |
| steps | Line segments, floored and clamped to 0–1000; ignored when indeterminate | `number` | `0` |
| status | default/primary/secondary/tertiary/info/success/warning/danger; default becomes success at 100 unless indeterminate | `ProgressStatus` | `default` |
| color | Solid or gradient stops; overrides status | `string \| Record<string, string>` | — |
| track-color | Background track color | `string` | — |
| buffer-color | Remaining line track decoration, not a second progress value | `ProgressColor` | — |
| track | Show track and buffer decoration | `boolean` | `true` |
| show-text | Show text; xs circle hides text | `boolean` | `true` |
| text-class | Text container class | `string` | — |
| rotate | Clockwise angle from twelve o'clock | `number` | `0` |
| animation | Determinate continuous line shimmer | `boolean` | `false` |
| indeterminate | Unknown progress; omits aria-valuenow | `boolean` | `false` |

### Size semantics

| size | xs | sm | md | lg | xl |
| --- | --- | --- | --- | --- | --- |
| Linear thickness / default circular stroke in px | 2 | 3 | 4 | 6 | 8 |
| Circular diameter in px | 16 | 48 | 64 | 80 | 96 |

`size=12` / `size="12"` means 12px; `size="2rem"`, `"50%"` and `"calc(100% - 2px)"` retain CSS lengths. Custom linear size controls thickness; custom circular size controls diameter. stroke-width always takes precedence for thickness. Invalid/nonpositive lengths fall back to md. Percentage circular diameters require a definite parent width. All five presets are implemented; xs circular progress hides text. Cedar inherits omitted size from ConfigProvider; Maple defaults to md.

### Slots

| Slot | Arguments | Description |
| --- | --- | --- |
| text | `{ percent: number }` | Takes precedence over default |
| default | `{ percent: number }` | Custom display text |

Indeterminate progress shows an ellipsis by default; use the text slot for business text. The component does not mutate values or emit updates. Provide `aria-label` for the business task. All built-in animations respect reduced-motion settings.

### Type definitions

Exports `ProgressProps`, `ProgressInstance`, `ProgressSize`, `ProgressMode`, `ProgressStatus`, `ProgressColor` and runtime `progressProps`.

## Style variables

| Variable | Default |
| --- | --- |
| `--c-progress-font-size` | `var(--c-sys-font-size-sm)` |
| `--c-progress-text-color` | `var(--c-sys-color-content-secondary)` |
| `--c-progress-track-color` | `var(--c-sys-color-state-hover)` |
| `--c-progress-default-color` | `var(--c-sys-color-content-brand)` |
| `--c-progress-primary-color` | `var(--c-sys-color-content-brand)` |
| `--c-progress-secondary-color` | `var(--c-sys-color-content-secondary)` |
| `--c-progress-tertiary-color` | `var(--c-sys-color-content-tertiary)` |
| `--c-progress-info-color` | `var(--c-sys-color-content-info)` |
| `--c-progress-success-color` | `var(--c-sys-color-content-success)` |
| `--c-progress-warning-color` | `var(--c-sys-color-content-warning)` |
| `--c-progress-danger-color` | `var(--c-sys-color-content-danger)` |
| `--c-progress-line-border-radius` | `9999px` |
| `--c-progress-text-gap` | `var(--c-sys-space-4)` |
| `--c-progress-steps-gap` | `var(--c-sys-space-2)` |
| `--c-progress-transition-duration` | `var(--c-sys-motion-duration-standard)` |
| `--c-progress-animation-duration` | `1.5s` |

Determinate circular success/danger states show completion/failure icons, including xs. The text slot overrides these; ARIA numeric values remain.

---

Document: llms/en-US/components/radio.md

<!-- Source: src/radio/README.en-US.md; locale: en-US; page: /en/components/radio/ -->

# Radio

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Reading direction

Radio groups inherit source dir. Horizontal keys follow visible direction in RTL and skip disabled options; vertical keys and Home/End keep logical order. Radio and button variants retain one Tab entry. Changing direction does not change the selected value.

## Basic examples

### Basic usage

- `disabled`: Prevents user interaction.

Example source: src/radio/__demos__/basic.vue

```vue
<template>
  <c-space wrap size="lg" fill>
    <c-radio value="radio">Radio</c-radio>
    <c-radio value="disabled radio" default-value="disabled radio" disabled>Disabled Radio </c-radio>
    <c-radio-group v-model="type" variant="button">
      <c-radio value="rounded1">Rounded1</c-radio>
      <c-radio value="rounded">Rounded</c-radio>
      <c-radio value="capsule">Capsule</c-radio>
    </c-radio-group>
  </c-space>
</template>

<script lang="ts">
</script>
```

## Groups and layout

### Radio group declarations

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration | Purpose                                                   | Related examples                                       |
| ------------- | --------------------------------------------------------- | ------------------------------------------------------ |
| `value`       | Option `value`                                            | Radio group declarations, Group Direction, Button Type |
| `disabled`    | Disabled state; inherits from the form/group when omitted | Radio group declarations, Grid Layout                  |

<!-- demo-config-notes:end -->

Compare child and options declarations, then select items to inspect the group model.

Example source: src/radio/__demos__/group-declaration-comparison.vue

```vue
<script setup lang="ts">
import { ref } from "vue"
import { proxyRefs as demoProxyRefs } from 'vue'

const scene2 = demoProxyRefs((() => {


    const value1 = ref('plain 1')


    const plainOptions = ['plain 1', 'plain 2', 'plain 3']



    const value2 = ref('1')


    const options = [
      { label: 'option 1', value: '1' },
      { label: 'option 2', value: '2' },
      { label: 'option 3', value: '3', disabled: true },
    ]
return { value1, plainOptions, value2, options }
})())
</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="group">
    <h4><span lang="zh-CN">单选框组</span><span lang="en-US">group</span></h4>
    <c-space direction="column" size="lg">
        <c-radio-group>
          <c-radio value="A">A</c-radio>
          <c-radio value="B">B</c-radio>
          <c-radio value="C">C</c-radio>
          <c-radio value="D">D</c-radio>
        </c-radio-group>
        <c-radio-group>
          <c-radio value="A">A</c-radio>
          <c-radio value="B">B</c-radio>
          <c-radio value="C">C</c-radio>
          <c-radio value="D" disabled>D</c-radio>
        </c-radio-group>
      </c-space>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="group-options">
    <h4><span lang="zh-CN">单选框组选项</span><span lang="en-US">group options</span></h4>
    <c-space direction="column" size="lg">
        <c-radio-group v-model="scene2.value1" :options="scene2.plainOptions" />
        <c-radio-group v-model="scene2.value2" :options="scene2.options" />
        <c-radio-group v-model="scene2.value2" :options="scene2.options">
          <template #label="{ data }">
            <c-tag>{{ data.label }}</c-tag>
          </template>
        </c-radio-group>
      </c-space>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

### Group Direction

Preview configuration: `orientation="vertical"`, `value="A"`, `value="B"`, `value="C"`.

Example source: src/radio/__demos__/group-direction.vue

```vue
<template>
  <c-radio-group orientation="vertical">
    <c-radio value="A">A</c-radio>
    <c-radio value="B">B</c-radio>
    <c-radio value="C">C</c-radio>
    <c-radio value="D">D</c-radio>
  </c-radio-group>
</template>
<script lang="ts">
</script>
```

### Button Type

Preview configuration: `variant="button"`, `value="Beijing"`, `value="Shanghai"`, `value="Guangzhou"`.

Example source: src/radio/__demos__/button-type.vue

```vue
<template>
  <c-radio-group variant="button">
    <c-radio value="Beijing">Beijing</c-radio>
    <c-radio value="Shanghai">Shanghai</c-radio>
    <c-radio value="Guangzhou">Guangzhou</c-radio>
    <c-radio value="Shenzhen">Shenzhen</c-radio>
  </c-radio-group>
</template>
<script lang="ts">
</script>
```

### Grid Layout

- `disabled`: Prevents user interaction.

Example source: src/radio/__demos__/grid-layout.vue

```vue
<template>
  <c-radio-group v-model="checkedValue">
    <c-grid :cols="3" :colGap="24" :rowGap="16">
      <c-grid-item>
        <c-radio value="1">Option 1</c-radio>
      </c-grid-item>
      <c-grid-item>
        <c-radio value="2" disabled>Option 2</c-radio>
      </c-grid-item>
      <c-grid-item>
        <c-radio value="3">Option 3</c-radio>
      </c-grid-item>
      <c-grid-item>
        <c-radio value="4">Option 4</c-radio>
      </c-grid-item>
      <c-grid-item>
        <c-radio value="5">Option 5</c-radio>
      </c-grid-item>
    </c-grid>
  </c-radio-group>
</template>

<script lang="ts">
import { ref } from 'vue'

export default {
  setup() {
    const checkedValue = ref('1')

    return {
      checkedValue,
    }
  },
}
</script>
```

### Group State

Preview configuration: `:default-value="'a'"`, `:options="options"`, `:readonly="readonly"`, `:model-value="''"`.

Example source: src/radio/__demos__/group-state.vue

```vue
<script setup>
import { ref } from 'vue'

const accepted = ref('a')
const proposed = ref('')
const readonly = ref(false)
const options = [{ label: '设备 A', value: 'a' }, { label: '设备 B', value: 'b' }]
</script>

<template>
  <c-space direction="column">
    <div>
      <p>非受控：default-value 只用于初始值</p>
      <c-radio-group :default-value="'a'" :options="options" />
    </div>
    <div>
      <p>受控：父级接受更新 {{ accepted }}</p>
      <c-radio-group v-model="accepted" :options="options" :readonly="readonly" />
      <c-button size="sm" @click="readonly = !readonly">{{ readonly ? '解除只读' : '设为只读' }}</c-button>
    </div>
    <div>
      <p>父级拒绝更新：仅记录提议 {{ proposed }}</p>
      <c-radio-group :model-value="''" :options="options" @update:model-value="proposed = $event" />
    </div>
  </c-space>
</template>
```

### Button Sizes

Preview configuration: `variant="button"`, `:size="size"`, `default-value="week"`, `:options="options"`.

Example source: src/radio/__demos__/button-sizes.vue

```vue
<script setup lang="ts">
const sizes = ['xs', 'sm', 'md', 'lg', 'xl'] as const
const options = [
  { label: '日', value: 'day' },
  { label: '周', value: 'week' },
  { label: '月', value: 'month' },
]
</script>
<template>
  <section class="radio-demo">
    <div v-for="size in sizes" :key="size">
      <p>{{ size }}</p>
      <c-radio-group variant="button" :size="size" default-value="week" :options="options" :aria-label="size" />
    </div>
    <p>纵向与只读</p>
    <c-radio-group variant="button" orientation="vertical" readonly default-value="day" :options="options" aria-label="只读周期" />
  </section>
</template>
<style scoped>
.radio-demo { display: flex; flex-direction: column; align-items: flex-start; gap: 12px; }
.radio-demo p { margin: 0 0 8px; }
</style>
```

## Options and value model

### Control Value

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration   | Purpose                                                   | Related examples          |
| --------------- | --------------------------------------------------------- | ------------------------- |
| `default-value` | Initial uncontrolled value                                | Control Value, Controlled |
| `value`         | Option `value`                                            | Control Value             |
| `readonly`      | Readonly state; inherits from the form/group when omitted | Control Value             |
| `disabled`      | Disabled state; inherits from the form/group when omitted | Control Value             |

<!-- demo-config-notes:end -->

- `readonly`: Displays the current value without allowing edits.
- `disabled`: Prevents user interaction.

Example source: src/radio/__demos__/control-value.vue

```vue
<script setup>
import { ref } from 'vue'
const control = ref()
const value = ref(null)

</script>
<template>
  <c-space direction="column">
    <p>null 表示未选中；重复选择不会取消。 当前值：{{ value }}</p>
    <c-radio ref="control" v-model="value" :value="false">选择 false 选项</c-radio>
    <c-space wrap>
      <c-button size="sm" @click="control?.select()">选中</c-button>
      <c-button size="sm" @click="control?.focus()">聚焦</c-button>
      <c-button size="sm" @click="value = null">重置</c-button>
    </c-space>
    
    <p>只读允许聚焦，禁用不允许操作；Enter/空格只影响当前控件。</p>
    <c-radio :default-value="true" readonly>只读</c-radio>
    <c-radio :default-value="true" disabled>禁用</c-radio>
  </c-space>
</template>
```

### Option Data

Preview configuration: `:options="options"`, `:field-names="fields"`, `orientation="vertical"`, `:options="renderOptions"`.

Example source: src/radio/__demos__/option-data.vue

```vue
<script setup lang="ts">
import { h, ref } from 'vue'

const value = ref<string | number | boolean | null>(null)
const fields = { value: 'id', label: 'name', disabled: 'unavailable', readonly: 'locked' }
const options = ref([
  { id: false, name: '布尔 false' },
  { id: 0, name: '数字 0' },
  { id: '', name: '空字符串' },
  { id: 'locked', name: '只读选项', locked: true },
  { id: 'disabled', name: '禁用选项', unavailable: true },
])
const renderOptions = [
  { value: 'render', label: (_data: unknown, checked: boolean) => h('strong', checked ? '已选择' : '渲染函数标签') },
]
</script>

<template>
  <section class="option-demo">
    <p>字段映射与标签插槽；只读可聚焦，禁用不可操作。</p>
    <c-radio-group v-model="value" :options="options" :field-names="fields" orientation="vertical">
      <template #label="{ data, checked }">{{ data.label }} {{ checked ? '✓' : '' }}</template>
    </c-radio-group>
    <p>当前值：{{ JSON.stringify(value) }}</p>
    <c-button @click="value = null">清空</c-button>
    <p>标签也支持渲染函数；不传 options 时使用默认插槽，传入 [] 时保持空组。</p>
    <c-radio-group :options="renderOptions" />
  </section>
</template>

<style scoped>
.option-demo { display: flex; flex-direction: column; gap: 12px; }
.option-demo p { margin: 0; }
</style>
```

### Controlled

Preview configuration: `:model-value="true"`, `:model-value="checked2"`, `:default-value="true"`.

Example source: src/radio/__demos__/controlled.vue

```vue
<template>
  <c-space wrap size="lg">
    <c-radio v-model="checked1">v-model</c-radio>
    <c-radio :model-value="true">binding "true"</c-radio>
    <c-radio :model-value="checked2">binding value2</c-radio>
    <c-radio :default-value="true">uncontrolled state</c-radio>
  </c-space>
  <div :style="{ marginTop: '20px' }">
    <c-space wrap size="lg">
      <c-button status="primary" @click="handleSetCheck"> {{ checked2 ? 'uncheck' : 'check' }} value2 </c-button>
      <c-button @click="handleReset"> reset all</c-button>
    </c-space>
  </div>
</template>

<script lang="ts">
import { ref } from 'vue'

export default {
  setup() {
    const checked1 = ref(false)
    const checked2 = ref(false)

    const handleSetCheck = () => {
      checked2.value = !checked2.value
    }

    const handleReset = () => {
      checked1.value = false
      checked2.value = false
    }

    return {
      checked1,
      checked2,
      handleSetCheck,
      handleReset,
    }
  },
}
</script>
```

## Interaction and keyboard

### State Lab

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration | Purpose                                                   | Related examples |
| ------------- | --------------------------------------------------------- | ---------------- |
| `value`       | Option `value`                                            | State Lab        |
| `disabled`    | Disabled state; inherits from the form/group when omitted | State Lab        |
| `readonly`    | Readonly state; inherits from the form/group when omitted | State Lab        |
| `error`       | Error state; inherits from the form/group when omitted    | State Lab        |

<!-- demo-config-notes:end -->

Preview configuration: `value="design"`.

Example source: src/radio/__demos__/state-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref("design");
const __demoState = __demoReactive({
  disabled: false,
  readonly: false,
  error: false,
});
</script>
<template>
  <c-space direction="column" :size="16">
    <c-space wrap>
      <c-checkbox v-model="__demoState['disabled']">disabled</c-checkbox>
      <c-checkbox v-model="__demoState['readonly']">readonly</c-checkbox>
      <c-checkbox v-model="__demoState['error']">error</c-checkbox>
    </c-space>
    <c-radio v-model="value" value="design" v-bind="__demoState">设计</c-radio>
  </c-space>
</template>
```

### Keyboard Navigation

Preview configuration: `:options="options"`, `aria-label="通知方式"`.

Example source: src/radio/__demos__/keyboard-navigation.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const value = ref<string | number | boolean | null>('email')
const options = [
  { label: '邮件', value: 'email' },
  { label: '只读', value: 'locked', readonly: true },
  { label: '禁用', value: 'disabled', disabled: true },
  { label: '短信', value: 'sms' },
]
</script>
<template>
  <section class="radio-demo">
    <p>Tab 进入分组；方向键循环，Home / End 跳到首尾。只读项可聚焦，不改变选值。</p>
    <c-radio-group v-model="value" :options="options" aria-label="通知方式" />
    <p>当前值：{{ value }}</p>
    <c-button @click="value = null">清空</c-button>
  </section>
</template>
<style scoped>
.radio-demo { display: flex; flex-direction: column; gap: 12px; }
.radio-demo p { margin: 0; }
</style>
```

## Control and content customization

### Native Control

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration | Purpose                                                   | Related examples             |
| ------------- | --------------------------------------------------------- | ---------------------------- |
| `value`       | Option `value`                                            | Native Control, Custom Radio |
| `readonly`    | Readonly state; inherits from the form/group when omitted | Native Control               |

<!-- demo-config-notes:end -->

- `readonly`: Displays the current value without allowing edits.

Example source: src/radio/__demos__/native-control.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const value = ref<string | number | boolean | null>('email')
</script>
<template>
  <section class="native-radio-demo">
    <p>图标与原生 input 属性</p>
    <c-radio-group v-model="value" name="channel" aria-label="通知方式">
      <c-radio value="email" :icon-size="24" checked-color="rebeccapurple" :input-attrs="{ id: 'radio-email' }">
        <template #checked-icon><span aria-hidden="true">●</span></template>
        <template #unchecked-icon><span aria-hidden="true">○</span></template>
        邮件
      </c-radio>
      <c-radio value="sms">短信</c-radio>
      <c-radio value="readonly" readonly>只读</c-radio>
    </c-radio-group>
    <p>当前值：{{ value }}</p>
  </section>
</template>
<style scoped>
.native-radio-demo { display: flex; flex-direction: column; gap: 12px; }
.native-radio-demo p { margin: 0; }
</style>
```

### Custom Radio

Preview configuration: `default-value="1"`, `value="1"`, `:model-value="checked"`, `checkable`.

Example source: src/radio/__demos__/custom-radio.vue

```vue
<template>
  <c-radio-group default-value="1">
    <c-radio value="1">
      <template #radio="{ checked }">
        <c-tag :model-value="checked" checkable>This is a tag radio 1</c-tag>
      </template>
    </c-radio>
    <c-radio value="2">
      <template #radio="{ checked }">
        <c-tag :model-value="checked" checkable>This is a tag radio 2</c-tag>
      </template>
    </c-radio>
    <c-radio value="3">
      <template #radio="{ checked }">
        <c-tag :model-value="checked" checkable>This is a tag radio 3</c-tag>
      </template>
    </c-radio>
  </c-radio-group>

  <div :style="{ marginTop: '20px' }">
    <c-radio-group>
      <template v-for="item in 2" :key="item">
        <c-radio :value="item">
          <template #radio="{ checked }">
            <c-space wrap align="flex-start" class="custom-radio-card" :class="{ 'custom-radio-card-checked': checked }">
              <div class="custom-radio-card-mask">
                <div class="custom-radio-card-mask-dot" />
              </div>
              <div>
                <div class="custom-radio-card-title">radio Card {{ item }}</div>
                <div>this is a text</div>
              </div>
            </c-space>
          </template>
        </c-radio>
      </template>
    </c-radio-group>
  </div>
</template>

<script lang="ts">
</script>
<style scoped>
.custom-radio-card {
  padding: 10px 16px;
  border: 1px solid var(--color-border-2);
  border-radius: 4px;
  width: 250px;
  box-sizing: border-box;
}

.custom-radio-card-mask {
  height: 14px;
  width: 14px;
  display: inline-flex;
  align-items: center;
  justify-content: center;
  border-radius: 100%;
  border: 1px solid var(--color-border-2);
  box-sizing: border-box;
}

.custom-radio-card-mask-dot {
  width: 8px;
  height: 8px;
  border-radius: 100%;
}

.custom-radio-card-title {
  color: var(--color-text-1);
  font-size: 14px;
  font-weight: bold;
  margin-bottom: 8px;
}

.custom-radio-card:hover,
.custom-radio-card-checked,
.custom-radio-card:hover .custom-radio-card-mask,
.custom-radio-card-checked .custom-radio-card-mask {
  border-color: rgb(var(--primary-6));
}

.custom-radio-card-checked {
  background-color: var(--color-primary-light-1);
}

.custom-radio-card:hover .custom-radio-card-title,
.custom-radio-card-checked .custom-radio-card-title {
  color: rgb(var(--primary-6));
}

.custom-radio-card-checked .custom-radio-card-mask-dot {
  background-color: rgb(var(--primary-6));
}
</style>
```

## Async options

### Async Options

Preview configuration: `edit-mode="direct"`, `:options="options"`.

Example source: src/radio/__demos__/async-options.vue

```vue
<script setup>
import { onDeactivated, onUnmounted, ref, shallowRef } from "vue";

const value = ref("remote");
const options = ref([]);
const loading = ref(false);
const changeCount = ref(0);
let pendingTimer;
const manual = ref(false);
const waiting = shallowRef([]);
const applied = ref(0);
const ignored = ref(0);
let version = 0;
let sequence = 0;

function cancelPending() {
  version++;
  if (pendingTimer !== undefined) {
    clearTimeout(pendingTimer);
  }
  pendingTimer = undefined;
  loading.value = false;
}

function load() {
  cancelPending();
  loading.value = true;
  const ticket = version;
  const id = ++sequence;
  const complete = () => {
    if (ticket !== version) {
      ignored.value++;
      return;
    }
    applied.value = id;
    options.value = [
      { label: "异步设备", value: "remote" },
      { label: "设备 A", value: "a" },
      { label: "停用设备", value: "locked", disabled: true },
    ];
    pendingTimer = undefined;
    loading.value = false;
  };
  if (manual.value) {
    new Promise((resolve) => {
      waiting.value = [...waiting.value, { id, resolve }];
    }).then(complete);
  } else {
    pendingTimer = setTimeout(complete, 800);
  }
}

function settle(latest) {
  const jobs = [...waiting.value];
  const job = latest ? jobs.pop() : jobs.shift();
  waiting.value = jobs;
  job?.resolve();
}

function cleanup() {
  cancelPending();
  const jobs = waiting.value;
  waiting.value = [];
  jobs.forEach((job) => job.resolve());
}

function remove() {
  cancelPending();
  options.value = [];
}

onDeactivated(cleanup);
onUnmounted(cleanup);
</script>

<template>
  <c-space class="radio-async-demo" direction="column">
    <p>业务值独立于当前选项，加载或移除选项不会清空已选值：{{ value }}</p>
    <c-checkbox v-model="manual" edit-mode="direct" @change="remove"
      >Manual responses / 手动返回</c-checkbox
    >
    <c-space wrap>
      <c-button size="sm" @click="load">加载选项</c-button>
      <c-button size="sm" @click="remove">移除选项</c-button>
      <c-button size="sm" @click="value = 'a'">设为设备 A</c-button>
      <c-button size="sm" @click="value = null">清空选择</c-button>
      <c-button
        size="sm"
        :disabled="waiting.length === 0"
        @click="settle(false)"
        >返回最早加载</c-button
      >
      <c-button size="sm" :disabled="waiting.length === 0" @click="settle(true)"
        >返回最新加载</c-button
      >
    </c-space>
    <p aria-live="polite">
      {{
        loading
          ? "加载中，可在完成前移除选项以取消本次加载。"
          : "加载完成后保留当前选值和键盘焦点。"
      }}
    </p>
    <c-radio-group
      v-model="value"
      edit-mode="direct"
      :options="options"
      @change="changeCount++"
    />
    <p>用户变更次数：{{ changeCount }}</p>
    <p role="status">
      Applied: {{ applied }} · Ignored: {{ ignored }} · Pending:
      {{ waiting.length }}
    </p>
  </c-space>
</template>
```

## API

### Empty values and reading placeholders

`empty-values` recognizes empty data; `empty-value` keeps existing clear output. `empty-text` defaults to `'-'` under `read-pretty`, with Field > FormItem > Form precedence and custom read slots first. With explicit empty-values, built-in required uses the policy; custom validators receive original data. See the [shared guide](llms/en-US/guide/empty-values.md).

| Prop         | Type               | Default and scope                                                           |
| ------------ | ------------------ | --------------------------------------------------------------------------- |
| empty-values | readonly unknown[] | Field > FormItem > Form > component-family default; replaces the whole list |
| empty-text   | string             | Field > FormItem > Form > '-'; explicit '' is valid                         |

These props belong to field presentation; pure panels do not gain reading mode. Form and FormItem provide inherited settings. The existing empty-value type and clear fallback remain component-specific.

`ChoiceValue = string | number | boolean`；`CheckboxModel = boolean | ChoiceValue[]`；`RadioModel = ChoiceValue | null`。

### Radio Props

| Prop                  | Description                                               | Type                      | Default   |
| --------------------- | --------------------------------------------------------- | ------------------------- | --------- |
| model-value (v-model) | Controlled value                                          | ChoiceValue \| null       | undefined |
| default-value         | Initial uncontrolled value                                | ChoiceValue \| null       | null      |
| value                 | Option `value`                                            | `string\|number\|boolean` | `true`    |
| variant               | Radio variant                                             | `'radio'\|'button'`       | `'radio'` |
| disabled              | Disabled state; inherits from the form/group when omitted | boolean                   | undefined |
| readonly              | Readonly state; inherits from the form/group when omitted | boolean                   | undefined |
| error                 | Error state; inherits from the form/group when omitted    | boolean                   | undefined |

### Radio Events

| Event              | Description          | Arguments                         |
| ------------------ | -------------------- | --------------------------------- |
| update:model-value | Proposes a new value | value: ChoiceValue                |
| change             | Value change         | value: ChoiceValue, event?: Event |
| focus              | Focus                | event: FocusEvent                 |
| blur               | Blur                 | event: FocusEvent                 |

### Radio Methods

| Method | Arguments              | Returns |
| ------ | ---------------------- | ------- |
| select | -                      | void    |
| focus  | options?: FocusOptions | void    |
| blur   | -                      | void    |

### Radio Slots

| Slot  | Description          | Arguments                                |
| ----- | -------------------- | ---------------------------------------- |
| radio | Custom radio control | `checked:boolean`<br/>`disabled:boolean` |

### RadioGroup Props

| Prop                  | Description                                                                                            | Type                                                                                                    | Default        |
| --------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- | -------------- |
| model-value (v-model) | Controlled value                                                                                       | RadioModel                                                                                              | undefined      |
| default-value         | Initial uncontrolled value                                                                             | RadioModel                                                                                              | null           |
| variant               | Radio-group variant                                                                                    | `'radio'\|'button'`                                                                                     | `'radio'`      |
| size                  | Radio-group size                                                                                       | `'xs'\|'sm'\|'md'\|'lg'\|'xl'`                                                                          | `-`            |
| options               | Options; replaces default slot when supplied                                                           | Array<ChoiceValue \| RadioOption \| Record<string, unknown>> / `(query, { signal }) => Array / Promise` | `undefined`    |
| orientation           | Horizontal/vertical arrangement of radio-group options, default horizontal; not text reading direction | `'horizontal'\|'vertical'`                                                                              | `'horizontal'` |
| disabled              | Disabled state; inherits from the form/group when omitted                                              | boolean                                                                                                 | undefined      |
| readonly              | Readonly state; inherits from the form/group when omitted                                              | boolean                                                                                                 | undefined      |
| error                 | Error state; inherits from the form/group when omitted                                                 | boolean                                                                                                 | undefined      |
| field-names           | Option field mapping                                                                                   | ChoiceFieldNames                                                                                        | undefined      |
| aria-label            | Accessible group name                                                                                  | string                                                                                                  | ''             |

### RadioGroup Events

| Event              | Description                          | Arguments                                      |
| ------------------ | ------------------------------------ | ---------------------------------------------- |
| update:model-value | Proposes a new value                 | value: string \| number \| boolean             |
| change             | Value change; notified once by Group | value: string \| number \| boolean, ev?: Event |

### RadioGroup Slots

| Slot  | Description          | Arguments                                |
| ----- | -------------------- | ---------------------------------------- |
| radio | Custom radio control | `checked:boolean`<br/>`disabled:boolean` |
| label | Radio label content  | `data: RadioOption, checked: boolean`    |

### RadioOption

| Field    | Description              | Type                                                              |
| -------- | ------------------------ | ----------------------------------------------------------------- |
| value    | Option identity          | ChoiceValue                                                       |
| label    | Label or render function | VNodeChild \| (data: RadioOption, checked: boolean) => VNodeChild |
| disabled | Disable interaction      | boolean                                                           |
| readonly | Read-only interaction    | boolean                                                           |

## Type definitions

The component exports the following types

```ts
import type { RadioProps } from "@cedar-design/ui";
```

### ChoiceFieldNames

`{ label?: string; value?: string; disabled?: string; readonly?: string; indeterminate?: string }`

Exported types：`RadioOption`、`ChoiceFieldNames`。

### Native attributes and appearance

| Component          | Prop                            | Description                                                       | Type                | Default   |
| ------------------ | ------------------------------- | ----------------------------------------------------------------- | ------------------- | --------- |
| Radio / RadioGroup | name                            | Native field name; child overrides group                          | string              | undefined |
| Radio              | aria-label                      | Native control accessible name                                    | string              | undefined |
| Radio              | input-attrs                     | Native input attributes                                           | InputHTMLAttributes | undefined |
| Radio              | checked-color / unchecked-color | Instance checked/unchecked colors; error/disabled take precedence | string              | undefined |
| Radio              | icon-size                       | Icon dimension; numbers are px, strings are CSS lengths           | number \| string    | undefined |
| Radio              | ripple                          | Touch ripple feedback                                             | boolean             | true      |

### Icons and default slot

checked-icon and unchecked-icon are supported on both platforms. default and radio slots receive { checked, disabled }. click emits the original MouseEvent once. Disabled emits no click; readonly may emit click without changing the value.

### Form field presentation and confirmation

This component supports `edit-mode` with field > FormItem > Form precedence. When unset, it defaults to `direct` and preserves `direct` editing. Supported values: `direct / click / dblclick`. Non-`direct` modes open the editor through the field value trigger and keep one draft; v-model updates only after confirmation. Cancel, reset or enabling readPretty discards the draft.

Cedar uses edit-mode="click" / "dblclick" to open an editor popup near the field. Enter/F2 also opens it; cancel/Escape discards the draft, and confirmation commits it. readPretty is an independent reading setting, separate from readonly and disabled.

`before-commit(value, { previousValue, signal })` can reject an overlay save. FormItem validates the candidate first and keeps the editor open on failure. `open / default-open / update:open` control the editor. Use `#read="{ value, text }"` to customize display. See the full field comparison in Form.

`read-pretty` is an independent boolean alongside `readonly` and `disabled`. It inherits from field to FormItem to Form; explicit `false` overrides the parent. The default is `false`. Reading mode renders no editor.

`empty-value` accepts explicit `null` (or `() => null`). Clearing publishes `null` unchanged; omitted values preserve the existing default. Editors render `null` as blank without converting ordinary empty-string input to `null`. In popup editing, clearing changes the draft; confirm commits it and cancel preserves the original model.

The `options` prop accepts an array or `(query, { signal }) => array/Promise`. The component manages loading, cancellation and stale-result isolation; failures emit load-error. Single/multiple groups initialize with an empty-string query, searchable fields reload when the query changes, and root loading for tree fields remains independent of existing load-more child loading.

---

Document: llms/en-US/components/rate.md

<!-- Source: src/rate/README.en-US.md; locale: en-US; page: /en/components/rate/ -->

# Rate

Keyboard and pointer rating selection.

## Basic examples

### Basic usage

Example source: src/rate/__demos__/basic.vue

```vue
<template>
  <c-rate  />
</template>

<script lang="ts" setup>
</script>
```

## Appearance and states

### Readonly

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration   | Purpose                                                        | Related examples |
| --------------- | -------------------------------------------------------------- | ---------------- |
| `default-value` | Initial uncontrolled value; subsequent changes do not reset it | Readonly         |
| `readonly`      | Focusable but not editable; inherits Form when omitted         | Readonly         |
| `color`         | Active color or increasing per-icon threshold color map        | Color            |

<!-- demo-config-notes:end -->

- `readonly`: Displays the current value without allowing edits.

Example source: src/rate/__demos__/readonly.vue

```vue
<template>
  <c-rate :default-value="4" readonly />
</template>

<script lang="ts" setup>
</script>
```

### Color

- `color`: Overrides the color.

Example source: src/rate/__demos__/color.vue

```vue
<template>
  <c-space direction="column">
    <c-rate color="red" />
    <c-rate :color="color" />
  </c-space>
</template>

<script lang="ts" setup>
const color = {
  2: 'red',
  4: 'green',
  5: 'blue',
}
</script>
```

## Content and presentation

### Sizes And Symbols

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration   | Purpose                                                           | Related examples                                   |
| --------------- | ----------------------------------------------------------------- | -------------------------------------------------- |
| `default-value` | Initial uncontrolled value; subsequent changes do not reset it    | Sizes And Symbols, Half, Rating count and clearing |
| `allow-half`    | Enable half-point steps                                           | Sizes And Symbols, Half                            |
| `grading`       | Fixed five-face rating; overrides slots and icon props            | Sizes And Symbols, Grading                         |
| `size`          | Icon dimension: number/numeric string in px, otherwise CSS length | Sizes And Symbols                                  |
| `aria-label`    | Accessible business label                                         | Sizes And Symbols                                  |
| `gap`           | Icon spacing: number/numeric string in px, otherwise CSS length   | Sizes And Symbols                                  |

<!-- demo-config-notes:end -->

- `size`: Controls the component size.

Example source: src/rate/__demos__/sizes-and-symbols.vue

```vue
<template>
  <c-space direction="column">
    <c-rate :default-value="3" :size="20" aria-label="20 像素评分" />
    <c-rate :default-value="3.5" size="2rem" gap="0.5rem" allow-half aria-label="自定义尺寸评分" />
    <c-rate :default-value="4" grading aria-label="表情评分" />
    <c-rate :default-value="3" aria-label="自定义字符评分">
      <template #character="{ value, active }"><span>{{ active ? '♥' : '♡' }}{{ value }}</span></template>
    </c-rate>
  </c-space>
</template>
```

### Half

Example source: src/rate/__demos__/half.vue

```vue
<template>
  <c-rate :default-value="2.5" allow-half />
</template>

<script lang="ts" setup>
</script>
```

### Rating count and clearing

Compare rating totals and clearing the current selection, separately from half steps, keyboards and controlled values.

Example source: src/rate/__demos__/value-rules-comparison.vue

```vue
<script setup lang="ts">


</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="clear">
    <h4><span lang="zh-CN">支持清除</span><span lang="en-US">clear</span></h4>
    <c-rate :default-value="3" clearable />
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="count">
    <h4><span lang="zh-CN">任意长度的评分</span><span lang="en-US">count</span></h4>
    <c-rate :count="10" />
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

### Grading

Example source: src/rate/__demos__/grading.vue

```vue
<template>
  <c-rate grading />
</template>

<script lang="ts" setup>
</script>
```

## Customization and slots

### Character

Example source: src/rate/__demos__/character.vue

```vue
<template>
  <c-rate :default-value="2">
    <template #character="index">
      <c-icon-check v-if="index < 3" />
      <c-icon-close v-else />
    </template>
  </c-rate>
</template>

<script lang="ts" setup>
</script>
```

## Interaction and control

### State Lab

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration   | Purpose                                                                  | Related examples    |
| --------------- | ------------------------------------------------------------------------ | ------------------- |
| `disabled`      | Disable interaction; inherits Form when omitted                          | State Lab, Keyboard |
| `readonly`      | Focusable but not editable; inherits Form when omitted                   | State Lab, Keyboard |
| `allow-half`    | Enable half-point steps                                                  | Keyboard            |
| `clearable`     | Click the current score again to clear; keyboard boundaries do not clear | Keyboard            |
| `aria-label`    | Accessible business label                                                | Keyboard            |
| `default-value` | Initial uncontrolled value; subsequent changes do not reset it           | Keyboard            |

<!-- demo-config-notes:end -->

Example source: src/rate/__demos__/state-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref(3);
const __demoState = __demoReactive({ disabled: false, readonly: false });
</script>
<template>
  <c-space direction="column" :size="16">
    <c-space wrap>
      <c-checkbox v-model="__demoState['disabled']">disabled</c-checkbox>
      <c-checkbox v-model="__demoState['readonly']">readonly</c-checkbox>
    </c-space>
    <c-rate v-model="value" v-bind="__demoState"></c-rate>
  </c-space>
</template>
```

### Keyboard

- `readonly`: Displays the current value without allowing edits.
- `disabled`: Prevents user interaction.

Example source: src/rate/__demos__/keyboard.vue

```vue
<script setup>
import { ref } from 'vue'
const score = ref(2.5)
</script>

<template>
  <c-space direction="column">
    <p>Tab 聚焦；方向键按半分调整；Home 清零，End 满分。重复点击当前分数可清空。</p>
    <c-rate v-model="score" allow-half clearable aria-label="服务评分" />
    <span>当前评分：{{ score }}</span>
    <c-rate :default-value="3" readonly aria-label="只读评分" />
    <c-rate :default-value="3" disabled aria-label="禁用评分" />
  </c-space>
</template>
```

## API

### Empty values and reading placeholders

`empty-values` recognizes empty data; `empty-value` keeps existing clear output. `empty-text` defaults to `'-'` under `read-pretty`, with Field > FormItem > Form precedence and custom read slots first. With explicit empty-values, built-in required uses the policy; custom validators receive original data. See the [shared guide](llms/en-US/guide/empty-values.md).

| Prop         | Type               | Default and scope                                                           |
| ------------ | ------------------ | --------------------------------------------------------------------------- |
| empty-values | readonly unknown[] | Field > FormItem > Form > component-family default; replaces the whole list |
| empty-text   | string             | Field > FormItem > Form > '-'; explicit '' is valid                         |

These props belong to field presentation; pure panels do not gain reading mode. Form and FormItem provide inherited settings. The existing empty-value type and clear fallback remain component-specific.

### Props

| Prop           | Description                                                              | Type                             | Default       |
| -------------- | ------------------------------------------------------------------------ | -------------------------------- | ------------- |
| model-value    | Controlled value, including zero; external updates emit no events        | number                           | undefined     |
| default-value  | Initial uncontrolled value; subsequent changes do not reset it           | number                           | 0             |
| count          | Positive finite number, rounded down; invalid values fall back to 5      | number \| string                 | 5             |
| allow-half     | Enable half-point steps                                                  | boolean                          | false         |
| clearable      | Click the current score again to clear; keyboard boundaries do not clear | boolean                          | false         |
| grading        | Fixed five-face rating; overrides slots and icon props                   | boolean                          | false         |
| disabled       | Disable interaction; inherits Form when omitted                          | boolean                          | undefined     |
| readonly       | Focusable but not editable; inherits Form when omitted                   | boolean                          | undefined     |
| aria-label     | Accessible business label                                                | string                           | undefined     |
| size           | Icon dimension: number/numeric string in px, otherwise CSS length        | number \| string                 | Style default |
| gap            | Icon spacing: number/numeric string in px, otherwise CSS length          | number \| string                 | Style default |
| color          | Active color or increasing per-icon threshold color map                  | string \| Record<string, string> | undefined     |
| empty-color    | Inactive color                                                           | string                           | undefined     |
| disabled-color | Disabled color, overriding active/inactive colors                        | string                           | undefined     |
| icon           | Checked icon                                                             | string \| Component              | Filled star   |
| half-icon      | Half icon                                                                | string \| Component              | Half star     |
| empty-icon     | Unchecked icon                                                           | string \| Component              | Empty star    |
| ripple         | Click ripple                                                             | boolean                          | true          |

size/gap do not accept xs/sm/md/lg/xl presets. Omitted, invalid or nonpositive values retain style defaults. CSS var/calc/min/max/clamp lengths are supported. Ratings normalize to 0–count in steps of 1 or 0.5. Nonfinite ratings display 0 without rewriting the external value.

### Events

| Event              | Arguments     | Description                                                   |
| ------------------ | ------------- | ------------------------------------------------------------- |
| update:model-value | value: number | User produces a new value                                     |
| change             | value: number | Confirmed new value; no duplicate for equal values            |
| hover-change       | value: number | Hover preview; resets to zero on leave/blur/disabled/readonly |

### Slots

| Slot      | Arguments                | Description                                                   |
| --------- | ------------------------ | ------------------------------------------------------------- |
| character | { index, value, active } | index starts at 0; value starts at 1. Replaces rating symbols |

Precedence: grading > character > icon/half-icon/empty-icon > default icon. String icons require global registration; component values do not.

### Methods

focus() focuses the rating; blur() removes focus. Readonly remains focusable, while disabled leaves the Tab sequence. Arrow keys adjust, Home clears and End selects the maximum. Keyboard events from interactive children and Alt/Ctrl/Meta combinations are not intercepted. Touch and mouse share half-selection/clearing rules.

### Type definitions

Exports RateProps, RateColor, RateIcon, RateInstance, RateExpose, RateEmits and RateCharacterSlotProps.

### Style variables

| Token                                 | Default                                        |
| ------------------------------------- | ---------------------------------------------- |
| `--c-rate-disabled-color`             | `var(--c-sys-color-content-disabled)`          |
| `--c-rate-error-color`                | `var(--c-sys-color-content-danger)`            |
| `--c-rate-active-scale`               | `1.2`                                          |
| `--c-rate-focus-color`                | `var(--c-sys-color-content-brand)`             |
| `--c-rate-focus-width`                | `2px`                                          |
| `--c-rate-focus-offset`               | `2px`                                          |
| `--c-rate-size`                       | `var(--c-font-size-title-3)`                   |
| `--c-rate-gap`                        | `var(--c-spacing-4)`                           |
| `--c-rate-min-height`                 | `var(--c-size-md)`                             |
| `--c-rate-action-padding`             | `0px`                                          |
| `--c-rate-empty-color`                | `var(--c-color-fill-3)`                        |
| `--c-rate-active-color`               | `rgb(var(--c-gold-6))`                         |
| `--c-rate-transition-duration`        | `var(--c-transition-duration-2)`               |
| `--c-rate-scale-duration`             | `var(--c-transition-duration-4)`               |
| `--c-rate-transition-timing-function` | `var(--c-transition-timing-function-standard)` |

Public token suffixes/meanings match across platforms. Cedar retains gold stars and compact spacing; Maple retains primary-color stars and touch padding. Defaults are recorded in the theme contract. Sources are maintained independently without a shared runtime.

`transition-duration` controls hover/color transitions, `scale-duration` controls selection animation, and `transition-timing-function` controls easing. Reduced motion disables these animations. `size` and `gap` props override the corresponding tokens for a single instance.

### Form field presentation and confirmation

This component supports `edit-mode` with field > FormItem > Form precedence. When unset, it defaults to `direct` and preserves `direct` editing. Supported values: `direct / click / dblclick`. Non-`direct` modes open the editor through the field value trigger and keep one draft; v-model updates only after confirmation. Cancel, reset or enabling readPretty discards the draft.

Cedar uses edit-mode="click" / "dblclick" to open an editor popup near the field. Enter/F2 also opens it; cancel/Escape discards the draft, and confirmation commits it. readPretty is an independent reading setting, separate from readonly and disabled.

`before-commit(value, { previousValue, signal })` can reject an overlay save. FormItem validates the candidate first and keeps the editor open on failure. `open / default-open / update:open` control the editor. Use `#read="{ value, text }"` to customize display. See the full field comparison in Form.

`read-pretty` is an independent boolean alongside `readonly` and `disabled`. It inherits from field to FormItem to Form; explicit `false` overrides the parent. The default is `false`. Reading mode renders no editor.

## Configuring the cleared value

`empty-value` / `emptyValue` sets the model value produced by clearing. It accepts a value in the component model type or a zero-argument factory. Omission preserves the existing default; use `() => undefined` to distinguish omission from returning undefined. Arrays are shallow-copied on every clear; selected items that cannot be cleared remain. It does not redefine emptiness, alter Form reset defaults or treat 0/false as universally empty.

`empty-value` accepts explicit `null` (or `() => null`). Clearing publishes `null` unchanged; omitted values preserve the existing default. Editors render `null` as blank without converting ordinary empty-string input to `null`. In popup editing, clearing changes the draft; confirm commits it and cancel preserves the original model.

---

Document: llms/en-US/components/resize-box.md

<!-- Source: src/resize-box/README.en-US.md; locale: en-US; page: /en/components/resize-box/ -->

# Resize Box

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

- `directions`: Can be stretched side, there are up, down, left and right can be used

Example source: src/resize-box/__demos__/basic.vue

```vue
<template>
  <div>
    <c-resize-box
      :directions="['right', 'bottom']"
      :style="{ width: '500px', minWidth: '100px', maxWidth: '100%', height: '200px', textAlign: 'center' }"
    >
      <c-typography-paragraph>We are building the future of content discovery and creation.</c-typography-paragraph>
      <c-divider  />
      <c-typography-paragraph>
        ByteDance's content platforms enable people to enjoy content powered by AI technology. We inform, entertain, and
        inspire people across language, culture and geography.
      </c-typography-paragraph>
      <c-divider>ByteDance</c-divider>
      <c-typography-paragraph>Yiming Zhang is the founder and CEO of ByteDance.</c-typography-paragraph>
    </c-resize-box>
  </div>
</template>

<script lang="ts" setup>
</script>
```

## Layout and arrangement

### Layout

Preview configuration: `:resize-directions="['right']"`.

Example source: src/resize-box/__demos__/layout.vue

```vue
<template>
  <div class="layout-demo">
    <c-layout>
      <c-layout-header>Header</c-layout-header>
      <c-layout>
        <c-layout-sider :resize-directions="['right']"> Sider </c-layout-sider>
        <c-layout-content>Content</c-layout-content>
      </c-layout>
      <c-layout-footer>Footer</c-layout-footer>
    </c-layout>
  </div>
</template>

<script lang="ts" setup>
</script>

<style scoped>
.layout-demo :deep(.c-layout-header),
.layout-demo :deep(.c-layout-footer),
.layout-demo :deep(.c-layout-sider-children),
.layout-demo :deep(.c-layout-content) {
  display: flex;
  flex-direction: column;
  justify-content: center;
  color: var(--color-white);
  font-size: 16px;
  font-stretch: condensed;
  text-align: center;
}

.layout-demo :deep(.c-layout-header),
.layout-demo :deep(.c-layout-footer) {
  height: 64px;
  background-color: var(--color-primary-light-4);
}

.layout-demo :deep(.c-layout-sider) {
  width: 206px;
  background-color: var(--color-primary-light-3);
  min-width: 150px;
  max-width: 500px;
  height: 200px;
}

.layout-demo :deep(.c-layout-content) {
  background-color: rgb(var(--brand-6));
}
</style>
```

## Interaction and control

### Controlled

- `directions`: Can be stretched side, there are up, down, left and right can be used
- `width`: Width
- `height`: Height

Example source: src/resize-box/__demos__/controlled.vue

```vue
<template>
  <div>
    <c-resize-box
      :directions="['right', 'bottom']"
      :style="{ minWidth: '100px', maxWidth: '100%', textAlign: 'center' }"
      v-model:width="width"
      v-model:height="height"
    >
      <c-typography-paragraph>We are building the future of content discovery and creation.</c-typography-paragraph>
      <c-divider  />
      <c-typography-paragraph>
        ByteDance's content platforms enable people to enjoy content powered by AI technology. We inform, entertain, and
        inspire people across language, culture and geography.
      </c-typography-paragraph>
      <c-divider>ByteDance</c-divider>
      <c-typography-paragraph>Yiming Zhang is the founder and CEO of ByteDance.</c-typography-paragraph>
    </c-resize-box>
  </div>
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const width = ref(500)
const height = ref(200)
</script>
```

### Custom Triggers

- `directions`: Can be stretched side, there are up, down, left and right can be used

Example source: src/resize-box/__demos__/custom-triggers.vue

```vue
<template>
  <c-resize-box
    :directions="['right', 'bottom']"
    style="width: 500px; min-width: 100px; max-width: 100%; height: 200px; text-align: center"
  >
    <template #resize-trigger="{ direction }">
      <div :class="[`resizebox-demo`, `resizebox-demo-${direction === 'right' ? 'vertical' : 'horizontal'}`]">
        <div class="resizebox-demo-line" />
      </div>
    </template>
    <c-typography-paragraph>We are building the future of content discovery and creation.</c-typography-paragraph>
    <c-divider  />
    <c-typography-paragraph>
      ByteDance's content platforms enable people to enjoy content powered by AI technology. We inform, entertain, and
      inspire people across language, culture and geography.
    </c-typography-paragraph>
    <c-divider>ByteDance</c-divider>
    <c-typography-paragraph>Yiming Zhang is the founder and CEO of ByteDance.</c-typography-paragraph>
  </c-resize-box>
</template>

<script lang="ts" setup>
</script>

<style scoped>
.resizebox-demo {
  position: relative;
  display: flex;
  align-items: center;
  justify-content: center;
  width: 100%;
  height: 100%;
  background-color: var(--c-color-bg-white);
}

.resizebox-demo::before,
.resizebox-demo::after {
  width: 6px;
  height: 6px;
  border: 1px solid rgb(var(--brand-6));
  content: '';
}

.resizebox-demo-line {
  flex: 1;
  background-color: rgb(var(--brand-6));
}

.resizebox-demo-vertical {
  flex-direction: column;
}

.resizebox-demo-vertical .resizebox-demo-line {
  width: 1px;
  height: 100%;
}

.resizebox-demo-horizontal .resizebox-demo-line {
  height: 1px;
}
</style>
```

## API

### `<resize-box>` Props

| Parameter | Description | Type | Default |
| -------------------- | ------------------------------------------ | -------------------------------------------- | :---------: |
| width **(v-model)** | Width | `number` | `-` |
| height **(v-model)** | Surface height | `number` | `-` |
| component | The html tag of the telescopic box | `string` | `'div'` |
| directions | Edges with enabled resize handles, right only by default. Any combination of top/right/bottom/left; describes neither pointer movement nor popup placement | `('left' \| 'right' \| 'top' \| 'bottom')[]` | `['right']` |

### `<resize-box>` Events

| Event | Description | Arguments |
| ------------ | -------------- | -------------------------------------------------------------- |
| moving-start | Emitted when dragging starts | ev: `MouseEvent` |
| moving | Emitted during dragging | size: `{ width: number; height: number; }`<br>ev: `MouseEvent` |
| moving-end | Emitted when dragging ends | ev: `MouseEvent` |

### `<resize-box>` Slots

| Slot | Description | Arguments |
| ------------------- | :----------: | --------------------------------------------------- |
| resize-trigger | Resize-handle content | direction: `'left' \| 'right' \| 'top' \| 'bottom'` |
| resize-trigger-icon | Resize-handle icon | direction: `'left' \| 'right' \| 'top' \| 'bottom'` |

### Type definitions

The component exports the following types

```ts
import type { ResizeBoxInstance } from '@cedar-design/ui'
```


### Placement semantics and configuration

directions means edges with enabled resize handles; the existing name is retained. Only the right edge is enabled by default; multiple edges can be combined. It is neither an orientation axis nor popup placement. Edges is a more direct name for a new design, but this update does not rename the API.


## Reading direction and interaction

ResizeBox directions name physical edges: left/right/top/bottom retain their sides in RTL. Handles support the corresponding axis arrow keys, mouse and touch pointers; Shift increases the step from 10px to 50px. Dimensions clamp at zero. Direction changes, edge removal and teardown cancel active gestures and release cursor ownership.

---

Document: llms/en-US/components/result.md

<!-- Source: src/result/README.en-US.md; locale: en-US; page: /en/components/result/ -->

# Result

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

- `status`: Selects the semantic state.

Example source: src/result/__demos__/basic.vue

```vue
<script setup lang="ts">
import { computed, ref } from 'vue'
const statuses = ['info', 'success', 'warning', 'danger', 'question', 'empty'] as const
const index = ref(0)
const status = computed(() => statuses[index.value])
</script>

<template>
  <c-result data-demo-result :status="status" :title="'Result: ' + status" subtitle="Local state preview">
    <template #extra>
      <c-space wrap>
        <c-button status="primary" @click="index = (index + 1) % statuses.length">Next status</c-button>
        <c-button @click="index = 0">Reset status</c-button>
      </c-space>
      <p aria-live="polite">Current status: {{ status }}</p>
    </template>
  </c-result>
</template>
```

## Content and presentation

### Success, warning and failure

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `status` | Result-page status | Success, warning and failure, HTTP result states, All |
| `title` | Title content | Success, warning and failure, All |
| `subtitle` | Subtitle content | HTTP result states |
<!-- demo-config-notes:end -->


Compare how semantic states affect the icon, title and actions. HTTP statuses and custom artwork remain separate.

Example source: src/result/__demos__/status-comparison.vue

```vue
<script setup lang="ts">


</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="success">
    <h4><span lang="zh-CN">成功状态</span><span lang="en-US">success</span></h4>
    <c-result status="success" title="This is title content">
        <template #subtitle> This is subtitle content </template>
        <template #extra>
          <c-space>
            <c-button status="primary">Back</c-button>
          </c-space>
        </template>
      </c-result>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="warning">
    <h4><span lang="zh-CN">警告状态</span><span lang="en-US">warning</span></h4>
    <c-result status="warning" title="This is title content">
        <template #subtitle> This is subtitle content </template>
    
        <template #extra>
          <c-space>
            <c-button status="primary">Back</c-button>
          </c-space>
        </template>
      </c-result>
  </section>

  <section class="demo-comparison-case demo-comparison-case--3" data-comparison-scene="error">
    <h4><span lang="zh-CN">错误状态</span><span lang="en-US">error</span></h4>
    <c-result status="danger" title="This is title content">
        <template #subtitle> This is subtitle content </template>
    
        <template #extra>
          <c-space>
            <c-button status="primary">Back</c-button>
          </c-space>
        </template>
      </c-result>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

### HTTP result states

Compare permission, missing-resource and server-error content, with recovery actions appropriate to each case.

Example source: src/result/__demos__/http-status-comparison.vue

```vue
<script setup lang="ts">


</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="403">
    <h4><span lang="zh-CN">HTTP状态码 403</span><span lang="en-US">403</span></h4>
    <c-result status="403" subtitle="Access to this resource on the server is denied.">
        <template #extra>
          <c-space>
            <c-button status="primary">Back</c-button>
          </c-space>
        </template>
      </c-result>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="404">
    <h4><span lang="zh-CN">HTTP状态码 404</span><span lang="en-US">404</span></h4>
    <c-result status="404" subtitle="Whoops, that page is gone.">
        <template #extra>
          <c-space>
            <c-button status="primary">Back</c-button>
          </c-space>
        </template>
      </c-result>
  </section>

  <section class="demo-comparison-case demo-comparison-case--3" data-comparison-scene="500">
    <h4><span lang="zh-CN">HTTP状态码 500</span><span lang="en-US">500</span></h4>
    <c-result status="500" subtitle="This page isn’t working.">
        <template #extra>
          <c-space>
            <c-button status="primary">Back</c-button>
          </c-space>
        </template>
      </c-result>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

### All

- `status`: Selects the semantic state.

Example source: src/result/__demos__/all.vue

```vue
<template>
  <c-result status="danger" title="No internet ">
    <template #icon>
      <c-icon-face-frown-fill />
    </template>
    <template #subtitle> DNS_PROBE_FINISHED_NO_INTERNET</template>

    <template #extra>
      <c-button status="primary">Refresh</c-button>
    </template>
    <c-typography style="background: var(--color-fill-2); padding: 24px">
      <c-typography-paragraph>Try:</c-typography-paragraph>
      <ul>
        <li>Checking the network cables, modem, and router</li>
        <li>Reconnecting to Wi-Fi</li>
      </ul>
    </c-typography>
  </c-result>
</template>

<script lang="ts" setup>
</script>
```

## Customization and slots

### Custom

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `title` | Title content | Custom |
| `subtitle` | Subtitle content | Custom |
<!-- demo-config-notes:end -->


Preview configuration: `title="This is title content"`, `subtitle="This is subtitle content"`.

Example source: src/result/__demos__/custom.vue

```vue
<template>
  <c-result title="This is title content" subtitle="This is subtitle content">
    <template #icon>
      <c-icon-face-smile-fill />
    </template>
    <template #extra>
      <c-space>
        <c-button status="secondary">Again</c-button>
        <c-button status="primary">Back</c-button>
      </c-space>
    </template>
  </c-result>
</template>

<script lang="ts" setup>
</script>
```

## API

### `<result>` Props

| Parameter | Description | Type | Default |
| -------- | ---------------- | -------------------------------------------------------------------------------- | :------: |
| status | Result-page status | `'info' \| 'success' \| 'warning' \| 'danger' \| 'question' \| 'empty' \| '403' \| '404' \| '500'` | `'info'` |
| title | Title content | `string` | `-` |
| subtitle | Subtitle content | `string` | `-` |
| image-size | Status graphic size; numbers are px | `string \| number` | `-` |
| animation | Whether status-graphic animation is enabled | `boolean` | `true` |

### `<result>` Slots

| Slot | Description | Arguments | Version |
| -------- | :------: | ---- | :---- |
| icon | Custom status graphic | `{ size?: string }` |  |
| title | Title | - |  |
| subtitle | Subtitle | - |  |
| extra | Actions | - | 2.8.0 |
| default | Default slot | - | 2.8.0 |

### Type definitions

The component exports the following types

```ts
import type { ResultInstance } from '@cedar-design/ui'
```

---

Document: llms/en-US/components/ripple.md

<!-- Source: src/ripple/README.en-US.md; locale: en-US; page: /en/components/ripple/ -->

# Ripple

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

Example source: src/ripple/__demos__/basic.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import { Ripple } from "@cedar-design/ui";
import "@cedar-design/ui/ripple/style";

const vRipple = Ripple;
const disabled = ref(false);
</script>

<template>
  <c-space wrap>
    <div role="button" tabindex="0" v-ripple="{ disabled }" class="ripple-demo"
      >Ripple</div
    >
    <div
      role="button" tabindex="0"
      v-ripple="{ disabled }"
      class="ripple-demo ripple-demo--long"
      >600ms 扩散／800ms 消退</div
    >
    <c-button @click="disabled = !disabled">{{
      disabled ? "启用水波" : "禁用水波"
    }}</c-button>
  </c-space>
</template>

<style scoped>
.ripple-demo--long {
  --c-ripple-expand-duration: 600ms;
  --c-ripple-fade-duration: 800ms;
}
.ripple-demo {
  position: relative;
  overflow: hidden;
  padding: 8px 20px;
  border: 1px solid var(--c-sys-color-border-default);
  border-radius: var(--c-sys-radius-sm);
  color: var(--c-sys-color-action-primary);
  background: var(--c-sys-color-surface-overlay);
  cursor: pointer;
}
</style>
```

## Options

| Options | Description | Type | Default |
| --- | --- | --- | --- |
| color | Ripple color | `string` | `currentColor` |
| disabled | Prevent ripples and cancel pending animation | `boolean` | `false` |

Use `v-ripple="{ color, disabled }"`. Unmount cancels animations/timers and removes listeners; each element maintains independent keyboard state.

## Styles

For direct directive registration, import `@cedar-design/ui/ripple/style`. Runtime imports no CSS, supporting SSR package imports. Variables use `--c-ripple-*` and are declared in `style/token.less`. Theme defaults may differ from mobile while motion/consumption protocols stay aligned.

| Variable | Default | Responsibility |
| --- | --- | --- |
| --c-ripple-color | currentColor | Ripple background; color option takes precedence |
| --c-ripple-cubic-bezier | cubic-bezier(0.68, 0.01, 0.62, 0.6) | Transform expansion easing |
| --c-ripple-expand-duration | 200ms | Transform expansion duration |
| --c-ripple-fade-duration | 140ms | Linear opacity appear/fade duration |

Variables belong on the actual directive host and inherit into ripples. Defaults currently match across platforms. 250ms is the minimum postcreation display/postfade removal wait, not visual duration or the entire lifecycle. Runtime reads computed transition duration/delay. Fade waits until the later of creation+250ms or activation+expansion duration; removal waits max(250ms, fade duration). Long overrides are not truncated. 0ms/unstyled retain cleanup floors. Reduced motion hides decoration. Expansion samples on creation/activation, fade on fade start; arbitrary midphase CSS changes/animations are not guaranteed.

Repeated release queues once. Disabling/unmounting cleans owned timers/direct ripples without deleting nested instances. Document listeners bind/remove against mount-time ownerDocument, without automatic cross-document rebinding. Only host Enter/Space and matching keyup/blur participate. The directive does not supply button semantics, accessible names or business clicking to plain divs. Real touch/OS preferences need separate validation.

---

Document: llms/en-US/components/row.md

<!-- Source: src/row/README.en-US.md; locale: en-US; page: /en/components/row/ -->

# Row

24-column Flex layout. Row manages gutters and alignment; Col manages spans, offsets, ordering and breakpoints. Use Grid for CSS Grid collapse and suffix items.

> **Choosing a layout**
>
> - Grid + GridItem: Use for form columns and card grids with consistent column widths, spans, responsive column counts, or collapsed rows and suffix items.
> - Row + Col: Use for 24-column Flex layouts that need horizontal/vertical alignment, wrapping control, fixed and flexible widths together, or responsive ordering. Row controls the row; Col controls width, offset and order.
> - Space: Use for simple groups of buttons, tags or text that only need spacing, direction and alignment. Use native Flex for more flexible width allocation.

## Basic examples

### 24-column layout

Example source: src/row/__demos__/basic.vue

```vue
<template><div>
  <c-row :gutter="12"><c-col :span="12"><div class="cell">12</div></c-col><c-col :span="12"><div class="cell soft">12</div></c-col></c-row>
  <c-row :gutter="12"><c-col v-for="i in 3" :key="i" :span="8"><div class="cell">8</div></c-col></c-row>
</div></template>

<style scoped>
.controls { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; }
.cell { box-sizing: border-box; padding: 12px; min-width: 0; border-radius: 4px; background: var(--c-color-primary); color: var(--c-color-white); text-align: center; overflow-wrap: anywhere; }
.soft { opacity: .7; }
</style>
```

## Layout and arrangement

### Two-axis and responsive gutters

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `gutter` | Gutter: number, responsive object or [horizontal, vertical] | Two-axis and responsive gutters, Horizontal and vertical alignment, Wrapping and plain container mode |
| `justify` | Horizontal alignment | Horizontal and vertical alignment, Layout Lab |
| `align` | Vertical alignment | Horizontal and vertical alignment, Layout Lab |
| `wrap` | Wrap columns | Wrapping and plain container mode |
| `div` | Use Row and Col as plain divs without layout styles | Wrapping and plain container mode |
<!-- demo-config-notes:end -->


Example source: src/row/__demos__/gutter.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const gap = ref(16)
const vertical = ref(true)
</script>
<template><div>
  <div class="controls"><c-radio-group v-model="gap"><c-radio v-for="value in [0, 8, 16, 24]" :key="value" :value="value">{{ value }}px</c-radio></c-radio-group><c-switch v-model="vertical" aria-label="Vertical gutter" />Vertical gap</div>
  <c-row :gutter="[gap, vertical ? gap : 0]"><c-col v-for="i in 6" :key="i" :span="8"><div class="cell">{{ i }}</div></c-col></c-row>
  <c-row :gutter="[{ xs: 8, md: 24 }, { xs: 8, md: 16 }]"><c-col v-for="i in 4" :key="i" :span="12"><div class="cell soft">Responsive gap</div></c-col></c-row>
</div></template>

<style scoped>
.controls { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; }
.cell { box-sizing: border-box; padding: 12px; min-width: 0; border-radius: 4px; background: var(--c-color-primary); color: var(--c-color-white); text-align: center; overflow-wrap: anywhere; }
.soft { opacity: .7; }
</style>
```

### Horizontal and vertical alignment

Example source: src/row/__demos__/alignment.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const justifies = ['start', 'center', 'end', 'space-around', 'space-between'] as const
const aligns = ['start', 'center', 'end', 'stretch'] as const
const justify = ref<typeof justifies[number]>('space-between')
const align = ref<typeof aligns[number]>('center')
</script>
<template><div>
  <c-radio-group v-model="justify"><c-radio v-for="value in justifies" :key="value" :value="value">{{ value }}</c-radio></c-radio-group>
  <c-radio-group v-model="align"><c-radio v-for="value in aligns" :key="value" :value="value">{{ value }}</c-radio></c-radio-group>
  <c-row :gutter="12" :justify="justify" :align="align"><c-col v-for="i in 3" :key="i" :span="6"><div class="cell" :style="{ minHeight: `${36 + i * 24}px`, height: '100%' }">{{ i }}</div></c-col></c-row>
</div></template>

<style scoped>
.controls { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; }
.cell { box-sizing: border-box; padding: 12px; min-width: 0; border-radius: 4px; background: var(--c-color-primary); color: var(--c-color-white); text-align: center; overflow-wrap: anywhere; }
.soft { opacity: .7; }
</style>
```

### Wrapping and plain container mode

Example source: src/row/__demos__/wrap.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const wrap = ref(true)
const div = ref(false)
</script>
<template><div>
  <div class="controls"><c-switch v-model="wrap" aria-label="Wrap" />Wrap<c-switch v-model="div" aria-label="Plain div" />Plain div</div>
  <div style="overflow: auto; padding: 8px"><c-row :gutter="12" :wrap="wrap" :div="div"><c-col v-for="i in 3" :key="i" :span="12"><div class="cell">{{ i }}</div></c-col></c-row></div>
</div></template>

<style scoped>
.controls { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; }
.cell { box-sizing: border-box; padding: 12px; min-width: 0; border-radius: 4px; background: var(--c-color-primary); color: var(--c-color-white); text-align: center; overflow-wrap: anywhere; }
.soft { opacity: .7; }
</style>
```

### Nested rows and isolated gutters

Example source: src/row/__demos__/nested.vue

```vue
<template><div><c-row :gutter="24"><c-col :span="16"><c-row :gutter="8"><c-col :span="12"><div class="cell">Inner 12</div></c-col><c-col :span="12"><div class="cell soft">Inner 12</div></c-col></c-row></c-col><c-col :span="8"><div class="cell">Outer 8</div></c-col></c-row></div></template>

<style scoped>
.controls { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; }
.cell { box-sizing: border-box; padding: 12px; min-width: 0; border-radius: 4px; background: var(--c-color-primary); color: var(--c-color-white); text-align: center; overflow-wrap: anywhere; }
.soft { opacity: .7; }
</style>
```

<!-- same-source-api:start -->

### Props

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| gutter | Gutter: number, responsive object or [horizontal, vertical] | `RowGutter` | `0` |
| justify | Horizontal alignment | `start / center / end / space-around / space-between` | `start` |
| align | Vertical alignment | `start / center / end / stretch` | `start` |
| wrap | Wrap columns | `boolean` | `true` |
| div | Use Row and Col as plain divs without layout styles | `boolean` | `false` |

### Events

| Event | Description |
| --- | --- |
| click | Native MouseEvent, emitted once per click |

### Slots

| Slot | Description |
| --- | --- |
| default | Layout content |

### Methods

| Method | Description |
| --- | --- |
<!-- same-source-api:end -->

The wrap example toggles wrapping and plain `div` mode independently. Plain mode removes Row layout styles and child Col spacing; gutter controls distinguish horizontal spacing from vertical spacing. Row uses Flex, not CSS Grid.

### Layout Lab

Example source: src/row/__demos__/layout-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";

const __demoLayout = __demoReactive({ align: "start", justify: "start" });
</script>
<template>
  <c-space direction="column" :size="16">
    <c-form layout="vertical">
      <c-form-item layout="vertical" size="sm" label="align">
        <c-radio-group
          v-model="__demoLayout['align']"
          aria-label="align"
          :options="[
            { label: 'start', value: 'start' },
            { label: 'center', value: 'center' },
            { label: 'end', value: 'end' },
            { label: 'stretch', value: 'stretch' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
      <c-form-item layout="vertical" size="sm" label="justify">
        <c-radio-group
          v-model="__demoLayout['justify']"
          aria-label="justify"
          :options="[
            { label: 'start', value: 'start' },
            { label: 'center', value: 'center' },
            { label: 'end', value: 'end' },
            { label: 'space-around', value: 'space-around' },
            { label: 'space-between', value: 'space-between' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
    </c-form>
    <c-row :gutter="12" v-bind="__demoLayout"
      ><c-col v-for="i in 3" :key="i" :span="8"
        ><div class="cell">8</div></c-col
      ></c-row
    >
  </c-space>
</template>
<style scoped>
.controls {
  display: flex;
  flex-wrap: wrap;
  align-items: center;
  gap: 12px;
}
.cell {
  box-sizing: border-box;
  padding: 12px;
  min-width: 0;
  border-radius: 4px;
  background: var(--c-color-primary);
  color: var(--c-color-white);
  text-align: center;
  overflow-wrap: anywhere;
}
.soft {
  opacity: 0.7;
}
</style>
```

## API

<!-- same-source-api:start -->
### Props

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| gutter | Gutter: number, responsive object or [horizontal, vertical] | `RowGutter` | `0` |
| justify | Horizontal alignment | `start / center / end / space-around / space-between` | `start` |
| align | Vertical alignment | `start / center / end / stretch` | `start` |
| wrap | Wrap columns | `boolean` | `true` |
| div | Use Row and Col as plain divs without layout styles | `boolean` | `false` |

### Events

| Event | Description |
| --- | --- |
| click | Native MouseEvent, emitted once per click |

### Slots

| Slot | Description |
| --- | --- |
| default | Layout content |

### Methods

| Method | Description |
| --- | --- |
<!-- same-source-api:end -->

Wrapping examples compare wrapped and ordinary `div` modes. Ordinary mode removes Row layout and child Col spacing. Gap examples distinguish horizontal/vertical spacing. Row uses Flex, not CSS Grid.

## Responsiveness and accessibility

Breakpoints use the browser viewport: xs is the base; sm ≥576, md ≥768, lg ≥992, xl ≥1200 and xxl ≥1600px. Configured values resolve downward from the largest matching breakpoint. SSR starts with xs and responds to the viewport after mounting. Grid collapsing and dynamic ordering are calculated after mounting. These layout containers add no keyboard shortcuts; callers supply content semantics and focusable elements. There are no public methods or dedicated theme tokens.

## Imports

Grid contains only Grid.Item. Row and Col are independent components with their own source, styles, navigation, documentation and demos. Grid.Row/Grid.Col, Row/Col re-exports from Grid and GridRowInstance/GridColInstance are removed. Import them from the library root or separate row/col entries. Installing Grid no longer registers Row/Col automatically.

---

Document: llms/en-US/components/scheduler.md

<!-- Source: src/scheduler/README.en-US.md; locale: en-US; page: /en/components/scheduler/ -->

# Scheduler

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Reading direction

Scheduler inherits `dir` from the page, a local container, or ConfigProvider. Use the documentation navigation switch to change LTR/RTL at runtime. Month/week/resource columns and horizontal time follow inline start; vertical time continues downwards. Switching direction preserves dates, event data, selection and the horizontal reading offset, and cancels active drag or resize gestures.

Hourly resource timelines support moving events and resizing both start and end, respecting `snapDuration`, readonly state, milestones and event `resizable`. Zoom preserves the date at the center of the visible time area. Resource labels stick to inline start; virtual rows and their heading scroll together.

Default overlap layouts use inline start. A custom `eventLayout` return value keeps the physical meaning of `left`; callers control that geometry. RTL does not reverse dates, time zones, dependencies or source resource order.

## Basic examples

### Basic usage

Preview configuration: `default-date="2026-09-09"`.

Example source: src/scheduler/__demos__/basic.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
import type { SchedulerEvent } from '@cedar-design/ui'
const events = ref<SchedulerEvent[]>([
  { id: 'meeting', title: '项目同步', start: '2026-09-09T09:00:00', end: '2026-09-09T10:00:00' },
])
</script>
<template>
  <c-scheduler v-model="events" default-date="2026-09-09" />
</template>
```

## Views and layout

### Layout Groups

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `default-date` | Initial navigation date | Layout Groups, Without Resources, Resource Week |
| `default-mode` | Default uncontrolled view | Layout Groups, Timeline, Hidden Days |
| `resources` | Currently visible resource rows/columns and local options; a complete directory is unnecessary | Resource Week, Timeline, Now Indicator |
| `start-hour` | Time-grid start hour, 0–23 | Layout Groups, Now Indicator, Stacked Events |
| `end-hour` | Time-grid end hour; greater than start and at most 24 | Layout Groups, Now Indicator, Stacked Events |
| `modes` | Views available for switching | Without Resources, Hidden Days, Now Indicator |
<!-- demo-config-notes:end -->


Preview configuration: `:default-date="today"`, `default-mode="day"`, `:event-layout="custom ? layout : 'stack'"`, `:show-sidebar="false"`.

Example source: src/scheduler/__demos__/layout-groups.vue

```vue
<template>
  <c-space direction="column" block>
    <c-alert
      >分组仅共享布局位置。业务关联保存在
      metadata，修改单块不会自动修改整组。</c-alert
    >
    <c-space>
      <c-checkbox v-model="grouped">连续日程组成布局组</c-checkbox>
      <c-checkbox v-model="custom">自定义横向留白</c-checkbox>
    </c-space>
    <c-scheduler
      v-model="displayEvents"
      :default-date="today"
      default-mode="day"
      :event-layout="custom ? layout : 'stack'"
      :show-sidebar="false"
      :start-hour="8"
      :end-hour="17"
    >
      <template #event="{ event }">
        <strong>{{ event.title }}</strong>
        <div v-if="event.metadata?.reference">
          关联：{{ event.metadata.reference }}
        </div>
      </template>
    </c-scheduler>
  </c-space>
</template>
<script setup lang="ts">
import { computed, ref } from "vue";
import type { SchedulerEvent, SchedulerEventLayout } from "../core";
const today = new Date();
const grouped = ref(true);
const custom = ref(false);
const at = (hour: number) => {
  const date = new Date(today);
  date.setHours(hour, 0, 0, 0);
  return date;
};
const events = ref<SchedulerEvent[]>([
  {
    id: "a",
    title: "阶段一",
    start: at(9),
    end: at(11),
    metadata: { reference: "A" },
  },
  {
    id: "b",
    title: "阶段二",
    start: at(11),
    end: at(13),
    metadata: { reference: "A" },
  },
  { id: "c", title: "独立日程", start: at(10), end: at(12) },
  {
    id: "d",
    title: "间隔后的阶段",
    start: at(15),
    end: at(16),
    metadata: { reference: "A" },
  },
]);
// Only the application interprets metadata and chooses which blocks share layout.
const displayEvents = computed({
  get: () =>
    events.value.map((event) => ({
      ...event,
      layoutGroupId:
        grouped.value && typeof event.metadata?.reference === "string"
          ? event.metadata.reference
          : undefined,
    })),
  set: (value: SchedulerEvent[]) => {
    events.value = value;
  },
});
// Product-specific percentages stay in the demo. Fractions are relative to one date/resource column.
const layout: SchedulerEventLayout = ({ column, columns }) => {
  const left = (column * 0.9) / columns;
  return {
    left,
    width: Math.min(Math.max(0.45, 1 - 0.1 * columns), 0.9 - left),
  };
};
</script>
```

### Without Resources

Preview configuration: `:modes="['day', 'week', 'month', 'agenda']"`, `default-date="2026-09-09"`.

Example source: src/scheduler/__demos__/without-resources.vue

```vue
<template>
  <p>仅管理发布时间与工作计划，不传人员或设备列表。编辑器不显示资源字段。</p>
  <c-scheduler
    v-model="events"
    :modes="['day', 'week', 'month', 'agenda']"
    default-date="2026-09-09"
  />
</template>
<script setup lang="ts">
import { ref } from "vue";
import type { SchedulerEvent } from "@cedar-design/ui";
const events = ref<SchedulerEvent[]>([
  {
    id: "release",
    title: "产品发布",
    start: "2026-09-09T10:00:00",
    end: "2026-09-09T11:00:00",
    description: "检查发布清单",
  },
  {
    id: "campaign",
    title: "专题活动",
    start: "2026-09-10",
    end: "2026-09-13",
    allDay: true,
  },
  { id: "draft", title: "下期内容选题", description: "未排期，可拖入时间格" },
]);
</script>
```

### Resource Week

Preview configuration: `default-date="2026-09-09"`, `:resources="resources"`.

Example source: src/scheduler/__demos__/resource-week.vue

```vue
<template>
  <c-scheduler
    v-model="events"
    default-date="2026-09-09"
    :resources="resources"
  />
</template>
<script setup lang="ts">
import { ref } from "vue";
import { createEvents, resources } from "./data";
const events = ref(createEvents());
</script>
```

### Timeline

Preview configuration: `default-date="2026-09-09"`, `default-mode="resource-timeline"`, `:resources="resources"`.

Example source: src/scheduler/__demos__/timeline.vue

```vue
<template>
  <c-scheduler
    v-model="events"
    default-date="2026-09-09"
    default-mode="resource-timeline"
    :resources="resources"
  />
</template>
<script setup lang="ts">
import { ref } from "vue";
import { createEvents, resources } from "./data";
const events = ref(createEvents());
</script>
```

### Hidden Days

Preview configuration: `default-date="2026-09-18"`, `default-mode="month"`, `:modes="['week', 'month', 'agenda']"`, `:hidden-days="hidden"`.

Example source: src/scheduler/__demos__/hidden-days.vue

```vue
<template>
  <c-space direction="column" block>
    <c-alert
      >隐藏日期只影响展示，原日程仍保留，并参与容量和冲突校验。跨周末任务会出现在周五及下周一；拖动到周一会按周一的实际日期保存。可切换周、月和议程检查同一份数据。</c-alert
    >
    <c-space wrap>
      <c-checkbox v-model="weekends">隐藏周末</c-checkbox>
      <c-checkbox v-model="wednesday">隐藏周三</c-checkbox>
      <c-tag>完整数据：{{ events.length }} 条</c-tag>
    </c-space>
    <c-scheduler
      key="hidden-days"
      v-model="events"
      default-date="2026-09-18"
      default-mode="month"
      :modes="['week', 'month', 'agenda']"
      :hidden-days="hidden"
      :first-day-of-week="0"
      history
    />
  </c-space>
</template>
<script setup lang="ts">
import { computed, ref } from "vue";
import type { SchedulerEvent } from "../core";
const weekends = ref(true);
const wednesday = ref(false);
const hidden = computed(() => [
  ...(weekends.value ? [0, 6] : []),
  ...(wednesday.value ? [3] : []),
]);
const events = ref<SchedulerEvent[]>([
  {
    id: "cross-weekend",
    title: "跨周末项目",
    start: "2026-09-18",
    end: "2026-09-22",
    allDay: true,
  },
  {
    id: "weekend",
    title: "周末值班",
    start: "2026-09-19T10:00:00",
    end: "2026-09-19T11:00:00",
  },
  {
    id: "wednesday",
    title: "周三评审",
    start: "2026-09-16T14:00:00",
    end: "2026-09-16T15:00:00",
  },
]);
</script>
```

### Now Indicator

Preview configuration: `v-model:date="date"`, `:show-now-indicator="enabled"`, `default-mode="resource-day"`, `:modes="['day', 'week', 'resource-day']"`.

Example source: src/scheduler/__demos__/now-indicator.vue

```vue
<template>
  <c-space direction="column" block>
    <c-alert
      >红线标出当前本地时间，每 30
      秒刷新。可以切换日、周和资源日程；日和资源日程查看明天时红线消失。标线不影响新建和拖动。</c-alert
    >
    <c-space wrap>
      <c-checkbox v-model="enabled">显示现在时间线</c-checkbox>
      <c-button @click="date = new Date()">查看今天</c-button>
      <c-button @click="date = addSchedulerDays(new Date(), 1)"
        >查看明天</c-button
      >
    </c-space>
    <c-scheduler
      key="now-indicator"
      v-model:date="date"
      :show-now-indicator="enabled"
      default-mode="resource-day"
      :modes="['day', 'week', 'resource-day']"
      :start-hour="0"
      :end-hour="24"
      :resources="resources"
    />
  </c-space>
</template>
<script setup lang="ts">
import { ref } from "vue";
import { addSchedulerDays } from "../core";
const date = ref(new Date());
const enabled = ref(true);
const resources = [
  { id: "a", label: "今日值班 A" },
  { id: "b", label: "今日值班 B" },
];
</script>
```

### Timeline Groups

Preview configuration: `v-model:scale="scale"`, `v-model:expanded-keys="expanded"`, `default-date="2026-09-09"`, `default-mode="resource-timeline"`.

Example source: src/scheduler/__demos__/timeline-groups.vue

```vue
<template>
  <c-space direction="column" block>
    <c-alert
      >按部门折叠资源；切换小时刻度可查看定位日的精确排期。资源名称在横向滚动时保持可见。</c-alert
    >
    <c-scheduler
      v-model="events"
      v-model:scale="scale"
      v-model:expanded-keys="expanded"
      default-date="2026-09-09"
      default-mode="resource-timeline"
      :resources="resources"
      :resource-group-by="groupBy"
    />
  </c-space>
</template>
<script setup lang="ts">
import { ref } from "vue";
import type { SchedulerResource, SchedulerScale } from "../core";
import { createEvents, resources } from "./data";
const events = ref(createEvents());
const scale = ref<SchedulerScale>("hour");
const expanded = ref(["产品与设计", "研发"]);
const groupBy = (resource: SchedulerResource) =>
  resource.id === resources[0].id ? "产品与设计" : "研发";
</script>
```

### Stacked Events

- `readonly`: Displays the current value without allowing edits.

Example source: src/scheduler/__demos__/stacked-events.vue

```vue
<template>
  <c-space direction="column" block>
    <c-alert
      >重叠卡片按数量等分起点并延伸到最右侧。本例最多直接显示 3
      张，更多日程通过“还有 N
      项”Popover查看。Tab聚焦前置，失焦恢复；单击或Enter打开详情。</c-alert
    >
    <c-space>
      <c-button @click="layout = layout === 'stack' ? 'columns' : 'stack'">{{
        layout === "stack" ? "切换并排布局" : "切换叠放布局"
      }}</c-button>
      <c-checkbox v-model="readonly">只读查看</c-checkbox>
    </c-space>
    <c-scheduler
      v-model="events"
      default-date="2026-09-22"
      default-mode="week"
      :event-layout="layout"
      :overlap-event-limit="3"
      :readonly="readonly"
      selectable
      :show-sidebar="false"
      :start-hour="8"
      :end-hour="16"
    />
  </c-space>
</template>
<script setup lang="ts">
import { ref } from "vue";
import type { SchedulerEvent } from "../core";
const layout = ref<"stack" | "columns">("stack");
const readonly = ref(false);
const events = ref<SchedulerEvent[]>([
  {
    id: "a",
    title: "站点巡检",
    start: "2026-09-22T09:00:00",
    end: "2026-09-22T12:00:00",
  },
  {
    id: "b",
    title: "设备维护",
    start: "2026-09-22T09:30:00",
    end: "2026-09-22T11:30:00",
  },
  {
    id: "c",
    title: "人员培训",
    start: "2026-09-22T10:00:00",
    end: "2026-09-22T12:30:00",
  },
  {
    id: "e",
    title: "安全检查",
    start: "2026-09-22T09:15:00",
    end: "2026-09-22T11:00:00",
  },
  {
    id: "f",
    title: "临时工单",
    start: "2026-09-22T09:45:00",
    end: "2026-09-22T12:00:00",
  },
  {
    id: "d",
    title: "独立任务",
    start: "2026-09-23T13:00:00",
    end: "2026-09-23T14:00:00",
  },
]);
</script>
```

## Resources and assignments

### Resources

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `default-date` | Initial navigation date | Resources, Resource Cross Groups, Resource Dimensions |
| `default-mode` | Default uncontrolled view | Resources, Resource Cross Groups, Resource Dimensions |
| `resources` | Currently visible resource rows/columns and local options; a complete directory is unnecessary | Resources, Resource Cross Groups, Resource Dimensions |
| `resource-dimensions` | Dimension definitions: `{ id, label }[]` | Resource Cross Groups, Resource Dimensions, Independent Assignments |
| `resource-filters` | Combined resource-dimension filters; supports v-model:resource-filters | Resource Cross Groups, Resource Dimensions, Virtual Resources |
| `show-assignment-details` | Edit resource occupancy and roles | Independent Assignments, Assignment Load |
<!-- demo-config-notes:end -->


Preview configuration: `default-date="2026-09-09"`, `default-mode="resource-day"`, `:resources="resources"`, `:start-hour="8"`.

Example source: src/scheduler/__demos__/resources.vue

```vue
<template>
  <c-scheduler
    v-model="events"
    default-date="2026-09-09"
    default-mode="resource-day"
    :resources="resources"
    :start-hour="8"
    :end-hour="18"
  />
</template>
<script setup lang="ts">
import { ref } from "vue";
import { createEvents, resources } from "./data";
const events = ref(createEvents());
</script>
```

### Resource Cross Groups

Preview configuration: `data-cross-groups-demo`, `v-model:resource-filters="filters"`, `:resource-group-dimensions="groupDimensions"`, `default-date="2026-09-22"`.

Example source: src/scheduler/__demos__/resource-cross-groups.vue

```vue
<template>
  <c-space direction="column" block>
    <c-alert
      >按站展开人员，也可切换为按人展开站。联合验收在两个人员行显示，但数据只有一条；拖动会修改整条任务的时间和对应资源。点击空白行可创建同时关联站与人的任务。</c-alert
    >
    <c-space wrap>
      <c-button
        @click="
          filters = { station: ['station:north'], person: ['person:lin'] }
        "
        >北站 + 小林</c-button
      >
      <c-button
        @click="
          filters = {
            station: ['station:north', 'station:south'],
            person: ['person:chen'],
          }
        "
        >两站 + 小陈</c-button
      >
      <c-button @click="filters = {}">清空维度筛选</c-button>
      <c-button @click="groupDimensions = ['station', 'person']"
        >站 → 人</c-button
      >
      <c-button @click="groupDimensions = ['person', 'station']"
        >人 → 站</c-button
      >
      <c-tag>匹配 {{ matching.length }} / {{ events.length }} 条任务</c-tag>
    </c-space>
    <c-scheduler
      data-cross-groups-demo
      key="resource-cross-groups"
      v-model="events"
      v-model:resource-filters="filters"
      :resource-group-dimensions="groupDimensions"
      default-date="2026-09-22"
      default-mode="resource-timeline"
      default-scale="hour"
      :resources="resources"
      :resource-dimensions="dimensions"
      history
    />
  </c-space>
</template>
<script setup lang="ts">
import { computed, ref } from "vue";
import { filterSchedulerEventsByResources } from "../core";
import type {
  SchedulerEvent,
  SchedulerResource,
  SchedulerResourceFilters,
} from "../core";
const dimensions = [
  { id: "station", label: "站" },
  { id: "person", label: "人" },
];
const resources: SchedulerResource[] = [
  { id: "station:north", label: "北站", dimensionId: "station", capacity: 2 },
  { id: "station:south", label: "南站", dimensionId: "station", capacity: 2 },
  { id: "person:lin", label: "小林", dimensionId: "person", capacity: 1 },
  { id: "person:chen", label: "小陈", dimensionId: "person", capacity: 1 },
];
const filters = ref<SchedulerResourceFilters>({});
const groupDimensions = ref(["station", "person"]);
const events = ref<SchedulerEvent[]>([
  {
    id: "north-lin",
    title: "北站巡检",
    start: "2026-09-22T09:00:00",
    end: "2026-09-22T10:00:00",
    resourceIds: ["station:north", "person:lin"],
  },
  {
    id: "north-chen",
    title: "北站检修",
    start: "2026-09-22T10:00:00",
    end: "2026-09-22T11:00:00",
    resourceIds: ["station:north", "person:chen"],
  },
  {
    id: "south-lin",
    title: "南站巡检",
    start: "2026-09-22T11:00:00",
    end: "2026-09-22T12:00:00",
    resourceIds: ["station:south", "person:lin"],
  },
  {
    id: "south-chen",
    title: "南站检修",
    start: "2026-09-22T13:00:00",
    end: "2026-09-22T14:00:00",
    resourceIds: ["station:south", "person:chen"],
  },
  {
    id: "joint",
    title: "北站联合验收",
    start: "2026-09-22T14:00:00",
    end: "2026-09-22T15:00:00",
    resourceIds: ["station:north", "person:lin", "person:chen"],
  },
]);
const matching = computed(() =>
  filterSchedulerEventsByResources(events.value, resources, filters.value),
);
</script>
```

### Resource Dimensions

Preview configuration: `data-dimensions-demo`, `v-model:resource-filters="filters"`, `v-model:resource-dimension="axis"`, `default-date="2026-09-22"`.

Example source: src/scheduler/__demos__/resource-dimensions.vue

```vue
<template>
  <c-space direction="column" block>
    <c-alert
      >一条任务同时关联站和人。左侧同一维度可多选，站与人之间组合筛选；上方“展示维度”切换资源行。打开任务详情可分别修改站和人，其他维度的关联会保留。</c-alert
    >
    <c-space wrap>
      <c-button
        @click="
          filters = { station: ['station:north'], person: ['person:lin'] }
        "
        >北站 + 小林</c-button
      >
      <c-button
        @click="
          filters = {
            station: ['station:north', 'station:south'],
            person: ['person:chen'],
          }
        "
        >两站 + 小陈</c-button
      >
      <c-button @click="filters = {}">清空维度筛选</c-button>
      <c-button @click="axis = 'station'">按站展示</c-button>
      <c-button @click="axis = 'person'">按人展示</c-button>
      <c-tag>匹配 {{ matching.length }} / {{ events.length }} 条任务</c-tag>
    </c-space>
    <c-scheduler
      data-dimensions-demo
      key="resource-dimensions"
      v-model="events"
      v-model:resource-filters="filters"
      v-model:resource-dimension="axis"
      default-date="2026-09-22"
      default-mode="resource-timeline"
      default-scale="hour"
      :resources="resources"
      :resource-dimensions="dimensions"
      history
    />
  </c-space>
</template>
<script setup lang="ts">
import { computed, ref } from "vue";
import { filterSchedulerEventsByResources } from "../core";
import type {
  SchedulerEvent,
  SchedulerResource,
  SchedulerResourceFilters,
} from "../core";
const dimensions = [
  { id: "station", label: "站" },
  { id: "person", label: "人" },
];
const resources: SchedulerResource[] = [
  { id: "station:north", label: "北站", dimensionId: "station", capacity: 2 },
  { id: "station:south", label: "南站", dimensionId: "station", capacity: 2 },
  { id: "person:lin", label: "小林", dimensionId: "person", capacity: 1 },
  { id: "person:chen", label: "小陈", dimensionId: "person", capacity: 1 },
];
const filters = ref<SchedulerResourceFilters>({
  station: ["station:north"],
  person: ["person:lin"],
});
const axis = ref("station");
const events = ref<SchedulerEvent[]>([
  {
    id: "north-lin",
    title: "北站巡检",
    start: "2026-09-22T09:00:00",
    end: "2026-09-22T10:00:00",
    resourceIds: ["station:north", "person:lin"],
  },
  {
    id: "north-chen",
    title: "北站检修",
    start: "2026-09-22T10:00:00",
    end: "2026-09-22T11:00:00",
    resourceIds: ["station:north", "person:chen"],
  },
  {
    id: "south-lin",
    title: "南站巡检",
    start: "2026-09-22T11:00:00",
    end: "2026-09-22T12:00:00",
    resourceIds: ["station:south", "person:lin"],
  },
  {
    id: "south-chen",
    title: "南站检修",
    start: "2026-09-22T13:00:00",
    end: "2026-09-22T14:00:00",
    resourceIds: ["station:south", "person:chen"],
  },
  {
    id: "joint",
    title: "北站联合验收",
    start: "2026-09-22T14:00:00",
    end: "2026-09-22T15:00:00",
    resourceIds: ["station:north", "person:lin", "person:chen"],
  },
]);
const matching = computed(() =>
  filterSchedulerEventsByResources(events.value, resources, filters.value),
);
</script>
```

### Independent Assignments

Preview configuration: `:resources="resources"`, `:resource-dimensions="dimensions"`, `:resource-group-dimensions="['station', 'person']"`, `default-date="2026-09-22"`.

Example source: src/scheduler/__demos__/independent-assignments.vue

```vue
<template>
  <c-space direction="column" block>
    <c-alert
      >同一业务任务有两个独立分配：北站小林 09:00–10:00、南站小陈
      13:00–15:00。它们共用
      metadata.taskId，各自拥有时间与占用量；修改一个分配不会移动另一个。</c-alert
    >
    <c-scheduler
      v-model="events"
      :resources="resources"
      :resource-dimensions="dimensions"
      :resource-group-dimensions="['station', 'person']"
      default-date="2026-09-22"
      default-mode="resource-timeline"
      default-scale="hour"
      show-assignment-details
      history
    />
  </c-space>
</template>
<script setup lang="ts">
import { ref } from "vue";
import { createSchedulerTaskEvents } from "./task-assignments";
const dimensions = [
  { id: "station", label: "站" },
  { id: "person", label: "人" },
];
const resources = [
  { id: "north", label: "北站", dimensionId: "station" },
  { id: "south", label: "南站", dimensionId: "station" },
  { id: "lin", label: "小林", dimensionId: "person", capacity: 1 },
  { id: "chen", label: "小陈", dimensionId: "person", capacity: 1 },
];
const events = ref(
  createSchedulerTaskEvents({ id: "inspection", title: "联合巡检" }, [
    {
      id: "north-lin",
      start: "2026-09-22T09:00:00",
      end: "2026-09-22T10:00:00",
      resourceIds: ["north", "lin"],
      resourceDetails: { lin: { units: 1, role: "负责" } },
    },
    {
      id: "south-chen",
      start: "2026-09-22T13:00:00",
      end: "2026-09-22T15:00:00",
      resourceIds: ["south", "chen"],
      resourceDetails: { chen: { units: 0.5, role: "负责" } },
    },
  ]),
);
</script>
```

### Assignment Load

Preview configuration: `default-date="2026-09-22"`, `default-mode="resource-timeline"`, `default-scale="hour"`, `:resources="resources"`.

Example source: src/scheduler/__demos__/assignment-load.vue

```vue
<template>
  <c-space direction="column" block>
    <c-alert
      >每条日程可配置资源占用量和角色。两条各占 0.5 的日程恰好占满容量
      1；尝试新增一条可验证阻止或提醒策略。详情中可直接修改分配信息，资源表头显示本日峰值负载。</c-alert
    >
    <c-space
      ><c-button @click="policy = {}">超载时阻止</c-button
      ><c-button @click="policy = { capacity: 'warn' }">超载时提醒</c-button
      ><c-button @click="add">新增 0.5 占用</c-button></c-space
    >
    <c-scheduler
      ref="scheduler"
      v-model="events"
      default-date="2026-09-22"
      default-mode="resource-timeline"
      default-scale="hour"
      :resources="resources"
      :rule-policy="policy"
      show-assignment-details
      show-resource-load
      history
    />
  </c-space>
</template>
<script setup lang="ts">
import { ref } from "vue";
import type { SchedulerInstance } from "../index";
import type { SchedulerEvent, SchedulerRulePolicy } from "../core";
const scheduler = ref<SchedulerInstance>();
const resources = [{ id: "device", label: "实验设备", capacity: 1 }];
const policy = ref<SchedulerRulePolicy>({});
let sequence = 2;
const events = ref<SchedulerEvent[]>(
  [0, 1].map((i) => ({
    id: `load${i}`,
    title: `任务 ${i + 1}`,
    start: "2026-09-22T09:00:00",
    end: "2026-09-22T10:00:00",
    resourceIds: ["device"],
    resourceDetails: { device: { units: 0.5, role: i ? "协作" : "负责" } },
  })),
);
function add() {
  const id = sequence++;
  return scheduler.value?.change({
    type: "create",
    event: { ...events.value[0], id: `load${id}`, title: `任务 ${id + 1}` },
  });
}
</script>
```

### Virtual Resources

Preview configuration: `data-virtual-resources-demo`, `v-model:resource-filters="filters"`, `:resources="resources"`, `:resource-dimensions="dimensions"`.

Example source: src/scheduler/__demos__/virtual-resources.vue

```vue
<template>
  <c-space direction="column" block>
    <c-alert
      >100 个站 × 20 位人员，共 2000
      个组合行。滚动时只挂载附近的行；点击空白格新建，或在当前可见行之间拖动任务。编辑后保留滚动位置；拖到边缘可自动滚动到其他组合行。</c-alert
    >
    <c-space wrap>
      <c-button @click="filters = {}">全部 2000 行</c-button>
      <c-button @click="filters = { station: ['s0', 's1', 's2'] }"
        >前 3 个站</c-button
      >
      <c-button @click="filters = { person: ['p0'] }">仅人员 001</c-button>
      <c-tag>{{ events.length }} 条日程</c-tag>
    </c-space>
    <c-scheduler
      key="virtual-resources"
      data-virtual-resources-demo
      v-model="events"
      v-model:resource-filters="filters"
      :resources="resources"
      :resource-dimensions="dimensions"
      :resource-group-dimensions="['station', 'person']"
      :virtual-list-props="{ height: 480, buffer: 10, estimatedSize: 80 }"
      default-date="2026-09-22"
      default-mode="resource-timeline"
      default-scale="hour"
      history
    />
  </c-space>
</template>
<script setup lang="ts">
import { ref } from "vue";
import type {
  SchedulerResource,
  SchedulerEvent,
  SchedulerResourceFilters,
} from "../core";
const dimensions = [
  { id: "station", label: "站" },
  { id: "person", label: "人" },
];
const resources: SchedulerResource[] = [
  ...Array.from({ length: 100 }, (_, i) => ({
    id: `s${i}`,
    label: `站点 ${String(i + 1).padStart(3, "0")}`,
    dimensionId: "station",
  })),
  ...Array.from({ length: 20 }, (_, i) => ({
    id: `p${i}`,
    label: `人员 ${String(i + 1).padStart(3, "0")}`,
    dimensionId: "person",
  })),
];
const filters = ref<SchedulerResourceFilters>({});
const events = ref<SchedulerEvent[]>(
  Array.from({ length: 100 }, (_, i) => ({
    id: `task${i}`,
    title: `巡检 ${String(i + 1).padStart(3, "0")}`,
    start: "2026-09-22T09:00:00",
    end: "2026-09-22T10:00:00",
    resourceIds: [`s${i}`, `p${i % 20}`],
  })),
);
</script>
```

## Working hours and capacity

### Recurring and date-specific working hours

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `default-date` | Initial navigation date | Recurring and date-specific working hours, Maintenance, Resource Capacity |
| `default-mode` | Default uncontrolled view | Recurring and date-specific working hours, Maintenance, Resource Capacity |
| `resources` | Currently visible resource rows/columns and local options; a complete directory is unnecessary | Recurring and date-specific working hours, Maintenance, Resource Capacity |
| `resource-label` | Resource field name, such as equipment or meeting room | Recurring and date-specific working hours, Maintenance |
| `allow-overlap` | Allow overlapping times for the same resource | Recurring and date-specific working hours |
<!-- demo-config-notes:end -->


Compare recurring hours with date-specific overrides. Attempt creation or editing inside and outside available periods to inspect full-duration validation.

Example source: src/scheduler/__demos__/working-hours-comparison.vue

```vue
<script setup lang="ts">
import { ref } from "vue"
import type { SchedulerEvent } from "../core"
import type { SchedulerWorkingHours } from "../core"
import type { SchedulerDateWorkingHours } from "../core"
import { proxyRefs as demoProxyRefs } from 'vue'

const scene1 = demoProxyRefs((() => {

const rooms = [
  { id: "room-a", label: "会议室 A" },
  { id: "room-b", label: "会议室 B" },
];

const hours: SchedulerWorkingHours[] = [
  { daysOfWeek: [1, 2, 3, 4, 5], startMinute: 540, endMinute: 720 },
  { daysOfWeek: [1, 2, 3, 4, 5], startMinute: 780, endMinute: 1080 },
];

const events = ref<SchedulerEvent[]>([
  {
    id: "meeting",
    title: "产品评审",
    start: "2026-09-09T10:00:00",
    end: "2026-09-09T11:00:00",
    resourceIds: ["room-a"],
  },
]);
return { rooms, hours, events }
})())

const scene2 = demoProxyRefs((() => {

const enabled = ref(true);

const resources = [
  { id: "lin", label: "小林" },
  { id: "chen", label: "小陈" },
  { id: "device", label: "设备" },
];

const hours = [
  { daysOfWeek: [1, 2, 3, 4, 5], startMinute: 540, endMinute: 1080 },
];

const overrides: SchedulerDateWorkingHours[] = [
  { date: "2026-09-12", intervals: [{ startMinute: 540, endMinute: 720 }] },
  {
    date: "2026-09-12",
    resourceIds: ["lin"],
    intervals: [
      { startMinute: 600, endMinute: 720 },
      { startMinute: 780, endMinute: 900 },
    ],
  },
  { date: "2026-09-12", resourceIds: ["device"], intervals: [] },
  { date: "2026-09-30", intervals: [{ startMinute: 540, endMinute: 720 }] },
];

const events = ref<SchedulerEvent[]>([
  {
    id: "makeup",
    title: "补班协作任务",
    start: "2026-09-12T10:00:00",
    end: "2026-09-12T11:00:00",
    resourceIds: ["lin", "chen"],
  },
]);
return { enabled, resources, hours, overrides, events }
})())
</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="working-hours">
    <h4><span lang="zh-CN">工作时间与维护时段</span><span lang="en-US">working hours</span></h4>
    <c-space direction="column" block>
        <c-alert
          >会议室工作日 09:00–12:00、13:00–18:00
          可预约。灰色时段包含午休和非工作时间；新建、拖动和编辑均会校验完整时长。</c-alert
        >
        <c-scheduler
          v-model="scene1.events"
          default-date="2026-09-09"
          default-mode="resource-day"
          resource-label="会议室"
          :resources="scene1.rooms"
          :working-hours="scene1.hours"
          :allow-overlap="false"
        />
      </c-space>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="date-working-hours">
    <h4><span lang="zh-CN">指定日期工作时间</span><span lang="en-US">date working hours</span></h4>
    <c-space direction="column" block>
        <c-alert
          >模拟周六补班：公共时段 09:00–12:00；小林改为
          10:00–12:00、13:00–15:00；设备全天关闭。关闭开关后恢复周一至周五规则。已有任务保留，再次保存时重新校验。</c-alert
        >
        <c-checkbox v-model="scene2.enabled">启用指定日期时段</c-checkbox>
        <c-scheduler
          key="date-hours"
          v-model="scene2.events"
          default-date="2026-09-12"
          default-mode="resource-day"
          :resources="scene2.resources"
          :working-hours="scene2.hours"
          :date-working-hours="scene2.enabled ? scene2.overrides : []"
        />
      </c-space>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

### Maintenance

Preview configuration: `default-date="2026-09-09"`, `default-mode="resource-timeline"`, `default-scale="hour"`, `resource-label="设备"`.

Example source: src/scheduler/__demos__/maintenance.vue

```vue
<template>
  <c-space direction="column" block>
    <c-alert
      >设备 A 在 10:00–12:00 维护，设备 B
      不受影响。可关闭维护规则，对比可用时段及拖动保存结果。</c-alert
    >
    <c-checkbox v-model="maintenance">启用设备 A 维护时段</c-checkbox>
    <c-scheduler
      v-model="events"
      default-date="2026-09-09"
      default-mode="resource-timeline"
      default-scale="hour"
      resource-label="设备"
      :resources="equipment"
      :disabled-ranges="maintenance ? ranges : []"
    />
  </c-space>
</template>
<script setup lang="ts">
import { ref } from "vue";
import type { SchedulerEvent, SchedulerDisabledRange } from "../core";
const maintenance = ref(true);
const equipment = [
  { id: "a", label: "设备 A" },
  { id: "b", label: "设备 B" },
];
const ranges: SchedulerDisabledRange[] = [
  {
    id: "maintenance-a",
    start: "2026-09-09T10:00:00",
    end: "2026-09-09T12:00:00",
    resourceIds: ["a"],
    label: "设备 A 定期维护",
  },
];
const events = ref<SchedulerEvent[]>([
  {
    id: "inspection",
    title: "样品检测",
    start: "2026-09-09T09:00:00",
    end: "2026-09-09T10:00:00",
    resourceIds: ["a"],
  },
]);
</script>
```

### Resource Capacity

Preview configuration: `:status="span.exceeded ? 'danger' : 'success'"`, `default-date="2026-09-15"`, `default-mode="resource-timeline"`, `default-scale="hour"`.

Example source: src/scheduler/__demos__/resource-capacity.vue

```vue
<template>
  <c-space direction="column" block>
    <c-alert
      >检测设备默认可并行处理 2 个任务。09:00–11:00 与 10:00–12:00 的两单已占满
      10:00–11:00；尝试追加第三单，或提高容量后重试。降低容量保留已有日程，并在下方标出超额时段。</c-alert
    >
    <c-space wrap>
      <c-button @click="capacity = 1">容量设为 1</c-button>
      <c-button @click="capacity = 2">容量设为 2</c-button>
      <c-button @click="capacity = 3">容量设为 3</c-button>
      <c-button status="primary" @click="addThird">尝试追加第三单</c-button>
      <c-button @click="reset">重置容量示例</c-button>
      <c-tag>当前容量：{{ capacity }}</c-tag>
      <c-tag v-if="result">{{ result }}</c-tag>
    </c-space>
    <c-space direction="column" block>
      <c-tag
        v-for="span in load"
        :key="+span.start"
        :status="span.exceeded ? 'danger' : 'success'"
      >
        {{ format(span.start) }}–{{ format(span.end) }}：{{ span.load }}/{{
          span.capacity
        }}
        {{ span.exceeded ? "超出容量" : "容量内" }}
      </c-tag>
      <c-tag v-if="!load.length">当前可见范围没有占用</c-tag>
    </c-space>
    <c-scheduler
      key="resource-capacity"
      ref="scheduler"
      v-model="events"
      default-date="2026-09-15"
      default-mode="resource-timeline"
      default-scale="hour"
      :resources="resources"
      history
      @range-change="range = $event"
    >
      <template #resource-header="{ resource }">
        <c-space
          ><span>{{ resource?.label }}</span
          ><c-tag>容量 {{ resource?.capacity }}</c-tag></c-space
        >
      </template>
    </c-scheduler>
  </c-space>
</template>
<script setup lang="ts">
import { computed, ref } from "vue";
import type { SchedulerInstance } from "../index";
import type { SchedulerEvent } from "../core";
import {
  getSchedulerResourceLoad,
  getSchedulerRange,
  schedulerDateKey,
} from "../core";
const scheduler = ref<SchedulerInstance>();
const capacity = ref(2);
const resources = computed(() => [
  { id: "lab", label: "检测设备", capacity: capacity.value },
]);
const initial: SchedulerEvent[] = [
  {
    id: "sample-a",
    title: "样品甲",
    start: "2026-09-15T09:00:00",
    end: "2026-09-15T11:00:00",
    resourceIds: ["lab"],
  },
  {
    id: "sample-b",
    title: "样品乙",
    start: "2026-09-15T10:00:00",
    end: "2026-09-15T12:00:00",
    resourceIds: ["lab"],
  },
];
const events = ref<SchedulerEvent[]>([...initial]);
const range = ref(getSchedulerRange("2026-09-15", "day"));
const load = computed(() =>
  getSchedulerResourceLoad(events.value, resources.value[0], range.value),
);
const result = ref("");
const format = (date: Date) =>
  `${schedulerDateKey(date)} ${String(date.getHours()).padStart(2, "0")}:${String(date.getMinutes()).padStart(2, "0")}`;
async function addThird() {
  if (events.value.some((event) => event.id === "sample-c")) {
    result.value = "第三单已存在，可撤销或重置后重试";
    return;
  }
  const saved = await scheduler.value?.change({
    type: "create",
    event: {
      id: "sample-c",
      title: "样品丙",
      start: "2026-09-15T10:30:00",
      end: "2026-09-15T11:00:00",
      resourceIds: ["lab"],
    },
  });
  result.value = saved ? "第三单已保存" : "第三单未保存：超出容量";
}
function reset() {
  events.value = [...initial];
  capacity.value = 2;
  result.value = "";
  scheduler.value?.goToDate(new Date(2026, 8, 15));
}
</script>
```

## Recurrence and calendars

### Recurring Events

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `default-mode` | Default uncontrolled view | Recurring Events, Calendar Recurrence, Business Calendar |
| `default-date` | Initial navigation date | Recurring Events, Business Calendar, Recurrence Following |
| `model-value` | Schedule data; supports v-model and becomes controlled when provided | Calendar Recurrence, Recurrence Following, Zoned Recurrence |
| `readonly` | Viewing/navigation allowed, editing blocked | Calendar Recurrence, Recurrence Following, Zoned Recurrence |
| `resources` | Currently visible resource rows/columns and local options; a complete directory is unnecessary | Recurring Events |
| `date` | Navigation date; supports v-model:date | Calendar Recurrence |
<!-- demo-config-notes:end -->


Preview configuration: `:options="frequencies"`, `aria-label="重复频率"`, `:min="1"`, `:max="12"`.

Example source: src/scheduler/__demos__/recurring-events.vue

```vue
<template>
  <c-space direction="column" block>
    <c-alert
      >重复会议按可见范围展开。编辑、拖动或删除卡片只影响这一次；新建日程是独立安排。修改上方规则会重建系列并清除本例中的例外。</c-alert
    >
    <c-space wrap>
      <c-select
        v-model="frequency"
        :options="frequencies"
        aria-label="重复频率"
      />
      <c-input-number
        v-model="interval"
        :min="1"
        :max="12"
        aria-label="重复间隔"
      />
      <c-tag>{{
        frequency === "daily" ? "天一次" : "周一次（周一、三、五）"
      }}</c-tag>
      <c-input-number
        v-model="count"
        :min="1"
        :max="60"
        aria-label="重复次数"
      />
      <c-tag>次后结束</c-tag>
      <c-button :disabled="!exceptions.length" @click="exceptions = []"
        >恢复全部例外</c-button
      >
    </c-space>
    <c-tag
      >{{ exceptions.length }} 条本次例外 ·
      {{ standalone.length }} 条独立安排</c-tag
    >
    <c-scheduler
      v-model="events"
      default-date="2026-09-09"
      default-mode="week"
      :resources="resources"
      :before-transaction="validateChange"
      @range-change="range = $event"
    >
      <template #event="{ event }">
        {{ event.title }}
        <c-tag v-if="occurrenceIds.has(event.id)" size="small"
          >重复 · 仅本次</c-tag
        >
      </template>
    </c-scheduler>
  </c-space>
</template>
<script setup lang="ts">
import { computed, ref, watch } from "vue";
import {
  SchedulerError,
  applySchedulerChange,
  diffSchedulerEvents,
  expandSchedulerRecurrences,
  getSchedulerRange,
  setSchedulerRecurrenceException,
} from "../core";
import type {
  SchedulerEvent,
  SchedulerRecurrenceException,
  SchedulerRecurrenceRule,
  SchedulerRecurringEvent,
} from "../core";
import type { SchedulerBeforeTransaction } from "../props";
const validateChange: SchedulerBeforeTransaction = ({ changes }) => {
  if (
    changes.some(
      (change) =>
        occurrenceIds.value.has(change.event.id) &&
        change.type !== "remove" &&
        change.event.start == null,
    )
  ) {
    throw new SchedulerError(
      "invalid-event",
      "重复实例必须保留排期；取消本次请使用删除",
    );
  }
};
const frequencies = [
  { label: "每天", value: "daily" },
  { label: "每周", value: "weekly" },
];
const frequency = ref<SchedulerRecurrenceRule["frequency"]>("weekly");
const interval = ref(1);
const count = ref(12);
const range = ref(getSchedulerRange("2026-09-09", "week"));
const resources = [
  { id: "design", label: "林夏 · 设计" },
  { id: "dev", label: "陈舟 · 前端" },
];
const exceptions = ref<SchedulerRecurrenceException[]>([]);
const standalone = ref<SchedulerEvent[]>([]);
const series = computed<SchedulerRecurringEvent[]>(() => [
  {
    event: {
      id: "weekly-review",
      title: "项目同步会",
      start: "2026-09-07T09:00:00",
      end: "2026-09-07T10:00:00",
      resourceIds: ["design", "dev"],
    },
    rule: {
      frequency: frequency.value,
      interval: interval.value || 1,
      count: count.value || 1,
      daysOfWeek: frequency.value === "weekly" ? [1, 3, 5] : undefined,
    },
  },
]);
watch([frequency, interval, count], () => {
  exceptions.value = [];
});
const occurrences = computed(() =>
  expandSchedulerRecurrences(series.value, range.value, {
    exceptions: exceptions.value,
  }),
);
const occurrenceIds = computed(
  () => new Set(occurrences.value.map((event) => event.id)),
);
const events = computed<SchedulerEvent[]>({
  get: () => [...occurrences.value, ...standalone.value],
  set: (next) => {
    const previous = [...occurrences.value, ...standalone.value];
    const originals = new Map(
      occurrences.value.map((event) => [event.id, event]),
    );
    let nextExceptions = exceptions.value;
    let nextStandalone = standalone.value;
    for (const change of diffSchedulerEvents(previous, next)) {
      const original = originals.get(change.event.id);
      if (original)
        nextExceptions = setSchedulerRecurrenceException(
          nextExceptions,
          original,
          change.type === "remove" ? undefined : change.event,
        );
      else nextStandalone = applySchedulerChange(nextStandalone, change);
    }
    // A real backend saves these series/exception records atomically, not expanded instances.
    exceptions.value = nextExceptions;
    standalone.value = nextStandalone;
  },
});
</script>
```

### Calendar Recurrence

- `readonly`: Displays the current value without allowing edits.

Example source: src/scheduler/__demos__/calendar-recurrence.vue

```vue
<template>
  <c-space direction="column" block>
    <c-alert
      >按月、按年安排任务。无效日期可选择跳过或落到月底；“最后一个工作日”仅按周一至周五计算，不包含节假日调休。</c-alert
    >
    <c-space direction="column" align="stretch" wrap>
      <c-form-item layout="vertical" size="sm" label="月年重复规则">
        <c-radio-group
          v-model="preset"
          aria-label="月年重复规则"
          :options="presets"
          variant="button"
          size="sm"
        />
      </c-form-item>
      <c-input-number
        v-model="interval"
        :min="1"
        :max="12"
        aria-label="月年重复间隔"
      />
      <c-tag>{{ preset === "leap" ? "年一次" : "个月一次" }}</c-tag>
      <c-input-number
        v-model="count"
        :min="1"
        :max="10"
        aria-label="月年重复次数"
      />
      <c-tag>次后结束</c-tag>
      <c-checkbox
        v-if="preset === 'day31' || preset === 'leap'"
        v-model="lastDay"
        >缺少该日期时落到月底</c-checkbox
      >
    </c-space>
    <c-tag>未来 40 年内的前 {{ preview.length }} 次安排（点日期定位）</c-tag>
    <c-space wrap>
      <c-button
        v-for="item in preview"
        :key="item.id"
        @click="date = schedulerDate(item.start!)"
        >{{ schedulerDateKey(item.start!) }}</c-button
      >
    </c-space>
    <c-scheduler
      key="calendar-recurrence-preview"
      v-model:date="date"
      :model-value="events"
      default-mode="month"
      readonly
      @range-change="range = $event"
    />
  </c-space>
</template>
<script setup lang="ts">
import { computed, ref, watch } from "vue";
import {
  expandSchedulerRecurrences,
  getSchedulerRange,
  schedulerDate,
  schedulerDateKey,
} from "../core";
import type { SchedulerDate, SchedulerRecurringEvent } from "../core";
const preset = ref("day31");
const interval = ref(1);
const count = ref(6);
const lastDay = ref(false);
const presets = [
  { label: "每月 31 日", value: "day31" },
  { label: "每月最后一个工作日", value: "weekday" },
  { label: "每月第二个星期一", value: "monday" },
  { label: "每年 2 月 29 日", value: "leap" },
];
const date = ref<SchedulerDate>("2026-01-31");
const range = ref(getSchedulerRange(date.value, "month"));
watch(preset, () => {
  date.value = preset.value === "leap" ? "2024-02-29" : "2026-01-01";
});
const series = computed<SchedulerRecurringEvent[]>(() => {
  const start =
    preset.value === "leap"
      ? "2024-02-29"
      : preset.value === "day31"
        ? "2026-01-31"
        : "2026-01-01";
  return [
    {
      event: {
        id: "calendar-plan",
        title: presets.find((item) => item.value === preset.value)!.label,
        start: `${start}T09:00:00`,
        end: `${start}T10:00:00`,
      },
      rule: {
        frequency: preset.value === "leap" ? "yearly" : "monthly",
        interval: interval.value || 1,
        count: count.value || 1,
        ...(preset.value === "weekday"
          ? { weekOfMonth: -1, daysOfWeek: [1, 2, 3, 4, 5] }
          : preset.value === "monday"
            ? { weekOfMonth: 2, daysOfWeek: [1] }
            : {
                overflow: lastDay.value
                  ? ("last-day" as const)
                  : ("skip" as const),
              }),
      },
    },
  ];
});
const events = computed(() =>
  expandSchedulerRecurrences(series.value, range.value),
);
const preview = computed(() => {
  const start = schedulerDate(series.value[0].event.start!);
  const end = new Date(start);
  end.setFullYear(end.getFullYear() + 40);
  return expandSchedulerRecurrences(series.value, { start, end }).slice(0, 10);
});
</script>
```

### Business Calendar

Preview configuration: `default-date="2026-02-26"`, `default-mode="week"`, `:working-hours="hours"`, `:disabled-ranges="blocked"`.

Example source: src/scheduler/__demos__/business-calendar.vue

```vue
<template>
  <c-space direction="column" block>
    <c-alert
      >以下日期均为模拟企业日历，不是官方放假通知。示例包含模拟春节休假、周末补班和月末企业休假；同一配置用于月末工作日计算和预约校验。</c-alert
    >
    <c-checkbox v-model="enabled">启用模拟休假与补班</c-checkbox>
    <c-space wrap
      ><c-tag v-for="item in settlements" :key="item.id"
        >结算日：{{ schedulerDateKey(item.start!) }}</c-tag
      ></c-space
    >
    <c-tag
      >2 月 27 日企业休假、28
      日周六补班。可尝试新增或移动任务，对比开关前后的保存结果。</c-tag
    >
    <c-scheduler
      key="business-calendar-bookings"
      v-model="bookings"
      default-date="2026-02-26"
      default-mode="week"
      :working-hours="hours"
      :disabled-ranges="blocked"
      :before-transaction="validateCalendar"
      @range-change="range = $event"
    />
  </c-space>
</template>
<script setup lang="ts">
import { computed, ref } from "vue";
import {
  expandSchedulerRecurrences,
  getSchedulerAvailabilityIssues,
  getSchedulerRange,
  schedulerDate,
  schedulerDateKey,
  SchedulerError,
} from "../core";
import { getSchedulerCalendarDisabledRanges } from "../core/business-calendar";
import type { SchedulerBusinessCalendar, SchedulerEvent } from "../core";
import type { SchedulerBeforeTransaction } from "../props";
const enabled = ref(true);
const range = ref(getSchedulerRange("2026-02-26", "week"));
const overrides: NonNullable<SchedulerBusinessCalendar["overrides"]> = [
  ...[16, 17, 18, 19, 20].map((day) => ({
    date: `2026-02-${day}`,
    working: false,
    label: "模拟春节休假",
  })),
  { date: "2026-02-14", working: true, label: "模拟补班" },
  { date: "2026-02-27", working: false, label: "企业休假" },
  { date: "2026-02-28", working: true, label: "模拟补班" },
];
const calendar = computed<SchedulerBusinessCalendar>(() => ({
  overrides: enabled.value ? overrides : [],
}));
// Calendar decides which dates work; hours separately decide when those dates work.
const hours = [
  { daysOfWeek: [0, 1, 2, 3, 4, 5, 6], startMinute: 540, endMinute: 1080 },
];
const blocked = computed(() =>
  getSchedulerCalendarDisabledRanges(calendar.value, range.value),
);
const bookings = ref<SchedulerEvent[]>([
  {
    id: "regular-job",
    title: "常规工作日任务",
    start: "2026-02-26T10:00:00",
    end: "2026-02-26T11:00:00",
  },
]);
const settlements = computed(() =>
  expandSchedulerRecurrences(
    [
      {
        event: {
          id: "settlement",
          title: "月末结算",
          start: "2026-02-01T09:00:00",
          end: "2026-02-01T10:00:00",
        },
        rule: {
          frequency: "monthly",
          weekOfMonth: -1,
          businessCalendar: calendar.value,
          count: 3,
        },
      },
    ],
    { start: new Date(2026, 1, 1), end: new Date(2026, 4, 1) },
  ),
);
const validateCalendar: SchedulerBeforeTransaction = ({ changes }) => {
  for (const change of changes) {
    if (
      change.type === "remove" ||
      change.event.start == null ||
      change.event.end == null
    )
      continue;
    // Editor changes can extend outside the visible window: validate the full proposal.
    const disabledRanges = getSchedulerCalendarDisabledRanges(calendar.value, {
      start: schedulerDate(change.event.start),
      end: schedulerDate(change.event.end),
    });
    const issues = getSchedulerAvailabilityIssues(change.event, {
      disabledRanges,
    });
    if (issues.length)
      throw new SchedulerError("unavailable", "日程包含非工作日", issues);
  }
};
</script>
```

### Recurrence Following

- `readonly`: Displays the current value without allowing edits.

Example source: src/scheduler/__demos__/recurrence-following.vue

```vue
<template>
  <c-space direction="column" block>
    <c-alert
      >点击会议选择“仅本次”或“本次及以后”。周五预设了一条“客户参会”例外：默认保护它，明确选择清除后才允许拆分。修改日期时需保留原规则的星期。</c-alert
    >
    <c-space wrap>
      <c-button @click="reset">重置示例</c-button>
      <c-checkbox v-model="reject">模拟保存失败</c-checkbox>
      <c-tag
        >{{ state.series.length }} 个系列 ·
        {{ state.exceptions.length }} 条例外</c-tag
      >
    </c-space>
    <c-space wrap>
      <c-tag v-for="item in state.series" :key="item.event.id"
        >{{ item.event.title }} · {{ item.rule.count ?? "不限" }} 次</c-tag
      >
    </c-space>
    <c-tag>{{ status }}</c-tag>
    <c-scheduler
      key="recurrence-following-calendar"
      :model-value="events"
      default-date="2026-09-09"
      default-mode="week"
      readonly
      :editable="false"
      @range-change="range = $event"
      @event-click="openEditor"
    />
    <c-dialog v-model:open="open" title="调整重复安排" :footer="false">
      <c-form
        v-if="draft"
        :model="draft"
        layout="vertical"
        @submit="save(false)"
      >
        <c-form-item label="修改范围">
          <c-select v-model="scope" :options="scopes" aria-label="修改范围" />
        </c-form-item>
        <c-form-item v-if="scope === 'following'" label="后续例外">
          <c-select
            v-model="policy"
            :options="policies"
            aria-label="后续例外处理"
          />
        </c-form-item>
        <c-form-item label="会议标题"
          ><c-input v-model="draft.title" aria-label="会议标题"
        /></c-form-item>
        <c-form-item label="开始时间"
          ><c-date
            v-model="draft.start"
            show-time
            value-format="Date"
            aria-label="会议开始"
        /></c-form-item>
        <c-form-item label="结束时间"
          ><c-date
            v-model="draft.end"
            show-time
            value-format="Date"
            aria-label="会议结束"
        /></c-form-item>
        <c-alert v-if="error" status="danger">{{ error }}</c-alert>
        <c-space wrap>
          <c-button status="primary" @click="save(false)">保存修改</c-button>
          <c-button @click="save(true)">取消所选安排</c-button>
          <c-button @click="open = false">返回</c-button>
        </c-space>
      </c-form>
    </c-dialog>
  </c-space>
</template>
<script setup lang="ts">
import { computed, ref, shallowRef } from "vue";
import {
  cloneSchedulerEvent,
  expandSchedulerRecurrences,
  getSchedulerRange,
  schedulerDate,
  setSchedulerRecurrenceException,
  splitSchedulerRecurrence,
} from "../core";
import type {
  SchedulerEvent,
  SchedulerOccurrence,
  SchedulerRecurringEvent,
  SchedulerRecurrenceException,
} from "../core";
const range = ref(getSchedulerRange("2026-09-09", "week"));
function initialState(): {
  series: SchedulerRecurringEvent[];
  exceptions: SchedulerRecurrenceException[];
} {
  const series: SchedulerRecurringEvent[] = [
    {
      event: {
        id: "team-sync",
        title: "团队同步会",
        start: "2026-09-07T09:00:00",
        end: "2026-09-07T10:00:00",
      },
      rule: { frequency: "weekly", daysOfWeek: [1, 3, 5], count: 9 },
    },
  ];
  const friday = expandSchedulerRecurrences(
    series,
    getSchedulerRange("2026-09-09", "week"),
  )[2];
  return {
    series,
    exceptions: setSchedulerRecurrenceException([], friday, {
      ...friday,
      title: "客户参会",
    }),
  };
}
const state = shallowRef(initialState());
const events = computed(() =>
  expandSchedulerRecurrences(state.value.series, range.value, {
    exceptions: state.value.exceptions,
  }),
);
const open = ref(false);
const reject = ref(false);
const scope = ref<"single" | "following">("single");
const policy = ref<"reject" | "discard">("reject");
const scopes = [
  { label: "仅本次", value: "single" },
  { label: "本次及以后", value: "following" },
];
const policies = [
  { label: "保护已有例外", value: "reject" },
  { label: "清除后续例外", value: "discard" },
];
const selected = shallowRef<SchedulerOccurrence>();
const draft = ref<{ title: string; start: Date; end: Date }>();
const error = ref("");
const status = ref("点击日程调整安排");
let baseline = state.value;
let nextId = 0;
function openEditor(event: SchedulerEvent) {
  const occurrence = events.value.find((item) => item.id === event.id);
  if (!occurrence) return;
  selected.value = { ...occurrence };
  draft.value = {
    title: occurrence.title,
    start: schedulerDate(occurrence.start!),
    end: schedulerDate(occurrence.end!),
  };
  scope.value = "single";
  policy.value = "reject";
  error.value = "";
  baseline = state.value;
  open.value = true;
}
function save(remove: boolean) {
  if (!selected.value || !draft.value) return;
  error.value = "";
  try {
    if (state.value !== baseline)
      throw new Error("安排已变化，请关闭后重新打开。");
    const replacement = {
      ...cloneSchedulerEvent(selected.value),
      ...draft.value,
    };
    let proposal: typeof state.value;
    let discarded = 0;
    if (scope.value === "following") {
      const affected = state.value.exceptions.filter(
        (item) =>
          item.seriesId === selected.value!.seriesId &&
          +schedulerDate(item.originalStart) >=
            +schedulerDate(selected.value!.originalStart),
      );
      if (affected.length && policy.value === "reject")
        throw new Error(
          `后续有 ${affected.length} 条例外，请选择清除后续例外或仅修改本次。`,
        );
      const result = splitSchedulerRecurrence(
        state.value.series,
        state.value.exceptions,
        selected.value,
        {
          nextEvent: remove
            ? undefined
            : { ...replacement, id: `team-sync-part-${nextId + 1}` },
          exceptionPolicy: policy.value,
        },
      );
      proposal = { series: result.series, exceptions: result.exceptions };
      discarded = result.removedExceptions.length;
    } else
      proposal = {
        series: state.value.series,
        exceptions: setSchedulerRecurrenceException(
          state.value.exceptions,
          selected.value,
          remove ? undefined : replacement,
        ),
      };
    // Save this complete canonical proposal atomically before publishing the projection.
    if (reject.value) throw new Error("模拟保存失败，原系列和例外均保留。");
    state.value = proposal;
    nextId++;
    status.value = `${remove ? "已取消" : "已修改"}${scope.value === "following" ? "本次及以后" : "本次"}；清除 ${discarded} 条后续例外`;
    open.value = false;
  } catch (cause) {
    error.value = cause instanceof Error ? cause.message : "保存失败";
  }
}
function reset() {
  state.value = initialState();
  open.value = false;
  status.value = "点击日程调整安排";
  reject.value = false;
}
</script>
```

### Zoned Recurrence

- `readonly`: Displays the current value without allowing edits.

Example source: src/scheduler/__demos__/zoned-recurrence.vue

```vue
<template>
  <c-space direction="column" block>
    <c-alert
      >每周一纽约时间 09:00，跨越夏令时切换后 UTC 时间会变化。RRULE
      由独立适配器解析，结果保留真实时间点；议程卡片同时展示所选时区时间。</c-alert
    >
    <c-space
      ><c-button @click="zone = 'America/New_York'">纽约时间</c-button
      ><c-button @click="zone = 'Asia/Shanghai'">上海时间</c-button
      ><c-tag>{{ zone }}</c-tag></c-space
    >
    <c-scheduler
      :model-value="events"
      default-date="2026-03-09"
      default-mode="agenda"
      readonly
    >
      <template #event="{ event }"
        >{{ event.title }} ·
        {{ formatSchedulerZonedDate(event.start, zone) }}</template
      >
    </c-scheduler>
  </c-space>
</template>
<script setup lang="ts">
import { ref } from "vue";
import { expandSchedulerRRule, formatSchedulerZonedDate } from "../adapters";
const zone = ref("America/New_York");
const events = expandSchedulerRRule(
  {
    event: {
      id: "ny",
      title: "纽约例会",
      start: "2026-03-02T14:00:00Z",
      end: "2026-03-02T15:00:00Z",
    },
    timeZone: "America/New_York",
    rule: "FREQ=WEEKLY;BYDAY=MO;COUNT=4",
  },
  { start: new Date("2026-03-01"), end: new Date("2026-04-01") },
);
</script>
```

## Editing and interaction

### Drag Feedback

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `default-date` | Initial navigation date | Drag Feedback, Duplicate Events, Custom Cards |
| `default-mode` | Default uncontrolled view | Drag Feedback, Duplicate Events, Custom Event |
| `resources` | Currently visible resource rows/columns and local options; a complete directory is unnecessary | Drag Feedback, Duplicate Events, Custom Cards |
| `before-change` | Return false to cancel; supports asynchronous interception and save APIs | Custom Event, Custom Editor, External Editor |
| `resource-label` | Resource field name, such as equipment or meeting room | Drag Feedback |
| `start-hour` | Time-grid start hour, 0–23 | Drag Feedback |
<!-- demo-config-notes:end -->


- `step`: Controls the allowed increment.

Example source: src/scheduler/__demos__/drag-feedback.vue

```vue
<template>
  <section class="scheduler-drag-demo">
    <p>
      拖动日程主体查看虚影和目标预览；拖上边缘调整开始，拖下边缘调整结束。按
      Escape 取消，松手才提交。
    </p>
    <c-scheduler
      v-model="events"
      default-date="2026-09-09"
      default-mode="resource-day"
      :resources="resources"
      resource-label="工作台"
      :start-hour="8"
      :end-hour="16"
      :step="15"
      :show-sidebar="false"
      style="--c-scheduler-max-height: 560px"
    >
      <template #event="{ event }">
        <strong>{{ event.title }}</strong
        ><br />
        <span>{{ event.description }}</span>
      </template>
    </c-scheduler>
    <c-button @click="events = createEvents()">重置日程</c-button>
    <ul aria-label="已提交日程">
      <li v-for="event in events" :key="event.id" :data-demo-event="event.id">
        {{ event.title }}：{{ event.start }} → {{ event.end }}；资源：{{
          event.resourceIds?.join(", ") || "无"
        }}
      </li>
    </ul>
  </section>
</template>
<script setup lang="ts">
import { ref } from "vue";
import type { SchedulerEvent, SchedulerResource } from "@cedar-design/ui";
const resources: SchedulerResource[] = [
  { id: "a", label: "工作台 A" },
  { id: "b", label: "工作台 B" },
];
function createEvents(): SchedulerEvent[] {
  return [
    {
      id: "design",
      title: "方案制作",
      description: "自定义卡片内容也会出现在虚影中",
      start: "2026-09-09T09:00:00",
      end: "2026-09-09T10:30:00",
      resourceIds: ["a"],
    },
    {
      id: "review",
      title: "验收检查",
      description: "试着拖动上边缘或下边缘",
      start: "2026-09-09T11:00:00",
      end: "2026-09-09T12:00:00",
      resourceIds: ["b"],
    },
  ];
}
const events = ref(createEvents());
</script>
```

### Duplicate Events

Preview configuration: `default-date="2026-09-16"`, `default-mode="week"`, `:resources="resources"`, `:before-transaction="persist"`.

Example source: src/scheduler/__demos__/duplicate-events.vue

```vue
<template>
  <c-space direction="column" block>
    <c-alert
      >点击日程详情中的“复制日程”，或使用下方按钮。副本取自已保存数据，生成新编号，尚未保存的表单修改不会带入。保存前可调整时间和人员；取消不创建日程。会议室容量为
      2，可体验第三条同时预约被拦截。</c-alert
    >
    <c-space wrap>
      <c-button @click="scheduler?.duplicateEvent('review')"
        >复制评审会议</c-button
      >
      <c-button @click="scheduler?.duplicateEvent('all-day')"
        >复制全天任务</c-button
      >
      <c-button @click="scheduler?.duplicateEvent('backlog')"
        >复制未排期任务</c-button
      >
      <c-checkbox v-model="reject">下一次副本保存失败</c-checkbox>
      <c-tag>已保存 {{ events.length }} 条日程</c-tag>
    </c-space>
    <c-scheduler
      key="duplicate-events"
      ref="scheduler"
      v-model="events"
      default-date="2026-09-16"
      default-mode="week"
      :resources="resources"
      :before-transaction="persist"
      history
    />
  </c-space>
</template>
<script setup lang="ts">
import { ref } from "vue";
import type { SchedulerInstance } from "../index";
import type { SchedulerEvent } from "../core";
import type { SchedulerBeforeTransaction } from "../props";
const scheduler = ref<SchedulerInstance>();
const reject = ref(false);
const resources = [{ id: "room", label: "协作会议室", capacity: 2 }];
const events = ref<SchedulerEvent[]>([
  {
    id: "review",
    title: "设计方案评审",
    start: "2026-09-16T10:00:00",
    end: "2026-09-16T11:00:00",
    resourceIds: ["room"],
    description: "讨论方案与任务分配",
    metadata: { taskId: "design" },
  },
  {
    id: "all-day",
    title: "资料整理日",
    start: "2026-09-17",
    end: "2026-09-18",
    allDay: true,
  },
  {
    id: "backlog",
    title: "待安排的用户访谈",
    description: "确认参与人员后安排时间",
  },
]);
const persist: SchedulerBeforeTransaction = async () => {
  const shouldReject = reject.value;
  if (shouldReject) reject.value = false;
  await new Promise((resolve) => setTimeout(resolve, 200));
  if (shouldReject) throw new Error("Simulated save failure");
};
</script>
```

### Event Dialog

Example source: src/scheduler/__demos__/event-dialog.vue

```vue
<template><EventDetailsExample /></template>
<script setup lang="ts">
import EventDetailsExample from "./event-details-example.vue";
</script>
```

### Event Popover

Example source: src/scheduler/__demos__/event-popover.vue

```vue
<template><EventDetailsExample preview /></template>
<script setup lang="ts">
import EventDetailsExample from "./event-details-example.vue";
</script>
```

### Custom Cards

Preview configuration: `default-date="2026-09-09"`, `:resources="resources"`.

Example source: src/scheduler/__demos__/custom-cards.vue

```vue
<template>
  <c-scheduler
    v-model="events"
    default-date="2026-09-09"
    :resources="resources"
  >
    <template #sidebar-extra="{ startDrag, cancelDrag, disabled }">
      <strong>自定义卡片</strong>
      <p>拖到右侧日期或时间格，确认后新增。卡片可重复使用。</p>
      <c-button
        v-for="card in cards"
        :key="card.title"
        class="scheduler-template-card"
        :disabled="disabled"
        :draggable="!disabled"
        @dragstart="startDrag(card, $event)"
        @dragend="cancelDrag"
      >
        <strong>{{ card.title }}</strong>
        <span>{{ card.description }} · {{ card.duration }} 分钟</span>
      </c-button>
    </template>
  </c-scheduler>
</template>
<script setup lang="ts">
import { ref } from "vue";
import type { SchedulerEvent, SchedulerEventTemplate } from "@cedar-design/ui";
import { resources } from "./data";
const events = ref<SchedulerEvent[]>([]);
const cards: SchedulerEventTemplate[] = [
  {
    title: "需求评审",
    description: "确认目标和验收标准",
    duration: 60,
    metadata: { taskId: "review" },
  },
  {
    title: "客户沟通",
    description: "记录反馈与后续安排",
    duration: 30,
    metadata: { taskId: "call" },
  },
  {
    title: "专注工作",
    description: "预留不被打扰的时段",
    duration: 90,
    metadata: { taskId: "focus" },
  },
];
</script>
<style scoped>
.scheduler-template-card {
  display: flex;
  flex-direction: column;
  gap: 8px;
  padding: 12px;
  text-align: left;
  border: 1px solid var(--c-color-border);
  border-radius: 8px;
  color: var(--c-color-text-1);
  background: var(--c-color-bg-2);
  cursor: grab;
}
.scheduler-template-card:disabled {
  cursor: not-allowed;
  opacity: 0.5;
}
.scheduler-template-card span {
  color: var(--c-color-text-2);
}
</style>
```

### Custom Event

Preview configuration: `default-date="2026-09-09"`, `default-mode="week"`, `:resources="resources"`.

Example source: src/scheduler/__demos__/custom-event.vue

```vue
<template>
  <c-alert>
    这里的工作、会议、休息和不可用时段都是 Demo 自己定义的业务类型，并非
    Scheduler
    内置枚举。新增时可选择类型，由业务配置映射标题建议、外观和默认权限。
  </c-alert>
  <c-space>
    <c-checkbox v-model="rejectSave">模拟后端保存失败</c-checkbox>
    <span>{{ requestStatus }}</span>
  </c-space>
  <c-loading :loading="loading" style="display: block">
  <c-scheduler
    :readonly="loading"
    v-model="events"
    default-date="2026-09-09"
    default-mode="week"
    :resources="resources"
    :before-change="saveToMockServer"
  >
    <template #event="{ event }">
      <span>{{ event.title }}</span>
      <c-tag size="sm" :status="event.readonly ? 'neutral' : 'info'">
        {{ typeOf(event).label }} · {{ event.readonly ? "只读" : "可编辑" }}
      </c-tag>
    </template>

    <template
      #editor="{
        action,
        event,
        save,
        remove,
        close,
        readonly,
        pending,
        errorMessage,
      }"
    >
      <h3>{{ action === "create" ? "新增日程" : "编辑日程" }}</h3>
      <c-alert v-if="errorMessage" status="danger">
        {{ errorMessage }}
      </c-alert>
      <c-form
        :model="event"
        layout="vertical"
        @submit="prepareAndSave(event, save)"
      >
        <c-form-item label="日程类型">
          <c-select
            :model-value="typeOf(event).id"
            :disabled="readonly || pending"
            @update:model-value="applyType(event, $event)"
          >
            <c-option
              v-for="type in eventTypes"
              :key="type.id"
              :value="type.id"
            >
              {{ type.label }} · {{ type.readonly ? "默认只读" : "默认可编辑" }}
            </c-option>
          </c-select>
        </c-form-item>

        <div class="scheduler-type-preview" :style="previewStyle(event)">
          <strong>{{ typeOf(event).label }}</strong>
          <span>{{ typeOf(event).description }}</span>
        </div>

        <c-form-item label="标题">
          <c-input
            v-model="event.title"
            :disabled="readonly || pending"
            placeholder="请输入日程标题"
          />
        </c-form-item>
        <c-form-item label="开始时间">
          <c-date
            :model-value="
              event.start == null ? undefined : schedulerDate(event.start)
            "
            :disabled="readonly || pending"
            show-time
            value-format="Date"
            @update:model-value="event.start = $event"
          />
        </c-form-item>
        <c-form-item label="结束时间">
          <c-date
            :model-value="
              event.end == null ? undefined : schedulerDate(event.end)
            "
            :disabled="readonly || pending"
            show-time
            value-format="Date"
            @update:model-value="event.end = $event"
          />
        </c-form-item>
        <c-form-item>
          <c-checkbox
            :model-value="!event.readonly"
            :disabled="readonly || pending"
            @update:model-value="event.readonly = !$event"
          >
            创建后允许修改和拖拽
          </c-checkbox>
        </c-form-item>
        <c-space>
          <c-button :disabled="pending" @click="close">取消</c-button>
          <c-button
            v-if="action === 'edit' && !readonly"
            status="danger"
            :disabled="pending"
            @click="remove"
            >删除</c-button
          >
          <c-button
            v-if="!readonly"
            html-type="submit"
            status="primary"
            :loading="pending"
            >保存日程</c-button
          >
        </c-space>
      </c-form>
    </template>
  </c-scheduler>
  </c-loading>
  <c-collapse class="scheduler-mock-log">
    <c-collapse-item name="request" title="查看最近一次 Mock API 请求">
      <pre>{{ lastRequest || "尚未提交" }}</pre>
    </c-collapse-item>
  </c-collapse>
</template>

<script setup lang="ts">
import { onMounted, ref } from "vue";
import { resources } from "./data";
import { cloneSchedulerEvent, schedulerDate } from "../core";
import type {
  SchedulerBeforeChange,
  SchedulerEvent,
  SchedulerEventBackgroundPattern,
} from "../index";

type EventType = {
  id: string;
  label: string;
  description: string;
  title: string;
  color: string;
  backgroundColor: string;
  backgroundPattern: SchedulerEventBackgroundPattern;
  readonly: boolean;
};

const eventTypes: EventType[] = [
  {
    id: "work",
    label: "工作安排",
    description: "普通任务，可继续编辑和拖拽调整时间。",
    title: "工作安排",
    color: "#1677ff",
    backgroundColor: "#e6f4ff",
    backgroundPattern: "solid",
    readonly: false,
  },
  {
    id: "meeting",
    label: "会议",
    description: "用圆点背景区分协作和沟通类日程。",
    title: "会议",
    color: "#d48806",
    backgroundColor: "#fffbe6",
    backgroundPattern: "dots",
    readonly: false,
  },
  {
    id: "rest",
    label: "休息",
    description: "休息时段默认锁定，保存后不允许修改或拖拽。",
    title: "休息",
    color: "#00a854",
    backgroundColor: "#f0fff4",
    backgroundPattern: "diagonal-stripes",
    readonly: true,
  },
  {
    id: "blocked",
    label: "不可用时段",
    description: "用于停机、封场等占用，默认只读。",
    title: "不可用时段",
    color: "#722ed1",
    backgroundColor: "#f9f0ff",
    backgroundPattern: "crosshatch",
    readonly: true,
  },
];

const seedEvents: SchedulerEvent[] = [
  createEvent("work", "work-1", "需求评审", "09:00", "10:30"),
  createEvent("meeting", "meeting-1", "项目周会", "10:00", "11:30"),
  createEvent("rest", "rest-1", "张志强 休息", "13:00", "15:00"),
  createEvent("blocked", "blocked-1", "会议室维护", "15:30", "17:30"),
];
const events = ref<SchedulerEvent[]>([]);
const loading = ref(true);
const rejectSave = ref(false);
const requestStatus = ref("正在从 Mock API 加载…");
const lastRequest = ref("");
let mockDatabase = seedEvents.map(cloneSchedulerEvent);

const wait = (milliseconds: number) =>
  new Promise((resolve) => setTimeout(resolve, milliseconds));
const mockApi = {
  async list() {
    await wait(300);
    return mockDatabase.map(cloneSchedulerEvent);
  },
  async save(next: SchedulerEvent[]) {
    await wait(500);
    if (rejectSave.value) throw new Error("Mock API：保存被拒绝");
    mockDatabase = next.map(cloneSchedulerEvent);
    return {
      revision: Date.now(),
      events: mockDatabase.map(cloneSchedulerEvent),
    };
  },
};

onMounted(async () => {
  events.value = await mockApi.list();
  loading.value = false;
  requestStatus.value = `已加载 ${events.value.length} 条日程`;
});

const saveToMockServer: SchedulerBeforeChange = async (context) => {
  lastRequest.value = JSON.stringify(
    {
      method: "PUT",
      url: "/api/scheduler/events",
      change: context.type,
      event: context.event,
      events: context.value,
    },
    null,
    2,
  );
  requestStatus.value = "正在提交 metadata 和日程数据…";
  try {
    const response = await mockApi.save(context.value);
    requestStatus.value = `保存成功 · revision ${response.revision}`;
    return true;
  } catch (error) {
    requestStatus.value = error instanceof Error ? error.message : "保存失败";
    throw error;
  }
};

function createEvent(
  typeId: string,
  id: string,
  title: string,
  start: string,
  end: string,
): SchedulerEvent {
  const event: SchedulerEvent = {
    id,
    title,
    start: `2026-09-09T${start}:00`,
    end: `2026-09-09T${end}:00`,
    resourceIds: [],
  };
  applyType(event, typeId, false);
  return event;
}

function typeOf(event: SchedulerEvent): EventType {
  return (
    eventTypes.find((type) => type.id === event.metadata?.typeId) ??
    eventTypes[0]
  );
}

function applyType(event: SchedulerEvent, value: unknown, suggestTitle = true) {
  const previous = typeOf(event);
  const type = eventTypes.find((item) => item.id === value) ?? eventTypes[0];
  const replaceTitle =
    suggestTitle && (!event.title.trim() || event.title === previous.title);
  event.color = type.color;
  event.backgroundColor = type.backgroundColor;
  event.backgroundPattern = type.backgroundPattern;
  event.metadata = { ...event.metadata, typeId: type.id };
  event.readonly = type.readonly;
  if (replaceTitle) event.title = type.title;
}

function prepareAndSave(
  event: SchedulerEvent,
  save: (event?: SchedulerEvent) => void,
) {
  const type = typeOf(event);
  event.color ??= type.color;
  event.backgroundColor ??= type.backgroundColor;
  event.backgroundPattern ??= type.backgroundPattern;
  event.metadata = {
    ...event.metadata,
    typeId: type.id,
    clientRequestId: `demo-${Date.now()}`,
  };
  save(event);
}

function previewStyle(event: SchedulerEvent) {
  const color = event.color ?? "#1677ff";
  const background = event.backgroundColor ?? "#e6f4ff";
  const pattern = event.backgroundPattern;
  const images: Record<SchedulerEventBackgroundPattern, string> = {
    solid: `linear-gradient(${background}, ${background})`,
    "diagonal-stripes": `repeating-linear-gradient(135deg, transparent 0 8px, color-mix(in srgb, ${color} 18%, transparent) 8px 16px)`,
    dots: `radial-gradient(circle, color-mix(in srgb, ${color} 28%, transparent) 1.5px, transparent 1.5px)`,
    crosshatch: `repeating-linear-gradient(45deg, transparent 0 9px, color-mix(in srgb, ${color} 14%, transparent) 9px 11px), repeating-linear-gradient(-45deg, transparent 0 9px, color-mix(in srgb, ${color} 14%, transparent) 9px 11px)`,
  };
  return {
    color,
    backgroundColor: background,
    backgroundImage: images[pattern ?? "solid"],
    backgroundSize: pattern === "dots" ? "10px 10px" : undefined,
    borderColor: color,
  };
}
</script>

<style scoped>
.scheduler-type-preview {
  display: grid;
  gap: 4px;
  margin: 0 0 16px;
  padding: 12px 14px;
  border: 1px solid;
  border-radius: 8px;
}

.scheduler-type-preview span {
  font-size: 12px;
  opacity: 0.75;
}

.scheduler-mock-log {
  margin-top: 12px;
}

.scheduler-mock-log pre {
  max-height: 260px;
  overflow: auto;
  padding: 12px;
  border-radius: 8px;
  background: var(--c-color-fill-1);
  font-size: 12px;
}
</style>
```

### Custom Editor

Preview configuration: `default-date="2026-09-09"`, `default-mode="day"`, `:before-change="beforeChange"`, `:model="event"`.

Example source: src/scheduler/__demos__/custom-editor.vue

```vue
<template>
  <c-checkbox v-model="reject">模拟接口拒绝保存</c-checkbox>
  <p>保留内置抽屉，替换全部表单内容；可看到新建/编辑标识及校验、接口错误。</p>
  <c-scheduler
    v-model="events"
    default-date="2026-09-09"
    default-mode="day"
    :before-change="beforeChange"
  >
    <template
      #editor="{
        action,
        event,
        save,
        remove,
        close,
        readonly,
        pending,
        errorMessage,
      }"
    >
      <h3>{{ action === "create" ? "新增工作计划" : "修改工作计划" }}</h3>
      <c-alert v-if="errorMessage" status="danger">{{ errorMessage }}</c-alert>
      <c-form :model="event" layout="vertical" @submit="save(event)">
        <c-form-item label="计划标题">
          <c-input v-model="event.title" :disabled="readonly || pending" />
        </c-form-item>
        <c-form-item label="开始时间">
          <c-date
            :model-value="event.start == null ? undefined : schedulerDate(event.start)"
            @update:model-value="event.start = $event"
            :show-time="!event.allDay"
            value-format="Date"
            :disabled="readonly || pending"
          />
        </c-form-item>
        <c-form-item label="结束时间（不含）">
          <c-date
            :model-value="event.end == null ? undefined : schedulerDate(event.end)"
            @update:model-value="event.end = $event"
            :show-time="!event.allDay"
            value-format="Date"
            :disabled="readonly || pending"
          />
        </c-form-item>
        <c-form-item label="验收说明">
          <c-textarea
            v-model="event.description"
            :disabled="readonly || pending"
          />
        </c-form-item>
        <c-space>
          <c-button :disabled="pending" @click="close">取消</c-button>
          <c-button
            v-if="action === 'edit' && !readonly"
            status="danger"
            :disabled="pending"
            @click="remove"
            >删除</c-button
          >
          <c-button
            v-if="!readonly"
            html-type="submit"
            status="primary"
            :loading="pending"
            >保存计划</c-button
          >
        </c-space>
      </c-form>
    </template>
  </c-scheduler>
</template>
<script setup lang="ts">
import { ref } from "vue";
import { schedulerDate } from "@cedar-design/ui/scheduler/core";
import type { SchedulerEvent, SchedulerBeforeChange } from "@cedar-design/ui";
const events = ref<SchedulerEvent[]>([
  {
    id: "plan",
    title: "交付验收",
    start: "2026-09-09T09:00:00",
    end: "2026-09-09T10:00:00",
    description: "确认验收清单",
  },
]);
const reject = ref(false);
const beforeChange: SchedulerBeforeChange = async () => {
  if (reject.value) throw new Error("模拟接口拒绝");
  return true;
};
</script>
```

### External Editor

Preview configuration: `:editable="false"`, `default-date="2026-09-09"`, `default-mode="day"`, `:before-change="beforeChange"`.

Example source: src/scheduler/__demos__/external-editor.vue

```vue
<template>
  <p>
    关闭内置编辑器，统一接收工具栏、日期格、卡片拖入及已有日程请求，使用独立
    Dialog。取消不写入，保存失败保留表单。
  </p>
  <c-checkbox v-model="reject">下一次模拟接口提交失败</c-checkbox>
  <c-scheduler
    ref="scheduler"
    v-model="events"
    :editable="false"
    default-date="2026-09-09"
    default-mode="day"
    :before-change="beforeChange"
    @editor-request="openEditor"
    @change-error="showError"
  >
    <template #sidebar-extra="{ startDrag, cancelDrag, disabled }">
      <c-button
        :draggable="!disabled"
        :disabled="disabled"
        @dragstart="startDrag(card, $event)"
        @dragend="cancelDrag"
        >拖入：现场检查 · 60 分钟</c-button
      >
    </template>
  </c-scheduler>
  <c-dialog
    v-model:open="open"
    :title="request?.action === 'create' ? '业务新增窗口' : '业务详情窗口'"
    :footer="false"
    :closable="!saving"
    :overlay-closable="!saving"
    :esc-to-close="!saving"
  >
    <template v-if="draft">
      <p>请求来源：{{ request?.source }}；业务页面也可接收相同请求。</p>
      <c-alert v-if="errorMessage" status="danger">{{ errorMessage }}</c-alert>
      <c-form :model="draft" layout="vertical" @submit="submit()">
        <c-form-item label="任务名称"
          ><c-input
            v-model="draft.title"
            :disabled="request?.readonly || saving"
        /></c-form-item>
        <c-form-item label="开始"
          ><c-date
            :model-value="draft.start == null ? undefined : schedulerDate(draft.start)"
            @update:model-value="draft.start = $event"
            :show-time="!draft.allDay"
            value-format="Date"
            :disabled="request?.readonly || saving"
        /></c-form-item>
        <c-form-item label="结束（不含）"
          ><c-date
            :model-value="draft.end == null ? undefined : schedulerDate(draft.end)"
            @update:model-value="draft.end = $event"
            :show-time="!draft.allDay"
            value-format="Date"
            :disabled="request?.readonly || saving"
        /></c-form-item>
        <c-form-item label="工作说明"
          ><c-textarea
            v-model="draft.description"
            :disabled="request?.readonly || saving"
        /></c-form-item>
        <c-space>
          <c-button :disabled="saving" @click="open = false">取消</c-button>
          <c-button
            v-if="request?.action === 'edit' && !request.readonly"
            status="danger"
            :disabled="saving"
            @click="submit(true)"
            >删除</c-button
          >
          <c-button
            v-if="!request?.readonly"
            status="primary"
            html-type="submit"
            :loading="saving"
            >确认保存</c-button
          >
        </c-space>
      </c-form>
    </template>
  </c-dialog>
</template>
<script setup lang="ts">
import { ref } from "vue";
import { cloneSchedulerEvent, schedulerDate } from "@cedar-design/ui/scheduler/core";
import type {
  SchedulerInstance,
  SchedulerEvent,
  SchedulerEditorRequest,
  SchedulerEventTemplate,
  SchedulerBeforeChange,
} from "@cedar-design/ui";
const scheduler = ref<SchedulerInstance>();
const events = ref<SchedulerEvent[]>([
  {
    id: "inspection",
    title: "设备例行检查",
    start: "2026-09-09T10:00:00",
    end: "2026-09-09T11:00:00",
  },
]);
const card: SchedulerEventTemplate = {
  title: "现场检查",
  duration: 60,
  description: "核对运行参数",
};
const request = ref<SchedulerEditorRequest>();
const draft = ref<SchedulerEvent>();
const open = ref(false);
const saving = ref(false);
const reject = ref(false);
const errorMessage = ref("");
let snapshot: string | undefined;
function openEditor(value: SchedulerEditorRequest) {
  if (open.value || saving.value) return;
  request.value = value;
  draft.value = cloneSchedulerEvent(value.event);
  snapshot = JSON.stringify(
    events.value.find((item) => item.id === value.event.id),
  );
  errorMessage.value = "";
  open.value = true;
}
const beforeChange: SchedulerBeforeChange = async () => {
  if (reject.value) {
    reject.value = false;
    throw new Error("模拟接口提交失败，请保留草稿直接重试");
  }
  return true;
};
function showError(error: unknown) {
  errorMessage.value = error instanceof Error ? error.message : "保存失败";
}
async function submit(remove = false) {
  if (
    !draft.value ||
    !request.value ||
    request.value.readonly ||
    saving.value ||
    !scheduler.value
  )
    return;
  if (
    draft.value.id !== request.value.event.id ||
    JSON.stringify(events.value.find((item) => item.id === draft.value!.id)) !==
      snapshot
  ) {
    errorMessage.value = "原日程已变化，请关闭并重新打开。";
    return;
  }
  saving.value = true;
  errorMessage.value = "";
  try {
    const success = await scheduler.value.change({
      type: remove
        ? "remove"
        : request.value.action === "create"
          ? "create"
          : "update",
      event: cloneSchedulerEvent(draft.value),
    });
    if (success) open.value = false;
    else if (!errorMessage.value)
      errorMessage.value = "保存被取消或当前不可提交，请重试。";
  } finally {
    saving.value = false;
  }
}
</script>
```

### Batch History

Preview configuration: `v-model:selected-keys="selected"`, `default-date="2026-09-09"`, `default-mode="resource-timeline"`, `:resources="resources"`.

Example source: src/scheduler/__demos__/batch-history.vue

```vue
<template>
  <c-space direction="column" block>
    <c-alert
      >开启“多选”后点击日程卡片，可整批后移一天、添加资源或删除。共享日程在多个资源列中只计为一项；撤销和重做同样经过保存接口。</c-alert
    >
    <c-checkbox v-model="reject">模拟整批保存失败</c-checkbox>
    <c-scheduler
      v-model="events"
      v-model:selected-keys="selected"
      default-date="2026-09-09"
      default-mode="resource-timeline"
      :resources="resources"
      selectable
      history
      :before-transaction="persist"
    />
    <c-tag>{{ status }}</c-tag>
  </c-space>
</template>
<script setup lang="ts">
import { ref } from "vue";
import type { SchedulerBeforeTransaction } from "../props";
import { createEvents, resources } from "./data";
const events = ref(createEvents());
const selected = ref<string[]>([]);
const reject = ref(false);
const status = ref("尚未提交");
const persist: SchedulerBeforeTransaction = async (context) => {
  status.value = `正在提交 ${context.changes.length} 项变更…`;
  await new Promise((resolve) => setTimeout(resolve, 350));
  if (reject.value) {
    status.value = "整批保存失败，日程和历史均保留";
    throw new Error("Demo rejected");
  }
  status.value = `已提交 ${context.changes.length} 项变更（${context.action === "undo" ? "撤销" : context.action === "redo" ? "重做" : "修改"}）`;
};
</script>
```

### Atomic Swap

Preview configuration: `default-date="2026-09-09"`, `default-mode="resource-day"`, `:resources="[{ id: 'room', label: '会议室 A' }]"`, `:allow-overlap="false"`.

Example source: src/scheduler/__demos__/atomic-swap.vue

```vue
<template>
  <c-space direction="column" block>
    <c-alert
      >会议室禁止重叠。两条日程可以通过一次事务交换时间；整体校验最终结果，任一项失败都不会改变另一项。</c-alert
    >
    <c-button @click="swap">交换两个会议的时间</c-button>
    <c-scheduler
      ref="scheduler"
      v-model="events"
      default-date="2026-09-09"
      default-mode="resource-day"
      :resources="[{ id: 'room', label: '会议室 A' }]"
      :allow-overlap="false"
      history
    />
  </c-space>
</template>
<script setup lang="ts">
import { ref } from "vue";
import type { SchedulerEvent } from "../core";
import type { SchedulerInstance } from "../index";
const scheduler = ref<SchedulerInstance>();
const events = ref<SchedulerEvent[]>([
  {
    id: "a",
    title: "产品评审",
    start: "2026-09-09T09:00:00",
    end: "2026-09-09T10:00:00",
    resourceIds: ["room"],
  },
  {
    id: "b",
    title: "技术评审",
    start: "2026-09-09T10:00:00",
    end: "2026-09-09T11:00:00",
    resourceIds: ["room"],
  },
]);
async function swap() {
  const [a, b] = events.value;
  await scheduler.value?.transaction([
    { type: "move", event: { ...a, start: b.start, end: b.end } },
    { type: "move", event: { ...b, start: a.start, end: a.end } },
  ]);
}
</script>
```

### Interaction Completion

Preview configuration: `v-model:mode="mode"`, `default-date="2026-09-22"`, `:slot-duration="60"`, `:snap-duration="15"`.

Example source: src/scheduler/__demos__/interaction-completion.vue

```vue
<template>
  <c-space direction="column" block>
    <c-alert
      >周视图空白处拖选创建，支持向上拖选；网格 60 分钟，指针吸附 15
      分钟，单击新建默认 45 分钟。月视图每天先显示 2
      条，可点击“更多日程”。</c-alert
    >
    <c-space
      ><c-button @click="mode = 'week'">拖选排期</c-button
      ><c-button @click="mode = 'month'">查看月历更多日程</c-button></c-space
    >
    <c-scheduler
      v-model="events"
      v-model:mode="mode"
      default-date="2026-09-22"
      :slot-duration="60"
      :snap-duration="15"
      :default-duration="45"
      :month-event-limit="2"
      drag-to-create
      history
    />
  </c-space>
</template>
<script setup lang="ts">
import { ref } from "vue";
import type { SchedulerEvent, SchedulerMode } from "../core";
const mode = ref<SchedulerMode>("week");
const events = ref<SchedulerEvent[]>(
  Array.from({ length: 5 }, (_, i) => ({
    id: `sample${i}`,
    title: `任务 ${i + 1}`,
    start: `2026-09-22T${String(i + 9).padStart(2, "0")}:00:00`,
    end: `2026-09-22T${String(i + 10).padStart(2, "0")}:00:00`,
  })),
);
</script>
```

### Advanced Planning

Preview configuration: `default-date="2026-09-22"`, `default-mode="resource-timeline"`, `default-scale="hour"`, `:resources="resources"`.

Example source: src/scheduler/__demos__/advanced-planning.vue

```vue
<template>
  <c-space direction="column" block>
    <c-alert
      >准备 → 执行 →
      验收里程碑。依赖连线在时间线中展示；把执行拖到准备完成前会被阻止。里程碑使用相同起止时间，不占用资源容量。缩放按钮以视口中心为锚点调整刻度宽度。</c-alert
    >
    <c-scheduler
      v-model="events"
      default-date="2026-09-22"
      default-mode="resource-timeline"
      default-scale="hour"
      :resources="resources"
      :dependencies="dependencies"
      show-resource-load
      history
    />
  </c-space>
</template>
<script setup lang="ts">
import { ref } from "vue";
import type { SchedulerEvent, SchedulerDependency } from "../core";
const resources = [{ id: "team", label: "执行团队", capacity: 1 }];
const dependencies: SchedulerDependency[] = [
  { id: "prepare-run", fromId: "prepare", toId: "run" },
  { id: "run-accept", fromId: "run", toId: "accept" },
];
const events = ref<SchedulerEvent[]>([
  {
    id: "prepare",
    title: "准备",
    start: "2026-09-22T09:00:00",
    end: "2026-09-22T10:00:00",
    resourceIds: ["team"],
  },
  {
    id: "run",
    title: "执行",
    start: "2026-09-22T10:00:00",
    end: "2026-09-22T12:00:00",
    resourceIds: ["team"],
  },
  {
    id: "accept",
    title: "验收里程碑",
    start: "2026-09-22T12:00:00",
    end: "2026-09-22T12:00:00",
    milestone: true,
    resourceIds: ["team"],
  },
]);
</script>
```

## Async loading and saving

### Async Resources

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `default-mode` | Default uncontrolled view | Async Resources, Remote Events, Async Change |
| `resources` | Currently visible resource rows/columns and local options; a complete directory is unnecessary | Async Resources, Async Change |
| `before-change` | Return false to cancel; supports asynchronous interception and save APIs | Async Resources, Async Change |
| `default-date` | Initial navigation date | Async Resources, Async Change |
| `resource-label` | Resource field name, such as equipment or meeting room | Async Resources |
| `request-resources` | Query resource candidates by keyword and cursor | Async Resources |
<!-- demo-config-notes:end -->


Preview configuration: `options`, `:resources="visibleResources"`, `:resource-label="kind === 'device' ? '设备' : '人员'"`, `:request-resources="requestResources"`.

Example source: src/scheduler/__demos__/async-resources.vue

```vue
<template>
  <c-space direction="column" align="stretch" wrap>
    <c-form-item layout="vertical" hide-label>
      <c-select
        v-model="kind"
        :options="[
          { value: 'device', label: '设备接口' },
          { value: 'person', label: '人员接口' },
        ]"
      />
    </c-form-item>
    <c-button @click="failNextSearch = true">下次搜索模拟失败</c-button>
    <c-button @click="retryHydration">模拟回显失败并重新加载</c-button>
    <c-button @click="useNextPage">切换可见资源页</c-button>
  </c-space>
  <p>
    当前仅提供 {{ visibleResources.length }} 条可见资源。已有日程关联第 12
    条，不在本页，仍通过 ID 接口回显名称。进入编辑器，搜索“12”或滚动加载更多。
  </p>
  <p role="status">{{ feedback }}</p>
  <c-scheduler
    :key="`${kind}-${revision}`"
    v-model="events"
    :resources="visibleResources"
    :resource-label="kind === 'device' ? '设备' : '人员'"
    :request-resources="requestResources"
    :resolve-resources="resolveResources"
    :before-change="beforeChange"
    default-mode="agenda"
    default-date="2026-09-09"
    @resource-error="resourceError"
  />
</template>
<script setup lang="ts">
import { computed, onScopeDispose, ref, watch } from "vue";
import type {
  SchedulerEvent,
  SchedulerRequestResources,
  SchedulerResolveResources,
  SchedulerBeforeChange,
  SchedulerResourceErrorContext,
} from "@cedar-design/ui";

const kind = ref<"device" | "person">("device");
// 业务接口字段在接入层适配，Scheduler 始终只认识 id / label。
const devices = Array.from({ length: 24 }, (_, index) => ({
  deviceId: `device-${index + 1}`,
  deviceName: `实验设备 ${index + 1}`,
}));
const people = Array.from({ length: 24 }, (_, index) => ({
  userId: `person-${index + 1}`,
  displayName: `工程师 ${index + 1}`,
}));
const directory = computed(() =>
  kind.value === "device"
    ? devices.map((item) => ({ id: item.deviceId, label: item.deviceName }))
    : people.map((item) => ({ id: item.userId, label: item.displayName })),
);
const page = ref(0);
const revision = ref(0);
const visibleResources = computed(() =>
  directory.value.slice(page.value * 4, page.value * 4 + 4),
);
const events = ref<SchedulerEvent[]>([]);
const feedback = ref("打开详情查看名称回显，或在资源下拉框搜索。");
const failNextSearch = ref(false);
const failNextResolve = ref(false);
const failedOperation = ref<"search" | "resolve">();
watch(
  kind,
  () => {
    failedOperation.value = undefined;
    feedback.value = "打开详情查看名称回显，或在资源下拉框搜索。";
    page.value = 0;
    events.value = [
      {
        id: `${kind.value}-job`,
        title: "已有排期：关联不在本页的资源",
        start: "2026-09-09T09:00:00",
        end: "2026-09-09T10:00:00",
        resourceIds: [`${kind.value}-12`],
      },
    ];
  },
  { immediate: true, flush: "sync" },
);

const lifetime = new AbortController();
onScopeDispose(() => lifetime.abort());
// 模拟接口延时；真实接入时直接 fetch(url, { signal })。
function delay(signal: AbortSignal) {
  return new Promise<void>((resolve, reject) => {
    if (signal.aborted) {
      reject(new Error("Aborted"));
      return;
    }
    const abort = () => {
      clearTimeout(timer);
      signal.removeEventListener("abort", abort);
      reject(new Error("Aborted"));
    };
    const timer = setTimeout(() => {
      signal.removeEventListener("abort", abort);
      resolve();
    }, 500);
    signal.addEventListener("abort", abort, { once: true });
  });
}
const requestResources: SchedulerRequestResources = async ({
  query,
  cursor,
  signal,
}) => {
  const data = directory.value;
  const fail = failNextSearch.value;
  failNextSearch.value = false;
  await delay(signal);
  if (fail) throw new Error("模拟搜索网络错误");
  const matches = data.filter(
    (item) => item.label.includes(query) || item.id.includes(query),
  );
  const offset = Number(cursor ?? 0);
  if (failedOperation.value === "search") {
    failedOperation.value = undefined;
    feedback.value = "搜索重试成功，可继续选择资源。";
  }
  return {
    items: matches.slice(offset, offset + 4),
    nextCursor: offset + 4 < matches.length ? String(offset + 4) : undefined,
  };
};
const resolveResources: SchedulerResolveResources = async (ids, { signal }) => {
  const data = directory.value;
  const fail = failNextResolve.value;
  failNextResolve.value = false;
  await delay(signal);
  if (fail) throw new Error("模拟回显网络错误");
  if (failedOperation.value === "resolve") {
    failedOperation.value = undefined;
    feedback.value = "资源名称回显成功，关联 ID 保持不变。";
  }
  return data.filter((item) => ids.includes(item.id));
};
const beforeChange: SchedulerBeforeChange = async ({ event, type }) => {
  const data = directory.value;
  await delay(lifetime.signal);
  // 演示服务端校验；生产环境还应验证权限、版本和全量时段冲突。
  if (
    type !== "remove" &&
    event.resourceIds?.some((id) => !data.some((item) => item.id === id))
  )
    throw new Error("资源不存在");
  feedback.value = "模拟接口保存成功，日程只保存 resourceIds，不保存显示名称。";
};
function resourceError(
  _error: unknown,
  context: SchedulerResourceErrorContext,
) {
  failedOperation.value = context.type;
  feedback.value =
    context.type === "resolve"
      ? "回显失败：ID 仍保留，点击日程内的重试按钮。"
      : "搜索失败：可在下拉框内重试。";
}
function retryHydration() {
  failNextResolve.value = true;
  revision.value++;
}
function useNextPage() {
  page.value = (page.value + 1) % 6;
}
</script>
```

### Remote Events

- `readonly`: Displays the current value without allowing edits.

Example source: src/scheduler/__demos__/remote-events.vue

```vue
<template>
  <c-space direction="column" block>
    <c-alert
      >翻页按可见范围请求；返回已访问日期命中 30
      秒缓存。可模拟失败后重试，也可连续切换日期，验证慢响应不会覆盖最新页面。</c-alert
    >
    <c-space wrap>
      <c-button @click="refresh()">刷新 / 重试</c-button>
      <c-button @click="jump(1)">下一天</c-button>
      <c-button @click="jump(-1)">上一天</c-button>
      <c-checkbox v-model="fail">模拟加载失败</c-checkbox>
      <c-checkbox v-model="outOfOrder">模拟乱序响应</c-checkbox>
    </c-space>
    <c-space wrap>
      <c-tag>请求 {{ requests }} 次</c-tag>
      <c-tag>{{
        loading
          ? "加载中"
          : error
            ? "加载失败，请重试"
            : `已加载 ${events.length} 项`
      }}</c-tag>
      <c-tag>{{ status }}</c-tag>
    </c-space>
    <c-scheduler
      v-model="events"
      v-model:date="date"
      default-mode="day"
      :readonly="loading || !!error"
      :before-transaction="persist"
      @range-change="range = $event"
    />
  </c-space>
</template>
<script setup lang="ts">
import { ref } from "vue";
import { useSchedulerDataSource } from "../use-data-source";
import {
  applySchedulerTransaction,
  cloneSchedulerEvent,
  isSchedulerEventInRange,
  schedulerDate,
} from "../core";
import type { SchedulerDate, SchedulerEvent, SchedulerRange } from "../core";
import type { SchedulerBeforeTransaction } from "../props";
const date = ref<SchedulerDate>("2026-09-09");
const range = ref<SchedulerRange>();
const fail = ref(false);
const outOfOrder = ref(false);
const requests = ref(0);
const status = ref("编辑日程会保存到模拟服务端");
let database: SchedulerEvent[] = Array.from({ length: 90 }, (_, index) => ({
  id: `remote-${index}`,
  title: `远程计划 ${index + 1}`,
  start: new Date(2026, 7, 15 + index, 9),
  end: new Date(2026, 7, 15 + index, 10),
}));
const { events, loading, error, refresh } = useSchedulerDataSource({
  range,
  requestEvents: async (query) => {
    const sequence = ++requests.value;
    const shouldFail = fail.value;
    const ignoreAbort = outOfOrder.value;
    const result = database
      .filter((event) => isSchedulerEventInRange(event, query))
      .map(cloneSchedulerEvent);
    await new Promise<void>((resolve, reject) => {
      const abort = () => {
        clearTimeout(timer);
        reject(new Error("Aborted"));
      };
      const timer = setTimeout(
        () => {
          query.signal.removeEventListener("abort", abort);
          resolve();
        },
        ignoreAbort ? (sequence % 2 ? 1800 : 200) : 450,
      );
      if (!ignoreAbort)
        query.signal.addEventListener("abort", abort, { once: true });
    });
    if (shouldFail) throw new Error("模拟接口失败");
    return result;
  },
});
function jump(offset: number) {
  const next = schedulerDate(date.value);
  next.setDate(next.getDate() + offset);
  date.value = next;
}
const persist: SchedulerBeforeTransaction = async (context) => {
  // Send the delta to the backend, never replace the full database with a loaded window.
  database = applySchedulerTransaction(database, context.changes);
  status.value = `已保存 ${context.changes.length} 项变更；查询缓存随 v-model 更新失效`;
};
</script>
```

### Async Change

Preview configuration: `:model-value="events"`, `default-date="2026-09-09"`, `default-mode="resource-day"`, `:resources="resources"`.

Example source: src/scheduler/__demos__/async-change.vue

```vue
<template>
  <section class="scheduler-async-demo">
    <c-space direction="column" block>
      <c-space>
        <c-checkbox v-model="reject">下一次模拟保存失败</c-checkbox>
        <c-checkbox v-model="accept">父组件接受更新</c-checkbox>
        <c-button @click="reset">重置日程</c-button>
      </c-space>
      <p>
        本地模拟 600ms
        保存；失败开关在一次失败后自动复位，可直接重试。取消或父组件拒绝提案不改变已保存值。
      </p>
      <c-scheduler
        :model-value="events"
        default-date="2026-09-09"
        default-mode="resource-day"
        :resources="resources"
        :before-change="beforeChange"
        @update:model-value="update"
        @change="outcome = accept ? '父组件已接受' : '父组件未接受提案'"
        @change-error="outcome = '保存失败，原值不变'"
      />
      <p role="status">{{ outcome }}；活动请求：{{ pendingCount }}</p>
      <ul aria-label="异步已提交日程">
        <li v-for="event in events" :key="event.id" :data-demo-event="event.id">
          {{ event.title }}：{{ event.start ?? "未排期" }} →
          {{ event.end ?? "未排期" }}；资源：{{ event.resourceIds?.join(",") }}
        </li>
      </ul>
    </c-space>
  </section>
</template>
<script setup lang="ts">
import { onBeforeUnmount, onDeactivated, ref } from "vue";
import type { SchedulerBeforeChange } from "../props";
import type { SchedulerEvent } from "../core";
import { createEvents, resources } from "./data";
const events = ref(createEvents());
const reject = ref(false);
const accept = ref(true);
const outcome = ref("尚未操作");
const pendingCount = ref(0);
const pending = new Map<ReturnType<typeof setTimeout>, () => void>();
const beforeChange: SchedulerBeforeChange = () =>
  new Promise<boolean>((resolve, rejectRequest) => {
    const fail = reject.value;
    const timer = setTimeout(() => {
      pending.delete(timer);
      pendingCount.value = pending.size;
      if (fail) {
        reject.value = false;
        rejectRequest(new Error("模拟接口失败"));
      } else resolve(true);
    }, 600);
    pending.set(timer, () => resolve(false));
    pendingCount.value = pending.size;
  });
function update(value: SchedulerEvent[]) {
  if (accept.value) events.value = value;
}
function cancelPending() {
  pending.forEach((cancel, timer) => {
    clearTimeout(timer);
    cancel();
  });
  pending.clear();
  pendingCount.value = 0;
}
function reset() {
  cancelPending();
  events.value = createEvents();
  outcome.value = "已重置";
}
onBeforeUnmount(cancelPending);
onDeactivated(cancelPending);
</script>
```

## Workflows and integration

### Equipment

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `resources` | Currently visible resource rows/columns and local options; a complete directory is unnecessary | Equipment, Task Calendar Details, Task Calendar Workbench |
| `default-mode` | Default uncontrolled view | Equipment, Calendar Integration, Task Calendar Details |
| `default-date` | Initial navigation date | Equipment, Calendar Integration, Task Calendar Details |
| `editable` | Enable the built-in editor; false delegates through editor-request | Task Calendar Details, Task Calendar Workbench |
| `start-hour` | Time-grid start hour, 0–23 | Task Calendar Details, Task Calendar Workbench |
| `end-hour` | Time-grid end hour; greater than start and at most 24 | Task Calendar Details, Task Calendar Workbench |
<!-- demo-config-notes:end -->


Preview configuration: `:resources="devices"`, `resource-label="设备"`, `default-mode="resource-day"`, `default-date="2026-09-09"`.

Example source: src/scheduler/__demos__/equipment.vue

```vue
<template>
  <p>
    设备共享使用时段：拖入左侧任务后确认排期；维护中的设备禁止新增分配，同一设备的时间冲突会阻止保存。
  </p>
  <c-scheduler
    v-model="events"
    :resources="devices"
    resource-label="设备"
    default-mode="resource-day"
    default-date="2026-09-09"
    :allow-overlap="false"
  >
    <template #sidebar-extra="{ startDrag, cancelDrag, disabled }">
      <strong>待安排工单</strong>
      <c-button
        v-for="task in tasks"
        :key="String(task.metadata?.taskId)"
        :draggable="!disabled"
        :disabled="disabled"
        @dragstart="startDrag(task, $event)"
        @dragend="cancelDrag"
      >
        {{ task.title }} · {{ task.duration }} 分钟
      </c-button>
    </template>
    <template #resource-header="{ resource, date }">
      <strong>{{ resource?.label ?? date.toLocaleDateString() }}</strong>
      <small v-if="resource">
        · {{ resource.disabled ? "维护中" : "可预约" }}</small
      >
    </template>
    <template #event="{ event }">
      <strong>{{ event.title }}</strong
      ><span v-if="event.metadata?.taskId">
        · {{ event.metadata?.taskId }}</span
      >
    </template>
  </c-scheduler>
</template>
<script setup lang="ts">
import { ref } from "vue";
import type {
  SchedulerEvent,
  SchedulerResource,
  SchedulerEventTemplate,
} from "@cedar-design/ui";
const devices: SchedulerResource[] = [
  { id: "laser-01", label: "激光切割机 01" },
  { id: "printer-02", label: "3D 打印机 02" },
  { id: "scanner-03", label: "扫描仪 03", disabled: true },
];
const tasks: SchedulerEventTemplate[] = [
  {
    title: "样件加工",
    duration: 90,
    metadata: { taskId: "JOB-201" },
    description: "安排加工设备并确认材料",
  },
  {
    title: "设备校准",
    duration: 30,
    metadata: { taskId: "JOB-202" },
    description: "校准完成后记录结果",
  },
];
const events = ref<SchedulerEvent[]>([
  {
    id: "run-1",
    title: "批次 A 加工",
    start: "2026-09-09T09:00:00",
    end: "2026-09-09T11:00:00",
    resourceIds: ["laser-01"],
    metadata: { taskId: "JOB-100" },
  },
  {
    id: "run-2",
    title: "联合验收（共用两台设备）",
    start: "2026-09-09T14:00:00",
    end: "2026-09-09T15:00:00",
    resourceIds: ["laser-01", "printer-02"],
    metadata: { taskId: "JOB-101" },
  },
  {
    id: "maintenance",
    title: "停机维护",
    start: "2026-09-09",
    end: "2026-09-10",
    allDay: true,
    resourceIds: ["scanner-03"],
    readonly: true,
  },
]);
</script>
```

### Calendar Integration

Preview configuration: `placeholder="ICS 文本"`, `:rows="4"`, `default-date="2026-09-22"`, `default-mode="week"`.

Example source: src/scheduler/__demos__/calendar-integration.vue

```vue
<template>
  <c-space direction="column" block>
    <c-alert
      >模拟服务端持有版本号：编辑保存延迟
      300ms，期间模拟远端更新会触发过期保护。导入/导出使用真实 ICS
      文本；打印生成独立文档，不打印整页组件文档。</c-alert
    >
    <c-space
      ><c-button @click="remote">模拟远端更新</c-button
      ><c-button @click="exportIcs">导出 ICS 文本</c-button
      ><c-button @click="importIcs">导入 ICS 文本</c-button
      ><c-button @click="print">打印日程</c-button
      ><c-tag>版本 {{ revision }}</c-tag></c-space
    >
    <c-alert v-if="error" status="danger">{{ error }}</c-alert>
    <c-textarea v-model="ical" placeholder="ICS 文本" :rows="4" />
    <c-scheduler
      v-model="events"
      default-date="2026-09-22"
      default-mode="week"
      :before-transaction="save"
      history
    />
  </c-space>
</template>
<script setup lang="ts">
import { ref, onBeforeUnmount } from "vue";
import {
  createSchedulerMemoryProvider,
  exportSchedulerICalendar,
  importSchedulerICalendar,
  createSchedulerPrintHtml,
} from "../adapters";
import type { SchedulerEvent, SchedulerTransactionContext } from "../core";
const events = ref<SchedulerEvent[]>([
  {
    id: "meeting",
    title: "团队会议",
    start: "2026-09-22T09:00:00",
    end: "2026-09-22T10:00:00",
  },
]);
const source = createSchedulerMemoryProvider(events.value),
  revision = ref(0),
  ical = ref(""),
  error = ref("");
const stop = source.subscribe!((snapshot, origin) => {
  if (origin === "editor") return;
  revision.value = snapshot.revision;
  events.value = snapshot.events;
});
onBeforeUnmount(stop);
async function save(context: SchedulerTransactionContext) {
  const expected = revision.value;
  await new Promise((resolve) => setTimeout(resolve, 300));
  const next = await source.commit(context.changes, expected, "editor");
  revision.value = next.revision;
}
async function remote() {
  try {
    await source.commit(
      [
        {
          type: "update",
          event: {
            ...events.value[0],
            title: `远端更新 ${revision.value + 1}`,
          },
        },
      ],
      revision.value,
      "remote",
    );
  } catch (cause) {
    error.value = String(cause);
  }
}
function exportIcs() {
  try {
    ical.value = exportSchedulerICalendar(events.value, {
      stamp: new Date(),
      name: "Cedar demo",
    });
    error.value = "";
  } catch (cause) {
    error.value = String(cause);
  }
}
async function importIcs() {
  try {
    const parsed = importSchedulerICalendar(ical.value, {
      timeZone: "Asia/Shanghai",
    });
    if (parsed.series.length)
      throw new Error("含重复系列，请先通过 RRULE 适配器展开");
    const existing = new Set(events.value.map((event) => event.id));
    await source.commit(
      parsed.events.map((event) => ({
        type: existing.has(event.id) ? "update" : "create",
        event,
      })),
      revision.value,
      "import",
    );
    error.value = "";
  } catch (cause) {
    error.value = String(cause);
  }
}
function print() {
  const page = window.open("", "_blank");
  if (!page) return;
  page.document.open();
  page.document.write(
    createSchedulerPrintHtml(events.value, { title: "团队日程" }),
  );
  page.document.close();
  page.focus();
  page.print();
}
</script>
```

### Task Calendar Details

Preview configuration: `:editable="false"`, `:resources="resources"`, `default-date="2026-09-09"`, `default-mode="resource-day"`.

Example source: src/scheduler/__demos__/task-calendar-details.vue

```vue
<template>
  <c-alert>
    点击日程先查看业务摘要，再进入高级详情。完整出勤单、任务与打卡记录由页面按
    metadata ID 查询，Scheduler 只保存展示字段和业务 ID。
  </c-alert>
  <c-scheduler
    v-model="events"
    :editable="false"
    :resources="resources"
    default-date="2026-09-09"
    default-mode="resource-day"
    :start-hour="0"
    :end-hour="24"
    :initial-scroll-minute="420"
    :modes="['resource-day']"
    :show-sidebar="false"
    @editor-request="activate"
  >
    <template #event="{ event }">
      <EventSummaryPopover
        :open="previewId === event.id"
        :title="event.title"
        @update:open="!$event && (previewId = undefined)"
        @click-outside="previewId = undefined"
      >
        <span :class="{ 'completed-event': event.readonly }">
          {{ event.title }} · {{ personLabel(event) }}
        </span>
        <template #content>
          <c-space v-if="orderOf(event)" direction="column" block>
            <c-space>
              <c-tag>{{ statusLabel(orderOf(event)!) }}</c-tag>
              <c-tag>{{ orderOf(event)!.source }}</c-tag>
            </c-space>
            <strong>{{ timeRange(event) }}</strong>
            <span>
              {{ orderOf(event)!.tasks.length }} 项任务 ·
              {{ totalMinutes(orderOf(event)!) }} 分钟 · 1 人
            </span>
            <span>设备：{{ deviceLabels(orderOf(event)!) }}</span>
            <span>最近打卡：{{ latestPunch(orderOf(event)!) }}</span>
            <c-space>
              <c-button status="primary" @click.stop="openDetails(event)">
                高级详情
              </c-button>
              <c-button @click.stop="previewId = undefined">关闭</c-button>
            </c-space>
          </c-space>
        </template>
      </EventSummaryPopover>
    </template>
  </c-scheduler>

  <c-dialog v-model:open="detailsOpen" title="出勤单高级详情" :footer="false">
    <template v-if="activeOrder">
      <c-space direction="column" block>
        <c-space>
          <c-tag>{{ statusLabel(activeOrder) }}</c-tag>
          <c-tag>{{ activeOrder.source }}</c-tag>
        </c-space>
        <p>执行人：{{ resourceLabel(activeOrder.personId) }} · 人数：1</p>
        <p>
          计划时间：{{ displayTime(activeOrder.plannedStart) }} –
          {{ displayTime(activeOrder.plannedEnd) }}
        </p>
        <p v-if="activeOrder.actualStart">
          实际时间：{{ displayTime(activeOrder.actualStart) }} –
          {{ displayTime(activeOrder.actualEnd) }}
        </p>
        <c-divider />
        <strong>任务与工单</strong>
        <div v-for="task in activeOrder.tasks" :key="task.id">
          <c-link :href="`#work-order-${task.id}`">{{ task.title }}</c-link>
          · 技能 {{ skillLabel(task.skill) }} · {{ task.standardMinutes }} 分钟
        </div>
        <p>总标准工时：{{ totalMinutes(activeOrder) }} 分钟</p>
        <c-divider />
        <strong>打卡记录</strong>
        <div v-for="record in activeOrder.punchRecords" :key="record.id">
          {{ resourceLabel(record.deviceId) }}：
          {{ displayTime(record.checkedInAt) }} –
          {{ displayTime(record.checkedOutAt) }}
        </div>
        <c-empty
          v-if="!activeOrder.punchRecords.length"
          description="暂无打卡记录"
        />
        <c-space>
          <c-button @click="detailsOpen = false">关闭</c-button>
          <c-button
            v-if="
              activeOrder.status !== 'closed' && activeOrder.kind !== 'rest'
            "
            status="primary"
            @click="closeOrder(activeOrder)"
          >
            按实际打卡时间关单
          </c-button>
        </c-space>
      </c-space>
    </template>
  </c-dialog>
</template>

<script setup lang="ts">
import { computed, ref } from "vue";
import type {
  SchedulerEditorRequest,
  SchedulerEvent,
  SchedulerResource,
} from "@cedar-design/ui";
import EventSummaryPopover from "./event-summary-popover.vue";
import {
  toTaskCalendarEvent,
  type TaskCalendarOrder,
} from "./task-calendar-model";

const resources: SchedulerResource[] = [
  { id: "person-li", label: "李卫东" },
  { id: "person-zhang", label: "张志强" },
  { id: "device-a", label: "月检站 A" },
  { id: "device-c", label: "预警处理台 C" },
];
const orders = ref<TaskCalendarOrder[]>([
  {
    id: "detail-101",
    kind: "work",
    status: "review",
    source: "设备待办",
    personId: "person-li",
    plannedStart: "2026-09-09T09:00:00",
    plannedEnd: "2026-09-09T11:00:00",
    tasks: [
      {
        id: "WO-301",
        title: "月检与运行参数复核",
        deviceId: "device-a",
        skill: "inspection",
        standardMinutes: 120,
      },
    ],
    punchRecords: [
      {
        id: "punch-1",
        deviceId: "device-a",
        checkedInAt: "2026-09-09T09:12:00",
        checkedOutAt: "2026-09-09T10:48:00",
      },
    ],
    color: "#1677ff",
  },
  {
    id: "detail-102",
    kind: "work",
    status: "closed",
    source: "站长负责范围",
    personId: "person-zhang",
    plannedStart: "2026-09-09T13:00:00",
    plannedEnd: "2026-09-09T14:00:00",
    actualStart: "2026-09-09T13:08:00",
    actualEnd: "2026-09-09T13:52:00",
    tasks: [
      {
        id: "WO-302",
        title: "预警处理",
        deviceId: "device-c",
        skill: "warning",
        standardMinutes: 60,
      },
    ],
    punchRecords: [
      {
        id: "punch-2",
        deviceId: "device-c",
        checkedInAt: "2026-09-09T13:08:00",
        checkedOutAt: "2026-09-09T13:52:00",
      },
    ],
    color: "#86909c",
  },
  {
    id: "detail-rest",
    kind: "rest",
    status: "planned",
    source: "个人安排",
    personId: "person-li",
    plannedStart: "2026-09-09T12:00:00",
    plannedEnd: "2026-09-09T13:00:00",
    tasks: [],
    punchRecords: [],
    color: "#00a854",
  },
]);
const events = ref<SchedulerEvent[]>(orders.value.map(toTaskCalendarEvent));
const previewId = ref<string>();
const activeOrderId = ref<string>();
const detailsOpen = ref(false);
const activeOrder = computed(() =>
  orders.value.find((order) => order.id === activeOrderId.value),
);

function activate(request: SchedulerEditorRequest) {
  if (request.action !== "edit") return;
  previewId.value = request.event.id;
  activeOrderId.value = businessId(request.event);
}
function openDetails(event: SchedulerEvent) {
  activeOrderId.value = businessId(event);
  previewId.value = undefined;
  detailsOpen.value = true;
}
function closeOrder(order: TaskCalendarOrder) {
  const punches = order.punchRecords;
  const first = punches[0]?.checkedInAt;
  const last = punches.at(-1)?.checkedOutAt;
  if (!first || !last) return;
  orders.value = orders.value.map((item) =>
    item.id === order.id
      ? { ...item, status: "closed", actualStart: first, actualEnd: last }
      : item,
  );
  events.value = orders.value.map(toTaskCalendarEvent);
}
function businessId(event: SchedulerEvent) {
  return String(event.metadata?.attendanceOrderId ?? event.id);
}
function orderOf(event: SchedulerEvent) {
  return orders.value.find((order) => order.id === businessId(event));
}
function totalMinutes(order: TaskCalendarOrder) {
  return order.tasks.reduce((total, task) => total + task.standardMinutes, 0);
}
function deviceLabels(order: TaskCalendarOrder) {
  return (
    [...new Set(order.tasks.map((task) => resourceLabel(task.deviceId)))].join(
      "、",
    ) || "无"
  );
}
function personLabel(event: SchedulerEvent) {
  return resourceLabel(orderOf(event)?.personId);
}
function resourceLabel(id?: string) {
  return resources.find((resource) => resource.id === id)?.label ?? "未知";
}
function skillLabel(skill: string) {
  return { inspection: "巡检", warning: "预警处理" }[skill] ?? skill;
}
function statusLabel(order: TaskCalendarOrder) {
  if (order.kind === "rest") return "休息";
  return {
    planned: "计划中",
    active: "执行中",
    review: "待关单",
    closed: "已完成",
  }[order.status];
}
function latestPunch(order: TaskCalendarOrder) {
  const record = order.punchRecords.at(-1);
  return record
    ? `${displayTime(record.checkedInAt)} – ${displayTime(record.checkedOutAt)}`
    : "暂无";
}
function timeRange(event: SchedulerEvent) {
  return `${displayTime(event.start)} – ${displayTime(event.end)}`;
}
function displayTime(value?: string | number | Date) {
  return value == null
    ? "未记录"
    : new Date(value).toLocaleString("zh-CN", {
        month: "numeric",
        day: "numeric",
        hour: "2-digit",
        minute: "2-digit",
        hour12: false,
      });
}
</script>

<style scoped>
.completed-event {
  opacity: 0.55;
}
</style>
```

### Task Calendar Workbench

- `step`: Controls the allowed increment.
- `readonly`: Displays the current value without allowing edits.
- `disabled`: Prevents user interaction.

Example source: src/scheduler/__demos__/task-calendar-workbench.vue

```vue
<template>
  <div
    ref="host"
    class="workbench-shell"
    @pointerdown.capture="captureDrag"
    @dragend="endDrag"
  >
    <nav v-if="navigationOpen" class="workbench-nav" aria-label="应用导航">
      <c-button variant="text">任务日历</c-button>
      <c-button variant="text" @click="navigationOpen = false"
        >收起导航</c-button
      >
    </nav>
    <c-scheduler
      ref="scheduler"
      class="task-calendar-workbench"
      :model-value="events"
      v-model:date="date"
      mode="week"
      show-now-indicator
      :snap-duration="1"
      :modes="['week']"
      :step="60"
      :start-hour="0"
      :end-hour="24"
      :initial-scroll-minute="420"
      :resources="data.resources"
      :event-layout="workbenchLayout"
      :editable="false"
      :readonly="role === 'viewer'"
      :disabled="saving"
      :preview-event="preview"
      :before-change="prepareMove"
      @change="finishMove"
      @change-error="moveError"
      @editor-request="openEditor"
    >
      <template #toolbar="{ navigate, create }">
        <c-space wrap>
          <c-button
            :aria-expanded="navigationOpen"
            @click="navigationOpen = !navigationOpen"
            >导航</c-button
          >
          <c-button aria-label="上一周" :disabled="saving" @click="navigate(-1)"
            >‹</c-button
          >
          <c-popover
            trigger="click"
            placement="bottom-start"
            :open="datePickerOpen"
            @update:open="datePickerOpen = $event"
          >
            <c-button :disabled="saving">{{ weekLabel(date) }}</c-button>
            <template #content
              ><c-date-picker
                :model-value="date"
                value-format="Date"
                @update:model-value="chooseDate"
            /></template>
          </c-popover>
          <c-button aria-label="下一周" :disabled="saving" @click="navigate(1)"
            >›</c-button
          >
          <c-button :disabled="saving" @click="goToday">今天</c-button>
        </c-space>
        <c-button
          status="primary"
          :disabled="saving || role === 'viewer'"
          @click="create"
          >新增出勤单</c-button
        >
      </template>
      <template #sidebar="{ startDrag, cancelDrag, disabled }">
        <div class="workbench-panels">
          <section class="source-panel" aria-label="人员设备选择">
            <strong class="panel-title">人员与设备</strong>
            <c-input
              v-model="query"
              placeholder="搜索人员、账号或设备"
              clearable
              :disabled="saving"
            />
            <div class="panel-scroll source-scroll">
              <c-tree
                :data="sourceTree"
                :checked-values="sourceKeys"
                :expanded-values="expandedSources"
                checkable
                only-check-leaf
                block-node
                :selectable="false"
                :disabled="saving"
                @update:expanded-values="expandedSources = $event"
                @check="checkSources"
              >
                <template #label="node">
                  <span
                    v-if="node.resourceId"
                    class="source-object"
                    :data-owner="node.resourceId"
                  >
                    {{ resource(node.resourceId)?.label }}
                    <small v-if="resource(node.resourceId)?.account">{{
                      resource(node.resourceId)?.account
                    }}</small>
                    <span
                      v-if="resource(node.resourceId)?.managers"
                      class="quick-actions"
                    >
                      <c-button
                        v-for="id in resource(node.resourceId)?.managers"
                        :key="id"
                        size="xs"
                        :disabled="saving"
                        :aria-pressed="selected.includes(id)"
                        @click.stop="toggleResource(id)"
                        >{{ resource(id)?.label }}
                        {{ selected.includes(id) ? "−" : "+" }}</c-button
                      >
                    </span>
                  </span>
                  <span v-else>{{ node.label }}</span>
                </template>
              </c-tree>
            </div>
          </section>
          <section class="pending-panel" aria-label="待分配任务">
            <strong
              >待分配任务 <c-tag>{{ pending.length }}</c-tag></strong
            >
            <div class="panel-scroll">
              <c-tree
                :data="pendingTree"
                :checked-values="pendingKeys"
                :expanded-values="expandedPending"
                checkable
                only-check-leaf
                block-node
                :selectable="false"
                :disabled="disabled"
                @update:expanded-values="expandedPending = $event"
                @check="checkPending"
              >
                <template #label="node">
                  <div
                    v-if="node.taskId"
                    class="pending-task"
                    :class="deadlineClass(task(node.taskId))"
                    :draggable="!disabled"
                    @dragstart="beginPending(node.taskId, startDrag, $event)"
                    @dragend="
                      cancelDrag();
                      endDrag();
                    "
                  >
                    <strong>{{ task(node.taskId)?.title }}</strong>
                    <span>{{
                      resource(task(node.taskId)?.deviceId)?.label
                    }}</span>
                    <span>{{ deadlineText(task(node.taskId)) }}</span>
                    <span
                      >{{ task(node.taskId)?.skill }} /
                      {{ task(node.taskId)?.people }} 人 /
                      {{ task(node.taskId)?.minutes }} 分钟</span
                    >
                    <small>{{ task(node.taskId)?.source }}</small>
                  </div>
                  <span v-else>{{ node.label }}</span>
                </template>
              </c-tree>
              <c-empty
                v-if="!pendingTree.length"
                description="暂无待分配任务"
              />
            </div>
          </section>
        </div>
      </template>
      <template #resource-header="{ date: day }">
        {{ day.toLocaleDateString("zh-CN", { weekday: "short" }) }}
        {{ day.getDate() }}
      </template>
      <template #column-background="{ date: day }">
        <div
          v-if="dragDeadline && schedulerDateKey(day) > dragDeadline"
          class="deadline-mask"
          aria-label="晚于任务截止日期"
        />
      </template>
      <template #event="{ event }">
        <div
          class="task-card"
          :data-order-id="event.metadata?.orderId"
          :data-edge="event.metadata?.edge"
          :class="{
            linked: activeOrder === event.metadata?.orderId,
            closed: event.metadata?.closed,
            rest: event.metadata?.kind === 'rest',
          }"
          @mouseenter="hoverOrder = String(event.metadata?.orderId ?? '')"
          @mouseleave="hoverOrder = ''"
          @dragover="allowMerge($event, event)"
          @drop="dropMerge($event, event)"
        >
          <strong>{{ event.title }}</strong>
          <span v-if="event.metadata?.kind !== 'rest'">{{
            event.metadata?.counterpart
          }}</span>
          <span v-if="!event.allDay"
            >{{ time(event.start) }}–{{ time(event.end) }}</span
          >
        </div>
      </template>
    </c-scheduler>
  </div>
  <c-alert
    v-if="notice"
    :status="noticeError ? 'danger' : 'warning'"
    class="workbench-notice"
    role="status"
    >{{ notice }}</c-alert
  >
  <c-space wrap class="workbench-test-controls">
    <span>联调演示</span>
    <c-select
      v-model="role"
      :options="roles"
      :disabled="saving"
      style="width: 170px"
    />
    <c-checkbox v-model="rejectSave" :disabled="saving"
      >模拟保存失败</c-checkbox
    >
    <c-checkbox v-model="conflict" :disabled="saving">模拟版本冲突</c-checkbox>
    <c-button :disabled="saving" @click="reload">重新加载</c-button>
    <c-popover trigger="click" title="最近提交的业务 DTO" placement="top">
      <c-button>提交数据</c-button>
      <template #content>
        <pre class="payload">{{ lastPayload || "尚未提交" }}</pre>
      </template>
    </c-popover>
  </c-space>
  <c-dialog
    v-model:open="editorOpen"
    :title="
      draft?.kind === 'rest'
        ? '休息安排'
        : draft?.version
          ? '出勤单详情'
          : '创建出勤单'
    "
    :footer="false"
    :closable="!saving"
    :overlay-closable="!saving"
    :esc-to-close="!saving"
    @update:open="onEditorVisibility"
  >
    <template v-if="draft">
      <c-alert v-if="editorError" status="danger">{{ editorError }}</c-alert>
      <template v-if="draft.kind === 'rest'">
        <p>{{ resource(draft.personId)?.label }}</p>
        <p>{{ format(draft.start) }} – {{ format(draft.end) }}</p>
        <c-button @click="closeEditor">关闭</c-button>
      </template>
      <c-form v-else :model="draft" layout="vertical" @submit="saveDraft()">
        <c-space
          ><c-tag>{{ statuses[draft.status] }}</c-tag
          ><span>{{ draft.id }}</span></c-space
        >
        <c-form-item label="执行人"
          ><c-select
            v-model="draft.personId"
            :options="personOptions"
            :disabled="readOnly || saving"
        /></c-form-item>
        <c-form-item label="开始"
          ><c-date
            :model-value="new Date(draft.start)"
            value-format="Date"
            :show-time="!draft.allDay"
            :disabled="readOnly || saving"
            @update:model-value="setStart"
        /></c-form-item>
        <c-form-item v-if="draft.allDay" label="结束日期（不含）"
          ><c-date
            :model-value="new Date(draft.end)"
            value-format="Date"
            :disabled="readOnly || saving"
            @update:model-value="setAllDayEnd"
        /></c-form-item>
        <p v-else>计划结束：{{ format(calculatedEnd) }}</p>
        <c-form-item label="任务">
          <div class="detail-task-list">
            <div
              v-for="(entry, index) in draftTasks"
              :key="entry.id"
              class="detail-task"
              :data-task-id="entry.id"
            >
              <WorkbenchPunches
                :data="data"
                :task="entry"
                :start="taskStart(index)"
              />
              <div>
                <c-tag>{{ entry.source }}</c-tag> ·
                {{ resource(entry.deviceId)?.label }}
              </div>
              <c-button variant="text" @click="workOrderTask = entry"
                >工单详情</c-button
              >
              <c-button
                v-if="!readOnly"
                variant="text"
                :disabled="saving"
                @click="removeDraftTask(entry.id)"
                >移出任务</c-button
              >
            </div>
            <c-select
              v-if="!readOnly"
              v-model="addTaskId"
              :options="availableTaskOptions"
              placeholder="选择同设备待办任务"
              :disabled="saving"
              @update:model-value="addTask"
            />
            <c-button
              v-if="!readOnly"
              :disabled="saving || !selectedTasks.length"
              @click="addSelected"
              >加入已勾选任务（{{ selectedTasks.length }}）</c-button
            >
          </div>
        </c-form-item>
        <template v-if="draft.status === 'closed'">
          <p v-for="record in linkedPunches" :key="record.id">
            实际：{{ format(record.start) }} – {{ format(record.end) }}
          </p>
        </template>
        <template v-if="closing && !readOnly">
          <c-divider />
          <c-form-item label="关联打卡">
            <div class="detail-task-list">
              <c-checkbox
                v-for="record in eligiblePunches"
                :key="record.id"
                :model-value="draft.punchIds.includes(record.id)"
                :disabled="saving"
                @update:model-value="togglePunch(record.id, $event)"
                >{{ format(record.start) }} – {{ time(record.end) }}</c-checkbox
              >
              <c-empty
                v-if="!eligiblePunches.length"
                description="暂无匹配打卡，可手动补录"
              />
            </div>
          </c-form-item>
          <c-checkbox v-model="manualPunch" :disabled="saving"
            >手动补录打卡</c-checkbox
          >
          <c-form-item v-if="manualPunch" label="登录"
            ><c-date
              v-model="punchStart"
              value-format="Date"
              show-time
              :disabled="saving"
          /></c-form-item>
          <c-form-item v-if="manualPunch" label="注销"
            ><c-date
              v-model="punchEnd"
              value-format="Date"
              show-time
              :disabled="saving"
          /></c-form-item>
        </template>
        <c-space wrap>
          <c-button
            v-if="!readOnly"
            html-type="submit"
            status="primary"
            :loading="saving"
            >{{ closing ? "确认关单" : "保存" }}</c-button
          >
          <c-button
            v-if="!readOnly && draft.version && !closing"
            :disabled="saving || !draft.taskIds.length"
            @click="closing = true"
            >关联打卡并关单</c-button
          >
          <c-button
            v-if="!readOnly && draft.version"
            status="danger"
            :disabled="saving"
            @click="saveDraft(true)"
            >删除出勤单</c-button
          >
          <c-button :disabled="saving" @click="closeEditor">{{
            readOnly ? "关闭" : "取消"
          }}</c-button>
        </c-space>
      </c-form>
    </template>
  </c-dialog>
  <c-dialog
    :open="!!workOrderTask"
    title="工单详情"
    :footer="false"
    @update:open="!$event && (workOrderTask = undefined)"
  >
    <template v-if="workOrderTask"
      ><h3>{{ workOrderTask.id }} · {{ workOrderTask.title }}</h3>
      <p>{{ resource(workOrderTask.deviceId)?.label }}</p>
      <p>
        {{ workOrderTask.skill }} / {{ workOrderTask.people }} 人 /
        {{ workOrderTask.minutes }} 分钟
      </p>
      <p>
        来源：{{ workOrderTask.source }}；截止：{{ workOrderTask.deadline }}
      </p></template
    >
  </c-dialog>
</template>
<script setup lang="ts">
import {
  computed,
  nextTick,
  onBeforeUnmount,
  onMounted,
  ref,
  watch,
} from "vue";
import type {
  SchedulerEvent,
  SchedulerEventTemplate,
  SchedulerEditorRequest,
  SchedulerChangeContext,
} from "../index";
import { schedulerDateKey } from "../core";
import type { TreeNodeData } from "../../tree";
import WorkbenchPunches from "./workbench-punches.vue";
import {
  createWorkbenchApi,
  createWorkbenchMock,
  copyData,
  moveWorkbenchOrder,
  orderEnd,
  orderTasks,
  pendingWorkbenchTasks,
  projectWorkbench,
  remainingDays,
  weekLabel,
  workbenchLayout,
  type WorkbenchOrder,
  type WorkbenchTask,
  type WorkbenchPunch,
  type SaveResult,
} from "./workbench-model";

const today = new Date();
const api = createWorkbenchApi(createWorkbenchMock(today));
const data = ref(api.load());
const date = ref(new Date(today));
const role = ref<"dispatcher" | "viewer">("dispatcher");
const roles = [
  { value: "dispatcher", label: "调度员（可编辑）" },
  { value: "viewer", label: "查看者（只读）" },
];
const statuses = {
  planned: "待出发",
  active: "进行中",
  submit: "待提交",
  review: "待审核",
  closed: "已完成",
};
const rejectSave = ref(false),
  conflict = ref(false),
  saving = ref(false),
  navigationOpen = ref(false),
  datePickerOpen = ref(false);
const query = ref(""),
  recent = ref<string[]>(["li", "station-a"]),
  selected = ref<string[]>(["me"]);
const selectedTasks = ref<string[]>([]),
  draggingTasks = ref<string[]>([]),
  dragDeadline = ref<string>();
const notice = ref(""),
  noticeError = ref(false),
  editorError = ref(""),
  lastPayload = ref("");
const editorOpen = ref(false),
  draft = ref<WorkbenchOrder>(),
  hoverOrder = ref("");
const closing = ref(false),
  manualPunch = ref(false),
  punchStart = ref<Date>(),
  punchEnd = ref<Date>();
const addTaskId = ref<string>(),
  workOrderTask = ref<WorkbenchTask>();
const host = ref<HTMLElement>();
const scheduler = ref();
let opener: HTMLElement | undefined;
let sequence = 0;
let staged: (() => SaveResult) | undefined;
const events = computed(() => projectWorkbench(data.value, selected.value));
const pending = computed(() => pendingWorkbenchTasks(data.value, today));
const resource = (id: unknown) =>
  data.value.resources.find((item) => item.id === id);
const task = (id: unknown) => data.value.tasks.find((item) => item.id === id);
const draftTasks = computed(() =>
  draft.value ? orderTasks(draft.value, data.value) : [],
);
const calculatedEnd = computed(() =>
  draft.value ? orderEnd(draft.value.start, draftTasks.value) : "",
);
const readOnly = computed(
  () =>
    role.value === "viewer" ||
    draft.value?.kind === "rest" ||
    draft.value?.status === "closed",
);
const activeOrder = computed(() =>
  editorOpen.value ? draft.value?.id : hoverOrder.value,
);
const personOptions = computed(() =>
  data.value.resources
    .filter((r) => r.dimensionId === "person")
    .map((r) => ({ value: r.id, label: r.label })),
);
const availableTaskOptions = computed(() =>
  pending.value
    .filter(
      (entry) =>
        !draft.value?.taskIds.includes(entry.id) &&
        (!draftTasks.value.length ||
          entry.deviceId === draftTasks.value[0].deviceId),
    )
    .map((entry) => ({
      value: entry.id,
      label: `${entry.title} · ${resource(entry.deviceId)?.label}`,
    })),
);
const eligiblePunches = computed(() =>
  data.value.punches.filter(
    (record) =>
      record.personId === draft.value?.personId &&
      record.deviceId === draftTasks.value[0]?.deviceId,
  ),
);
const linkedPunches = computed(() =>
  data.value.punches.filter((record) =>
    draft.value?.punchIds.includes(record.id),
  ),
);
const preview = computed<SchedulerEvent | undefined>(() =>
  editorOpen.value && draft.value?.version === 0
    ? {
        id: "workbench-draft",
        title:
          draftTasks.value.map((entry) => entry.title).join("、") || "新出勤单",
        start: draft.value.start,
        end: draft.value.allDay
          ? draft.value.end
          : draft.value.taskIds.length
            ? calculatedEnd.value
            : new Date(+new Date(draft.value.start) + 3600000).toISOString(),
        allDay: draft.value.allDay,
        color: resource(draft.value.personId)?.color,
        backgroundColor: resource(draft.value.personId)?.background,
      }
    : undefined,
);

interface Node extends TreeNodeData {
  resourceId?: string;
  taskId?: string;
  children?: Node[];
}
const group = (key: string, title: string, ids: string[]): Node => ({
  value: key,
  label: title,
  children: ids.map((id) => ({
    value: `${key}/${id}`,
    label: resource(id)?.label,
    resourceId: id,
  })),
});
const sourceTree = computed<Node[]>(() => [
  ...(query.value.trim()
    ? [
        group(
          "search",
          "搜索结果",
          data.value.resources
            .filter((r) =>
              `${r.label} ${r.account ?? ""}`
                .toLowerCase()
                .includes(query.value.trim().toLowerCase()),
            )
            .map((r) => r.id),
        ),
      ]
    : []),
  group("self", "自己", ["me"]),
  group("stations", "我的站", ["station-a", "station-b"]),
  group("favorites", "收藏", ["station-a", "station-c"]),
  group("recent", "最近使用", recent.value),
]);
const expandedSources = ref<Array<string | number>>([
  "self",
  "stations",
  "favorites",
  "recent",
  "search",
]);
const sourceKeys = computed(() =>
  sourceTree.value
    .flatMap((node) => node.children ?? [])
    .filter((node) => selected.value.includes(node.resourceId!))
    .map((node) => node.value!),
);
function checkSources(
  _keys: Array<string | number>,
  context: { checked?: boolean; node?: Node },
) {
  if (saving.value || !context.node) return;
  const ids = context.node.resourceId
    ? [context.node.resourceId]
    : (context.node.children ?? []).map((node) => node.resourceId!);
  selected.value = context.checked
    ? [...new Set([...selected.value, ...ids])]
    : selected.value.filter((id) => !ids.includes(id));
  if (context.checked)
    recent.value = [...new Set([...ids, ...recent.value])].slice(0, 12);
}
function toggleResource(id: string) {
  selected.value = selected.value.includes(id)
    ? selected.value.filter((value) => value !== id)
    : [...selected.value, id];
  recent.value = [...new Set([id, ...recent.value])].slice(0, 12);
}
const pendingTree = computed<Node[]>(() =>
  selected.value.flatMap((id) => {
    const owner = resource(id);
    const ids =
      owner?.dimensionId === "device"
        ? [id]
        : data.value.resources
            .filter((r) => r.managers?.includes(id))
            .map((r) => r.id);
    const tasks = pending.value.filter((entry) => ids.includes(entry.deviceId));
    return tasks.length
      ? [
          {
            value: `pending/${id}`,
            label: owner?.label,
            children: tasks.map((entry) => ({
              value: `pending/${id}/${entry.id}`,
              label: entry.title,
              taskId: entry.id,
            })),
          },
        ]
      : [];
  }),
);
const expandedPending = ref<Array<string | number>>(
  data.value.resources.map((r) => `pending/${r.id}`),
);
const pendingKeys = computed(() =>
  pendingTree.value
    .flatMap((node) => node.children ?? [])
    .filter((node) => selectedTasks.value.includes(node.taskId!))
    .map((node) => node.value!),
);
function checkPending(
  _keys: Array<string | number>,
  context: { checked?: boolean; node?: Node },
) {
  if (!context.node) return;
  const ids = context.node.taskId
    ? [context.node.taskId]
    : (context.node.children ?? []).map((node) => node.taskId!);
  const next = context.checked
    ? [...new Set([...selectedTasks.value, ...ids])]
    : selectedTasks.value.filter((id) => !ids.includes(id));
  if (new Set(next.map((id) => task(id)?.deviceId)).size > 1)
    return showNotice("请勾选同一设备的任务", true);
  selectedTasks.value = next;
}
const deadlineClass = (entry?: WorkbenchTask) => ({
  overdue: entry && remainingDays(entry, today) < 0,
  urgent:
    entry &&
    remainingDays(entry, today) >= 0 &&
    remainingDays(entry, today) <= 3,
});
const deadlineText = (entry?: WorkbenchTask) => {
  if (!entry) return "";
  const days = remainingDays(entry, today);
  return days < 0
    ? `逾期 ${-days} 天`
    : days === 0
      ? "今天截止"
      : `剩 ${days} 天`;
};
function beginPending(
  id: string,
  startDrag: (template: SchedulerEventTemplate, event: DragEvent) => void,
  event: DragEvent,
) {
  const ids = selectedTasks.value.includes(id)
    ? [...selectedTasks.value]
    : [id];
  draggingTasks.value = ids;
  dragDeadline.value = ids
    .map((key) => task(key)?.deadline ?? "")
    .filter(Boolean)
    .sort()[0];
  startDrag(
    {
      title: ids.map((key) => task(key)?.title).join("、"),
      duration: ids.reduce((sum, key) => sum + (task(key)?.minutes ?? 0), 0),
      metadata: { taskIds: ids },
    },
    event,
  );
}
function captureDrag(event: PointerEvent) {
  const node = (event.target as HTMLElement).closest<HTMLElement>(
    "[data-order-id]",
  );
  const order = data.value.orders.find(
    (item) => item.id === node?.dataset.orderId,
  );
  if (
    order &&
    order.kind === "work" &&
    order.status !== "closed" &&
    role.value !== "viewer"
  )
    dragDeadline.value = orderTasks(order, data.value)
      .map((entry) => entry.deadline)
      .sort()[0];
}
function endDrag() {
  dragDeadline.value = undefined;
  draggingTasks.value = [];
}
function allowMerge(event: DragEvent, target: SchedulerEvent) {
  if (
    draggingTasks.value.length &&
    !target.readonly &&
    !saving.value &&
    role.value !== "viewer"
  )
    event.preventDefault();
}
async function dropMerge(event: DragEvent, target: SchedulerEvent) {
  if (!draggingTasks.value.length) return;
  event.preventDefault();
  event.stopPropagation();
  const ids = [...draggingTasks.value];
  endDrag();
  const current = data.value.orders.find(
    (order) => order.id === target.metadata?.orderId,
  );
  if (!current || target.readonly || saving.value || role.value === "viewer")
    return showNotice("当前记录不可合并", true);
  const next = copyData(current);
  next.taskIds = [...new Set([...next.taskIds, ...ids])];
  if (!next.allDay)
    next.end = orderEnd(next.start, orderTasks(next, data.value));
  await persist(next);
}
function openEditor(request: SchedulerEditorRequest) {
  editorError.value = "";
  closing.value = false;
  manualPunch.value = false;
  addTaskId.value = undefined;
  opener =
    document.activeElement instanceof HTMLElement
      ? document.activeElement
      : undefined;
  if (request.action === "edit") {
    const order = data.value.orders.find(
      (item) => item.id === request.event.metadata?.orderId,
    );
    if (!order) return;
    draft.value = copyData(order);
  } else {
    const templateIds = request.event.metadata?.taskIds;
    const ids = Array.isArray(templateIds)
      ? templateIds.filter((id): id is string => typeof id === "string")
      : [...selectedTasks.value];
    const start = new Date(request.event.start ?? date.value);
    if (request.source === "toolbar") start.setHours(9, 0, 0, 0);
    else if (request.source === "cell") start.setMinutes(0, 0, 0);
    draft.value = {
      id: `ATT-${Date.now()}-${++sequence}`,
      version: 0,
      personId:
        selected.value.find((id) => resource(id)?.dimensionId === "person") ??
        "me",
      taskIds: ids,
      start: start.toISOString(),
      end: request.event.allDay
        ? new Date(request.event.end!).toISOString()
        : orderEnd(
            start.toISOString(),
            ids.map(task).filter((entry): entry is WorkbenchTask => !!entry),
          ),
      allDay: request.event.allDay,
      kind: "work",
      status: "planned",
      punchIds: [],
    };
  }
  punchStart.value = new Date(draft.value.start);
  punchEnd.value = new Date(draft.value.end);
  editorOpen.value = true;
  endDrag();
}
function setStart(value: Date | undefined) {
  if (draft.value && value && Number.isFinite(+value))
    draft.value.start = value.toISOString();
}
function setAllDayEnd(value: Date | undefined) {
  if (draft.value && value && Number.isFinite(+value))
    draft.value.end = value.toISOString();
}
function addTask(id: string) {
  if (draft.value && id)
    draft.value.taskIds = [...new Set([...draft.value.taskIds, id])];
  addTaskId.value = undefined;
}
function addSelected() {
  if (!draft.value) return;
  const ids = [...new Set([...draft.value.taskIds, ...selectedTasks.value])];
  if (new Set(ids.map((id) => task(id)?.deviceId)).size > 1) {
    editorError.value = "一张出勤单只能安排同一设备的任务";
    return;
  }
  draft.value.taskIds = ids;
}
function removeDraftTask(id: string) {
  if (draft.value)
    draft.value.taskIds = draft.value.taskIds.filter((value) => value !== id);
}
function taskStart(index: number) {
  return draft.value
    ? orderEnd(draft.value.start, draftTasks.value.slice(0, index))
    : "";
}
function togglePunch(id: string, checked: boolean) {
  if (draft.value)
    draft.value.punchIds = checked
      ? [...new Set([...draft.value.punchIds, id])]
      : draft.value.punchIds.filter((key) => key !== id);
}
function options() {
  const value = {
    role: role.value,
    fail: rejectSave.value,
    conflict: conflict.value,
  };
  conflict.value = false;
  return value;
}
function accept(result: SaveResult) {
  data.value = result.data;
  selectedTasks.value = selectedTasks.value.filter((id) =>
    pending.value.some((entry) => entry.id === id),
  );
  showNotice(result.warnings.join("；") || "已保存", false);
}
async function persist(
  value: WorkbenchOrder,
  remove = false,
  manual?: WorkbenchPunch,
) {
  saving.value = true;
  editorError.value = "";
  lastPayload.value = JSON.stringify(
    {
      operation: remove ? "remove" : "save",
      order: value,
      manualPunch: manual,
    },
    null,
    2,
  );
  try {
    accept(await api.save(value, options(), remove, manual));
    return true;
  } catch (error) {
    editorError.value = error instanceof Error ? error.message : "保存失败";
    showNotice(editorError.value, true);
    return false;
  } finally {
    saving.value = false;
  }
}
async function saveDraft(remove = false) {
  if (!draft.value || saving.value || readOnly.value) return;
  const value = copyData(draft.value);
  const dissolve = !!value.version && !value.taskIds.length;
  if (!value.allDay && value.taskIds.length)
    value.end = orderEnd(value.start, orderTasks(value, data.value));
  let manual: WorkbenchPunch | undefined;
  if (closing.value && !remove && !dissolve) {
    value.status = "closed";
    if (manualPunch.value) {
      if (
        !punchStart.value ||
        !punchEnd.value ||
        !Number.isFinite(+punchStart.value) ||
        !Number.isFinite(+punchEnd.value)
      ) {
        editorError.value = "请填写登录和注销时间";
        return;
      }
      manual = {
        id: `punch-${Date.now()}-${++sequence}`,
        personId: value.personId,
        deviceId: draftTasks.value[0]?.deviceId ?? "",
        start: punchStart.value.toISOString(),
        end: punchEnd.value.toISOString(),
      };
      value.punchIds = [...value.punchIds, manual.id];
    }
  }
  if (await persist(value, remove || dissolve, manual)) closeEditor();
}
async function prepareMove(context: SchedulerChangeContext) {
  if (!context.previous || context.type !== "move")
    throw new Error("请在出勤单详情中修改");
  if (context.event.allDay !== context.previous.allDay)
    throw new Error("请在详情中调整全天安排");
  const next = moveWorkbenchOrder(data.value, context.event, context.previous);
  lastPayload.value = JSON.stringify(
    { operation: "move", order: next },
    null,
    2,
  );
  staged = await api.prepare(next, options());
  return true;
}
function finishMove() {
  try {
    if (staged) accept(staged());
  } catch (error) {
    moveError(error);
  } finally {
    staged = undefined;
    endDrag();
  }
}
function moveError(error: unknown) {
  staged = undefined;
  showNotice(error instanceof Error ? error.message : "保存失败", true);
  endDrag();
}
function showNotice(message: string, error: boolean) {
  notice.value = message;
  noticeError.value = error;
}
function reload() {
  data.value = api.load();
  if (draft.value?.version)
    draft.value = copyData(
      data.value.orders.find((item) => item.id === draft.value?.id) ??
        draft.value,
    );
  editorError.value = "";
  showNotice("已重新加载", false);
}
async function onEditorVisibility(open: boolean) {
  if (open) return;
  hoverOrder.value = "";
  await nextTick();
  if (opener?.isConnected) opener.focus({ preventScroll: true });
}
function closeEditor() {
  editorOpen.value = false;
  void onEditorVisibility(false);
}
async function chooseDate(value: Date | undefined) {
  if (value && Number.isFinite(+value)) date.value = value;
  datePickerOpen.value = false;
}
async function goToday() {
  date.value = new Date();
  await nextTick();
  const container =
    host.value?.querySelector<HTMLElement>(".c-scheduler__main");
  const heading = [
    ...(host.value?.querySelectorAll<HTMLElement>(
      "[data-scheduler-heading-date]",
    ) ?? []),
  ].find(
    (element) =>
      schedulerDateKey(element.dataset.schedulerHeadingDate!) ===
      schedulerDateKey(new Date()),
  );
  const cell = host.value?.querySelector<HTMLElement>(
    ".c-scheduler__time-cell",
  );
  if (container && cell) {
    container.scrollTop = (cell.getBoundingClientRect().height || 36) * 7;
    if (heading) container.scrollLeft = Math.max(0, heading.offsetLeft - 64);
  }
}
const time = (value: SchedulerEvent["start"]) =>
  value == null
    ? ""
    : new Date(value).toLocaleTimeString("zh-CN", {
        hour: "2-digit",
        minute: "2-digit",
        hour12: false,
      });
const format = (value: string) =>
  new Date(value).toLocaleString("zh-CN", {
    month: "numeric",
    day: "numeric",
    hour: "2-digit",
    minute: "2-digit",
    hour12: false,
  });
const cancelWithEscape = (event: KeyboardEvent) => {
  if (event.key === "Escape") endDrag();
};
onMounted(() => {
  window.addEventListener("pointerup", endDrag);
  window.addEventListener("pointercancel", endDrag);
  window.addEventListener("blur", endDrag);
  window.addEventListener("keydown", cancelWithEscape);
});
onBeforeUnmount(() => {
  window.removeEventListener("pointerup", endDrag);
  window.removeEventListener("pointercancel", endDrag);
  window.removeEventListener("blur", endDrag);
  window.removeEventListener("keydown", cancelWithEscape);
});
watch(query, () => {
  if (!expandedSources.value.includes("search"))
    expandedSources.value.push("search");
});
</script>
<style scoped>
.workbench-shell {
  display: flex;
  min-width: 0;
}
.workbench-nav {
  flex: 0 0 88px;
  display: flex;
  flex-direction: column;
  border: 1px solid var(--c-color-border);
}
.task-calendar-workbench {
  min-width: 0;
  flex: 1;
  --c-scheduler-sidebar-width: 420px;
  --c-scheduler-max-height: 650px;
  --c-scheduler-min-height: 650px;
  --c-scheduler-column-min-width: 110px;
  --c-scheduler-gap: 8px;
  --c-scheduler-padding: 10px;
}
.task-calendar-workbench :deep(.c-scheduler__sidebar) {
  padding: 0;
  overflow: hidden;
}
.workbench-panels {
  display: grid;
  grid-template-columns: 190px minmax(0, 1fr);
  grid-template-rows: minmax(0, 1fr);
  height: 650px;
  min-height: 0;
}
.source-panel,
.pending-panel {
  min-width: 0;
  min-height: 0;
  display: flex;
  flex-direction: column;
  padding: 12px;
  gap: 12px;
}
.source-panel {
  border-right: 1px solid var(--c-color-border);
}
.panel-scroll {
  min-height: 0;
  flex: 1;
  overflow-y: auto;
  overflow-x: hidden;
}
.source-object {
  color: var(--c-color-text-1);
  position: relative;
  display: block;
  white-space: nowrap;
}
.source-object small {
  display: block;
  font-size: 11px;
  color: var(--c-color-text-3);
}
.quick-actions {
  display: none;
  position: absolute;
  right: 0;
  bottom: 100%;
  z-index: 5;
  background: var(--c-color-bg-2);
  box-shadow: 0 2px 8px #0002;
}
.source-object:hover .quick-actions,
.source-object:focus-within .quick-actions,
.source-scroll :deep(.c-tree-node:focus-within) .quick-actions {
  display: flex;
}
.source-scroll :deep(.c-tree-node:has([data-owner="me"])) {
  --c-checkbox-control-color-checked: #466caa;
}
.source-scroll :deep(.c-tree-node:has([data-owner="li"])) {
  --c-checkbox-control-color-checked: #ad813c;
}
.source-scroll :deep(.c-tree-node:has([data-owner="zhang"])) {
  --c-checkbox-control-color-checked: #4b8d70;
}
.source-scroll :deep(.c-tree-node:has([data-owner="station-a"])) {
  --c-checkbox-control-color-checked: #8670ac;
}
.source-scroll :deep(.c-tree-node:has([data-owner="station-b"])) {
  --c-checkbox-control-color-checked: #a1657e;
}
.source-scroll :deep(.c-tree-node:has([data-owner="station-c"])) {
  --c-checkbox-control-color-checked: #458c98;
}
.pending-task {
  color: var(--c-color-text-2);
  display: flex;
  flex-direction: column;
  white-space: normal;
  font-size: 12px;
  line-height: 1.5;
  padding: 8px 0;
  cursor: grab;
}
.pending-task.overdue {
  color: #b8434b;
}
.pending-task.urgent {
  color: #a7782d;
}
.task-card {
  color: var(--c-scheduler-event-color);
  width: 100%;
  height: 100%;
  min-height: 0;
  display: flex;
  flex-direction: column;
  overflow: hidden;
  text-align: left;
}
.task-card > * {
  white-space: nowrap;
  overflow: hidden;
  text-overflow: clip;
  flex-shrink: 0;
  line-height: 16px;
}
.task-card.closed::after {
  content: "";
  position: absolute;
  inset: 0;
  background: #ffffff66;
  pointer-events: none;
}
.task-calendar-workbench :deep(.c-scheduler__event) {
  border: 1px solid var(--c-scheduler-event-color);
  border-left-width: 4px;
  color: var(--c-scheduler-event-color);
  margin-bottom: 0;
}
.task-calendar-workbench :deep(.c-scheduler__event--static) {
  border-left-width: 1px;
}
.task-calendar-workbench :deep(.c-scheduler__positioned-event) {
  padding-top: 0;
  padding-bottom: 0;
}
.task-calendar-workbench :deep(.c-scheduler__event:has([data-edge="first"])) {
  border-bottom: 0;
  border-bottom-left-radius: 0;
  border-bottom-right-radius: 0;
}
.task-calendar-workbench :deep(.c-scheduler__event:has([data-edge="middle"])) {
  border-block: 0;
  border-radius: 0;
}
.task-calendar-workbench :deep(.c-scheduler__event:has([data-edge="last"])) {
  border-top: 0;
  border-top-left-radius: 0;
  border-top-right-radius: 0;
}
.task-calendar-workbench :deep(.c-scheduler__event:has(.linked)) {
  box-shadow: inset 0 0 0 2px currentColor;
}
.task-calendar-workbench :deep(.c-scheduler__event:has(.rest)) {
  border-style: dashed;
}
.task-calendar-workbench :deep(.c-scheduler__event-button) {
  height: 100%;
  align-items: flex-start;
  padding-block: 0;
}
.deadline-mask {
  position: absolute;
  inset: 0;
  background: #66708526;
  pointer-events: none;
}
.detail-task-list {
  display: flex;
  flex-direction: column;
  gap: 12px;
  width: 100%;
}
.detail-task {
  padding: 8px 0;
  border-bottom: 1px solid var(--c-color-border);
}
.workbench-test-controls,
.workbench-notice {
  margin-top: 12px;
}
.payload {
  max-width: 480px;
  max-height: 300px;
  overflow: auto;
}

.task-calendar-workbench :deep(.c-scheduler__toolbar) {
  padding: 14px 16px;
}
.task-calendar-workbench :deep(.c-scheduler__toolbar .c-button) {
  box-shadow: none;
}
.task-calendar-workbench :deep(.c-scheduler__time-heading) {
  font-weight: 500;
}
.panel-title {
  font-size: 13px;
  font-weight: 600;
  color: var(--c-color-text-1);
}
.panel-scroll {
  scrollbar-width: thin;
  scrollbar-color: var(--c-color-border) transparent;
}
.source-scroll :deep(.c-tree-node-title-text),
.pending-panel :deep(.c-tree-node-title-text) {
  color: var(--c-color-text-2);
}
.pending-task {
  border-bottom: 1px solid var(--c-color-border);
}
.pending-task > small {
  color: var(--c-color-text-3);
}
.pending-task:active {
  cursor: grabbing;
}
.task-card > :first-child {
  font-weight: 600;
}
.task-card > :not(:first-child) {
  opacity: 0.85;
}
.quick-actions {
  border: 1px solid var(--c-color-border);
  border-radius: 6px;
  padding: 4px;
}
.workbench-test-controls {
  padding: 12px 16px;
  background: var(--c-color-fill-1);
  border-radius: 8px;
}
</style>
```

## API

### `<c-scheduler>` Props

| Prop | Description | Type | Default |
| -------------------------- | ----------------------------------------------------------------------- | ----------------------------------------------- | ------------ |
| model-value | Schedule data; supports v-model and becomes controlled when provided | SchedulerEvent[] | — |
| preview-event | Unsaved new-event placeholders; visual only | SchedulerEvent | — |
| default-value | Initial uncontrolled data | SchedulerEvent[] | [] |
| mode | Current view; supports v-model:mode | SchedulerMode | — |
| default-mode | Default uncontrolled view | SchedulerMode | week |
| date | Navigation date; supports v-model:date | Date / string / number | — |
| default-date | Initial navigation date | Date / string / number | Current date |
| resource-dimensions | Dimension definitions: `{ id, label }[]` | SchedulerResourceDimension[] | [] |
| resource-filters | Combined resource-dimension filters; supports v-model:resource-filters | SchedulerResourceFilters | — |
| default-resource-filters | Initial uncontrolled filters | SchedulerResourceFilters | {} |
| resource-dimension | Resource row/column dimension; an empty string shows all | string | — |
| default-resource-dimension | Initial uncontrolled display dimension | string | '' |
| resources | Currently visible resource rows/columns and local options; a complete directory is unnecessary | SchedulerResource[] | [] |
| resource-label | Resource field name, such as equipment or meeting room | string | Localized resource label |
| request-resources | Query resource candidates by keyword and cursor | SchedulerRequestResources | — |
| resolve-resources | Batch-resolve resource names by ID | SchedulerResolveResources | — |
| modes | Views available for switching | SchedulerMode[] | All six views |
| first-day-of-week | Week start: 0 Sunday to 6 Saturday | number | 1 |
| start-hour | Time-grid start hour, 0–23 | number | 8 |
| end-hour | Time-grid end hour; greater than start and at most 24 | number | 20 |
| initial-scroll-minute | Minute of day initially scrolled into view; subsequent renders retain user scroll position | number | — |
| step | Grid/snap interval in minutes; a positive integer dividing 60 | number | 30 |
| slot-duration | Grid interval in minutes; positive integer | number | step |
| snap-duration | Pointer snap interval in minutes; positive integer | number | step |
| default-duration | Default duration for click-to-create, in positive integer minutes | number | step |
| drag-to-create | Drag-select empty slots in day/week/resource-day views | boolean | false |
| month-event-limit | Maximum directly displayed events per month-view day; extra events use Popover | number | 3 |
| overlap-event-limit | Maximum directly displayed events per overlapping time-grid group; extra events use Popover | number | — |
| zoom / default-zoom | Timeline zoom, 0.5–4 | number | 1 |
| show-date-header | Tiered timeline date headers | boolean | true |
| show-assignment-details | Edit resource occupancy and roles | boolean | false |
| show-resource-load | Resource peak load, capacity and utilization within the range | boolean | false |
| rule-policy | allow/warn/block policies for capacity/unavailable/conflict | SchedulerRulePolicy | {}（block） |
| dependencies | Task dependencies | SchedulerDependency[] | [] |
| event-layout | Time-grid layout: stack / columns / geometry callback. Week defaults to stack; others to columns | SchedulerEventLayout | Depends on the view |
| readonly | Viewing/navigation allowed, editing blocked | boolean | false |
| disabled | Disable interaction | boolean | false |
| hidden-days | Hide specified weekdays in week/month/agenda, 0–6; cannot hide every day | number[] | [] |
| show-now-indicator | Show the current local-time line in day/week/resource-day views | boolean | false |
| show-sidebar | Show filters and the unscheduled list | boolean | true |
| allow-overlap | Allow overlapping times for the same resource | boolean | true |
| editable | Enable the built-in editor; false delegates through editor-request | boolean | true |
| before-change | Return false to cancel; supports asynchronous interception and save APIs | SchedulerBeforeChange / SchedulerBeforeChange[] | — |

mode is `day | week | month | agenda | resource-day | resource-timeline`. Agenda/resource-timeline navigate by week. Events outside time-grid hours remain visible in month/agenda/timeline.

With controlled model-value, the component proposes data and waits for parent acceptance before changing the UI; it does not move first and roll back after request failure. Input arrays/objects are not mutated. before-change receives detached copies; editing them does not alter the committed proposal.

### `<c-scheduler>` Events

| Event | Description | Arguments |
| ------------------------ | ---------------------------------------------------------------- | ------------------------------------ |
| update:model-value | Proposes a new main value | SchedulerEvent[] |
| update:resourceFilters | Combined resource-filter changes; controlled mode waits for parent acceptance | SchedulerResourceFilters |
| update:resourceDimension | Resource row/column display-dimension changes | string |
| update:mode | View changes | SchedulerMode |
| update:zoom | Timeline zoom changes | number |
| rule-warning | Advisory rule issues on an accepted proposal | SchedulerError[] |
| update:date | Navigation-date changes | Date |
| change | Validation/hooks complete; controlled mode has proposed a validated value | value, SchedulerChangeContext |
| change-error | Validation, conflict, save or stale-proposal errors | error, SchedulerChange |
| event-click | Activate an event with a copy; stacked events support click/Enter too, while multiselection does not activate | SchedulerEvent |
| cell-click | Click an empty time slot | SchedulerCell |
| range-change | Initial and actual visible-date-range changes | SchedulerRange |
| resource-error | Resource search/display resolution fails without changing schedule data | error, SchedulerResourceErrorContext |
| editor-request | Only with editable=false: request external creation or viewing/editing | SchedulerEditorRequest |

### `<c-scheduler>` Slots

| Slot | Arguments | Description |
| ----------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ |
| event | { event } | Event-button content |
| sidebar | { startDrag, cancelDrag, disabled, unscheduled } | Replace the entire sidebar, e.g. with a resource tree/task pool; hidden when show-sidebar=false |
| sidebar-extra | { startDrag, cancelDrag, disabled } | Content above the default sidebar; startDrag(template: SchedulerEventTemplate, event: DragEvent). Hidden when show-sidebar=false |
| resource-header | { resource?, resources?, date } | Resource or date header |
| toolbar | { date, mode, navigate, create } | Replace the toolbar; navigate(-1/1) changes range, create() follows toolbar creation |
| column-background | { date, resource? } | Background for day/week/resource-day columns without intercepting pointers; useful for soft warnings/heatmaps |
| toolbar-extra | { date, mode } | Toolbar extension |
| editor | SchedulerEditorSlotProps | Custom drawer content: action, event, error, errorMessage, save, remove, close, readonly, pending |
| empty | — | Empty state |

### Instance methods

| Method | Description |
| ---------------------------------- | -------------------------------------------------------------- |
| `change(change): Promise<boolean>` | Execute create/update/remove/move/resize with all validation/hooks |
| duplicateEvent(id: string) | Open a separately copied draft or request custom creation; returns boolean without automatically saving |
| goToDate(date: Date) | Navigate to a date; respects controlled models |

## Type definitions

```ts
import type {
  SchedulerProps,
  SchedulerInstance,
  SchedulerMode,
  SchedulerEvent,
  SchedulerResource,
  SchedulerChange,
  SchedulerChangeContext,
  SchedulerBeforeChange,
  SchedulerEventTemplate,
  SchedulerRequestResources,
  SchedulerResolveResources,
  SchedulerResourcePage,
  SchedulerResourceQuery,
  SchedulerResourceErrorContext,
  SchedulerEditorRequest,
  SchedulerEditorAction,
  SchedulerEditorSlotProps,
} from "@cedar-design/ui";

interface SchedulerEvent {
  id: string;
  title: string;
  start?: Date | string | number;
  end?: Date | string | number;
  allDay?: boolean;
  resourceIds?: string[];
  resourceDetails?: Record<string, { units?: number; role?: string }>;
  milestone?: boolean;
  layoutGroupId?: string;
  description?: string;
  color?: string;
  accentColor?: string;
  backgroundColor?: string;
  backgroundPattern?: "solid" | "diagonal-stripes" | "dots" | "crosshatch";
  metadata?: Record<string, unknown>;
  readonly?: boolean;
  resizable?: boolean; // false disables time-grid resizing while preserving moving/viewing
}
type SchedulerEventTemplate = Pick<
  SchedulerEvent,
  | "title"
  | "description"
  | "color"
  | "accentColor"
  | "backgroundColor"
  | "backgroundPattern"
  | "metadata"
  | "resourceIds"
> & {
  duration?: number; // positive minutes; defaults to default-duration or step
};
interface SchedulerResource {
  id: string;
  dimensionId?: string;
  label: string;
  color?: string;
  disabled?: boolean;
  capacity?: number; // nonnegative safe integer; omission leaves concurrent event counts unlimited
}
interface SchedulerResourceQuery {
  dimensionId?: string;
  query: string;
  cursor?: string;
  signal: AbortSignal;
}
interface SchedulerResourcePage {
  items: SchedulerResource[];
  nextCursor?: string;
}
type SchedulerRequestResources = (
  query: SchedulerResourceQuery,
) => SchedulerResourcePage | Promise<SchedulerResourcePage>;
type SchedulerResolveResources = (
  ids: string[],
  context: { signal: AbortSignal },
) => SchedulerResource[] | Promise<SchedulerResource[]>;
type SchedulerResourceErrorContext =
  | { type: "search"; query: string; cursor?: string }
  | { type: "resolve"; ids: string[] };

type SchedulerEditorAction = "create" | "edit";
type SchedulerEditorRequest = { event: SchedulerEvent; readonly: boolean } & (
  | { action: "create"; source: "toolbar" | "cell" | "drop" }
  | { action: "edit"; source: "event" }
);
interface SchedulerEditorSlotProps {
  action: SchedulerEditorAction;
  event: SchedulerEvent;
  error?: SchedulerError;
  errorMessage?: string;
  readonly: boolean;
  pending: boolean;
  save: (event?: SchedulerEvent) => void;
  remove: () => void;
  close: () => void;
}
```

Every event id must be unique. Omitting both start/end means unscheduled; otherwise end must follow start, except timed milestones requiring start=end. All intervals are `[start, end)`, so adjacent intervals do not conflict. allDay uses `YYYY-MM-DD` strings with an exclusive end, e.g. September 9–10 for a one-day event.

Display currently uses the runtime's local zone; timed events should use ISO instants. Arbitrary IANA display zones are not promised. Cross-zone RRULE, ICS and version synchronization come from separate adapters; business code must connect real external accounts. Configure virtual resource rows with virtual-list-props. See examples for local undo and range-based remote loading. Pointer drag supports moving/resizing; Escape cancels. Keyboard/touch users can also schedule/assign through the editor. Disabled resource options prevent new assignments/drops while existing associations may remain or be removed.

## Independent core

`src/scheduler/core` imports no Vue, DOM or external calendar library. It can be tested independently and later extracted as scheduler-core. The published pure-core subentry avoids importing component runtime:

```ts
import {
  applySchedulerChange,
  getSchedulerConflicts,
  layoutSchedulerEvents,
} from "@cedar-design/ui/scheduler/core";
```

Other date/timeline utilities are exported from this entry too. The core computes and applies immutable changes; it does not handle networking, authorization or database transactions.

### Style variables

All variables are defined in `style/token.less` and support light/dark theme overrides.

| Variable | Default |
| -------------------------------- | ------------------------------ |
| --c-scheduler-background | var(--c-color-bg-2) |
| --c-scheduler-color | var(--c-color-text-1) |
| --c-scheduler-border-color | var(--c-color-border) |
| --c-scheduler-sidebar-width | 220px |
| --c-scheduler-slot-height | 36px |
| --c-scheduler-column-min-width | 120px |
| --c-scheduler-max-height | 720px |
| --c-scheduler-event-color | rgb(var(--c-primary-6)) |
| --c-scheduler-event-accent-color | var(--c-scheduler-event-color) |
| --c-scheduler-event-background | var(--c-color-primary-light-1) |
| --c-scheduler-lane-height | 38px |
| --c-scheduler-ghost-opacity | 0.75 |
| --c-scheduler-preview-opacity | 0.85 |
| --c-scheduler-preview-duration | 100ms |
| --c-scheduler-ghost-z-index | 2000 |

### Before-hook waiting feedback

Before-hook waits show visible feedback and aria-busy. Rejected or failed operations recover; duplicate submissions do not start another copy. Notification event Promises never drive loading.

---

Document: llms/en-US/components/scrollbar.md

<!-- Source: src/scrollbar/README.en-US.md; locale: en-US; page: /en/components/scrollbar/ -->

# Scrollbar

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

Example source: src/scrollbar/__demos__/basic.vue

```vue
<template>
  <c-scrollbar style="height: 200px; overflow: auto">
    <div style="height: 2000px; width: 2000px; background-color: var(--c-color-primary-light-1)">Content</div>
  </c-scrollbar>
</template>

<script lang="ts" setup>
</script>
```

## Appearance and states

### Type

- `type`: Type

Example source: src/scrollbar/__demos__/type.vue

```vue
<template>
  <c-scrollbar type="track" style="height: 200px; overflow: auto">
    <div style="height: 2000px; width: 2000px; background-color: var(--color-primary-light-4)">Content</div>
  </c-scrollbar>
</template>

<script lang="ts" setup>
</script>
```

## Lifecycle and edge cases

### Thumb Lifecycle

Example source: src/scrollbar/__demos__/thumb-lifecycle.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const active = ref(true)
const mounted = ref(true)
const scrolls = ref(0)
</script>
<template>
  <div>
    <c-button @click="active = !active">Activate / 停用与激活</c-button>
    <c-button @click="mounted = !mounted">Mount / 卸载与挂载</c-button>
    <c-button @mouseenter="active = false">Hover while dragging to deactivate / 拖动时移入停用</c-button>
    <p>Scroll notifications / 滚动通知: {{ scrolls }}. Drag a thumb, release, open context menu or blur the window; later movement must not replay. Fresh activation requires a fresh press.</p>
    <KeepAlive v-if="mounted">
      <c-scrollbar v-if="active" style="height: 160px; width: 260px; overflow: auto" @scroll="scrolls++">
        <div style="height: 800px; width: 700px">Drag the horizontal/vertical thumb / 拖动横向或纵向滑块</div>
      </c-scrollbar>
    </KeepAlive>
  </div>
</template>
```

### Lifecycle

Example source: src/scrollbar/__demos__/lifecycle.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
import type { ScrollbarInstance } from '@cedar-design/ui'
const active = ref(true)
const mounted = ref(true)
const bar = ref<ScrollbarInstance>()
let retained: ScrollbarInstance | undefined
function remember() { retained = bar.value }
function scrollRetained() { retained?.scrollTo(100, 100) }
</script>
<template>
  <div>
    <c-button @click="remember">Remember handle / 保留句柄</c-button>
    <c-button @click="active = !active">Activate / 停用与激活</c-button>
    <c-button @click="mounted = !mounted">Mount / 卸载与挂载</c-button>
    <c-button @click="scrollRetained">Retained scroll / 调用保留滚动</c-button>
    <c-button @click="bar?.scrollTo(0, 0)">Origin / 回到原点</c-button>
    <p>Remember the handle, deactivate or unmount, then call it. It must be inert. Activate for fresh commands; zero coordinates must work.</p>
    <KeepAlive v-if="mounted">
      <c-scrollbar v-if="active" ref="bar" style="height: 160px; width: 260px; overflow: auto">
        <div style="height: 800px; width: 700px">Scrollable content / 可滚动内容</div>
      </c-scrollbar>
    </KeepAlive>
  </div>
</template>
```

## API

### `<scrollbar>` Props

| Parameter | Description | Type | Default |
| ----------- | ---------- | ----------------------- | :-------: |
| type | Type | `'track' \| 'embed'` | `'embed'` |
| outer-class | Outer class | `string\|object\|array` | `-` |
| outer-style | Outer style | `StyleValue` | `-` |

### `<scrollbar>` Events

| Event | Description | Arguments |
| ------ | ---------- | ---- |
| scroll | Emitted on scrolling | - |

### `<scrollbar>` Methods

| Method | Description | Arguments | Returns | Version |
| ---------- | -------- | ---------------------------------------------------------------- | ------ | :----- |
| scrollTo | Scroll | options: `number \| {left?: number;top?: number}`<br>y: `number` | - |  |
| scrollTop | Vertical scroll | top: `number` | - | 2.40.0 |
| scrollLeft | Horizontal scroll | left: `number` | - | 2.40.0 |

### Type definitions

The component exports the following types

```ts
import type { ScrollbarBoxInstance } from '@cedar-design/ui'
```

---

Document: llms/en-US/components/search.md

<!-- Source: src/search/README.en-US.md; locale: en-US; page: /en/components/search/ -->

# Search

Search submits keywords and controlled field models. The application handles requests and loading.

## Basic examples

### Basic usage

Enter a keyword and press Enter. The first example has one input and one submitted value.

Example source: src/search/__demos__/en-US/basic.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
import type { SearchResult } from '@cedar-design/ui'
const keyword = ref('')
const submitted = ref('')
function onSearch(result: SearchResult) { submitted.value = result.modelValue }
</script>
<template>
  <c-search v-model="keyword" placeholder="Enter keywords and press Enter" @search="onSearch" />
  <p role="status">Submitted: {{ submitted || 'No search yet' }}</p>
</template>
```

## Data and options

### Search button

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration     | Purpose                                  | Related examples                               |
| ----------------- | ---------------------------------------- | ---------------------------------------------- |
| `placeholder`     | Placeholder                              | Search button, With Fields, Controlled history |
| `search-button`   | Whether to show the shared search button | Search button, With Fields                     |
| `recent-searches` | Controlled search history                | With Fields, Controlled history                |
| `button-text`     | Shared search button text                | Search button                                  |
| `fields`          | Search field options                     | With Fields                                    |
| `select-style`    | Field selector style                     | With Fields                                    |

<!-- demo-config-notes:end -->

Example source: src/search/__demos__/en-US/search-button.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
import type { SearchResult } from '@cedar-design/ui'
const keyword = ref('')
const submitted = ref('')
function onSearch(result: SearchResult) { submitted.value = result.modelValue }
</script>
<template>
  <c-search v-model="keyword" search-button button-text="Search" placeholder="Click Search to submit" @search="onSearch" />
  <p role="status">Submitted: {{ submitted || 'No search yet' }}</p>
</template>
```

### With Fields

Example source: src/search/__demos__/with-fields.vue

```vue
<template>
  <c-space direction="column">
    <c-search
      v-model="keyword"
      v-model:model-field="modelField"
      v-model:model="model"
      :style="inputStyle"
      :fields="fields"
      :recent-searches="recentSearches"
      :select-style="{ minWidth: '140px' }"
      default-field="name"
      placeholder="请输入搜索内容"
      search-button
      @change="handleChange"
      @search="handleSearch"
    />
    <c-button @click="resetModel">Reset Model</c-button>
    <div>最近提交：{{ latestChange || "-" }}</div>
    <pre v-if="latestResult">{{ JSON.stringify(latestResult, null, 2) }}</pre>
  </c-space>
</template>

<script lang="ts" setup>
import { ref } from "vue";
import type { SearchResult, SearchField } from "@cedar-design/ui";

const inputStyle = { width: "420px" };
const keyword = ref("");
const modelField = ref("name");
const model = ref<Record<string, unknown>>({});
const recentSearches = ref<string[]>(["设备 A", "设备 B", "设备 C"]);
const latestChange = ref("");
const latestResult = ref<SearchResult>();

const fields: SearchField[] = [
  {
    value: "id",
    label: "设备 ID",
    placeholder: "请输入设备 ID",
  },
  {
    value: "name",
    label: "设备名称",
    placeholder: "请输入设备名称",
  },
  {
    value: "desc",
    label: "设备描述",
    placeholder: "请输入设备描述",
  },
];

function handleSearch(data: SearchResult) {
  recentSearches.value = data.recentSearches;
  latestResult.value = data;
}

function handleChange(value: string) {
  latestChange.value = value;
}

function resetModel() {
  model.value = {};
  keyword.value = "";
}
</script>
```

### Controlled history

Example source: src/search/__demos__/local-storage.vue

```vue
<template>
  <c-space direction="column">
    <c-search
      v-model="keyword"
      :style="inputStyle"
      placeholder="业务侧使用 localStorage 保存搜索历史"
      :recent-searches="recentSearches"
      @search="handleSearch"
    />
    <c-button @click="clearRecentSearches">Clear History</c-button>
  </c-space>
</template>

<script lang="ts" setup>
import { ref } from "vue";
import type { SearchResult } from "@cedar-design/ui";

const inputStyle = { width: "360px" };
const storageKey = "__cedar_search_history__";

const keyword = ref("");
const recentSearches = ref<string[]>(loadRecentSearches());

function loadRecentSearches() {
  try {
    return JSON.parse(localStorage.getItem(storageKey) || "[]");
  } catch {
    return [];
  }
}

function saveRecentSearches(list: string[]) {
  localStorage.setItem(storageKey, JSON.stringify(list));
  recentSearches.value = list;
}

function handleSearch(data: SearchResult) {
  saveRecentSearches(data.recentSearches);
}

function clearRecentSearches() {
  saveRecentSearches([]);
}
</script>
```

## Customization and slots

### History presentation and slots

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration     | Purpose                                                                                 | Related examples               |
| ----------------- | --------------------------------------------------------------------------------------- | ------------------------------ |
| `edit-mode`       | Search editing mode: direct searches in place; popup opens the search editor in a popup | History presentation and slots |
| `recent-searches` | Controlled search history                                                               | History presentation and slots |
| `label`           | Text to the left of the search input                                                    | History presentation and slots |
| `placeholder`     | Placeholder                                                                             | History presentation and slots |
| `clearable`       | Whether the value can be cleared                                                        | History presentation and slots |
| `show-action`     | Whether to show the mobile action                                                       | History presentation and slots |

<!-- demo-config-notes:end -->

Example source: src/search/__demos__/en-US/presentation.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
const keyword = ref("");
const popup = ref(false);
const history = ref(["Project A", "Device B"]);
const lastAction = ref("No search yet");
</script>
<template>
  <div class="search-demo">
    <c-checkbox v-model="popup"
      >popup fullscreen search (uncheck for inline)</c-checkbox
    >
    <c-search
      v-model="keyword"
      :edit-mode="popup ? 'popup' : 'direct'"
      :recent-searches="history"
      label="Resource"
      placeholder="Enter resource name"
      clearable
      show-action
      action-text="Cancel"
      @cancel="lastAction = 'Cancelled'"
      @search="
        (result) => {
          history = result.recentSearches;
          lastAction = result.modelValue;
        }
      "
    />
    <c-search
      v-model="keyword"
      search-button
      :button-props="{ variant: 'outline' }"
      placeholder="Custom button slots"
      @search="(result) => (lastAction = result.modelValue)"
    >
      <template #button-icon><span aria-hidden="true">⌕</span></template>
      <template #button-default>Find</template>
    </c-search>
    <div>Last action：{{ lastAction }}</div>
  </div>
</template>
<style scoped>
.search-demo {
  display: flex;
  flex-direction: column;
  gap: 12px;
  max-width: 100%;
}
</style>
```

### Functional playground

## Interaction and control

### State Lab

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration   | Purpose                                            | Related examples           |
| --------------- | -------------------------------------------------- | -------------------------- |
| `placeholder`   | Placeholder                                        | State Lab, Loading         |
| `loading`       | Loading state; submission is blocked while loading | State Lab, Loading         |
| `readonly`      | Whether readonly                                   | State Lab, Loading         |
| `search-button` | Whether to show the shared search button           | Loading, Controlled Fields |
| `disabled`      | Whether disabled                                   | State Lab                  |
| `default-value` | Uncontrolled default keyword                       | Loading                    |

<!-- demo-config-notes:end -->

Example source: src/search/__demos__/state-lab.vue

```vue
<script setup lang="ts">
import { reactive as __demoReactive } from "vue";
const inputStyle = { width: "360px" };
const __demoState = __demoReactive({ disabled: false, readonly: false });
</script>
<template>
  <c-space direction="column" :size="16">
    <c-space wrap>
      <c-checkbox v-model="__demoState['disabled']">disabled</c-checkbox>
      <c-checkbox v-model="__demoState['readonly']">readonly</c-checkbox>
    </c-space>
    <c-search
      :style="inputStyle"
      placeholder="加载中"
      loading
      v-bind="__demoState"
    />
  </c-space>
</template>
```

### Loading

- `readonly`: Displays the current value without allowing edits.

Example source: src/search/__demos__/loading.vue

```vue
<template>
  <c-space direction="column">
    <c-search :style="inputStyle" placeholder="加载中" loading />
    <c-search
      :style="inputStyle"
      placeholder="按钮加载中"
      search-button
      loading
    />
    <c-search :style="inputStyle" default-value="只读内容" readonly />
  </c-space>
</template>

<script lang="ts" setup>
const inputStyle = { width: "360px" };
</script>
```

### Controlled Fields

Example source: src/search/__demos__/en-US/controlled-fields.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import type { SearchResult } from "@cedar-design/ui";

const field = ref("name");
const model = ref<Record<string, unknown>>({
  name: "Device A",
  tenant: "demo",
});
const accepted = ref(true);
const history = ref(["Device A", "42"]);
const result = ref<SearchResult>();
const fields = [
  { value: "name", label: "Device name", placeholder: "Enter name" },
  { value: "id", label: "Device ID", placeholder: "Enter ID" },
];
function updateModel(proposal: Record<string, unknown>) {
  if (accepted.value) model.value = proposal;
}
function updateField(proposal: string) {
  if (accepted.value) field.value = proposal;
}
function search(next: SearchResult) {
  result.value = next;
  history.value = next.recentSearches;
}
</script>
<template>
  <div class="search-demo">
    <c-checkbox v-model="accepted"
      >Accept updates (uncheck to demonstrate controlled rejection)</c-checkbox
    >
    <c-search
      :model="model"
      :model-field="field"
      :fields="fields"
      :recent-searches="history"
      edit-mode="direct"
      search-button
      button-text="Search"
      clearable
      @update:model="updateModel"
      @update:model-field="updateField"
      @search="search"
    />
    <c-button
      variant="text"
      @click="model = { name: 'External value', tenant: 'demo' }"
      >Replace model externally</c-button
    >
    <div>Accepted model：{{ model }}</div>
    <pre v-if="result">{{ JSON.stringify(result, null, 2) }}</pre>
  </div>
</template>
<style scoped>
.search-demo {
  display: flex;
  flex-direction: column;
  gap: 12px;
  max-width: 100%;
}
.search-demo pre {
  white-space: pre-wrap;
  overflow-wrap: anywhere;
}
</style>
```

## API

### Empty values and reading placeholders

`empty-values` recognizes empty data; `empty-value` keeps existing clear output. `empty-text` defaults to `'-'` under `read-pretty`, with Field > FormItem > Form precedence and custom read slots first. With explicit empty-values, built-in required uses the policy; custom validators receive original data. See the [shared guide](llms/en-US/guide/empty-values.md).

| Prop         | Type               | Default and scope                                                           |
| ------------ | ------------------ | --------------------------------------------------------------------------- |
| empty-values | readonly unknown[] | Field > FormItem > Form > component-family default; replaces the whole list |
| empty-text   | string             | Field > FormItem > Form > '-'; explicit '' is valid                         |

These props belong to field presentation; pure panels do not gain reading mode. Form and FormItem provide inherited settings. The existing empty-value type and clear fallback remain component-specific.

### Props

| Arguments                  | Description                                                                             | Type                      | Default                               |
| -------------------------- | --------------------------------------------------------------------------------------- | ------------------------- | ------------------------------------- |
| `v-model`                  | Search keyword                                                                          | _string_                  | `-`                                   |
| `default-value`            | Uncontrolled default keyword                                                            | _string_                  | `''`                                  |
| `v-model:model-field`      | Current search field                                                                    | _string_                  | `-`                                   |
| `default-field`            | Uncontrolled default field                                                              | _string_                  | `-`                                   |
| `v-model:model`            | Object updated by field in field-search mode                                            | _Record<string, unknown>_ | `-`                                   |
| `fields`                   | Search field options                                                                    | _SearchField[]_           | `[]`                                  |
| `select-style`             | Field selector style                                                                    | _StyleValue_              | `-`                                   |
| `recent-searches`          | Controlled search history                                                               | _string[]_                | `[]`                                  |
| `max-search-history-count` | Maximum items in the next history list                                                  | _number_                  | `5`                                   |
| `edit-mode`                | Search editing mode: direct searches in place; popup opens the search editor in a popup | `'direct' \| 'popup'`     | `'direct'`                            |
| `search-button`            | Whether to show the shared search button                                                | _boolean_                 | `false`                               |
| `button-text`              | Shared search button text                                                               | _string_                  | `-`                                   |
| `button-props`             | Shared search button props                                                              | _ButtonProps_             | `-`                                   |
| `loading`                  | Loading state; submission is blocked while loading                                      | _boolean_                 | `false`                               |
| `clearable`                | Whether the value can be cleared                                                        | _boolean_                 | `false`                               |
| `variant`                  | Input variant: `filled`, `outline`, or `standard`                                       | _string_                  | `outline`                             |
| `size`                     | Input size inherited from Form / ConfigProvider                                         | `xs / sm / md / lg / xl`  | `md`                                  |
| `placeholder`              | Placeholder                                                                             | _string_                  | `-`                                   |
| `disabled`                 | Whether disabled                                                                        | _boolean_                 | `false`                               |
| `readonly`                 | Whether readonly                                                                        | _boolean_                 | `false`                               |
| `label`                    | Text to the left of the search input                                                    | _string_                  | `-`                                   |
| `shape`                    | Inner field shape: `round` or `square`                                                  | _string_                  | `square`                              |
| `background`               | Outer background color                                                                  | _string_                  | `-`                                   |
| `input-background`         | Inner field background color                                                            | _string_                  | `-`                                   |
| `show-action`              | Whether to show the mobile action                                                       | _boolean_                 | `false`                               |
| `action-text`              | Action button text                                                                      | `string`                  | Follows global locale and action-type |
| `action-type`              | Action type: `cancel` or `search`                                                       | _string_                  | `cancel`                              |
| `search-icon`              | Search icon name                                                                        | _string_                  | `magnify`                             |
| `max-length`               | Maximum length                                                                          | _string \| number_        | `-`                                   |
| `enterkeyhint`             | Virtual keyboard Enter hint                                                             | _string_                  | `search`                              |

### Events

| Event               | Description                                              | Callback arguments                   |
| ------------------- | -------------------------------------------------------- | ------------------------------------ |
| `update:modelValue` | Emitted when the keyword updates                         | `value: string`                      |
| `update:modelField` | Emitted when the field updates                           | `field: string`                      |
| `update:model`      | Emitted when the field model updates                     | `model: Record<string, unknown>`     |
| `input`             | Emitted during live editing                              | `value: string, event: Event`        |
| `change`            | Emitted on blur, Enter commit, or field change           | `value: string, event: Event`        |
| `clear`             | Emitted when clearing                                    | `event: Event`                       |
| `search`            | Emitted by the icon, button, Enter, or history selection | `result: SearchResult, event: Event` |
| `focus`             | Emitted on focus                                         | `event: FocusEvent`                  |
| `blur`              | Emitted on blur                                          | `event: FocusEvent`                  |
| `cancel`            | Emitted by the mobile cancel action                      | `event: Event`                       |

### Slots

| Name             | Description                                    | Arguments   |
| ---------------- | ---------------------------------------------- | ----------- |
| `prefix`         | Input prefix; replaces the default search icon | `-`         |
| `suffix`         | Input suffix                                   | `-`         |
| `clear-icon`     | Clear icon                                     | `{ clear }` |
| `button-default` | Shared search button content                   | `-`         |
| `button-icon`    | Shared search button icon                      | `-`         |
| `label`          | Left label                                     | `-`         |
| `action`         | Action content                                 | `-`         |

### Methods

| Method  | Description | Arguments | Returns |
| ------- | ----------- | --------- | ------- |
| `focus` | Focus       | `-`       | `-`     |
| `blur`  | Blur        | `-`       | `-`     |

### SearchField

| Arguments     | Description                                         | Type     |
| ------------- | --------------------------------------------------- | -------- |
| `label`       | Field label                                         | _string_ |
| `value`       | Field value                                         | _string_ |
| `placeholder` | Field `placeholder`; overrides Search `placeholder` | _string_ |

### SearchResult

| Arguments        | Description         | Type                                   |
| ---------------- | ------------------- | -------------------------------------- |
| `modelField`     | Search field        | _string \| undefined_                  |
| `modelValue`     | Raw search keyword  | _string_                               |
| `model`          | Field model object  | _Record<string, unknown> \| undefined_ |
| `recentSearches` | Next search history | _string[]_                             |

Input event contract: editing emits `input` before `update:modelValue`; committing on blur emits `change` only for a changed value. Clearing emits `clear → input → update:modelValue → change` once, updates the search field model once, and does not submit a search.

input fires before model updates. Enter waits for Input submission and controlled-value reconciliation before producing search results. If the parent rejects a trim proposal, search still uses the actual controlled value. Clearing notifies clear → input → update:modelValue → change without automatically searching.

## Controlled-model protocol

Value precedence is `modelValue` > `model`[current field] > uncontrolled `defaultValue`. With `model` and a current field, missing/null values display an empty string. Keep simultaneously bound models consistent in the parent. `modelField` overrides `defaultField` and the first field. Internal logic never forcibly overrides controlled values.

`model` is not mutated in place. Every logical update emits a new `update:model` object, clearing other declared fields while retaining undeclared properties. Use `v-model:model` or explicitly accept proposals. Switching fields produces one `update:modelField → update:modelValue → update:model → change` sequence. Parents can reject proposals. Enter/button/history searches wait one update cycle, then read the actually accepted field, keyword and `model`.

History is neither filtered by current input nor persisted internally. New history returned by `search` is trimmed, emptied entries removed, deduplicated and limited to the configured maximum. Empty keywords are not added. Nonfinite/negative limits are treated as 0. Clearing does not `search`; cancel proposes an empty string and emits cancel/change without searching.

Editing emits `input → update:modelValue`; changed commits emit `change`. Clear emits `clear → input → update:modelValue → change` once. Disabled, readonly and loading block search, cancel, history and field actions. Form / FormItem / InputGroup state is inherited. Deactivation or unmount cancels pending asynchronous search.

### Platform boundaries

The controller, public API and history content are independently copied. Both default to `presentation=inline`; Cedar defaults to `shape=square` and Maple to `shape=round`. Fullscreen history uses local Drawer / Popup instances. Desktop InputGroup and mobile search-bar layout/touch spacing remain independent. Input supports `xs/sm/md/lg/xl`; outer bar density is configured by Search tokens rather than scaled by size.

### Public types

`SearchPresentation`、`SearchProps`, `SearchEmits`, `SearchSlots`, `SearchExpose`, `SearchField`, `SearchResult`.

### Forwarded Input props

Explicit Input props include `modelModifiers`, `type`, `ariaLabel`, `placeholder`, `maxLength`, `readonly`, `disabled`, `autofocus`, `enterkeyhint`, `textColor`, `focusColor`, `blurColor`, `size`, `variant`, `clearable`, `inputAttrs` and `error`. `inputAttrs` carries native name/autocomplete/ARIA attributes to both outer and fullscreen Input; `error` overrides inherited `error` state. Search actions, popup cancellation and dialog labels follow the global locale. Programmatic cancel, field and history selection notify Form change once; native edits retain the Input event pipeline.

## Configuring the cleared value

`empty-value` / `emptyValue` sets the model value produced by clearing. It accepts a value in the component model type or a zero-argument factory. Omission preserves the existing default; use `() => undefined` to distinguish omission from returning undefined. Arrays are shallow-copied on every clear; selected items that cannot be cleared remain. It does not redefine emptiness, alter Form reset defaults or treat 0/false as universally empty.
Text and person-ID models remain strings; use an empty string or a business-defined string sentinel.

---

Document: llms/en-US/components/segmented.md

<!-- Source: src/segmented/README.en-US.md; locale: en-US; page: /en/components/segmented/ -->

# Segmented

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

- `options`: Options

Example source: src/segmented/__demos__/basic.vue

```vue
<template>
  <c-segmented v-model="value" :options="['Daily', 'Weekly', 'Monthly']" />
</template>

<script setup>
import { ref } from 'vue'

const value = ref('Daily')
</script>
```

## Appearance and states

### Segment sizes and disabled states

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `size` | Size | Segment sizes and disabled states |
| `options` | Action list | Segment sizes and disabled states |
| `disabled` | Disable interaction | Segment sizes and disabled states |
| `default-value` | Uncontrolled default value | Segment sizes and disabled states |
<!-- demo-config-notes:end -->


Compare density at each size and disabled-option behavior.

Example source: src/segmented/__demos__/appearance-state-comparison.vue

```vue
<script setup lang="ts">
import { ref } from "vue"
import { proxyRefs as demoProxyRefs } from 'vue'

const scene1 = demoProxyRefs((() => {


const value = ref('md')

const options = ['xs', 'sm', 'md', 'lg', 'xl']
return { value, options }
})())

const scene2 = demoProxyRefs((() => {


const value = ref('on')
return { value }
})())
</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="size">
    <h4><span lang="zh-CN">尺寸</span><span lang="en-US">size</span></h4>
    <c-space direction="column">
        <c-segmented v-model="scene1.value" size="xs" :options="scene1.options" />
        <c-segmented v-model="scene1.value" size="sm" :options="scene1.options" />
        <c-segmented v-model="scene1.value" size="md" :options="scene1.options" />
        <c-segmented v-model="scene1.value" size="lg" :options="scene1.options" />
        <c-segmented v-model="scene1.value" size="xl" :options="scene1.options" />
      </c-space>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="disabled">
    <h4><span lang="zh-CN">禁用</span><span lang="en-US">disabled</span></h4>
    <c-space wrap>
        <c-segmented disabled :options="['A', 'B', 'C']" default-value="A" />
        <c-segmented
          v-model="scene2.value"
          :options="[{
      label: '可用',
      value: 'on'
    }, {
      label: '禁用',
      value: 'off',
      disabled: true
    }]"
        />
      </c-space>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

## Layout and arrangement

### Block

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `block` | Fill parent width | Block |
| `options` | Action list | Block |
<!-- demo-config-notes:end -->


- `block`: Fit parent width
- `options`: Options

Example source: src/segmented/__demos__/block.vue

```vue
<template>
  <div style="width: 360px">
    <c-segmented v-model="value" block :options="['列表', '看板', '日历']" />
  </div>
</template>

<script setup>
import { ref } from 'vue'

const value = ref('列表')
</script>
```

## Interaction and control

### Controlled

- `model-value`: Binding value
- `options`: Options

Example source: src/segmented/__demos__/controlled.vue

```vue
<template>
  <c-space direction="column">
    <c-segmented :model-value="value" :options="options" @change="onChange" />
    <div>当前值：{{ value }}</div>
  </c-space>
</template>

<script setup>
import { ref } from 'vue'

const value = ref('a')
const options = [
  { label: '选项 A', value: 'a' },
  { label: '选项 B', value: 'b' },
  { label: '选项 C', value: 'c', disabled: true },
]

const onChange = (next) => {
  value.value = next
}
</script>
```

## Accessibility

- The root uses `role="radiogroup"`; native `radio` options support keyboard changes.
- `name` binds a native form field `name`.
- Whole-control disabling sets `aria-disabled`.

## API

### Segmented Props

| Arguments | Description | Type | Default |
| --- | --- | --- | --- |
| model-value / v-model | Current value | `string \| number` | — |
| default-value | Uncontrolled default value | `string \| number` | — |
| options | Action list | `(string \| number \| SegmentedOption)[]` | `[]` |
| size | Size | `xs \| sm \| md \| lg \| xl` | `md` |
| disabled | Disable interaction | `boolean` | `false` |
| block | Fill parent width | `boolean` | `false` |
| orientation | Horizontal/vertical arrangement of segmented options, default horizontal; not text reading direction | `horizontal \| vertical` | `horizontal` |
| name | Native name | `string` | — |

### SegmentedOption

| Field | Description | Type |
| --- | --- | --- |
| label | Label | `string \| () => VNodeChild` |
| value | Value | `string \| number` |
| disabled | Disable this item | `boolean` |

### Segmented Events

| Event | Description | Arguments |
| --- | --- | --- |
| change | Value change | `(value, event)` |
| update:model-value | v-model | `(value)` |

### Segmented Slots

| Slot | Description | Arguments |
| --- | --- | --- |
| label | Custom option content | `{ data: SegmentedOption }` |

---

Document: llms/en-US/components/select.md

<!-- Source: src/select/README.en-US.md; locale: en-US; page: /en/components/select/ -->

# Select

Single or multiple selection with array options, controlled values and shared field presentation.

## Reading direction

Select inherits source `dir`. Standalone fields align to inline start; FormItem content-align still takes precedence when inherited. Explicit left/right alignment remains physical. Tags keep their array order and empty-search Backspace removes the last closable value. Dropdowns and picker panels retain source direction, including in a custom popup-container.

## Async arrays and clearing

useAsyncData is a public composable exported by @cedar-design/use. Pass a loader to that composable and bind its data/loading to Select. Options remain arrays. An initialization call is per owner; share a parent result to avoid duplicate loading.

empty-value sets the single-selection clear result. Omitted preserves the existing behavior: empty string unless an empty-string option exists, in which case clearing may produce undefined. The event types include undefined. Multiple selection keeps its array semantics and cannot clear disabled selected options.

case-sensitive defaults to false. search-fields defaults to ['label']; ['value', 'label'] matches either field. Custom filters retain priority.

| Variable                              | Default                             |
| ------------------------------------- | ----------------------------------- |
| `--c-select-popup-option-check-color` | `var(--c-sys-color-action-primary)` |
| `--c-select-popup-option-check-size`  | `var(--c-sys-font-size-md)`         |
| `--c-select-popup-option-check-gap`   | `var(--c-sys-space-4)`              |

## Basic examples

### Basic

Example source: src/select/__demos__/basic.vue

```vue
<template>
  <c-space direction="column">
    <c-select v-model="value" :style="{ width: '240px' }" placeholder="Please select ..." aria-label="基础单选示例" clearable>
      <c-option>Beijing</c-option>
      <c-option>Shanghai</c-option>
      <c-option>Guangzhou</c-option>
      <c-option disabled>Disabled</c-option>
    </c-select>
  </c-space>
</template>

<script lang="ts">
import { defineComponent, ref } from 'vue'
export default defineComponent({
  setup() {
    const value = ref('Shanghai')
    return {
      value,
    }
  },
})
</script>
```

## Appearance and states

### Appearance configuration comparison

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration | Purpose                                                                 | Related examples                                   |
| ------------- | ----------------------------------------------------------------------- | -------------------------------------------------- |
| `options`     | Primitive, object or grouped options; one source for every presentation | Appearance configuration comparison, Control Sizes |
| `clearable`   | Allow clearing; preserve disabled selections                            | Appearance configuration comparison, Control Sizes |
| `size`        | Supports all five sizes; inherits group/form settings                   | Control Sizes                                      |
| `variant`     | filled, outline, standard; inherits InputGroup                          | Control Sizes                                      |
| `placeholder` | Placeholder                                                             | Control Sizes                                      |
| `multiple`    | Multiple selection; enables search by default                           | Control Sizes                                      |

<!-- demo-config-notes:end -->

Choose a dimension to compare all its values side by side while keeping other settings and content identical. Change the other settings to inspect combinations; input specimens share one model.

Example source: src/select/__demos__/appearance-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref("design");
const options = [
  { label: "研发", value: "dev" },
  { label: "设计", value: "design" },
  { label: "运营", value: "ops", disabled: true },
];
const __demoAppearance = __demoReactive({ variant: "filled", size: "md" });

import { computed as demoComputed, ref as demoRef } from 'vue'
const demoCompareFields = [{"name":"variant","values":["filled","outline","standard"]},{"name":"size","values":["xs","sm","md","lg","xl"]}]
const demoCompareAxis = demoRef("variant")
const demoComparedOptions = demoComputed(() => demoCompareFields.find(field => field.name === demoCompareAxis.value)?.values ?? [])
</script>
<template>
  <c-space direction="column" :size="16">
    <c-form layout="vertical">
      <c-form-item layout="vertical" size="sm" label="variant">
        <c-radio-group
          v-model="__demoAppearance['variant']"
          aria-label="variant"
          :options="[
            { label: 'filled', value: 'filled' },
            { label: 'outline', value: 'outline' },
            { label: 'standard', value: 'standard' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
      <c-form-item layout="vertical" size="sm" label="size">
        <c-radio-group
          v-model="__demoAppearance['size']"
          aria-label="size"
          :options="[
            { label: 'xs', value: 'xs' },
            { label: 'sm', value: 'sm' },
            { label: 'md', value: 'md' },
            { label: 'lg', value: 'lg' },
            { label: 'xl', value: 'xl' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
    </c-form>
    <p class="demo-config-comparison-hint"><span lang="zh-CN">选择一个对比维度；其他配置和内容保持一致。输入类示例共享同一个值，便于比较外观。</span><span lang="en-US">Compare one dimension while keeping the other settings and content identical. Input specimens share the same value.</span></p>
<c-radio-group v-model="demoCompareAxis" aria-label="Compare configuration" :options="demoCompareFields.map(field => ({ label: field.name, value: field.name }))" />
<div class="demo-config-comparison">
<section v-for="sample in demoComparedOptions" :key="String(sample)">
<p><code>{{ demoCompareAxis }}={{ sample }}</code></p>
<c-select
      v-model="value"
      :options="options"
      clearable
      v-bind="{ ...__demoAppearance, [demoCompareAxis]: sample }"
    ></c-select>
</section>
</div>
  </c-space>
</template>

<style scoped>
.demo-config-comparison { display: grid; grid-template-columns: repeat(auto-fit, minmax(min(100%, 220px), 1fr)); gap: 20px; min-width: 0; max-width: 100%; }
.demo-config-comparison > section { min-width: 0; }
.demo-config-comparison p { margin: 0 0 8px; }
html:not([lang='en-US']) .demo-config-comparison-hint > [lang='en-US'],
html[lang='en-US'] .demo-config-comparison-hint > [lang='zh-CN'] { display: none; }
</style>
```

### Control Sizes

Example source: src/field-decorator/__demos__/control-sizes.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
const sizes = ["xs", "sm", "md", "lg", "xl"] as const;
const variants = ["outline", "filled", "standard"] as const;
const size = ref<(typeof sizes)[number]>("md");
const variant = ref<(typeof variants)[number]>("outline");
const options = [
  { value: "beijing", label: "Beijing" },
  { value: "shanghai", label: "Shanghai" },
];
const cascaderOptions = [{ value: "china", label: "China", children: options }];

const inputValue = ref("Beijing");
const selectValue = ref("beijing");
const cascaderValue = ref("beijing");
const selectMultiple = ref(["beijing", "shanghai"]);
const cascaderMultiple = ref(["beijing", "shanghai"]);
const selectOverflow = ref(["long", "beijing", "shanghai"]);
const cascaderOverflow = ref(["long", "beijing", "shanghai"]);
const selectedOptions = [
  ...options,
  {
    value: "long",
    label:
      "A very long selected option label for overflow comparison — full text preview keeps the selected value unchanged.",
  },
];
const selectedCascaderOptions = [
  { value: "china", label: "China", children: selectedOptions },
];
function resetSelections() {
  inputValue.value = "Beijing";
  selectValue.value = "beijing";
  cascaderValue.value = "beijing";
  selectMultiple.value = ["beijing", "shanghai"];
  cascaderMultiple.value = ["beijing", "shanghai"];
  selectOverflow.value = ["long", "beijing", "shanghai"];
  cascaderOverflow.value = ["long", "beijing", "shanghai"];
}
</script>
<template>
  <section
    aria-label="Form control size comparison"
    class="control-size-comparison"
  >
    <c-space wrap :size="12">
      <c-radio-group v-model="size" aria-label="Comparison size">
        <c-radio v-for="item in sizes" :key="item" :value="item">{{
          item
        }}</c-radio>
      </c-radio-group>
      <c-radio-group v-model="variant" aria-label="Comparison variant">
        <c-radio v-for="item in variants" :key="item" :value="item">{{
          item
        }}</c-radio>
      </c-radio-group>
    </c-space>
    <div class="control-size-comparison__grid">
      <div data-control="Input">
        <p>Input</p>
        <c-input :size="size" :variant="variant" placeholder="Input" />
      </div>
      <div data-control="Button">
        <p>Button</p>
        <c-button :size="size" variant="outline">Button</c-button>
      </div>
      <div data-control="Select">
        <p>Select</p>
        <c-select
          :size="size"
          :variant="variant"
          :options="options"
          placeholder="Select"
        />
      </div>
      <div data-control="Date">
        <p>Date</p>
        <c-date :size="size" :variant="variant" placeholder="Date" />
      </div>
      <div data-control="Time">
        <p>Time</p>
        <c-time :size="size" :variant="variant" placeholder="Time" />
      </div>
      <div data-control="InputNumber">
        <p>InputNumber</p>
        <c-input-number :size="size" :variant="variant" placeholder="Number" />
      </div>
      <div data-control="AutoComplete">
        <p>AutoComplete</p>
        <c-auto-complete
          :size="size"
          :variant="variant"
          :options="options"
          placeholder="AutoComplete"
        />
      </div>
      <div data-control="Cascader">
        <p>Cascader</p>
        <c-cascader
          :size="size"
          :variant="variant"
          :options="cascaderOptions"
          placeholder="Cascader"
        />
      </div>
      <div data-control="DateRange">
        <p>DateRange</p>
        <c-date-range
          :size="size"
          :variant="variant"
          :placeholder="['Start', 'End']"
        />
      </div>
      <div data-control="TimeRange">
        <p>TimeRange</p>
        <c-time-range
          :size="size"
          :variant="variant"
          :placeholder="['Start', 'End']"
        />
      </div>
    </div>

    <section
      aria-label="Selected control size comparison"
      class="control-size-comparison__states"
    >
      <c-space wrap align="center" :size="12">
        <span>Selected / Clearable / Multiple — 有值、可清空与多选不换行</span>
        <span
          >Hover or focus truncated text; tap on touch screens /
          悬停或聚焦省略正文查看全文；触屏点按查看，点外部关闭</span
        >
        <c-button size="sm" variant="outline" @click="resetSelections"
          >Reset / 恢复选中值</c-button
        >
      </c-space>
      <div class="control-size-comparison__grid">
        <div data-control="InputValue">
          <p>Input · clearable</p>
          <c-input
            v-model="inputValue"
            :size="size"
            :variant="variant"
            clearable
            placeholder="Input value"
          />
        </div>
        <div data-control="ButtonReference">
          <p>Button · reference</p>
          <c-button :size="size" variant="outline">Button</c-button>
        </div>
        <div data-control="SelectValue">
          <p>Select · clearable</p>
          <c-select
            v-model="selectValue"
            :size="size"
            :variant="variant"
            :options="selectedOptions"
            clearable
            placeholder="Select value"
          />
        </div>
        <div data-control="CascaderValue">
          <p>Cascader · clearable</p>
          <c-cascader
            v-model="cascaderValue"
            :size="size"
            :variant="variant"
            :options="selectedCascaderOptions"
            clearable
            placeholder="Cascader value"
          />
        </div>
        <div data-control="SelectMultiple">
          <p>Select · multiple / nowrap</p>
          <c-select
            v-model="selectMultiple"
            :size="size"
            :variant="variant"
            :options="selectedOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Select multiple"
          />
        </div>
        <div data-control="CascaderMultiple">
          <p>Cascader · multiple / nowrap</p>
          <c-cascader
            v-model="cascaderMultiple"
            :size="size"
            :variant="variant"
            :options="selectedCascaderOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Cascader multiple"
          />
        </div>
        <div data-control="SelectOverflow">
          <p>Select · long values / nowrap</p>
          <c-select
            v-model="selectOverflow"
            edit-mode="direct"
            :size="size"
            :variant="variant"
            :options="selectedOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Select long values"
          />
        </div>
        <div data-control="CascaderOverflow">
          <p>Cascader · long values / nowrap</p>
          <c-cascader
            v-model="cascaderOverflow"
            edit-mode="direct"
            :size="size"
            :variant="variant"
            :options="selectedCascaderOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Cascader long values"
          />
        </div>
      </div>
    </section>
  </section>
</template>
<style scoped>
.control-size-comparison,
.control-size-comparison__states {
  display: grid;
  gap: 24px;
}
.control-size-comparison__grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
  align-items: start;
  gap: 24px 16px;
}
.control-size-comparison__grid > div {
  min-width: 0;
}
.control-size-comparison__grid p {
  margin: 0 0 12px;
  font-size: 14px;
  line-height: 20px;
}
.control-size-comparison__grid :deep(.c-input-number),
.control-size-comparison__grid :deep(.c-auto-complete) {
  width: 100%;
}
</style>
```

## Selection modes and options

### Multiple

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration | Purpose                                                                 | Related examples                     |
| ------------- | ----------------------------------------------------------------------- | ------------------------------------ |
| `placeholder` | Placeholder                                                             | Multiple, Same Label, Optgroup       |
| `multiple`    | Multiple selection; enables search by default                           | Multiple, Same Label, Optgroup       |
| `clearable`   | Allow clearing; preserve disabled selections                            | Multiple, Same Label, Options Review |
| `filterable`  | Enable search; optionally retainInputValue                              | Same Label, Options Review           |
| `options`     | Primitive, object or grouped options; one source for every presentation | Same Label, Group Spacing            |
| `scrollbar`   | Whether to enable virtual scroll bar                                    | Multiple                             |

<!-- demo-config-notes:end -->

Example source: src/select/__demos__/multiple.vue

```vue
<template>
  <c-space direction="column" size="lg">
    <c-select
      :default-value="['Beijing', 'Shanghai']"
      :style="{ width: '360px' }"
      placeholder="Please select ..."
      multiple
      scrollbar
    >
      <c-option>Beijing</c-option>
      <c-option :tag-props="{ color: 'red' }">Shanghai</c-option>
      <c-option>Guangzhou</c-option>
      <c-option disabled>Disabled</c-option>
      <c-option>Shenzhen</c-option>
      <c-option>Wuhan</c-option>
    </c-select>
    <c-select
      :default-value="['Beijing', 'Shanghai', 'Guangzhou']"
      :style="{ width: '360px' }"
      placeholder="Please select ..."
      multiple
      :max-tag-count="2"
      clearable
      scrollbar
    >
      <c-option>Beijing</c-option>
      <c-option>Shanghai</c-option>
      <c-option>Guangzhou</c-option>
      <c-option disabled>Disabled</c-option>
      <c-option>Shenzhen</c-option>
      <c-option>Chengdu</c-option>
      <c-option>Wuhan</c-option>
    </c-select>
  </c-space>
</template>

<script lang="ts">
import { defineComponent, ref } from 'vue'
export default defineComponent({
  setup() {
    const value = ref('Shanghai')
    return {
      value,
    }
  },
})
</script>
```

### Same Label

Example source: src/select/__demos__/same-label.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'

const value = ref([1, 2])
const options = [
  { value: 1, label: '设备' },
  { value: 2, label: '设备' },
  { value: 3, label: '备用设备' },
]
</script>

<template>
  <c-space direction="column">
    <c-select v-model="value" multiple filterable clearable :options="options" placeholder="选择设备" />
    <span>已选 ID：{{ value.join(', ') || '无' }}</span>
  </c-space>
</template>
```

### Optgroup

Example source: src/select/__demos__/optgroup.vue

```vue
<template>
  <c-space direction="column" size="lg">
    <c-select :style="{ width: '320px' }" placeholder="Please select ...">
      <c-optgroup label="Group-1">
        <c-option>Beijing</c-option>
        <c-option>Shanghai</c-option>
      </c-optgroup>
      <c-optgroup label="Group-2">
        <c-option>Guangzhou</c-option>
        <c-option disabled>Disabled</c-option>
        <c-option>Shenzhen</c-option>
      </c-optgroup>
      <c-optgroup label="Group-3">
        <c-option>Chengdu</c-option>
        <c-option>Wuhan</c-option>
      </c-optgroup>
    </c-select>
    <c-select :style="{ width: '320px' }" placeholder="Please select ..." multiple>
      <c-optgroup label="Group-1">
        <c-option>Beijing</c-option>
        <c-option>Shanghai</c-option>
      </c-optgroup>
      <c-optgroup label="Group-2">
        <c-option>Guangzhou</c-option>
        <c-option disabled>Disabled</c-option>
        <c-option>Shenzhen</c-option>
      </c-optgroup>
      <c-optgroup label="Group-3">
        <c-option>Chengdu</c-option>
        <c-option>Wuhan</c-option>
      </c-optgroup>
    </c-select>
  </c-space>
</template>

<script lang="ts">
import { defineComponent, ref } from 'vue'
export default defineComponent({
  })
</script>
```

### Group Spacing

Example source: src/select/__demos__/group-spacing.vue

```vue
<script setup lang="ts">
const options = [
  {
    isGroup: true,
    label: "华北",
    options: [
      { value: "beijing", label: "北京" },
      { value: "tianjin", label: "天津" },
    ],
  },
  {
    isGroup: true,
    label: "华东",
    options: [
      { value: "shanghai", label: "上海" },
      { value: "hangzhou", label: "杭州" },
    ],
  },
];
</script>

<template>
  <c-select
    :options="options"
    placeholder="分组候选"
    :style="{ width: '280px' }"
  />
</template>
```

### Options Review

Example source: src/select/__demos__/options-review.vue

```vue
<script setup lang="ts">
import { ref, watch } from 'vue'
const multiple = ref(true)
const filterable = ref(true)
const disabled = ref(false)
const value = ref<string | string[] | undefined>([])
watch(multiple, (next) => { value.value = next ? [] : undefined })
</script>
<template>
  <c-space direction="column">
    <c-space>
      <c-checkbox v-model="multiple">多选</c-checkbox>
      <c-checkbox v-model="filterable">允许搜索</c-checkbox>
      <c-checkbox v-model="disabled">禁用研发选项</c-checkbox>
      <c-button @click="value = multiple ? [] : undefined">清空选择</c-button>
    </c-space>
    <c-select v-model="value" :multiple="multiple" :filterable="filterable" clearable placeholder="子组件选项审查" :style="{ width: '280px' }">
      <c-optgroup label="研发组">
        <template #label><c-tag>研发组插槽</c-tag></template>
        <c-option value="dev" label="研发" :disabled="disabled" :tag-props="{ size: 'sm' }" :index="0">
          <template #default="{ selected }"><c-tag>{{ selected ? '已选研发' : '选择研发' }}</c-tag></template>
          <template #icon><c-tag>图标</c-tag></template>
          <template #suffix><c-tag>后缀</c-tag></template>
        </c-option>
      </c-optgroup>
    </c-select>
    <p role="status">当前值：{{ JSON.stringify(value) }}</p>
  </c-space>
</template>
```

### Allow Create

Example source: src/select/__demos__/allow-create.vue

```vue
<template>
  <c-space direction="column" size="lg">
    <c-select :style="{ width: '320px' }" placeholder="Please select ..." creatable>
      <c-option>Beijing</c-option>
      <c-option>Shanghai</c-option>
      <c-option>Guangzhou</c-option>
      <c-option disabled>Disabled</c-option>
      <c-option>Shenzhen</c-option>
      <c-option>Chengdu</c-option>
      <c-option>Wuhan</c-option>
    </c-select>
    <c-select :style="{ width: '320px' }" placeholder="Please select ..." multiple creatable>
      <c-option>Beijing</c-option>
      <c-option>Shanghai</c-option>
      <c-option>Guangzhou</c-option>
      <c-option disabled>Disabled</c-option>
      <c-option>Shenzhen</c-option>
      <c-option>Chengdu</c-option>
      <c-option>Wuhan</c-option>
    </c-select>
  </c-space>
</template>

<script lang="ts">
import { defineComponent } from 'vue'
export default defineComponent({})
</script>
```

### Fallback Option

Example source: src/select/__demos__/fallback-option.vue

```vue
<template>
  <c-space direction="column" size="lg">
    <c-select
      default-value="Shanxi"
      :style="{ width: '320px' }"
      placeholder="Please select ..."
      :fallback-option="fallback"
    >
      <c-option>Beijing</c-option>
      <c-option>Shanghai</c-option>
      <c-option>Guangzhou</c-option>
      <c-option disabled>Disabled</c-option>
    </c-select>
    <c-select
      default-value="Shanxi"
      :style="{ width: '320px' }"
      placeholder="Please select ..."
      :fallback-option="fallback"
      :show-extr-options="false"
    >
      <c-option>Beijing</c-option>
      <c-option>Shanghai</c-option>
      <c-option>Guangzhou</c-option>
      <c-option disabled>Disabled</c-option>
    </c-select>
    <c-select
      :default-value="['Shanxi', 'Nanjing', 'Hangzhou']"
      :style="{ width: '320px' }"
      placeholder="Please select ..."
      multiple
      :fallback-option="fallback"
    >
      <c-option>Beijing</c-option>
      <c-option>Shanghai</c-option>
      <c-option>Guangzhou</c-option>
      <c-option disabled>Disabled</c-option>
      <c-option>Shenzhen</c-option>
      <c-option>Chengdu</c-option>
      <c-option>Wuhan</c-option>
    </c-select>
  </c-space>
</template>

<script lang="ts">
import { defineComponent, ref } from 'vue'
export default defineComponent({
  setup() {
    const fallback = (value: any) => {
      return {
        value,
        label: `++${value}++`,
      }
    }
    return {
      fallback,
    }
  },
})
</script>
```

## Search and filtering

### Filterable

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration    | Purpose                                                                 | Related examples                             |
| ---------------- | ----------------------------------------------------------------------- | -------------------------------------------- |
| `placeholder`    | Placeholder                                                             | Filterable, Search Matching, Dropdown Scroll |
| `options`        | Primitive, object or grouped options; one source for every presentation | Filterable, Search Matching, Virtual List    |
| `filterable`     | Enable search; optionally retainInputValue                              | Filterable, Search Matching                  |
| `loading`        | Loading state; blocks selection and confirmation                        | Filterable                                   |
| `multiple`       | Multiple selection; enables search by default                           | Filterable                                   |
| `case-sensitive` | Case-sensitive built-in filtering; custom filters take priority         | Search Matching                              |

<!-- demo-config-notes:end -->

Example source: src/select/__demos__/filterable.vue

```vue
<template>
  <c-space direction="column" size="lg">
    <c-select :style="{ width: '320px' }" placeholder="Please select ..." filterable>
      <c-option>Beijing</c-option>
      <c-option>Shanghai</c-option>
      <c-option>Guangzhou</c-option>
      <c-option disabled>Disabled</c-option>
      <c-option>Shenzhen</c-option>
      <c-option>Chengdu</c-option>
      <c-option>Wuhan</c-option>
    </c-select>
    <c-select :style="{ width: '320px' }" placeholder="Please select ..." :filterable="{ retainInputValue: true }">
      <c-option>Beijing</c-option>
      <c-option>Shanghai</c-option>
      <c-option>Guangzhou</c-option>
      <c-option disabled>Disabled</c-option>
      <c-option>Shenzhen</c-option>
      <c-option>Chengdu</c-option>
      <c-option>Wuhan</c-option>
    </c-select>
    <c-select
      :options="options"
      :style="{ width: '320px' }"
      :loading="loading"
      placeholder="Please select ..."
      multiple
      @search="handleSearch" />
  </c-space>
</template>

<script lang="ts">
import { defineComponent, ref } from 'vue'
export default defineComponent({
  setup() {
    const options = ref(['Option1', 'Option2', 'Option3'])
    const loading = ref(false)

    const handleSearch = (value: any) => {
      if (value) {
        loading.value = true
        window.setTimeout(() => {
          options.value = [`${value}-Option1`, `${value}-Option2`, `${value}-Option3`]
          loading.value = false
        }, 2000)
      } else {
        options.value = []
      }
    }

    return {
      options,
      loading,
      handleSearch,
    }
  },
})
</script>
```

### Search Matching

Example source: src/select/__demos__/search-matching.vue

```vue
<script setup lang="ts">
import { computed, ref } from "vue";
const value = ref("");
const mode = ref("label");
const caseSensitive = ref(false);
const modes = [
  { value: "label", label: "默认：只匹配 label" },
  { value: "both", label: "配置：value 或 label" },
];
const options = [
  { value: "USER_A", label: "Apple" },
  { value: "USER_B", label: "Banana" },
];
const searchFields = computed<("label" | "value")[]>(() =>
  mode.value === "both" ? ["value", "label"] : ["label"],
);
</script>
<template>
  <c-space direction="column" align="stretch" fill>
    <c-form-item layout="vertical" size="sm" label="匹配字段">
      <c-radio-group
        v-model="mode"
        aria-label="匹配字段"
        :options="modes"
        variant="button"
        size="sm"
      />
    </c-form-item>
    <c-space
      ><c-switch v-model="caseSensitive" /><span>区分大小写</span></c-space
    >
    <c-select
      v-model="value"
      :options="options"
      :case-sensitive="caseSensitive"
      :search-fields="searchFields"
      :search-delay="0"
      filterable
      placeholder="输入 Apple、apple 或 USER_A"
    />
    <p>
      默认搜索 label，不区分大小写；配置两字段后，USER_A 和 Apple
      都能找到同一个选项。
    </p>
  </c-space>
</template>
```

### Dropdown Scroll

Example source: src/select/__demos__/dropdown-scroll.vue

```vue
<template>
  <c-select
    :style="{ width: '320px' }"
    default-value="Beijing"
    placeholder="Please select ..."
    @dropdown-scroll="handleScroll"
    @dropdown-reach-bottom="handleReachBottom"
  >
    <c-option>Beijing</c-option>
    <c-option>Shanghai</c-option>
    <c-option>Guangzhou</c-option>
    <c-option disabled>Disabled</c-option>
    <c-option>Shenzhen</c-option>
    <c-option>Chengdu</c-option>
    <c-option>Wuhan</c-option>
  </c-select>
</template>

<script lang="ts">
import { defineComponent, ref } from 'vue'
export default defineComponent({
  setup() {
    const handleScroll = (ev) => {
      console.log('scroll', ev)
    }
    const handleReachBottom = (ev) => {
      console.log('reach the bottom', ev)
    }

    return {
      handleScroll,
      handleReachBottom,
    }
  },
})
</script>
```

### Virtual List

Example source: src/select/__demos__/virtual-list.vue

```vue
<template>
  <c-select
    :style="{ width: '320px' }"
    :options="options"
    placeholder="Please select ..."
    :virtual-list-props="{ height: 200 }" />
</template>

<script lang="ts">
import { defineComponent } from 'vue'
export default defineComponent({
  setup() {
    const options = Array(1000)
      .fill(null)
      .map((_, index) => `Option ${index}`)

    return {
      options,
    }
  },
})
</script>
```

## Content and dropdown customization

### Tag Props

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration | Purpose                                                                 | Related examples                        |
| ------------- | ----------------------------------------------------------------------- | --------------------------------------- |
| `placeholder` | Placeholder                                                             | Tag Props, Custom Header, Custom Footer |
| `multiple`    | Multiple selection; enables search by default                           | Tag Props, Custom Header, Slots Review  |
| `options`     | Primitive, object or grouped options; one source for every presentation | Tag Props, Slots Review                 |
| `filterable`  | Enable search; optionally retainInputValue                              | Custom Footer, Slots Review             |
| `clearable`   | Allow clearing; preserve disabled selections                            | Slots Review                            |

<!-- demo-config-notes:end -->

Example source: src/select/__demos__/tag-props.vue

```vue
<template>
  <c-space direction="column" size="lg">
    <c-select
      multiple
      :default-value="['urgent', 'high', 'medium', 'low', 'custom', 'outline']"
      :style="{ width: '520px' }"
      placeholder="Please select ..."
      :options="colorOptions"
    />
    <c-select
      multiple
      :default-value="['long']"
      :style="{ width: '320px' }"
      placeholder="Please select ..."
      :options="widthOptions"
    />
  </c-space>
</template>

<script lang="ts">
import { defineComponent } from 'vue'

export default defineComponent({
  setup() {
    const colorOptions = [
      { value: 'urgent', label: '紧急', tagProps: { color: 'red' } },
      { value: 'high', label: '高', tagProps: { status: 'danger' } },
      { value: 'medium', label: '中', tagProps: { status: 'warning' } },
      { value: 'low', label: '低', tagProps: { status: 'success' } },
      { value: 'custom', label: '自定义色', tagProps: { color: '#165DFF' } },
      {
        value: 'outline',
        label: '描边',
        tagProps: { variant: 'outline', status: 'primary' },
      },
    ]

    const widthOptions = [
      {
        value: 'long',
        label: '这是一段很长的选项文案，用来演示 Tag 最大宽度截断',
        tagProps: {
          nowrap: true,
          style: { maxWidth: '160px' },
        },
      },
      { value: 'short', label: '短标签' },
    ]

    return {
      colorOptions,
      widthOptions,
    }
  },
})
</script>
```

### Custom Header

Example source: src/select/__demos__/custom-header.vue

```vue
<template>
  <c-select :default-value="'Beijing'" :style="{ width: '360px' }" placeholder="Please select ..." multiple>
    <c-option>Beijing</c-option>
    <c-option>Shanghai</c-option>
    <c-option>Guangzhou</c-option>
    <c-option disabled>Disabled</c-option>
    <c-option>Shenzhen</c-option>
    <c-option>Wuhan</c-option>
    <template #header>
      <div style="padding: 6px 12px">
        <c-checkbox value="1">全选</c-checkbox>
      </div>
    </template>
  </c-select>
</template>

<script lang="ts">
import { defineComponent, ref } from 'vue'
export default defineComponent({
  })
</script>
```

### Custom Footer

Example source: src/select/__demos__/custom-footer.vue

```vue
<template>
  <c-space>
    <c-select :default-value="'Beijing'" :style="{ width: '360px' }" placeholder="Please select ..." filterable>
      <c-option>Beijing</c-option>
      <c-option>Shanghai</c-option>
      <c-option>Guangzhou</c-option>
      <c-option disabled>Disabled</c-option>
      <c-option>Shenzhen</c-option>
      <c-option>Wuhan</c-option>
      <template #footer>
        <div style="padding: 6px 0; text-align: center">
          <c-button>Click Me</c-button>
        </div>
      </template>
    </c-select>
    <c-select
      :default-value="'Beijing'"
      :style="{ width: '360px' }"
      placeholder="Please select ..."
      filterable
      show-footer-on-empty
    >
      <c-option>Beijing</c-option>
      <c-option>Shanghai</c-option>
      <c-option>Guangzhou</c-option>
      <c-option disabled>Disabled</c-option>
      <c-option>Shenzhen</c-option>
      <c-option>Wuhan</c-option>
      <template #footer>
        <div style="padding: 6px 0; text-align: center">
          <c-button>Click Me</c-button>
        </div>
      </template>
    </c-select>
  </c-space>
</template>

<script lang="ts">
import { defineComponent, ref } from 'vue'
export default defineComponent({
  })
</script>
```

### Custom Label

Example source: src/select/__demos__/custom-label.vue

```vue
<template>
  <c-select v-model:modelValue="value" :style="{ width: '320px' }" placeholder="Please select ...">
    <template #label="{ data }">
      <span> <c-icon-plus />{{ data?.label }}</span>
    </template>
    <c-option>Beijing</c-option>
    <c-option>Shanghai</c-option>
    <c-option>Guangzhou</c-option>
    <c-option disabled>Disabled</c-option>
  </c-select>
</template>

<script lang="ts">
import { defineComponent, ref } from 'vue'
export default defineComponent({
  setup() {
    const value = ref('Beijing')
    return { value }
  },
})
</script>
```

### Slots Review

Example source: src/select/__demos__/slots-review.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const value = ref<string[]>(['dev'])
const selectedSlot = ref(false)
const triggerSlot = ref(false)
const clears = ref(0)
const options = [{ value: 'dev', label: '研发' }, { value: 'design', label: '设计' }, { value: 'ops', label: '运营', disabled: true }]
function onClear(clear: (event: MouseEvent) => void, event: MouseEvent) {
  clears.value++
  clear(event)
}
</script>
<template>
  <c-space direction="column">
    <c-space>
      <c-checkbox v-model="selectedSlot">自定义已选区</c-checkbox>
      <c-checkbox v-model="triggerSlot">自定义触发器</c-checkbox>
    </c-space>
    <c-select v-model="value" :options="options" multiple filterable clearable placeholder="复杂插槽审查" :style="{ width: '320px' }">
      <template #prefix><c-tag>前缀</c-tag></template>
      <template #suffix><c-tag>后缀</c-tag></template>
      <template #header><c-tag>菜单页头</c-tag></template>
      <template #footer><c-tag>菜单页脚</c-tag></template>
      <template #option="{ data }"><c-tag>选项：{{ data.label }}</c-tag></template>
      <template #label="{ data }"><c-tag>已选：{{ data.label }}</c-tag></template>
      <template #clear-icon="{ clear }"><c-button size="xs" @mousedown.prevent @click.stop="onClear(clear, $event)">插槽清空</c-button></template>
      <template #arrow-icon><c-tag>展开</c-tag></template>
      <template #search-icon><c-tag>搜索</c-tag></template>
      <template #loading-icon><c-tag>加载</c-tag></template>
      <template #empty><c-tag>无匹配选项</c-tag></template>
      <template #read="{ text }"><c-tag>阅读：{{ text }}</c-tag></template>
      <template v-if="selectedSlot" #selected><c-tag>已选区域：{{ value.join(' / ') }}</c-tag></template>
      <template v-if="triggerSlot" #trigger><c-button>插槽打开选择器</c-button></template>
    </c-select>
    <p role="status">当前值：{{ JSON.stringify(value) }}；插槽清空：{{ clears }}</p>
  </c-space>
</template>
```

## Value model and linked fields

### Selection Data Flow

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration                 | Purpose                                                                                                                                                                                 | Related examples                                                 |
| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| `options`                     | Primitive, object or grouped options; one source for every presentation                                                                                                                 | Selection Data Flow, Linkage, Empty recognition and clear output |
| `clearable`                   | Allow clearing; preserve disabled selections                                                                                                                                            | Empty recognition and clear output, Interaction state comparison |
| `edit-mode`                   | Field presentation; inherits FormItem/Form when omitted                                                                                                                                 | Selection Data Flow                                              |
| `default-active-first-option` | On opening, activate the first enabled candidate if no valid selected option exists. Highlighting does not update modelValue or emit change; an existing valid selection takes priority | Selection Data Flow                                              |
| `placeholder`                 | Placeholder                                                                                                                                                                             | Selection Data Flow                                              |
| `empty-value`                 | Clear output override; return an array for multiple selection and preserve protected items                                                                                              | Empty recognition and clear output                               |

<!-- demo-config-notes:end -->

Example source: src/select/__demos__/selection-data-flow.vue

```vue
<script setup lang="ts">
import { computed, reactive, ref } from "vue";

const props = defineProps<{ english?: boolean }>();
const autoFirst = ref(true);
const generation = ref(0);
const form = reactive<{ city?: string; panelCity?: string }>({
  city: undefined,
  panelCity: undefined,
});
const logs = reactive<{ inline: string[]; panel: string[] }>({
  inline: [],
  panel: [],
});
const counts = reactive({ inline: 0, panel: 0 });
const options = computed(() => [
  { label: props.english ? "Hangzhou" : "杭州", value: "hangzhou" },
  { label: props.english ? "Shanghai" : "上海", value: "shanghai" },
  {
    label: props.english ? "Beijing (disabled)" : "北京（禁用）",
    value: "beijing",
    disabled: true,
  },
]);
function show(value: unknown) {
  return value === undefined ? "undefined" : JSON.stringify(value);
}
function record(kind: "inline" | "panel", event: string, value: unknown) {
  if (event === "update:modelValue") {
    counts[kind]++;
  }
  logs[kind].unshift(`${event}(${show(value)})`);
  logs[kind].splice(8);
}
function reset() {
  generation.value++;
  form.city = undefined;
  form.panelCity = undefined;
  counts.inline = counts.panel = 0;
  logs.inline = [];
  logs.panel = [];
}
</script>

<template>
  <div class="selection-data-flow">
    <c-checkbox v-model="autoFirst" @change="reset"
      >defaultActiveFirstOption = {{ autoFirst }}</c-checkbox
    >
    <c-button @click="reset">{{
      english ? "Reset both forms and logs" : "重置两组表单和日志"
    }}</c-button>
    <p>
      {{
        english
          ? "Each field starts empty. Open it and inspect the highlighted candidate: highlighting does not select a city. Change the switch to remount both fields."
          : "两组字段初始都没有值。打开后观察候选行的高亮：高亮不代表选中城市。切换开关会重建两组字段，便于从空值重新比较。"
      }}
    </p>

    <section>
      <h4>
        inline · {{ english ? "Selection commits immediately" : "选择即提交" }}
      </h4>
      <c-form-item layout="vertical" hide-label>
        <c-select
          :key="`inline-${generation}`"
          v-model="form.city"
          edit-mode="direct"
          :options="options"
          :default-active-first-option="autoFirst"
          :placeholder="english ? 'Choose a city' : '请选择城市'"
          @update:model-value="record('inline', 'update:modelValue', $event)"
          @change="record('inline', 'change', $event)"
          @open-change="record('inline', 'open-change', $event)"
        >
          <template #footer>
            <p class="panel-value">
              form.city = {{ show(form.city) }} · update:modelValue ×
              {{ counts.inline }}
            </p>
          </template>
        </c-select>
      </c-form-item>
      <p>
        {{
          english
            ? "Move with arrow keys, then press Enter, or click a city. Closing without selecting leaves the form unchanged."
            : "上下键移动后按 Enter，或点击城市，才更新表单。只打开、移动候选或关闭，不更新表单。"
        }}
      </p>
      <p role="status">
        form.city = <code>{{ show(form.city) }}</code> · update:modelValue ×
        {{ counts.inline }}
      </p>
      <ol v-if="logs.inline.length" aria-live="polite">
        <li v-for="(entry, index) in logs.inline" :key="index">
          <code>{{ entry }}</code>
        </li>
      </ol>
      <p v-else>
        {{ english ? "No component events yet." : "尚无组件事件。" }}
      </p>
    </section>

    <section>
      <h4>
        click · {{ english ? "Confirm commits the draft" : "确认后提交草稿" }}
      </h4>
      <c-form-item layout="vertical" hide-label>
        <c-select
          :key="`panel-${generation}`"
          v-model="form.panelCity"
          edit-mode="click"
          :options="options"
          :default-active-first-option="autoFirst"
          :placeholder="
            english ? 'Choose a city, then confirm' : '选择城市后确认'
          "
          @update:model-value="record('panel', 'update:modelValue', $event)"
          @change="record('panel', 'change', $event)"
          @open-change="record('panel', 'open-change', $event)"
        >
          <template #footer>
            <p class="panel-value">
              {{ english ? "Committed form value" : "已提交表单值" }}：{{
                show(form.panelCity)
              }}
              · update:modelValue × {{ counts.panel }}
            </p>
          </template>
        </c-select>
      </c-form-item>
      <p>
        {{
          english
            ? "Choose a city in the editor: the selection mark is a draft. Confirm saves it; cancel or Escape discards it. Highlighting a candidate alone is not a draft selection."
            : "在编辑面板选择城市后，勾选标记表示草稿；确认才保存，取消或 Escape 丢弃草稿。只有候选高亮、尚未选择，不算草稿选择。"
        }}
      </p>
      <p role="status">
        form.panelCity = <code>{{ show(form.panelCity) }}</code> ·
        update:modelValue × {{ counts.panel }}
      </p>
      <ol v-if="logs.panel.length" aria-live="polite">
        <li v-for="(entry, index) in logs.panel" :key="index">
          <code>{{ entry }}</code>
        </li>
      </ol>
      <p v-else>
        {{ english ? "No component events yet." : "尚无组件事件。" }}
      </p>
    </section>
    <p>
      {{
        english
          ? "Logs are newest first. open-change only changes panel visibility; update:modelValue is the event that writes the form value."
          : "日志按最新在前排列。open-change 只表示打开或关闭面板；update:modelValue 才对应表单值更新。"
      }}
    </p>
  </div>
</template>

<style scoped>
.selection-data-flow {
  display: grid;
  gap: 12px;
  min-width: 0;
}
.selection-data-flow section {
  display: grid;
  gap: 8px;
  min-width: 0;
}
.selection-data-flow p,
.selection-data-flow h4 {
  margin: 0;
}
.selection-data-flow code {
  overflow-wrap: anywhere;
}
.panel-value {
  padding: 8px;
}
</style>
```

### Linkage

Example source: src/select/__demos__/linkage.vue

```vue
<template>
  <c-space>
    <c-select :style="{ width: '200px' }" v-model="province">
      <c-option v-for="value of Object.keys(data)" :key="value">{{ value }}</c-option>
    </c-select>
    <c-select :style="{ width: '200px' }" :options="data[province] || []" v-model="city" />
  </c-space>
</template>

<script lang="ts">
import { defineComponent, ref, watch } from 'vue'
export default defineComponent({
  setup() {
    const province = ref('Sichuan')
    const city = ref('Chengdu')
    const data = {
      Beijing: ['Haidian', 'Chaoyang', 'Changping'],
      Sichuan: ['Chengdu', 'Mianyang', 'Aba'],
      Guangdong: ['Guangzhou', 'Shenzhen', 'Shantou'],
    }

    watch(province, () => {
      city.value = ''
    })

    return {
      province,
      city,
      data,
    }
  },
})
</script>
```

### Empty recognition and clear output

This example keeps an empty string as the valid All option and clears to null. Compare the selected All option with the cleared state in the model output. Deleting the search query does not remove the selected value. The additional fields show multiple selection clearing to [] and a factory explicitly producing undefined, each with its own model output.

Example source: src/select/__demos__/en-US/empty-value.vue

```vue
<script setup lang="ts">
import { reactive, ref } from "vue";
const model = reactive({ status: "" as string | null });
const multiple = ref(["active"]);
const optional = ref<string | undefined>("active");
const options = [
  { value: "", label: "All" },
  { value: "active", label: "Active" },
];
</script>
<template>
  <c-space direction="column">
    <p>
      All uses an empty string as a valid option value. Clearing produces null.
    </p>
    <c-form :model="model" layout="vertical">
      <c-form-item field="status" label="Status">
        <c-select
          v-model="model.status"
          :options="options"
          edit-mode="direct"
          clearable
          :empty-values="[null, undefined]"
          :empty-value="null"
        />
      </c-form-item>
    </c-form>
    <c-button @click="model.status = ''">Choose All</c-button>
    <p>
      Current model: <output>{{ JSON.stringify(model.status) }}</output>
    </p>
    <c-form layout="vertical">
      <c-form-item label="Multiple: clear to []">
        <c-select
          v-model="multiple"
          :options="options"
          edit-mode="direct"
          multiple
          clearable
          :empty-value="() => []"
        />
        <output>{{ JSON.stringify(multiple) }}</output>
      </c-form-item>
      <c-form-item label="Single: clear to undefined">
        <c-select
          v-model="optional"
          :options="options"
          edit-mode="direct"
          clearable
          :empty-value="() => undefined"
        />
        <output>{{ String(optional) }}</output>
      </c-form-item>
    </c-form>
  </c-space>
</template>
```

### Interaction state comparison

Toggle disabled, read-only and error states, then interact with the same instance. Recovery controls remain outside the target; error appearance alone does not validate data.

Example source: src/select/__demos__/state-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref("design");
const options = [
  { label: "研发", value: "dev" },
  { label: "设计", value: "design" },
  { label: "运营", value: "ops", disabled: true },
];
const __demoState = __demoReactive({
  disabled: false,
  readonly: false,
  error: false,
});
</script>
<template>
  <c-space direction="column" :size="16">
    <c-space wrap>
      <c-checkbox v-model="__demoState['disabled']">disabled</c-checkbox>
      <c-checkbox v-model="__demoState['readonly']">readonly</c-checkbox>
      <c-checkbox v-model="__demoState['error']">error</c-checkbox>
    </c-space>
    <c-select
      v-model="value"
      :options="options"
      clearable
      v-bind="__demoState"
    ></c-select>
  </c-space>
</template>
```

## Async data and search

### Loading

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration   | Purpose                                                                 | Related examples                        |
| --------------- | ----------------------------------------------------------------------- | --------------------------------------- |
| `loading`       | Loading state; blocks selection and confirmation                        | Loading, Search, Async Devices          |
| `options`       | Primitive, object or grouped options; one source for every presentation | Search, Async Devices, Async Source     |
| `placeholder`   | Placeholder                                                             | Loading, Search, Async Devices          |
| `filterable`    | Enable search; optionally retainInputValue                              | Async Devices, Async Source, Async Data |
| `multiple`      | Multiple selection; enables search by default                           | Search, Async Devices                   |
| `filter-option` | false disables local filtering; callback receives query and raw option  | Search                                  |

<!-- demo-config-notes:end -->

Example source: src/select/__demos__/loading.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const busy = ref(true)
const value = ref('beijing')
const options = [{ label: '北京 / Beijing', value: 'beijing' }, { label: '上海 / Shanghai', value: 'shanghai' }, { label: '广州 / Guangzhou', value: 'guangzhou' }]
</script>
<template>
  <c-space direction="column" :size="16" style="width: 100%">
    <c-form layout="vertical">
      <c-form-item label="加载状态 / Loading"><c-switch v-model="busy" /></c-form-item>
      <c-form-item label="默认指示器 / Default"><c-select v-model="value" :loading="busy" :options="options" edit-mode="direct" loading-mode="default" /></c-form-item>
      <c-form-item label="底部加载线 / Line"><c-select v-model="value" :loading="busy" :options="options" edit-mode="direct" loading-mode="line" /></c-form-item>
    </c-form>
    <p>切换加载状态；加载期间保留已选值，暂停选择与确认，关闭加载后恢复。Loading preserves the selected value and pauses selection.</p>
  </c-space>
</template>
```

### Search

Example source: src/select/__demos__/search.vue

```vue
<template>
  <c-space direction="column" size="lg">
    <div>Show selections after search options</div>
    <c-select
      :style="{ width: '320px' }"
      :loading="loading"
      placeholder="Please select ..."
      multiple
      :filter-option="false"
      @search="handleSearch"
    >
      <c-option v-for="item of options" :key="item" :value="item">{{ item }}</c-option>
    </c-select>
    <div>Hide selections after search options</div>
    <c-select
      :options="options"
      :style="{ width: '320px' }"
      :loading="loading"
      placeholder="Please select ..."
      multiple
      :filter-option="false"
      :show-extr-options="false"
      @search="handleSearch" />
  </c-space>
</template>

<script lang="ts">
import { defineComponent, ref } from 'vue'
export default defineComponent({
  setup() {
    const options = ref(['Option1', 'Option2', 'Option3'])
    const loading = ref(false)

    const handleSearch = (value: any) => {
      if (value) {
        loading.value = true
        window.setTimeout(() => {
          options.value = [`${value}-Option1`, `${value}-Option2`, `${value}-Option3`]
          loading.value = false
        }, 2000)
      } else {
        options.value = []
      }
    }

    return {
      options,
      loading,
      handleSearch,
    }
  },
})
</script>
```

### Async Devices

Example source: src/select/__demos__/async-devices.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const value = ref([2])
const options = ref<{ id: number; name: string; disabled?: boolean }[]>([])
const loading = ref(false)
async function load() {
  loading.value = true
  try {
    options.value = await Promise.resolve(Array.from({ length: 200 }, (_, index) => ({
      id: index + 1, name: `设备 ${index + 1}`, disabled: index === 3,
    })))
  } finally { loading.value = false }
}
</script>
<template>
  <c-space direction="column" :size="16">
    <c-button @click="load">加载设备列表</c-button>
    <c-select v-model="value" :options="options" :loading="loading"
      :field-names="{ label: 'name', value: 'id' }" :virtual-list-props="{ height: 180 }"
      :limit="3" multiple filterable clearable placeholder="最多选择三个设备" />
    <p>已提交 ID：{{ value }}。加载前显示 ID，加载后自动回显名称。</p>
  </c-space>
</template>
```

### Async Source

Example source: src/select/__demos__/async-source.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { useAsyncData } from '@cedar-design/use'
const value = ref('mengshuai')
// A shared business function can be imported and reused in other fields.
const loadPeople = async () => {
  await new Promise(resolve => setTimeout(resolve, 200))
  return [{ value: 'mengshuai', label: '孟帅' }, { value: 'wujiaming', label: '吴甲明' }]
}
const { data: options, loading, error, refresh } = useAsyncData(loadPeople, {
  initialData: [] as { value: string; label: string }[],
})
</script>
<template>
  <c-space direction="column">
    <c-select v-model="value" :options="options" :loading="loading" filterable />
    <p v-if="error" role="alert">加载失败，请重试。</p>
    <c-button @click="refresh()">重新加载</c-button>
  </c-space>
</template>
```

### Async Data

Example source: src/select/__demos__/en-US/async-data.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const value = ref('')
// Replace this loader body with your API and response mapping.
async function request(query: string, { signal }: { signal: AbortSignal }) {
  await new Promise<void>((resolve, reject) => {
    const abort = () => { clearTimeout(timer); reject(new Error('Cancelled')) }
    const timer = setTimeout(() => { signal.removeEventListener('abort', abort); resolve() }, 300)
    if (signal.aborted) { abort(); return }
    signal.addEventListener('abort', abort, { once: true })
  })
  return [{ value: 'a', label: 'Alice' }, { value: 'b', label: 'Bob' }].filter(option => option.label.toLowerCase().includes(query.toLowerCase()))
}
const error = ref('')
</script>
<template>
  <c-space direction="column">
    <c-select v-model="value" :options="request" filterable @load-error="error = 'Load failed'" />
    <p role="alert">{{ error }}</p>
    <p>Selected: {{ value }}</p>
  </c-space>
</template>
```

## Configuration and lifecycle

### Passthrough Options

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration         | Purpose                                                                                                                                                                                 | Related examples                                              |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| `options`             | Primitive, object or grouped options; one source for every presentation                                                                                                                 | Passthrough Options, Scheduler Lifecycle, Copying and editing |
| `edit-mode`           | Field presentation; inherits FormItem/Form when omitted                                                                                                                                 | Passthrough Options, Copying and editing                      |
| `trigger-props`       | Optional dropdown Trigger settings. Placement defaults to bottom-start and automatically adjusts when space is limited. The field owns open state; there is no top-level placement prop | Passthrough Options                                           |
| `open-trigger-target` | Pointer opening target: the whole field or only the suffix icon. Explicit keyboard opening and controlled open remain available.                                                        | Copying and editing                                           |
| `filterable`          | Enable search; optionally retainInputValue                                                                                                                                              | Copying and editing                                           |

<!-- demo-config-notes:end -->

Example source: src/select/__demos__/passthrough-options.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import type { SelectTriggerOptions } from "@cedar-design/ui";
const open = ref(false);
const triggerOptions: SelectTriggerOptions = {
  placement: "top-start",
  popupOffset: 8,
  popupContainer: false,
};
const options = [
  { value: "USER_A", label: "Apple" },
  { value: "USER_B", label: "Banana" },
];
</script>
<template>
  <c-space direction="column" fill>
    <c-button @click="open = !open">{{
      open ? "关闭面板" : "打开面板"
    }}</c-button>
    <c-select
      edit-mode="direct"
      v-model:open="open"
      :options="options"
      :trigger-props="triggerOptions"
      aria-label="透传配置示例"
    />
    <p role="status">顶层 open：{{ open }}；嵌套配置：向上展开并调整偏移。</p>
  </c-space>
</template>
```

### Select

| Prop                                          | Description                                                                                                                                                                             | Type                                                        | Default                          |
| --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | -------------------------------- |
| `open-trigger-target`                         | Pointer opening target: the whole field or only the suffix icon. Explicit keyboard opening and controlled open remain available.                                                        | `'field' \| 'icon'`                                         | `'field'`                        |
| `model-value / default-value`                 | Controlled value / uncontrolled initial value                                                                                                                                           | `Value`                                                     | `Single: ''; multiple: []`       |
| `open / default-open`                         | Controlled / initial open state                                                                                                                                                         | `boolean`                                                   | `undefined / false`              |
| `input-value / default-input-value`           | Search text, independent of selected values                                                                                                                                             | `string`                                                    | `undefined / ''`                 |
| `multiple`                                    | Multiple selection; enables search by default                                                                                                                                           | `boolean`                                                   | `false`                          |
| `size`                                        | Supports all five sizes; inherits group/form settings                                                                                                                                   | `ComponentSize`                                             | `md`                             |
| `variant`                                     | filled, outline, standard; inherits InputGroup                                                                                                                                          | `FormControlVariant`                                        | `filled`                         |
| `disabled / readonly / error`                 | Inherits form state unless explicitly overridden                                                                                                                                        | `boolean`                                                   | `undefined`                      |
| `placeholder`                                 | Placeholder                                                                                                                                                                             | `string`                                                    | `—`                              |
| `hint / line`                                 | Floating hint / standard variant underline                                                                                                                                              | `boolean`                                                   | `true`                           |
| `text-color / focus-color / blur-color`       | Field colors                                                                                                                                                                            | `string`                                                    | `—`                              |
| `loading`                                     | Loading state; blocks selection and confirmation                                                                                                                                        | `boolean`                                                   | `false`                          |
| `show-tags`                                   | Show tags; false displays separated text                                                                                                                                                | `boolean`                                                   | `true`                           |
| `separator`                                   | Separator when show-tags=false                                                                                                                                                          | `string`                                                    | `,`                              |
| `text-align`                                  | Value alignment: left / center / right. Inherits FormItem content-align when omitted; defaults to inline start outside forms.                                                                   | `'left' \| 'center' \| 'right'`                             | `-`                              |
| `max-tag-count`                               | Maximum visible tags; 0 means unlimited                                                                                                                                                 | `number`                                                    | `0`                              |
| `tag-nowrap`                                  | Keep tags on one line with ellipsis and preserved removal icons; overflow scrolls horizontally; hover, focus or tap truncated text to preview it                                        | `boolean`                                                   | `false`                          |
| `popup-container`                             | Selector, element, element resolver, or false for inline rendering                                                                                                                      | `PopupContainer`                                            | `—`                              |
| `trigger-props`                               | Optional dropdown Trigger settings. Placement defaults to bottom-start and automatically adjusts when space is limited. The field owns open state; there is no top-level placement prop | `TriggerProps`                                              | `—`                              |
| `virtual-list-props`                          | Pass the virtual list attribute, pass in this parameter to turn on virtual scrolling [VirtualListProps](#VirtualListProps)                                                              | `VirtualListProps`                                          | `—`                              |
| `search-delay`                                | Search debounce delay in ms                                                                                                                                                             | `number`                                                    | `500`                            |
| `format-label`                                | Format selected labels; use label slot for VNodes                                                                                                                                       | `function`                                                  | `—`                              |
| `clearable`                                   | Allow clearing; preserve disabled selections                                                                                                                                            | `boolean`                                                   | `true`                           |
| `empty-value`                                 | Clear output override; return an array for multiple selection and preserve protected items                                                                                              | `SelectEmptyValue`                                          | `undefined`                      |
| `options`                                     | Primitive, object or grouped options; one source for every presentation                                                                                                                 | `SelectOption[]` / `(query, { signal }) => Array / Promise` | `undefined`                      |
| `field-names`                                 | Map value, label, disabled, tagProps, render; object values need a unique ID field                                                                                                      | `SelectFieldNames`                                          | `—`                              |
| `filterable`                                  | Enable search; optionally retainInputValue                                                                                                                                              | `boolean or { retainInputValue?: boolean }`                 | `Single: false / multiple: true` |
| case-sensitive                                | Case-sensitive built-in filtering; custom filters take priority                                                                                                                         | boolean                                                     | false                            |
| `filter-option`                               | false disables local filtering; callback receives query and raw option                                                                                                                  | `boolean or (input, option) => boolean`                     | automatic: arrays on; loader off |
| `creatable`                                   | Allow creating missing options                                                                                                                                                          | `boolean`                                                   | `false`                          |
| `fallback-option`                             | Display unresolved values or return a complete fallback option                                                                                                                          | `boolean or (value) => SelectOptionData`                    | `true`                           |
| `show-extra-options`                          | Display fallback/created options in the panel                                                                                                                                           | `boolean`                                                   | `true`                           |
| `limit`                                       | Selection limit; 0 means unlimited                                                                                                                                                      | `number`                                                    | `0`                              |
| `auto-fit-popup-width`                        | Match Menu width to the field                                                                                                                                                           | `boolean`                                                   | `true`                           |
| `default-active-first-option`                 | On opening, activate the first enabled candidate if no valid selected option exists. Highlighting does not update modelValue or emit change; an existing valid selection takes priority | `boolean`                                                   | `true`                           |
| `unmount-on-close`                            | Unmount Menu content when closed                                                                                                                                                        | `boolean`                                                   | `false`                          |
| `scrollbar`                                   | Whether to enable virtual scroll bar                                                                                                                                                    | `boolean or ScrollbarProps`                                 | `true`                           |
| `show-header-on-empty / show-footer-on-empty` | Display header/footer in empty state                                                                                                                                                    | `boolean`                                                   | `false`                          |
| `edit-mode`                                   | Field presentation; inherits FormItem/Form when omitted                                                                                                                                 | `direct / click / dblclick`                                 | `direct`                         |
| `before-commit`                               | Asynchronous before-commit hook after validation                                                                                                                                        | `(value, context) => void / false / Promise`                | —                                |

### Option Props

| Prop      | Description                                                 | Type                                                   | Default   |
| --------- | ----------------------------------------------------------- | ------------------------------------------------------ | --------- |
| value     | Option Value                                                | string \| number \| boolean \| Record<string, unknown> | undefined |
| label     | Option group title                                          | string                                                 | undefined |
| disabled  | Whether to disable                                          | boolean                                                | false     |
| tag-props | Props of the multi-select label corresponding to the option | TagProps                                               | undefined |
| index     | Explicit option order                                       | number                                                 | undefined |

### Option Slots

| Slot    | Description           | Arguments             |
| ------- | --------------------- | --------------------- |
| default | Custom option content | { selected: boolean } |
| icon    | Option icon           | -                     |
| suffix  | Option suffix         | -                     |

### Optgroup Props

| Prop  | Description        | Type   | Default   |
| ----- | ------------------ | ------ | --------- |
| label | Option group title | string | undefined |

### Optgroup Slots

| Slot    | Description                   | Arguments |
| ------- | ----------------------------- | --------- |
| label   | Option group title            | -         |
| default | Option children in this group | -         |

### Select Slots

| Slot         | Description                             | Arguments       |
| ------------ | --------------------------------------- | --------------- |
| default      | Option or Optgroup children             | -               |
| option       | Custom option content                   | { data }        |
| label        | Option group title                      | { data }        |
| selected     | Replace the whole selected-value region | -               |
| header       | Menu header                             | -               |
| footer       | Menu footer                             | -               |
| trigger      | Custom field trigger                    | -               |
| prefix       | Field prefix                            | -               |
| suffix       | Field suffix                            | -               |
| clear-icon   | Custom clear action                     | { clear }       |
| arrow-icon   | Dropdown arrow                          | -               |
| search-icon  | Search icon                             | -               |
| loading-icon | Loading icon                            | -               |
| empty        | Empty-state content                     | -               |
| read         | Read-mode content                       | { value, text } |

### Select Events

| Event                 | Description                                              | Arguments    |
| --------------------- | -------------------------------------------------------- | ------------ |
| update:model-value    | Request a model value update                             | value        |
| change                | Option                                                   | value        |
| update:open           | Request popup visibility                                 | open         |
| open-change           | Popup visibility changes                                 | open         |
| update:input-value    | Request search text update                               | text         |
| input-value-change    | Search text changes                                      | text         |
| search                | Triggered when the user searches                         | text         |
| focus                 | Focus enters the field                                   | event        |
| blur                  | Focus leaves the field                                   | event        |
| clear                 | Triggered when the value of the input changes            | event        |
| remove                | Triggered when the delete button of the label is clicked | value        |
| exceed-limit          | Selection would exceed the multiple-selection limit      | value, event |
| dropdown-scroll       | Menu scrolls                                             | event        |
| dropdown-reach-bottom | Menu reaches its bottom                                  | event        |

### Select Methods

| Method | Description            | Arguments |
| ------ | ---------------------- | --------- |
| focus  | Focus the actual field | -         |
| blur   | Blur the actual field  | -         |

### Scheduler Lifecycle

Example source: src/select/__demos__/scheduler-lifecycle.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
const active = ref(true);
const open = ref(false);
const value = ref("Item 101");
const options = Array.from(
  { length: 200 },
  (_, index) => "Item " + (index + 1),
);
</script>
<template>
  <div>
    <c-button @click="open = !open">Open / close</c-button>
    <c-button @click="active = !active">Activate / deactivate</c-button>
    <p>
      Open the menu, navigate with Arrow keys, then close or deactivate. Old
      scrolling must not replay.
    </p>
    <KeepAlive>
      <c-select
        v-if="active"
        v-model="value"
        v-model:open="open"
        :options="options"
        style="width: 240px"
      />
    </KeepAlive>
  </div>
</template>
```

### Api Review

### Copying and editing

With open-trigger-target="icon", use the input area to edit or copy and the suffix button to open. Existing text remains copyable when editing or search is disabled.

Example source: src/select/__demos__/open-trigger-target.en-US.vue

```vue
<template>
  <c-space direction="column" align="stretch">
    <c-radio-group
      v-model="target"
      :options="[
        { label: 'Whole field', value: 'field' },
        { label: 'Suffix icon only', value: 'icon' },
      ]"
    />
    <label><c-switch v-model="editable" /> Allow editing / search</label>
    <c-form-item layout="vertical" hide-label>
      <c-select
        v-model="value"
        edit-mode="direct"
        :open-trigger-target="target"
        :filterable="editable"
        :options="[
          { value: 'a', label: 'Alpha' },
          { value: 'b', label: 'Beta' },
        ]"
      />
    </c-form-item>
    <p>
      Disable editing to copy existing text. In icon mode, editing does not open
      the panel.
    </p>
  </c-space>
</template>
<script setup lang="ts">
import { ref } from "vue";
const target = ref<"field" | "icon">("icon");
const editable = ref(true);
const value = ref("a");
</script>
```

### Shared field loading

`loading` displays the shared field indicator. `loading-mode` is `default` (indicator) or `line` (an indeterminate bottom line); it defaults to `default`. Rendering belongs to FieldDecorator. Loading does not implicitly disable editing or change readonly. Set those states separately.

## API

### Empty values and reading placeholders

`empty-values` recognizes empty data; `empty-value` keeps existing clear output. `empty-text` defaults to `'-'` under `read-pretty`, with Field > FormItem > Form precedence and custom read slots first. With explicit empty-values, built-in required uses the policy; custom validators receive original data. See the [shared guide](llms/en-US/guide/empty-values.md).

| Prop         | Type               | Default and scope                                                           |
| ------------ | ------------------ | --------------------------------------------------------------------------- |
| empty-values | readonly unknown[] | Field > FormItem > Form > component-family default; replaces the whole list |
| empty-text   | string             | Field > FormItem > Form > '-'; explicit '' is valid                         |

These props belong to field presentation; pure panels do not gain reading mode. Form and FormItem provide inherited settings. The existing empty-value type and clear fallback remain component-specific.

Selected rows show a primary-colored right-side checkmark in both single/multiple modes; candidate highlighting alone does not. In click/dblclick editors, checkmarks reflect draft selection, committed to Form only on confirmation. Disabled selected items retain disabled appearance.

### Cleared values and 1.x compatibility

`SelectValue` includes `undefined`. By default, single-select clear emits `''`; if the current options contain a `value: ''` option, it emits `undefined` to distinguish clearing from selecting that option. This published behavior is preserved. Both `change` and `update:modelValue` use `SelectValue`.

`empty-value` defines clear output; omission preserves the existing fallback. Single selection can use `() => undefined` to explicitly return undefined; multiple selection should return an array matching its model shape. Protected disabled selections take priority and prevent the clear override from running. Controlled mode still requires parent acceptance.

Root and component entries export `SelectValue` and `SelectEmptyValue`.

### Select props

Use `v-model`, `v-model:open` and `v-model:input-value` for controlled state. Clear values are `''` for single selection and `[]` for multiple selection. Select uses `undefined` when an actual empty-string option exists.

| Prop                                          | Description                                                                                                                                                                             | Type                                                        | Default                                                      |
| --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------ |
| `open-trigger-target`                         | Pointer opening target: the whole field or only the suffix icon. Explicit keyboard opening and controlled open remain available.                                                        | `'field' \| 'icon'`                                         | `'field'`                                                    |
| `model-value / default-value`                 | Controlled value / uncontrolled initial value                                                                                                                                           | `Value`                                                     | `Single: ''; multiple: []`                                   |
| `open / default-open`                         | Controlled / initial open state                                                                                                                                                         | `boolean`                                                   | `undefined / false`                                          |
| `input-value / default-input-value`           | Search text, independent of selected values                                                                                                                                             | `string`                                                    | `undefined / ''`                                             |
| `multiple`                                    | Multiple selection; enables search by default                                                                                                                                           | `boolean`                                                   | `false`                                                      |
| `size`                                        | Supports all five sizes; inherits group/form settings                                                                                                                                   | `ComponentSize`                                             | `md`                                                         |
| `variant`                                     | filled, outline, standard; inherits InputGroup                                                                                                                                          | `FormControlVariant`                                        | `filled`                                                     |
| `disabled / readonly / error`                 | Inherits form state unless explicitly overridden                                                                                                                                        | `boolean`                                                   | `undefined`                                                  |
| `placeholder`                                 | Placeholder                                                                                                                                                                             | `string`                                                    | `—`                                                          |
| `hint / line`                                 | Floating hint / standard variant underline                                                                                                                                              | `boolean`                                                   | `true`                                                       |
| `text-color / focus-color / blur-color`       | Field colors                                                                                                                                                                            | `string`                                                    | `—`                                                          |
| `loading`                                     | Loading state; blocks selection and confirmation                                                                                                                                        | `boolean`                                                   | `false`                                                      |
| `loading-mode` | Loading layout: default indicator or bottom line | `default / line` | `default` |
| `show-tags`                                   | Show tags; false displays separated text                                                                                                                                                | `boolean`                                                   | `true`                                                       |
| `separator`                                   | Separator when show-tags=false                                                                                                                                                          | `string`                                                    | `,`                                                          |
| `text-align`                                  | Text alignment: left / center / right. Inherits FormItem content-align when unset; standalone fields default to inline start                                                                    | `'left' \| 'center' \| 'right'`                             | `-`                                                          |
| `max-tag-count`                               | Maximum visible tags; 0 means unlimited                                                                                                                                                 | `number`                                                    | `0`                                                          |
| `tag-nowrap`                                  | Keep tags on one line with ellipsis and preserved removal icons; overflow scrolls horizontally; hover, focus or tap truncated text to preview it                                        | `boolean`                                                   | `false`                                                      |
| `popup-container`                             | Selector, element, element resolver, or false for inline rendering                                                                                                                      | `PopupContainer`                                            | `—`                                                          |
| `trigger-props`                               | Optional dropdown Trigger settings. Placement defaults to bottom-start and automatically adjusts when space is limited. The field owns open state; there is no top-level placement prop | `TriggerProps`                                              | `—`                                                          |
| `virtual-list-props`                          | Pass the virtual list attribute, pass in this parameter to turn on virtual scrolling [VirtualListProps](#VirtualListProps)                                                              | `VirtualListProps`                                          | `—`                                                          |
| `search-delay`                                | Search debounce delay in ms                                                                                                                                                             | `number`                                                    | `500`                                                        |
| `format-label`                                | Format selected labels; use label slot for VNodes                                                                                                                                       | `function`                                                  | `—`                                                          |
| `clearable`                                   | Allow clearing; preserve disabled selections                                                                                                                                            | `boolean`                                                   | `true`                                                       |
| `empty-value`                                 | Clear output override; return an array for multiple selection and preserve protected items                                                                                              | `SelectEmptyValue`                                          | `undefined`                                                  |
| `options`                                     | Primitive, object or grouped options; one source for every presentation                                                                                                                 | `SelectOption[]` / `(query, { signal }) => Array / Promise` | `undefined`                                                  |
| `field-names`                                 | Map value, label, disabled, tagProps, render; object values need a unique ID field                                                                                                      | `SelectFieldNames`                                          | `—`                                                          |
| `filterable`                                  | Enable search; optionally retainInputValue                                                                                                                                              | `boolean or { retainInputValue?: boolean }`                 | `Single: false; multiple: true`                              |
| case-sensitive                                | Case-sensitive built-in filtering; custom filters take priority                                                                                                                         | boolean                                                     | false                                                        |
| `filter-option`                               | false disables local filtering; callback receives query and raw option                                                                                                                  | `boolean or (input, option) => boolean`                     | Automatic: enabled for arrays, disabled for loader functions |
| `creatable`                                   | Allow creating missing options                                                                                                                                                          | `boolean`                                                   | `false`                                                      |
| `fallback-option`                             | Display unresolved values or return a complete fallback option                                                                                                                          | `boolean or (value) => SelectOptionData`                    | `true`                                                       |
| `show-extra-options`                          | Display fallback/created options in the panel                                                                                                                                           | `boolean`                                                   | `true`                                                       |
| `limit`                                       | Selection limit; 0 means unlimited                                                                                                                                                      | `number`                                                    | `0`                                                          |
| `auto-fit-popup-width`                        | Match Menu width to the field                                                                                                                                                           | `boolean`                                                   | `true`                                                       |
| `default-active-first-option`                 | On opening, activate the first enabled candidate if no valid selected option exists. Highlighting does not update modelValue or emit change; an existing valid selection takes priority | `boolean`                                                   | `true`                                                       |
| `unmount-on-close`                            | Unmount Menu content when closed                                                                                                                                                        | `boolean`                                                   | `false`                                                      |
| `scrollbar`                                   | Whether to enable virtual scroll bar                                                                                                                                                    | `boolean or ScrollbarProps`                                 | `true`                                                       |
| `show-header-on-empty / show-footer-on-empty` | Display header/footer in empty state                                                                                                                                                    | `boolean`                                                   | `false`                                                      |
| `edit-mode`                                   | Field presentation; inherits FormItem/Form when omitted                                                                                                                                 | `direct / click / dblclick`                                 | `direct`                                                     |
| `before-commit`                               | Asynchronous before-commit hook after validation                                                                                                                                        | `(value, context) => void / false / Promise`                | —                                                            |

### Events and methods

- `update:modelValue`, `change(value)`: emitted on commit, not while editing a draft.
- `update:open`, `open-change(open)`: request an expanded-state change.
- `update:inputValue`, `input-value-change(text)`, `search(text)`: search state.
- `focus(event)`, `blur(event)`, `clear(event)`: native field events; only the field owner notifies Form.
- Methods: `focus()`, `blur()`.

Select also emits `remove(value)`, `exceed-limit(value, event)`, `dropdown-scroll(event)`, and `dropdown-reach-bottom(event)`.

### Slots and option data

Use `label({ data })` for custom `selected` labels; `selected` replaces the whole selection area. Also supports `prefix`, `suffix`, `clear-icon({ clear })`, `arrow-icon`, `loading-icon`, `search-icon`, `empty`, and `option({ data })`.

Option `label` is searchable plain text. Use `render` or the `option` slot for custom `option` content, and `format-label` or `label` slot for selected content. Values identify selections; labels never do. `disabled` blocks selection/removal, and `tagProps` customizes selected tags.

Select additionally supports `header`, `footer`, `trigger`, and default `Option / Optgroup` children. Option props: `value`, `label`, `disabled`, `tagProps`, `index`; its default slot receives `selected`. Group data uses `{ isGroup: true, label, options }`. List and Picker also accept slot options; Picker displays their text labels.

Single/multiple options both use popup-option-padding-horizontal. There is no implicit search-highlight DOM; custom option slots style their own highlighted fragments. Unused multi-popup-option-padding-horizontal and popup-option-highlight-* variables are removed.

`read-pretty` is an independent boolean alongside `readonly` and `disabled`. It inherits from field to FormItem to Form; explicit `false` overrides the parent. The default is `false`. Reading mode renders no editor.

### Option Props

| Prop      | Description                                                 | Type                                                   | Default   |
| --------- | ----------------------------------------------------------- | ------------------------------------------------------ | --------- |
| value     | Option Value                                                | string \| number \| boolean \| Record<string, unknown> | undefined |
| label     | Option group title                                          | string                                                 | undefined |
| disabled  | Whether to disable                                          | boolean                                                | false     |
| tag-props | Props of the multi-select label corresponding to the option | TagProps                                               | undefined |
| index     | Explicit option order                                       | number                                                 | undefined |

### Option Slots

| Slot    | Description           | Arguments             |
| ------- | --------------------- | --------------------- |
| default | Custom option content | { selected: boolean } |
| icon    | Option icon           | -                     |
| suffix  | Option suffix         | -                     |

### Optgroup Props

| Prop  | Description        | Type   | Default   |
| ----- | ------------------ | ------ | --------- |
| label | Option group title | string | undefined |

### Optgroup Slots

| Slot    | Description                    | Arguments |
| ------- | ------------------------------ | --------- |
| label   | Option group title             | -         |
| default | Option children inside a group | -         |

### Select Slots

| Slot         | Description                             | Arguments       |
| ------------ | --------------------------------------- | --------------- |
| default      | Option / Optgroup children              | -               |
| option       | Custom option content                   | { data }        |
| label        | Option group title                      | { data }        |
| selected     | Replace the whole selected-value region | -               |
| header       | Menu header                             | -               |
| footer       | Menu footer                             | -               |
| trigger      | Custom field trigger                    | -               |
| prefix       | Field prefix                            | -               |
| suffix       | Field suffix                            | -               |
| clear-icon   | Custom clear action                     | { clear }       |
| arrow-icon   | Dropdown arrow                          | -               |
| search-icon  | Search icon                             | -               |
| loading-icon | Loading icon                            | -               |
| empty        | Empty-state content                     | -               |
| read         | Read-mode content                       | { value, text } |

### Select Events

| Event                 | Description                                              | Arguments    |
| --------------------- | -------------------------------------------------------- | ------------ |
| update:model-value    | Request a model value update                             | value        |
| change                | Option                                                   | value        |
| update:open           | Request popup visibility                                 | open         |
| open-change           | Popup visibility changes                                 | open         |
| update:input-value    | Request search text update                               | text         |
| input-value-change    | Search text changes                                      | text         |
| search                | Triggered when the user searches                         | text         |
| focus                 | Field gains focus                                        | event        |
| blur                  | Field loses focus                                        | event        |
| clear                 | Triggered when the value of the input changes            | event        |
| remove                | Triggered when the delete button of the label is clicked | value        |
| exceed-limit          | Selection would exceed the multiple-selection limit      | value, event |
| dropdown-scroll       | Menu scrolls                                             | event        |
| dropdown-reach-bottom | Menu reaches its bottom                                  | event        |

### Select Methods

| Method | Description            | Arguments |
| ------ | ---------------------- | --------- |
| focus  | Focus the actual field | -         |
| blur   | Blur the actual field  | -         |

### Selected-checkmark style variables

| Variable                              | Default                             |
| ------------------------------------- | ----------------------------------- |
| `--c-select-popup-option-check-color` | `var(--c-sys-color-action-primary)` |
| `--c-select-popup-option-check-size`  | `var(--c-sys-font-size-md)`         |
| `--c-select-popup-option-check-gap`   | `var(--c-sys-space-4)`              |

### Public type exports

Root and component entries export `SelectEmits`、`SelectSlots`、`SelectExpose` alongside Props and Instance. Emits are event argument tuples derived from the runtime validators; Expose contains focus/blur.

### Built-in search fields

`searchFields` / `search-fields` is a readonly `('label' | 'value')[]`, defaulting to `['label']`. Multiple fields use OR matching, case-insensitive by default. `['value', 'label']` searches codes and names; fieldNames maps semantic fields to business fields. An empty array matches no items for a nonempty query. Values are compared as strings; object traversal, object values and pinyin matching require a custom callback. A custom callback takes precedence and decides case handling itself. Remote results use the existing protocol for disabling local filtering. Cascader retains path semantics and checks the configured fields on each path node.

## Loading options through a function prop

Pass options(query, { signal }) directly; useAsyncData is unnecessary. options still accepts arrays, and an explicit array, including [], takes precedence. The component manages loading, stale-result isolation and cancellation. load-error reports failures, and the instance refresh() method retries. A business loader may accept only query and ignore the second argument.

filterable enables entering a search query. filterOption controls only local matching and never sends requests. With an options loader, remote results are not filtered again by default; with only an array, local matching is enabled by default. Most callers do not need filter-option.

```vue
<c-select v-model="value" :options="loadOptions" filterable />
```

`empty-value` accepts explicit `null` (or `() => null`). Clearing publishes `null` unchanged; omitted values preserve the existing default. Editors render `null` as blank without converting ordinary empty-string input to `null`. In popup editing, clearing changes the draft; confirm commits it and cancel preserves the original model.

Cancellable hooks use `(payload, done, context)`: closure payloads contain `{ action }`, change/commit payloads contain `{ value, previousValue }`, and Popup uses `{ reason }`. Context provides `signal` and an optional original `event`. Return a boolean/Promise, or call done()/done(false). Synchronous void waits for done; Promise&lt;void&gt; allows the operation. First completion wins. Pending state controls loading/disabled automatically. Cancellation invalidates stale results. Button refs are not exposed.

---

Document: llms/en-US/components/skeleton.md

<!-- Source: src/skeleton/README.en-US.md; locale: en-US; page: /en/components/skeleton/ -->

# Skeleton

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

Preview configuration: `:loading="loading"`.

Example source: src/skeleton/__demos__/basic.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
const loading = ref(true);
</script>

<template>
  <c-switch v-model="loading" />
  <c-skeleton :loading="loading">加载的数据</c-skeleton>
</template>
```

## Content and presentation

### Skeleton content shapes

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `title` | Whether to show a title placeholder | Skeleton content shapes, Animation |
| `loading` | Whether to display the loading skeleton | Skeleton content shapes, Fullscreen |
| `avatar` | Whether to show an avatar placeholder | Skeleton content shapes, Animation |
| `rows` | The paragraph number of rows | Skeleton content shapes |
| `rows-width` | Width of each row | Skeleton content shapes |
| `card` | Whether to show a card placeholder | Skeleton content shapes |
<!-- demo-config-notes:end -->


Compare text-row placeholders with avatar and card shapes according to the final content layout.

Example source: src/skeleton/__demos__/content-comparison.vue

```vue
<script setup lang="ts">
import { ref } from "vue"
import { proxyRefs as demoProxyRefs } from 'vue'

const scene1 = demoProxyRefs((() => {

const loading = ref(true);
return { loading }
})())
</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="title-and-rows">
    <h4><span lang="zh-CN">标题与段落</span><span lang="en-US">title and rows</span></h4>
    <c-skeleton
        title
        :rows="3"
        :loading="scene1.loading"
        :rows-width="['200px', '100px', '50px']"
      >
        加载的数据
      </c-skeleton>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="avatar-and-card">
    <h4><span lang="zh-CN">头像与卡片</span><span lang="en-US">avatar and card</span></h4>
    <c-skeleton title avatar card :rows="3">加载的数据</c-skeleton>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

### Animation

Preview configuration: `title`, `avatar`, `:animation="animation"`.

Example source: src/skeleton/__demos__/animation.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
const animation = ref(true);
</script>

<template>
  <c-switch v-model="animation" />
  <c-skeleton title avatar :animation="animation">加载的数据</c-skeleton>
</template>
```

### Fullscreen

Preview configuration: `fullscreen`, `:loading="loading"`.

Example source: src/skeleton/__demos__/fullscreen.vue

```vue
<script setup lang="ts">
import { onUnmounted, ref } from "vue";
const loading = ref(false);
let timer: ReturnType<typeof setTimeout> | undefined;

function show() {
  loading.value = true;
  clearTimeout(timer);
  timer = setTimeout(() => {
    loading.value = false;
  }, 2000);
}
onUnmounted(() => clearTimeout(timer));
</script>

<template>
  <c-button status="danger" @click="show">切换全屏模式</c-button>
  <c-skeleton fullscreen :loading="loading" />
</template>
```

## Customization and slots

### Custom Template

Preview configuration: `:rows="3"`, `:widths="['100%', '100%', '60%']"`, `shape="circle"`.

Example source: src/skeleton/__demos__/custom-template.vue

```vue
<template>
  <c-skeleton>
    <template #template>
      <c-space block direction="column" size="lg">
        <c-skeleton-line :rows="3" :widths="['100%', '100%', '60%']" />
        <c-skeleton-shape shape="circle" />
      </c-space>
    </template>
    加载的数据
  </c-skeleton>
</template>
```

## API

### `<skeleton>` Props

| Parameter | Description | Type | Default |
| ------------------ | ---------------------------- | ------------------------- | :-----: |
| loading | Whether to display the loading skeleton | `boolean` | `true` |
| animation | Whether skeleton animation is enabled | `boolean` | `true` |
| title | Whether to show a title placeholder | `boolean` | `false` |
| avatar | Whether to show an avatar placeholder | `boolean` | `false` |
| card | Whether to show a card placeholder | `boolean` | `false` |
| rows | The paragraph number of rows | `number \| string` | `3` |
| rows-width | Width of each row | `Array<number \| string>` | `[]` |
| title-width | `50%` | `number \| string` | `-` |
| avatar-size | `34px` | `number \| string` | `-` |
| card-height | `160px` | `number \| string` | `-` |
| fullscreen | Whether to use a fullscreen placeholder | `boolean` | `false` |
| fullscreen-z-index | Fullscreen placeholder stacking level | `number \| string` | `100` |

### `<skeleton>` Slots

| Slot | Description |
| -------- | -------------------- |
| default | Actual content after loading |
| template | Custom loading placeholder |

### `<skeleton-line>` Props

| Parameter | Description | Type | Default |
| ------------ | ---------------- | ------------------------- | :----: |
| rows | Displayed row count | `number` | `1` |
| widths | Line skeleton width | `Array<number \| string>` | `[]` |
| line-height | Line skeleton height | `number` | `20` |
| line-spacing | Line skeleton row spacing | `number` | `15` |

### `<skeleton-shape>` Props

| Parameter | Description | Type | Default |
| ------ | -------------- | ---------------------- | :--------: |
| shape | Graphic skeleton shape | `'square' \| 'circle'` | `'square'` |
| size | Graphic skeleton size | `'sm' \| 'md' \| 'lg'` | `'md'` |

### Type definitions

The component exports the following types

```ts
import type {
  SkeletonInstance,
  SkeletonLineProps,
  SkeletonShapeProps,
} from "@cedar-design/ui";
```

## Shared implementation and platform boundaries

Each platform maintains a complete local implementation. They do not import a common core or share component instances or reactive state. Changes must update both implementations. Component bodies, props, key styles and paired tests have read-only source consistency checks; theme tokens and installation entries remain local to each library.

Skeleton, SkeletonLine and SkeletonShape use independently copied source. Each library maintains its skeleton theme and size tokens.

### Managed defaults

| Token | Default |
| --- | --- |
| `--c-skeleton-content-padding` | `var(--c-sys-space-6)` |
| `--c-skeleton-card-border-radius` | `var(--c-sys-radius-md)` |
| `--c-skeleton-card-margin-bottom` | `var(--c-sys-space-6)` |
| `--c-skeleton-card-background-color` | `var(--c-sys-color-state-hover)` |
| `--c-skeleton-animation-background` | `linear-gradient(90deg, transparent, var(--c-sys-color-surface-default), transparent)` |
| `--c-skeleton-avatar-border-radius` | `50%` |
| `--c-skeleton-avatar-margin-right` | `var(--c-sys-space-6)` |
| `--c-skeleton-avatar-background-color` | `var(--c-sys-color-state-hover)` |
| `--c-skeleton-title-border-radius` | `10px` |
| `--c-skeleton-title-background-color` | `var(--c-sys-color-state-hover)` |
| `--c-skeleton-row-height` | `12px` |
| `--c-skeleton-row-border-radius` | `10px` |
| `--c-skeleton-row-margin-top` | `10px` |
| `--c-skeleton-shape-size-sm` | `36px` |
| `--c-skeleton-shape-size-md` | `48px` |
| `--c-skeleton-shape-size-lg` | `60px` |
| `--c-skeleton-shape-border-radius` | `var(--c-sys-radius-md)` |

### Motion variables

| Token | Default |
| --- | --- |
| `--c-skeleton-animation-duration` | `1s` |
| `--c-skeleton-transition-duration` | `var(--c-sys-motion-duration-slow)` |

Built-in motion follows prefers-reduced-motion: reduce, preserving content/state feedback while disabling decorative spinning, shimmer and ripples. Icon name changes skip waiting and cancel unfinished transitions. Ripple duration variables affect only CSS; the 250ms lifecycle timer remains unchanged, so each visual stage should not exceed 250ms. Callers must adapt custom animation classes.

---

Document: llms/en-US/components/slider.md

<!-- Source: src/slider/README.en-US.md; locale: en-US; page: /en/components/slider/ -->

# Slider

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

Example source: src/slider/__demos__/basic.vue

```vue
<template>
  <c-slider></c-slider>
</template>
<script lang="ts" setup>
</script>
```

## Layout and arrangement

### Vertical

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration  | Purpose                                                                                                                 | Related examples |
| -------------- | ----------------------------------------------------------------------------------------------------------------------- | ---------------- |
| `orientation`  | Horizontal/vertical axis of the slider track and interaction, default horizontal; not the direction of value increments | Vertical         |
| `aria-label`   | Name, or separate names for range thumbs                                                                                | Vertical         |
| `range`        | Fixed low/high thumbs; initial reversed values are sorted                                                               | Vertical         |
| `show-tooltip` | true on hover/focus/drag, false hidden, always persistent                                                               | Vertical         |

<!-- demo-config-notes:end -->

Preview configuration: `orientation="vertical"`, `aria-label="Vertical value"`, `range`, `show-tooltip="always"`.

Example source: src/slider/__demos__/vertical.vue

```vue
<script setup>
import { ref } from 'vue'

const value = ref(50)
const pair = ref([7, 64])
</script>

<template>
  <section class="slider-vertical-demo">
    <c-space justify="space-around">
      <div class="slider-vertical-demo__track">
        <c-slider v-model="value" orientation="vertical" aria-label="Vertical value" />
      </div>
      <div class="slider-vertical-demo__track">
        <c-slider
          v-model="pair"
          range
          show-tooltip="always"
          orientation="vertical"
          :aria-label="['Vertical minimum', 'Vertical maximum']"
        />
      </div>
    </c-space>
    <output aria-label="Vertical values">{{ value }} / {{ pair[0] }}–{{ pair[1] }}</output>
  </section>
</template>

<style scoped>
.slider-vertical-demo {
  display: flex;
  flex-direction: column;
  gap: 16px;
}
.slider-vertical-demo__track {
  height: 300px;
}
</style>
```

## Content and presentation

### Touch And Labels

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration  | Purpose                                                   | Related examples |
| -------------- | --------------------------------------------------------- | ---------------- |
| `show-tooltip` | true on hover/focus/drag, false hidden, always persistent | Touch And Labels |
| `aria-label`   | Name, or separate names for range thumbs                  | Touch And Labels |

<!-- demo-config-notes:end -->

Preview configuration: `show-tooltip="always"`, `aria-label="Always visible"`, `:show-tooltip="false"`, `active-color="#722ed1"`.

Example source: src/slider/__demos__/touch-and-labels.vue

```vue
<script setup>
import { ref } from "vue";

const value = ref(45);
</script>
<template>
  <c-space direction="column" size="36px" style="padding: 32px 12px">
    <c-slider
      v-model="value"
      show-tooltip="always"
      aria-label="Always visible"
    />
    <c-slider
      v-model="value"
      :show-tooltip="false"
      active-color="#722ed1"
      thumb-color="#f4edff"
      :track-height="8"
      :thumb-size="24"
      aria-label="Custom size"
    />
    <c-slider v-model="value" aria-label="Custom handle"
      ><template #button="{ currentValue }"
        ><span class="slider-custom-handle">{{ currentValue }}</span></template
      ></c-slider
    >
  </c-space>
</template>
<style scoped>
.slider-custom-handle {
  display: flex;
  align-items: center;
  justify-content: center;
  width: 28px;
  height: 28px;
  border: 1px solid currentColor;
  border-radius: 50%;
  background: white;
  transform: translate(-6px, -6px);
}
</style>
```

## Interaction and control

### State Lab

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration | Purpose                                                    | Related examples                 |
| ------------- | ---------------------------------------------------------- | -------------------------------- |
| `aria-label`  | Name, or separate names for range thumbs                   | Keyboard Input, Controlled Range |
| `range`       | Fixed low/high thumbs; initial reversed values are sorted  | Keyboard Input, Controlled Range |
| `step`        | Positive finite step aligned to min; max remains reachable | Keyboard Input                   |
| `marks`       | Map positions within the finite range to text              | Keyboard Input                   |
| `show-ticks`  | Show step ticks; dense ticks are reduced, up to 1000       | Keyboard Input                   |
| `show-input`  | InputNumber; Enter or blur commits via the same model      | Keyboard Input                   |

<!-- demo-config-notes:end -->

Example source: src/slider/__demos__/state-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref(30);
const __demoState = __demoReactive({
  disabled: false,
  readonly: false,
  error: false,
});
</script>
<template>
  <c-space direction="column" :size="16">
    <c-space wrap>
      <c-checkbox v-model="__demoState['disabled']">disabled</c-checkbox>
      <c-checkbox v-model="__demoState['readonly']">readonly</c-checkbox>
      <c-checkbox v-model="__demoState['error']">error</c-checkbox>
    </c-space>
    <c-slider v-model="value" v-bind="__demoState"></c-slider>
  </c-space>
</template>
```

### Keyboard Input

- `step`: Controls the allowed increment.

Example source: src/slider/__demos__/keyboard-input.vue

```vue
<script setup>
import { ref } from "vue";

const value = ref(30);
const pair = ref([20, 80]);
const marks = { 0: "0", 25: "25", 50: "50", 75: "75", 100: "100" };
</script>
<template>
  <c-space direction="column" size="32px" style="padding: 24px 12px">
    <c-slider
      v-model="value"
      :step="5"
      :marks="marks"
      show-ticks
      show-input
      aria-label="Volume"
    />
    <c-slider
      v-model="pair"
      range
      show-input
      :aria-label="['Minimum', 'Maximum']"
      :format-tooltip="(value) => value + '%'"
    />
  </c-space>
</template>
```

### Controlled Range

- `readonly`: Displays the current value without allowing edits.
- `disabled`: Prevents user interaction.

Example source: src/slider/__demos__/controlled-range.vue

```vue
<script setup>
import { ref } from "vue";

const accepted = ref([30, 70]);
const proposed = ref(50);
</script>
<template>
  <c-space direction="column" size="28px" style="padding: 24px 12px">
    <c-slider
      v-model="accepted"
      range
      show-tooltip="always"
      :aria-label="['Minimum', 'Maximum']"
    />
    <c-slider
      :model-value="50"
      aria-label="Controlled rejection"
      @update:model-value="proposed = $event"
    />
    <output>{{ proposed }}</output>
    <c-slider :default-value="40" readonly aria-label="Read only" />
    <c-slider :default-value="40" disabled aria-label="Disabled" />
  </c-space>
</template>
```

## API

### Empty values and reading placeholders

`empty-values` recognizes empty data; `empty-value` keeps existing clear output. `empty-text` defaults to `'-'` under `read-pretty`, with Field > FormItem > Form precedence and custom read slots first. With explicit empty-values, built-in required uses the policy; custom validators receive original data. See the [shared guide](llms/en-US/guide/empty-values.md).

| Prop         | Type               | Default and scope                                                           |
| ------------ | ------------------ | --------------------------------------------------------------------------- |
| empty-values | readonly unknown[] | Field > FormItem > Form > component-family default; replaces the whole list |
| empty-text   | string             | Field > FormItem > Form > '-'; explicit '' is valid                         |

These props belong to field presentation; pure panels do not gain reading mode. Form and FormItem provide inherited settings. The existing empty-value type and clear fallback remain component-specific.

### Props

| Prop                                     | Description                                                                                                             | Type                             | Default        |
| ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | -------------------------------- | -------------- |
| model-value                              | Controlled value; range uses a tuple                                                                                    | `SliderValue`                    | —              |
| default-value                            | Initial uncontrolled value                                                                                              | `SliderValue`                    | `0`            |
| min / max                                | Finite bounds; numeric strings are accepted. Invalid values fall back to 0/100. max<=min blocks interaction             | `number \| string`               | `0 / 100`      |
| step                                     | Positive finite step aligned to min; max remains reachable                                                              | `number \| string`               | `1`            |
| range                                    | Fixed low/high thumbs; initial reversed values are sorted                                                               | `boolean`                        | `false`        |
| orientation                              | Horizontal/vertical axis of the slider track and interaction, default horizontal; not the direction of value increments | `horizontal \| vertical`         | `horizontal`   |
| disabled / readonly / error              | Inherits applicable FormItem/Form state when omitted; readonly is focusable but cannot change values                    | `boolean`                        | Inherited      |
| show-ticks                               | Show step ticks; dense ticks are reduced, up to 1000                                                                    | `boolean`                        | `false`        |
| marks                                    | Map positions within the finite range to text                                                                           | `Record<number,string>`          | —              |
| show-input                               | InputNumber; Enter or blur commits via the same model                                                                   | `boolean`                        | `false`        |
| show-tooltip                             | true on hover/focus/drag, false hidden, always persistent                                                               | `boolean \| 'always'`            | `true`         |
| format-tooltip                           | Formats tooltip and aria-valuetext                                                                                      | `(value:number)=>string\|number` | Original value |
| aria-label                               | Name, or separate names for range thumbs                                                                                | `string \| [string,string]`      | —              |
| active-color / track-color / thumb-color | Active track/background/thumb fill colors                                                                               | `string`                         | CSS variable   |
| label-color / label-text-color           | Tooltip background/text colors                                                                                          | `string`                         | CSS variable   |
| track-height / thumb-size                | Track thickness/thumb diameter in numeric px or CSS lengths; invalid values retain theme defaults                       | `number \| string`               | CSS variable   |

### Behavior and keyboard

Arrows adjust by step, PageUp/PageDown by 10 steps, Home/End reach available endpoints. Range-thumb ARIA min/max follow the other thumb. When overlapping, clicks left/down separate the lower thumb, right/up the upper thumb. Keyboard events inside interactive thumb content are not intercepted. Readonly retains focus/tooltips; disabled leaves the Tab sequence.

Pointer Events unify mouse, touch and pen. pointerup commits final coordinates; pointercancel/lost capture ends the latest proposal. Disabling, unmounting or KeepAlive deactivation cleans listeners/capture and stops value events. Horizontal sliders allow vertical page scrolling; vertical sliders allow horizontal scrolling.

Controlled display changes only after parent updates; normalization does not emit automatically. change/update:model-value report distinct proposals; end includes the final proposal without guaranteeing acceptance. Each keyboard/numeric-input operation has start/end; a drag has one pair. Internal InputNumber does not duplicate Form validation. label-visible is removed; use show-tooltip without a compatibility alias.

### Events

| Event              | Arguments     | Meaning                                               |
| ------------------ | ------------- | ----------------------------------------------------- |
| update:model-value | `SliderValue` | Request an update                                     |
| change             | `SliderValue` | Distinct numeric proposal paired with the model event |
| start              | —             | Interaction starts                                    |
| end                | `SliderValue` | Final proposal when interaction ends                  |

### Slots / Methods

The button slot receives `{ currentValue:number,index:number }`. Custom content retains keyboard, ARIA and tooltip behavior. focus(index=0) focuses thumbs in display order; blur() removes focus.

Exports SliderProps, SliderValue, SliderOrientation, SliderTooltipFormatter, SliderTooltipVisibility, SliderEmits, SliderSlots, SliderExpose, SliderInstance and runtime sliderProps. Component bodies/styles are independently copied; installation/Form integration remain local to each library.

### Style variables

| Variable                         | Default                                |
| -------------------------------- | -------------------------------------- |
| `--c-slider-active-color`        | `var(--c-sys-color-content-brand)`     |
| `--c-slider-track-color`         | `var(--c-sys-color-state-hover)`       |
| `--c-slider-thumb-color`         | `var(--c-sys-color-surface-default)`   |
| `--c-slider-thumb-border-color`  | `var(--c-sys-color-content-brand)`     |
| `--c-slider-text-color`          | `var(--c-sys-color-content-secondary)` |
| `--c-slider-tooltip-background`  | `var(--c-sys-color-surface-tooltip)`   |
| `--c-slider-tooltip-color`       | `var(--c-sys-color-content-on-dark)`   |
| `--c-slider-error-color`         | `var(--c-sys-color-content-danger)`    |
| `--c-slider-disabled-color`      | `var(--c-sys-color-content-disabled)`  |
| `--c-slider-track-height`        | `4px`                                  |
| `--c-slider-thumb-size`          | `16px`                                 |
| `--c-slider-control-height`      | `var(--c-sys-control-height-md)`       |
| `--c-slider-font-size`           | `var(--c-sys-font-size-sm)`            |
| `--c-slider-gap`                 | `var(--c-sys-space-4)`                 |
| `--c-slider-radius`              | `var(--c-sys-radius-md)`               |
| `--c-slider-transition-duration` | `var(--c-sys-motion-duration-fast)`    |
| `--c-slider-input-width`         | `80px`                                 |

### Form field presentation and confirmation

This component supports `edit-mode` with field > FormItem > Form precedence. When unset, it defaults to `direct` and preserves `direct` editing. Supported values: `direct / click / dblclick`. Non-`direct` modes open the editor through the field value trigger and keep one draft; v-model updates only after confirmation. Cancel, reset or enabling readPretty discards the draft.

Cedar uses edit-mode="click" / "dblclick" to open an editor popup near the field. Enter/F2 also opens it; cancel/Escape discards the draft, and confirmation commits it. readPretty is an independent reading setting, separate from readonly and disabled.

`before-commit(value, { previousValue, signal })` can reject an overlay save. FormItem validates the candidate first and keeps the editor open on failure. `open / default-open / update:open` control the editor. Use `#read="{ value, text }"` to customize display. See the full field comparison in Form.

`read-pretty` is an independent boolean alongside `readonly` and `disabled`. It inherits from field to FormItem to Form; explicit `false` overrides the parent. The default is `false`. Reading mode renders no editor.

`empty-value` accepts explicit `null` (or `() => null`). Clearing publishes `null` unchanged; omitted values preserve the existing default. Editors render `null` as blank without converting ordinary empty-string input to `null`. In popup editing, clearing changes the draft; confirm commits it and cancel preserves the original model.

---

Document: llms/en-US/components/space.md

<!-- Source: src/space/README.en-US.md; locale: en-US; page: /en/components/space/ -->

# Space

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

Example source: src/space/__demos__/basic.vue

```vue
<template>
  <c-space>
    <div>Space:</div>
    <c-tag v-if="false">Tag</c-tag>
    <c-button status="primary">Item1</c-button>
    <c-button status="primary">Item2</c-button>
  </c-space>
</template>
```

## Appearance and states

### Size

- `size`: Controls the component size.

Example source: src/space/__demos__/size.vue

```vue
<template>
  <div>
    <div style="margin-bottom: 20px">
      <c-radio-group v-model="size" type="button">
        <c-radio value="xs">xs</c-radio>
        <c-radio value="sm">sm</c-radio>
        <c-radio value="md">md</c-radio>
        <c-radio value="lg">lg</c-radio>
        <c-radio value="xl">xl</c-radio>
      </c-radio-group>
    </div>
    <c-space :size="size">
      <c-button status="primary">Item1</c-button>
      <c-button status="primary">Item2</c-button>
      <c-button status="primary">Item3</c-button>
    </c-space>
  </div>
</template>
<script lang="ts">
import { defineComponent, ref } from 'vue'
export default defineComponent({
  setup() {
    const size = ref('md')

    return {
      size,
    }
  },
})
</script>
```

## Layout and arrangement

### Vertical

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `direction` | Row/column order of children, default row; column stacks them vertically. Does not use horizontal/vertical values | Vertical, Align, Layout Lab |
| `align` | Cross-axis alignment: `flex-start`, `flex-end`, `center`, `stretch` or `baseline`. When omitted, inferred from `direction`: `row` → `center`, `column` → `stretch` | Align, Layout Lab |
| `wrap` | Whether to exceed the line break | Wrap, Split |
| `size` | Gap: `xs`/`sm`/`md`/`lg`/`xl` or `[rowGap, columnGap]`, supporting CSS lengths and shorthand | Split, Layout Lab |
| `justify` | Main axis arrangement, Can be set to `flex-start` `flex-end` `center` `space-around` `space-between` `space-evenly` | Layout Lab |
<!-- demo-config-notes:end -->


- `direction`: Controls the content direction.

Example source: src/space/__demos__/vertical.vue

```vue
<template>
  <c-space direction="column">
    <c-button status="primary" long>Item1</c-button>
    <c-button status="primary" long>Item2</c-button>
    <c-button status="primary" long>Item3</c-button>
  </c-space>
</template>
<script lang="ts">
import { defineComponent } from 'vue'
export default defineComponent({
  })
</script>
```

### Align

- `direction`: Controls the content direction.
- `align`: Controls alignment on the cross axis.

Example source: src/space/__demos__/align.vue

```vue
<template>
  <c-space direction="column" align="stretch">
    <c-space direction="column">
      <c-radio-group v-model="direction">
        <c-radio value="row">row</c-radio>
        <c-radio value="column">column</c-radio>
      </c-radio-group>
      <c-radio-group v-model="align">
        <c-radio value="flex-start">flex-start</c-radio>
        <c-radio value="flex-end">flex-end</c-radio>
        <c-radio value="center">center</c-radio>
        <c-radio value="stretch">stretch</c-radio>
        <c-radio value="baseline">baseline</c-radio>
      </c-radio-group>
    </c-space>
    <c-space :align="align" :direction="direction" style="padding: 10px; background-color: var(--color-fill-2)">
      <div>Space:</div>
      <c-button status="primary">Item2</c-button>
      <c-card title="Card"> Card content </c-card>
    </c-space>
  </c-space>
</template>
<script lang="ts" setup>
import { ref } from 'vue'
const direction = ref('row')
const align = ref('center')
</script>
```

### Wrap

Example source: src/space/__demos__/wrap.vue

```vue
<template>
  <c-space wrap>
    <c-button status="primary">Item1</c-button>
    <c-button status="primary">Item2</c-button>
    <c-button status="primary">Item3</c-button>
    <c-button status="primary">Item4</c-button>
    <c-button status="primary">Item5</c-button>
    <c-button status="primary">Item6</c-button>
    <c-button status="primary">Item7</c-button>
    <c-button status="primary">Item8</c-button>
    <c-button status="primary">Item9</c-button>
    <c-button status="primary">Item10</c-button>
    <c-button status="primary">Item11</c-button>
    <c-button status="primary">Item12</c-button>
    <c-button status="primary">Item13</c-button>
    <c-button status="primary">Item14</c-button>
    <c-button status="primary">Item15</c-button>
    <c-button status="primary">Item16</c-button>
    <c-button status="primary">Item17</c-button>
    <c-button status="primary">Item18</c-button>
    <c-button status="primary">Item19</c-button>
    <c-button status="primary">Item20</c-button>
  </c-space>
</template>
<script lang="ts">
import { defineComponent } from 'vue'
export default defineComponent({})
</script>
```

### Split

- `size`: Controls the component size.

Example source: src/space/__demos__/split.vue

```vue
<template>
  <c-radio-group v-model="size">
    <c-radio value="xs">xs</c-radio>
    <c-radio value="sm">sm</c-radio>
    <c-radio value="md">md</c-radio>
    <c-radio value="lg">lg</c-radio>
    <c-radio value="xl">xl</c-radio>
  </c-radio-group>
  <br />
  <br />
  通过 divider 组件实现分割，并且通过 inset 和 spacing 调整分割线尺寸。
  <br />
  <br />
  <c-space :size="size" wrap>
    <template #split>
      <c-divider orientation="vertical" inset="md" spacing="0" />
    </template>
    <c-button status="primary">Item1</c-button>
    <c-button status="primary">Item2</c-button>
    <c-button status="primary">Item3</c-button>
    <c-button status="primary">Item4</c-button>
    <c-button status="primary">Item5</c-button>
    <c-button status="primary">Item6</c-button>
    <c-button status="primary">Item7</c-button>
    <c-button status="primary">Item8</c-button>
    <c-button status="primary">Item9</c-button>
    <c-button status="primary">Item10</c-button>
  </c-space>
  <br />
  通过自定义分割内容实现分割。
  <br />
  <br />
  <c-space :size="size" wrap>
    <template #split> <div>/</div> </template>
    <c-button status="primary">Item1</c-button>
    <c-button status="primary">Item2</c-button>
    <c-button status="primary">Item3</c-button>
    <c-button status="primary">Item4</c-button>
    <c-button status="primary">Item5</c-button>
    <c-button status="primary">Item6</c-button>
    <c-button status="primary">Item7</c-button>
    <c-button status="primary">Item8</c-button>
    <c-button status="primary">Item9</c-button>
    <c-button status="primary">Item10</c-button>
  </c-space>
</template>
<script lang="ts" setup>
import { ref } from 'vue'
const size = ref('md')
</script>
```

### Layout Lab

- `direction`: Controls the content direction.
- `size`: Controls the component size.

Example source: src/space/__demos__/layout-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";

const __demoLayout = __demoReactive({
  direction: "row",
  align: "flex-start",
  justify: "flex-start",
});
</script>
<template>
  <c-space direction="column" :size="16">
    <c-form layout="vertical">
      <c-form-item layout="vertical" size="sm" label="direction">
        <c-radio-group
          v-model="__demoLayout['direction']"
          aria-label="direction"
          :options="[
            { label: 'row', value: 'row' },
            { label: 'column', value: 'column' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
      <c-form-item layout="vertical" size="sm" label="align">
        <c-radio-group
          v-model="__demoLayout['align']"
          aria-label="align"
          :options="[
            { label: 'flex-start', value: 'flex-start' },
            { label: 'flex-end', value: 'flex-end' },
            { label: 'center', value: 'center' },
            { label: 'baseline', value: 'baseline' },
            { label: 'stretch', value: 'stretch' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
      <c-form-item layout="vertical" size="sm" label="justify">
        <c-select
          v-model="__demoLayout['justify']"
          :clearable="false"
          :options="[
            { label: 'flex-start', value: 'flex-start' },
            { label: 'flex-end', value: 'flex-end' },
            { label: 'center', value: 'center' },
            { label: 'space-around', value: 'space-around' },
            { label: 'space-between', value: 'space-between' },
            { label: 'space-evenly', value: 'space-evenly' },
          ]"
          aria-label="justify"
        />
      </c-form-item>
    </c-form>
    <c-space v-bind="__demoLayout">
      <div>Space:</div>
      <c-tag v-if="false">Tag</c-tag>
      <c-button status="primary">Item1</c-button>
      <c-button status="primary">Item2</c-button>
    </c-space>
  </c-space>
</template>
```

### Split wrapping and content state

Change wrapping, direction and order after typing a draft. A separator stays with its preceding item and may appear at a line end.

Example source: src/space/__demos__/split-wrapping.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'

const wrap = ref(true)
const direction = ref<'row' | 'column'>('row')
const items = ref(['A', 'B', 'C'])
</script>
<template>
  <c-space wrap :size="8">
    <c-button data-space-toggle-wrap @click="wrap = !wrap">换行 / Wrap</c-button>
    <c-button data-space-toggle-direction @click="direction = direction === 'row' ? 'column' : 'row'">方向 / Direction</c-button>
    <c-button data-space-reorder @click="items = [...items].reverse()">重排 / Reorder</c-button>
  </c-space>
  <p>输入草稿后切换布局或重排，文字仍跟随对应项。Drafts stay with their items.</p>
  <div style="max-width: 100%; overflow: auto">
    <c-space data-space-split-demo :size="12" :wrap="wrap" :direction="direction" style="width: 260px; max-width: 100%">
      <template v-for="item in items" :key="item">
        <label class="space-split-field">
          <span>Item {{ item }}</span>
          <input :aria-label="'Draft ' + item" placeholder="草稿 / Draft" />
        </label>
      </template>
      <template #split><span aria-hidden="true">/</span></template>
    </c-space>
  </div>
  <p>分隔符跟随前项，允许位于行尾。Separators stay with the preceding item.</p>
</template>
<style scoped>
.space-split-field {
  display: inline-flex;
  flex-direction: column;
  gap: 4px;
  width: 110px;
}
.space-split-field input {
  min-width: 0;
  width: 100%;
  box-sizing: border-box;
}
</style>
```

## Interaction and control

### Interactive Layout

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `wrap` | Whether to exceed the line break | Interactive Layout |
| `size` | Gap: `xs`/`sm`/`md`/`lg`/`xl` or `[rowGap, columnGap]`, supporting CSS lengths and shorthand | Interactive Layout |
| `direction` | Row/column order of children, default row; column stacks them vertically. Does not use horizontal/vertical values | Interactive Layout |
<!-- demo-config-notes:end -->


- `size`: Controls the component size.
- `direction`: Controls the content direction.

Example source: src/space/__demos__/interactive-layout.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'

const direction = ref<'row' | 'column'>('row')
const gap = ref(8)
const wrap = ref(false)
const count = ref(3)
</script>

<template>
  <div>
    <c-space wrap :size="8">
      <c-button @click="direction = direction === 'row' ? 'column' : 'row'">Toggle direction</c-button>
      <c-button @click="gap = gap === 8 ? 24 : 8">Toggle gap</c-button>
      <c-button @click="wrap = !wrap">Toggle wrap</c-button>
      <c-button :disabled="count >= 6" @click="count++">Add item</c-button>
      <c-button :disabled="count <= 1" @click="count--">Remove item</c-button>
    </c-space>
    <p aria-live="polite">{{ direction }} / gap {{ gap }} / wrap {{ wrap }} / items {{ count }}</p>
    <div style="max-width: 100%; overflow: auto">
      <c-space data-demo-layout :direction="direction" :size="[8, gap]" :wrap="wrap" style="width: 260px; max-width: 100%">
        <div v-for="item in count" :key="item" style="width: 72px; padding: 8px; box-sizing: border-box; border: 1px solid currentColor">Item {{ item }}</div>
      </c-space>
    </div>
  </div>
</template>
```

## Reading direction

Inherits the nearest `dir="ltr|rtl"`. Row layout follows reading order; column layout stays top to bottom. Flex-start/flex-end follows the corresponding flex axis. The size pair always means [rowGap,columnGap], including in RTL. Wrapping and split slots preserve content order. Direction changes do not reverse data or recreate children with stable keys.

## API

### Children and size boundaries

Keyed Fragment groups preserve their local child identity when reordered. Pure whitespace, empty text, comments and empty Fragments do not create spacing items; visible text, zero and empty elements remain. Empty split content also produces no separator item.

With wrap and split, separators stay with their preceding item. This permits trailing separators at line ends; it does not suppress separators at every line boundary. Items wider than the available line may still overflow. Without wrap, the existing Flex gap and justify allocation are unchanged. Layout switches preserve content nodes.

block switches the container between flex and inline-flex. align=stretch stretches item wrappers, not every control inside them: use the child control's block option or width:100% when required.

Invalid size shapes, negative/nonfinite numbers or tuples without exactly two lengths fall back to md and receive development diagnostics. Tuple entries are lengths, not presets. CSS var/calc expressions remain supported; CSS grammar and resolved values belong to the browser.


### Space Props

### Props

| Arguments | Description | Type | Default |
| --------- | ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | ---------------------- |
| direction | Row/column order of children, default row; column stacks them vertically. Does not use horizontal/vertical values | _string_ | `row` |
| justify | Main axis arrangement, Can be set to `flex-start` `flex-end` `center` `space-around` `space-between` `space-evenly` | _string_ | `flex-start` |
| align | Cross-axis alignment: `flex-start`, `flex-end`, `center`, `stretch` or `baseline`. When omitted, inferred from `direction`: `row` → `center`, `column` → `stretch` | _string_ | `-` |
| size | Gap: `xs`/`sm`/`md`/`lg`/`xl` or `[rowGap, columnGap]`, supporting CSS lengths and shorthand | _string \| number \| [string \| number, string \| number]_ | `md` |
| wrap | Whether to exceed the line break | _boolean_ | `false` |
| block | Whether to use a flex container | _boolean_ | `true` |

### Slots

| Slot | Description | Arguments |
| --------- | ---------- | ---- |
| `default` | Content of space | `-` |
| `split` | Range separator | `-` |

### Type definitions

```ts
import type { SpaceProps, SpaceSize, SpaceDirection, SpaceAlign, SpaceJustify, SpaceInternalSize, SpaceInstance } from '@cedar-design/ui'
```

### Style variables

| Variable | Default |
| --- | --- |
| `--c-space-size-xs-row-gap` | `var(--c-sys-space-2)` |
| `--c-space-size-xs-column-gap` | `var(--c-sys-space-2)` |
| `--c-space-size-sm-row-gap` | `var(--c-sys-space-4)` |
| `--c-space-size-sm-column-gap` | `var(--c-sys-space-3)` |
| `--c-space-size-md-row-gap` | `var(--c-sys-space-5)` |
| `--c-space-size-md-column-gap` | `var(--c-sys-space-4)` |
| `--c-space-size-lg-row-gap` | `var(--c-sys-space-6)` |
| `--c-space-size-lg-column-gap` | `var(--c-sys-space-5)` |
| `--c-space-size-xl-row-gap` | `var(--c-sys-space-8)` |
| `--c-space-size-xl-column-gap` | `var(--c-sys-space-6)` |

## Shared implementation and platform boundaries

Each platform maintains complete local source without a common core or shared instances/reactive state. Update both implementations together. Read-only parity checks cover bodies, props, child flattening, main styles, size tokens and paired tests. Only installation entries/namespaces are adapted locally.

Both default to `size="md"`, `wrap=false`, `block=true` and `direction="row"`. Omitted align means center for row and stretch for column. Maple callers previously relying on default wrapping must add `wrap` explicitly.

`size` supports all five presets, numbers/numeric strings in px, CSS lengths/expressions such as 1rem or var(--gap), and `[rowGap, columnGap]`. Arrays are always row then column; direction does not swap them. Array entries are lengths, not preset names. Shared [row,column] presets: xs=[4,4], sm=[8,6], md=[12,8], lg=[16,12], xl=[24,16] px, overridable through CSS variables.

---

Document: llms/en-US/components/split-button.md

<!-- Source: src/split-button/README.en-US.md; locale: en-US; page: /en/components/split-button/ -->

# Split Button

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

- `placement`: Chooses the position relative to the trigger.

Example source: src/split-button/__demos__/basic.vue

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

const publish = () => {
  Message.info("发布成功");
};
const handleSelect = (_value: unknown, option: { label?: unknown }) => {
  Message.info(String(option.label));
};
</script>

<template>
  <c-split-button
    placement="bottom-end"
    @click="publish"
    @select="handleSelect"
  >
    发布

    <template #content>
      <c-menu-option label="保存草稿" value="draft" />
      <c-menu-option label="保存并发布" value="publish" />
      <c-menu-option label="暂无权限" value="restricted" disabled />
    </template>
  </c-split-button>
</template>
```

## Appearance and states

### Variants

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `variant` | Button group variant | Variants |
| `disabled` | Whether the entire split button is disabled | Disabled |
| `button-props` | Props for the primary button | Disabled |
| `trigger-button-props` | Props for the menu trigger button | Disabled |
| `placement` | Preferred popup side relative to the trigger, default bottom. With the default auto-fit-position enabled, Trigger may flip and constrain it to the viewport when space is limited; this is not a fixed final position | Appearance configuration comparison |
<!-- demo-config-notes:end -->


- `variant`: Selects the visual variant.

Example source: src/split-button/__demos__/variants.vue

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

const publish = () => {
  Message.info("发布成功");
};
const handleSelect = (_value: unknown, option: { label?: unknown }) => {
  Message.info(String(option.label));
};
const variants = ["default", "outline", "tonal", "text"] as const;
</script>

<template>
  <c-space wrap>
    <c-split-button
      v-for="variant in variants"
      :key="variant"
      :variant="variant"
      @click="publish"
      @select="handleSelect"
    >
      {{ variant }}

      <template #content>
        <c-menu-option label="保存草稿" value="draft" />
        <c-menu-option label="保存并发布" value="publish" />
        <c-menu-option label="暂无权限" value="restricted" disabled />
      </template>
    </c-split-button>
  </c-space>
</template>
```

### Disabled

- `disabled`: Prevents user interaction.

Example source: src/split-button/__demos__/disabled.vue

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

const publish = () => {
  Message.info("发布成功");
};
const handleSelect = (_value: unknown, option: { label?: unknown }) => {
  Message.info(String(option.label));
};
</script>

<template>
  <c-space wrap>
    <c-split-button
      disabled
      :button-props="{ disabled: false }"
      :trigger-button-props="{ disabled: false }"
      @click="publish"
      @select="handleSelect"
    >
      整体禁用

      <template #content>
        <c-menu-option label="保存草稿" value="draft" />
        <c-menu-option label="保存并发布" value="publish" />
        <c-menu-option label="暂无权限" value="restricted" disabled />
      </template>
    </c-split-button>
    <c-split-button
      :button-props="{ disabled: true }"
      @click="publish"
      @select="handleSelect"
    >
      仅禁用主按钮

      <template #content>
        <c-menu-option label="保存草稿" value="draft" />
        <c-menu-option label="保存并发布" value="publish" />
        <c-menu-option label="暂无权限" value="restricted" disabled />
      </template>
    </c-split-button>
    <c-split-button
      :trigger-button-props="{ disabled: true }"
      @click="publish"
      @select="handleSelect"
    >
      仅禁用菜单按钮

      <template #content>
        <c-menu-option label="保存草稿" value="draft" />
        <c-menu-option label="保存并发布" value="publish" />
        <c-menu-option label="暂无权限" value="restricted" disabled />
      </template>
    </c-split-button>
  </c-space>
</template>
```

### Appearance configuration comparison

Choose an axis to compare its available values with the same content and model. Other settings remain unchanged while comparing.

Example source: src/split-button/__demos__/appearance-lab.vue

```vue
<script setup lang="ts">
import { reactive } from "vue";
import type { ComponentSize, SemanticStatus } from "../../_utils/constant";
import { Message } from "@cedar-design/ui";
const publish = () => {
  Message.info("发布成功");
};
const handleSelect = (_value: unknown, option: { label?: unknown }) => {
  Message.info(String(option.label));
};
const __demoAppearance = reactive<{ status: SemanticStatus; size: ComponentSize }>({
  status: "default",
  size: "md",
});

import { computed as demoComputed, ref as demoRef } from 'vue'

const demoCompareFields = [{"name":"status","values":["default","primary","secondary","tertiary","info","success","warning","danger"]},{"name":"size","values":["xs","sm","md","lg","xl"]}]
const demoCompareAxis = demoRef("status")
const demoComparedOptions = demoComputed(() => demoCompareFields.find(field => field.name === demoCompareAxis.value)?.values ?? [])
</script>
<template>
  <c-space direction="column" align="flex-start" :size="16">
    <c-form layout="vertical">
      <c-form-item layout="vertical" size="sm" label="status">
        <c-select
          v-model="__demoAppearance['status']"
          :clearable="false"
          :options="[
            { label: 'default', value: 'default' },
            { label: 'primary', value: 'primary' },
            { label: 'secondary', value: 'secondary' },
            { label: 'tertiary', value: 'tertiary' },
            { label: 'info', value: 'info' },
            { label: 'success', value: 'success' },
            { label: 'warning', value: 'warning' },
            { label: 'danger', value: 'danger' },
          ]"
          aria-label="status"
        />
      </c-form-item>
      <c-form-item layout="vertical" size="sm" label="size">
        <c-radio-group
          v-model="__demoAppearance['size']"
          aria-label="size"
          :options="[
            { label: 'xs', value: 'xs' },
            { label: 'sm', value: 'sm' },
            { label: 'md', value: 'md' },
            { label: 'lg', value: 'lg' },
            { label: 'xl', value: 'xl' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
    </c-form>
    <p class="demo-config-comparison-hint"><span lang="zh-CN">选择一个对比维度；其他配置和内容保持一致。输入类示例共享同一个值，便于比较外观。</span><span lang="en-US">Compare one dimension while keeping the other settings and content identical. Input specimens share the same value.</span></p>
<c-radio-group v-model="demoCompareAxis" aria-label="Compare configuration" :options="demoCompareFields.map(field => ({ label: field.name, value: field.name }))" />
<div class="demo-config-comparison">
<section v-for="sample in demoComparedOptions" :key="String(sample)">
<p><code>{{ demoCompareAxis }}={{ sample }}</code></p>
<c-split-button
      placement="bottom-end"
      @click="publish"
      @select="handleSelect"
      v-bind="{ ...__demoAppearance, [demoCompareAxis]: sample }"
    >
      发布

      <template #content>
        <c-menu-option label="保存草稿" value="draft" />
        <c-menu-option label="保存并发布" value="publish" />
        <c-menu-option label="暂无权限" value="restricted" disabled />
      </template>
    </c-split-button>
</section>
</div>
  </c-space>
</template>

<style scoped>
.demo-config-comparison { display: grid; grid-template-columns: repeat(auto-fit, minmax(min(100%, 220px), 1fr)); gap: 20px; min-width: 0; max-width: 100%; }
.demo-config-comparison > section { min-width: 0; }
.demo-config-comparison p { margin: 0 0 8px; }
html:not([lang='en-US']) .demo-config-comparison-hint > [lang='en-US'],
html[lang='en-US'] .demo-config-comparison-hint > [lang='zh-CN'] { display: none; }
</style>
```

## Content and presentation

### Popup

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `placement` | Preferred popup side relative to the trigger, default bottom. With the default auto-fit-position enabled, Trigger may flip and constrain it to the viewport when space is limited; this is not a fixed final position | Popup |
| `offset-y` | Screen-vertical offset; numbers are px, strings are converted as lengths | Popup |
| `popup-max-height` | Maximum menu height | Popup |
| `hide-on-select` | Close the menu after selection | Popup |
<!-- demo-config-notes:end -->


- `placement`: Chooses the position relative to the trigger.

Example source: src/split-button/__demos__/popup.vue

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

const lastAction = ref("");
const handleSelect = (value: unknown, option: { label?: unknown }) => {
  lastAction.value = String(value);
  Message.info(String(option.label));
};
</script>

<template>
  <c-space direction="column" align="flex-start">
    <c-split-button
      placement="bottom-start"
      :offset-y="8"
      :popup-max-height="160"
      :hide-on-select="false"
      @click="lastAction = 'publish'"
      @select="handleSelect"
    >
      选择操作
      <template #content>
        <c-menu-option label="保存草稿" value="draft" />
        <c-menu-option label="保存并发布" value="publish" />
        <c-menu-option label="暂无权限" value="restricted" disabled />
      </template>
    </c-split-button>
    <span aria-live="polite">最近操作: {{ lastAction || "暂无操作" }}</span>
    <span>选择后菜单保持展开，可连续选择；点击外部关闭。</span>
  </c-space>
</template>
```

## Customization and slots

### Custom Icon

Preview configuration: `label="保存草稿"`, `value="draft"`, `label="保存并发布"`, `value="publish"`.

Example source: src/split-button/__demos__/custom-icon.vue

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

const publish = () => {
  Message.info("发布成功");
};
const handleSelect = (_value: unknown, option: { label?: unknown }) => {
  Message.info(String(option.label));
};
</script>

<template>
  <c-split-button @click="publish" @select="handleSelect">
    发布
    <template #icon="{ open }">
      <c-icon-menu-down
        :style="{
          transform: open ? 'rotate(180deg)' : undefined,
          transition: 'transform 0.2s',
        }"
      />
    </template>
    <template #content>
      <c-menu-option label="保存草稿" value="draft" />
      <c-menu-option label="保存并发布" value="publish" />
      <c-menu-option label="暂无权限" value="restricted" disabled />
    </template>
  </c-split-button>
</template>
```

## Interaction and control

### Controlled

Preview configuration: `v-model:open="open"`, `label="保存草稿"`, `value="draft"`, `label="保存并发布"`.

Example source: src/split-button/__demos__/controlled.vue

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

const publish = () => {
  Message.info("发布成功");
};
const handleSelect = (_value: unknown, option: { label?: unknown }) => {
  Message.info(String(option.label));
};
const open = ref(false);
</script>

<template>
  <c-space direction="column" align="flex-start">
    <c-space wrap>
      <c-button @click.stop="open = true">展开菜单</c-button>
      <c-button @click.stop="open = false">关闭菜单</c-button>
    </c-space>
    <c-split-button v-model:open="open" @click="publish" @select="handleSelect">
      发布

      <template #content>
        <c-menu-option label="保存草稿" value="draft" />
        <c-menu-option label="保存并发布" value="publish" />
        <c-menu-option label="暂无权限" value="restricted" disabled />
      </template>
    </c-split-button>
    <span aria-live="polite">{{ open ? "已展开" : "已关闭" }}</span>
  </c-space>
</template>
```

## Async and dynamic data

### Async Action

click is a normal emitted event and supports async handlers. Business state controls loading; restore it in finally. Listener Promises do not automatically drive loading. Disabled/loading links have no effective href.

Example source: src/split-button/__demos__/async-action.vue

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

const completed = ref(0);
const publishing = ref(false)
const publish = async () => {
  if (publishing.value) return
  publishing.value = true
  try {
    await new Promise<void>((resolve) => setTimeout(resolve, 800))
    completed.value += 1
    Message.info('发布成功 / Published')
  } finally { publishing.value = false }
}
const handleSelect = (_value: unknown, option: { label?: unknown }) => {
  Message.info(String(option.label));
};
</script>

<template>
  <c-space direction="column" align="flex-start">
    <c-split-button :button-props="{ loading: publishing }" @click="publish" @select="handleSelect">
      发布

      <template #content>
        <c-menu-option label="保存草稿" value="draft" />
        <c-menu-option label="保存并发布" value="publish" />
        <c-menu-option label="暂无权限" value="restricted" disabled />
      </template>
    </c-split-button>
    <span aria-live="polite">完成次数: {{ completed }}</span>
  </c-space>
</template>
```

## Reading direction

The primary action sits at reading start and the menu button at reading end. Direction changes neither swap actions nor select a value. Enter/Space retains native button behavior. Up/Down opens the menu and skips disabled items; Home/End focuses boundaries, Enter selects and Escape closes and restores focus. Popovers inherit the reference direction; start/end alignment follows reading direction while explicit left/right remains physical. Downward slot graphics are not mirrored.

## API

### `<split-button>` Props

| Parameter | Description | Type | Default |
| -------------------- | ----------------------------------------- | ------------------------------------------------ | :-------: |
| open **(v-model)** | Whether the menu is open | `boolean` | `-` |
| default-open | Default menu open state in uncontrolled mode | `boolean` | `false` |
| disabled | Whether the entire split button is disabled | `boolean` | `false` |
| status | Button group semantic status | `SemanticStatus` | `default` |
| variant | Button group variant | `ButtonVariant` | `default` |
| size | Button group size | `ComponentSize` | `md` |
| color | Background color | `string` | `''` |
| text-color | Custom text color | `string` | `''` |
| elevation | Button group elevation | `boolean \| number` | `true` |
| button-props | Props for the primary button | `Partial<ButtonProps>` | `-` |
| trigger-button-props | Props for the menu trigger button | `Partial<ButtonProps>` | `-` |
| trigger | Menu trigger method | `'hover' \| 'click' \| 'focus' \| 'contextMenu'` | `click` |
| placement | Preferred popup side relative to the trigger, default bottom. With the default auto-fit-position enabled, Trigger may flip and constrain it to the viewport when space is limited; this is not a fixed final position | `MenuPlacement`: the standard twelve placements | `bottom` |
| popup-container | Menu mount container | `PopupContainer` | `-` |
| popup-max-height | Maximum menu height | `boolean \| number` | `true` |
| popup-class | Menu popup class | `string \| array \| object` | `-` |
| offset-x | Screen-horizontal offset; numbers are px, strings are converted as lengths | `string \| number` | `0` |
| offset-y | Screen-vertical offset; numbers are px, strings are converted as lengths | `string \| number` | `0` |
| hide-on-select | Close the menu after selection | `boolean` | `true` |

### `<split-button>` Events

| Event | Description | Arguments |
| ----------- | -------------------------- | -------------------- |
| update:open | Emitted when an open-state update is requested | open: `boolean` |
| open-change | Emitted when the menu open state changes | open: `boolean` |
| click | Emitted when the primary button is clicked | event: `MouseEvent` |
| select | Emitted when a menu option is selected | value, option, event |

### `<split-button>` Slots

| Slot | Description | Arguments |
| ------- | ---------------- | --------------- |
| default | Primary button content | - |
| icon | Menu trigger button icon | open: `boolean` |
| content | Menu content | - |

### Instance methods

| Method | Description |
| -------- | -------------------------- |
| open() | Request menu opening; disabled prevents it |
| close() | Request menu closing |
| resize() | Recalculate menu position |

Controlled `open` emits update requests only; callers must update it. Main-button clicks bubble normally without opening the menu.

Like Button, `click` is a Promise-consuming `onClick` callback prop supporting `@click`, not a second emitted notification. If `button-props.onClick` is also supplied, each handler runs once.

Both platforms independently copy bodies, props, style dependency entries and contract tests. Cedar adapts positioning through Menu without shared instances/runtime.

## Type definitions

```ts
import type { SplitButtonInstance, SplitButtonProps } from '@cedar-design/ui'
```


### Placement semantics and configuration

The menu side passes through the internal Menu placement to Trigger and uses MenuPlacement, without a second positioning entry.

---

Document: llms/en-US/components/split.md

<!-- Source: src/split/README.en-US.md; locale: en-US; page: /en/components/split/ -->

# Split

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

- `size`: The size of the segmentation, it can be 0~1 representing a percentage, or a specific number of pixels, such as 300px
- `min`: Minimum threshold, it can be 0~1 representing a percentage, or a specific number of pixels, such as 300px

Example source: src/split/__demos__/basic.vue

```vue
<template>
  <div>
    <c-split
      :style="{
        height: '200px',
        width: '100%',
        minWidth: '500px',
        border: '1px solid var(--c-color-border-2)',
      }"
      v-model:size="size"
      min="80px"
    >
      <template #first>
        <c-typography-paragraph>Left</c-typography-paragraph>
      </template>
      <template #second>
        <c-typography-paragraph>Right</c-typography-paragraph>
      </template>
    </c-split>
  </div>
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const size = ref(0.5)
</script>
```

## Layout and arrangement

### Nested

- `orientation`: Direction of division

Example source: src/split/__demos__/nested.vue

```vue
<template>
  <div>
    <c-split
      :style="{
        height: '200px',
        width: '100%',
        minWidth: '500px',
        border: '1px solid var(--color-border)',
      }"
    >
      <template #first>
        <c-typography-paragraph>Left</c-typography-paragraph>
      </template>
      <template #second>
        <div>
          <c-split orientation="vertical" :style="{ height: '200px' }">
            <template #first>
              <c-typography-paragraph>Top</c-typography-paragraph>
            </template>
            <template #second>
              <c-typography-paragraph>Bottom</c-typography-paragraph>
            </template>
          </c-split>
        </div>
      </template>
    </c-split>
  </div>
</template>

<script lang="ts" setup>
</script>
```

## API

### `<split>` Props

| Parameter | Description | Type | Default |
| ------------------ | ----------------------------------------------------------------- | ---------------------------- | :------------: |
| component | The html tag of the split box | `string` | `'div'` |
| orientation | Arrangement axis of the two panels: horizontal by default means left/right panels, whose divider handle is vertical | `'horizontal' \| 'vertical'` | `'horizontal'` |
| size **(v-model)** | The size of the segmentation, it can be 0~1 representing a percentage, or a specific number of pixels, such as 300px | `number\|string` | `-` |
| default-size | Default split size, it can be 0~1 representing a percentage, or a specific number of pixels, such as 300px | `number\|string` | `0.5` |
| min | Minimum threshold, it can be 0~1 representing a percentage, or a specific number of pixels, such as 300px | `number\|string` | `-` |
| max | Maximum threshold, it can be 0~1 representing a percentage, or a specific number of pixels, such as 300px | `number\|string` | `-` |
| disabled | Whether disabled | `boolean` | `false` |

### `<split>` Events

| Event | Description | Arguments |
| ---------- | ---------------- | ---- |
| move-start | Emitted before dragging starts | - |
| moving | Emitted during dragging | - |
| move-end | Emitted after dragging ends | - |

### `<split>` Slots

| Slot | Description | Arguments |
| ------------------- | :--------------: | ---- |
| first | First panel content | - |
| resize-trigger | Resize-handle content | - |
| resize-trigger-icon | Resize-handle icon | - |
| second | Second panel content | - |

### Type definitions

The component exports the following types

```ts
import type { SplitInstance } from '@cedar-design/ui'
```

`--c-split-trigger-size-icon-wrapper` (default 6px) controls handle thickness: width for vertical handles, height for horizontal handles. It does not change their 100% length along the panel.


## Reading direction and interaction

Split inherits the nearest native dir. Size and bounds always describe the first pane, preserving ratio or pixel units. In RTL, dragging left grows the first horizontal pane; vertical movement is unchanged. Focused separators support arrows, Shift, Home and End. Direction/orientation changes, disablement and teardown cancel gestures and restore the cursor without changing the size merely because direction changed.

---

Document: llms/en-US/components/statistic.md

<!-- Source: src/statistic/README.en-US.md; locale: en-US; page: /en/components/statistic/ -->

# Statistic

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

Preview configuration: `title="Downloads"`, `:value="125670"`, `show-group-separator`, `title="Comments"`.

Example source: src/statistic/__demos__/basic.vue

```vue
<template>
  <c-space size="xl" wrap>
    <c-statistic title="Downloads" :value="125670" show-group-separator />
    <c-statistic title="Comments" extra="Compared to yesterday" :value="40509" :precision="2" />
    <c-statistic title="Active Users" value="1.28k" />
  </c-space>
</template>
```

## Content and presentation

### Tabular Nums

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `title` | Displayed-value title | Tabular Nums, Extra, Animation |
| `value` | Displayed value | Tabular Nums, Extra, Animation |
| `suffix` | Value suffix | Tabular Nums |
| `value-style` | Custom style of the value | Tabular Nums |
| `tabular-nums` | Use tabular digits to prevent width changes as values update | Tabular Nums |
| `prefix` | Value prefix | Extra |
<!-- demo-config-notes:end -->


Preview configuration: `title="比例数字（右侧标记会跳动）"`, `:value="count"`, `suffix="\|"`, `:value-style="{ fontVariantNumeric: 'proportional-nums' }"`.

Example source: src/statistic/__demos__/tabular-nums.vue

```vue
<template>
  <c-space size="xl" wrap>
    <c-statistic
      title="比例数字（右侧标记会跳动）"
      :value="count"
      suffix="|"
      :value-style="{ fontVariantNumeric: 'proportional-nums' }"
    />
    <c-statistic title="等宽数字（右侧标记保持稳定）" :value="count" suffix="|" tabular-nums />
  </c-space>
</template>

<script lang="ts" setup>
import { onBeforeUnmount, onMounted, ref } from 'vue'

const values = [1111, 8888, 1010, 9090]
const index = ref(0)
const count = ref(values[0])
let timer = 0

onMounted(() => {
  timer = window.setInterval(() => {
    index.value = (index.value + 1) % values.length
    count.value = values[index.value]
  }, 800)
})

onBeforeUnmount(() => {
  window.clearInterval(timer)
})
</script>
```

### Extra

Preview configuration: `title="Revenue"`, `:value="9280"`, `prefix="$"`, `show-group-separator`.

Example source: src/statistic/__demos__/extra.vue

```vue
<template>
  <c-space size="xl" wrap>
    <c-statistic title="Revenue" :value="9280" prefix="$" show-group-separator extra="Compared to yesterday +12.8%" />
    <c-statistic title="New Users" :value="1280" show-group-separator>
      <template #extra>
        <span style="color: var(--c-color-success)">较上周 +8.4%</span>
      </template>
    </c-statistic>
  </c-space>
</template>
```

### Animation

Preview configuration: `title="Growth Rate"`, `:value="50.52"`, `:precision="2"`, `:value-from="0"`.

Example source: src/statistic/__demos__/animation.vue

```vue
<template>
  <c-space size="xl" align="flex-end" wrap>
    <c-statistic
      title="Growth Rate"
      :value="50.52"
      :precision="2"
      :value-from="0"
      :start="started"
      animation
    >
      <template #prefix>
        <IconArrowRise />
      </template>
      <template #suffix>%</template>
    </c-statistic>
    <c-button status="primary" @click="started = true">Start</c-button>
  </c-space>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import { IconArrowRise } from '@cedar-design/icons-vue'

const started = ref(false)
</script>
```

### Statistic

Preview configuration: `title="Countdown"`, `:time="2 * 60 * 60 * 1000"`, `title="Campaign"`, `:time="4 * 24 * 60 * 60 * 1000"`.

Example source: src/countdown/__demos__/statistic.vue

```vue
<template>
  <c-space size="xl" wrap>
    <c-statistic title="Countdown">
      <c-countdown :time="2 * 60 * 60 * 1000" />
    </c-statistic>
    <c-statistic title="Campaign">
      <c-countdown :time="4 * 24 * 60 * 60 * 1000" format="DD 天 HH 时 mm 分 ss 秒" />
    </c-statistic>
  </c-space>
</template>
```

## Customization and slots

### Prefix Suffix

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `title` | Displayed-value title | Prefix Suffix, Count To |
| `suffix` | Value suffix | Prefix Suffix, Count To |
| `value` | Displayed value | Prefix Suffix |
| `prefix` | Value prefix | Prefix Suffix |
| `show-group-separator` | Whether to show the group separator | Prefix Suffix |
| `precision` | Decimal places (number mode) | Prefix Suffix |
<!-- demo-config-notes:end -->


Preview configuration: `title="Account Balance"`, `:value="125670"`, `prefix="$"`, `show-group-separator`.

Example source: src/statistic/__demos__/prefix-suffix.vue

```vue
<template>
  <c-space size="xl" wrap>
    <c-statistic title="Account Balance" :value="125670" prefix="$" show-group-separator />
    <c-statistic title="Growth Rate" :value="12.8" :precision="1" suffix="%" :value-style="{ color: 'var(--c-color-success)' }">
      <template #prefix>
        <IconArrowRise />
      </template>
    </c-statistic>
    <c-statistic title="Bounce Rate" :value="3.2" :precision="1" suffix="%" :value-style="{ color: 'var(--c-color-danger)' }">
      <template #prefix>
        <IconArrowFall />
      </template>
    </c-statistic>
  </c-space>
</template>

<script lang="ts" setup>
import { IconArrowFall, IconArrowRise } from '@cedar-design/icons-vue'
</script>
```

### Count To

Preview configuration: `title="Active Users"`, `:from="0"`, `:to="125670"`, `:duration="2000"`.

Example source: src/statistic/__demos__/count-to.vue

```vue
<template>
  <c-space size="xl" wrap>
    <c-statistic title="Active Users">
      <c-count-to :from="0" :to="125670" :duration="2000" />
    </c-statistic>
    <c-statistic title="Conversion Rate" suffix="%">
      <c-count-to :from="0" :to="36.8" :duration="2000" :precision="1" />
    </c-statistic>
  </c-space>
</template>
```

## API

### `<Statistic>` Props

| Prop | Description | Type | Default |
| ---------------------- | -------------------------------------------------------------- | ------------------------- | ------------ |
| `title` | Displayed-value title | `string` | - |
| `value` | Displayed value | `number \| string \| Date` | - |
| `prefix` | Value prefix | `string` | - |
| `suffix` | Value suffix | `string` | - |
| `format` | Date format (date mode) | `string` | `'HH:mm:ss'` |
| `extra` | Extra content | `string` | - |
| `start` | Whether to start the animation | `boolean` | `true` |
| `precision` | Decimal places (number mode) | `number` | `0` |
| `separator` | Group separator (number mode) | `string` | - |
| `show-group-separator` | Whether to show the group separator | `boolean` | `false` |
| `tabular-nums` | Use tabular digits to prevent width changes as values update | `boolean` | `false` |
| `animation` | Whether to enable animation | `boolean` | `false` |
| `animation-duration` | Animation duration | `number` | `2000` |
| `value-from` | Animation start value | `number` | - |
| `placeholder` | Placeholder when `value` is `undefined` and the default slot is unused | `string` | - |
| `value-style` | Custom style of the value | `CSSProperties` | - |

### `<Statistic>` Slots

| Slot | Description | Arguments |
| --------- | ---------------------------------------- | ---- |
| `default` | Custom `value`, used when `value` is not provided | `-` |
| `title` | Title | `-` |
| `prefix` | The prepend icon of alert | `-` |
| `suffix` | Suffix | `-` |
| `extra` | Extra content | `-` |

### Type definitions

The component exports the following types

```ts
import type { StatisticProps } from '@cedar-design/ui'
```

### Style variables

| Variable | Default |
| --- | --- |
| `--c-statistic-title-color` | `var(--c-sys-color-content-secondary)` |
| `--c-statistic-title-font-size` | `var(--c-font-size-body-3)` |
| `--c-statistic-title-margin-bottom` | `var(--c-spacing-4)` |
| `--c-statistic-value-color` | `var(--c-sys-color-content-primary)` |
| `--c-statistic-value-font-size` | `26px` |
| `--c-statistic-value-font-weight` | `var(--c-font-weight-500)` |
| `--c-statistic-decimal-font-size` | `inherit` |
| `--c-statistic-prefix-color` | `var(--c-sys-color-content-secondary)` |
| `--c-statistic-prefix-font-size` | `14px` |
| `--c-statistic-prefix-spacing` | `var(--c-spacing-1)` |
| `--c-statistic-suffix-color` | `var(--c-sys-color-content-secondary)` |
| `--c-statistic-suffix-font-size` | `14px` |
| `--c-statistic-suffix-spacing` | `var(--c-spacing-1)` |
| `--c-statistic-extra-color` | `var(--c-sys-color-content-secondary)` |
| `--c-statistic-extra-font-size` | `var(--c-font-size-body-3)` |
| `--c-statistic-extra-margin-top` | `var(--c-spacing-4)` |

## Shared implementation and platform boundaries

Each platform maintains a complete local implementation. They do not import a common core or share component instances or reactive state. Changes must update both implementations. Component bodies, props, key styles and paired tests have read-only source consistency checks; theme tokens and installation entries remain local to each library.

Placeholder text updates when the default slot appears/disappears. Animation pauses on unmount/KeepAlive deactivation.

---

Document: llms/en-US/components/steps.md

<!-- Source: src/steps/README.en-US.md; locale: en-US; page: /en/components/steps/ -->

# Steps

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

- `status`: Selects the semantic state.

Example source: src/steps/__demos__/basic.vue

```vue
<template>
  <c-radio-group v-model="currentStatus" variant="button" style="margin-bottom: 16px">
    <c-radio v-for="status in statuses" :key="status" :value="status">{{ status }}</c-radio>
  </c-radio-group>
  <c-steps :status="currentStatus">
    <c-step description="This is a description">Succeeded</c-step>
    <c-step description="This is a description">Processing</c-step>
    <c-step description="This is a description">Pending</c-step>
  </c-steps>
</template>
<script setup lang="ts">
import { ref } from 'vue'

const statuses = ['wait', 'process', 'finish', 'error'] as const
const currentStatus = ref<(typeof statuses)[number]>('process')
</script>
```

## Appearance and states

### Appearance Lab

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `type` | Steps appearance type | Step types and states |
| `status` | Current step status | Step types and states |
| `changeable` | Whether clicking can change steps | Step types and states |
<!-- demo-config-notes:end -->


Preview configuration: `layout="vertical"`, `aria-label="status"`, `options`, `variant="button"`.

Example source: src/steps/__demos__/appearance-lab.vue

```vue
<script setup lang="ts">
import { reactive as __demoReactive } from "vue";
const __demoAppearance = __demoReactive({ status: "wait", size: "md" });

import { computed as demoComputed, ref as demoRef } from 'vue'
const demoCompareFields = [{"name":"status","values":["wait","process","finish","error"]},{"name":"size","values":["sm","md"]}]
const demoCompareAxis = demoRef("status")
const demoComparedOptions = demoComputed(() => demoCompareFields.find(field => field.name === demoCompareAxis.value)?.values ?? [])
</script>
<template>
  <c-space direction="column" :size="16">
    <c-form layout="vertical">
      <c-form-item layout="vertical" size="sm" label="status">
        <c-radio-group
          v-model="__demoAppearance['status']"
          aria-label="status"
          :options="[
            { label: 'wait', value: 'wait' },
            { label: 'process', value: 'process' },
            { label: 'finish', value: 'finish' },
            { label: 'error', value: 'error' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
      <c-form-item layout="vertical" size="sm" label="size">
        <c-radio-group
          v-model="__demoAppearance['size']"
          aria-label="size"
          :options="[
            { label: 'sm', value: 'sm' },
            { label: 'md', value: 'md' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
    </c-form>
    <p class="demo-config-comparison-hint"><span lang="zh-CN">选择一个对比维度；其他配置和内容保持一致。输入类示例共享同一个值，便于比较外观。</span><span lang="en-US">Compare one dimension while keeping the other settings and content identical. Input specimens share the same value.</span></p>
<c-radio-group v-model="demoCompareAxis" aria-label="Compare configuration" :options="demoCompareFields.map(field => ({ label: field.name, value: field.name }))" />
<div class="demo-config-comparison">
<section v-for="sample in demoComparedOptions" :key="String(sample)">
<p><code>{{ demoCompareAxis }}={{ sample }}</code></p>
<c-steps :model-value="2" v-bind="{ ...__demoAppearance, [demoCompareAxis]: sample }">
      <c-step>Succeeded</c-step>
      <c-step>Processing</c-step>
      <c-step>Pending</c-step>
    </c-steps>
</section>
</div>
  </c-space>
</template>

<style scoped>
.demo-config-comparison { display: grid; grid-template-columns: repeat(auto-fit, minmax(min(100%, 220px), 1fr)); gap: 20px; min-width: 0; max-width: 100%; }
.demo-config-comparison > section { min-width: 0; }
.demo-config-comparison p { margin: 0 0 8px; }
html:not([lang='en-US']) .demo-config-comparison-hint > [lang='en-US'],
html[lang='en-US'] .demo-config-comparison-hint > [lang='zh-CN'] { display: none; }
</style>
```

### Step types and states

All four types share one current-step and status model. Click a step or select 1–3, then choose wait, process, finish or error: default, arrow, dot and navigation update together. Status changes the current node’s semantic state without changing its index. Titles and descriptions follow the page language to fit the phone preview.

<details>
<summary>Configuration details and limits</summary>

#### Types

Preview configuration: `aria-label="Current step"`, `options`, `variant="button"`, `size="sm"`.

#### Error

- `status`: Selects the semantic state.

#### Arrow

- `status`: Selects the semantic state.

#### Dot

- `status`: Selects the semantic state.

#### Navigation

- `status`: Selects the semantic state.

</details>

Example source: src/steps/__demos__/types.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import type { StepsType } from "@cedar-design/ui";

const current = ref(2)
const statuses = ['wait', 'process', 'finish', 'error'] as const
const status = ref<(typeof statuses)[number]>('process')
const types: StepsType[] = ["default", "arrow", "dot", "navigation"];
</script>

<template>
  <section class="step-type-comparison">
    <c-form-item layout="vertical" size="sm" label="Current step">
      <c-radio-group
        v-model="current"
        aria-label="Current step"
        :options="[
          { label: '1', value: 1 },
          { label: '2', value: 2 },
          { label: '3', value: 3 },
        ]"
        variant="button"
        size="sm"
      />
    </c-form-item>
    <c-form-item layout="vertical" size="sm" label="Status"><c-radio-group v-model="status" aria-label="Step status" :options="statuses.map(value => ({ label: value, value }))" /></c-form-item>
    <p>
      点击步骤或选择序号，对比同一进度的四种外观。Click a step to compare the
      same progress.
    </p>
    <section v-for="type in types" :key="type" :data-step-type="type">
      <p>
        <code>{{ type }}</code>
      </p>
      <c-steps v-model="current" :type="type" :status="status" changeable>
        <c-step><span lang="zh-CN">提交</span><span lang="en-US">Submit</span><template #description><span lang="zh-CN">提交信息</span><span lang="en-US">Details</span></template></c-step>
        <c-step><span lang="zh-CN">审核</span><span lang="en-US">Review</span><template #description><span lang="zh-CN">审核信息</span><span lang="en-US">Review</span></template></c-step>
        <c-step><span lang="zh-CN">完成</span><span lang="en-US">Done</span><template #description><span lang="zh-CN">完成信息</span><span lang="en-US">Complete</span></template></c-step>
      </c-steps>
    </section>
  </section>
</template>

<style scoped>
html:not([lang='en-US']) .step-type-comparison [lang='en-US'],
html[lang='en-US'] .step-type-comparison [lang='zh-CN'] { display: none; }
</style>
```

## Layout and arrangement

### Content Placement

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `status` | Current step status | Content Placement, Vertical |
| `content-placement` | Content side relative to the step node: right or bottom, default right. Dot steps derive it from orientation; navigation steps always use right | Content Placement |
| `orientation` | Horizontal/vertical axis of the step flow, default horizontal; arrow and navigation variants remain horizontal | Vertical |
<!-- demo-config-notes:end -->


- `status`: Selects the semantic state.

Example source: src/steps/__demos__/content-placement.vue

```vue
<template>
  <c-radio-group v-model="currentStatus" variant="button" style="margin-bottom: 16px">
    <c-radio v-for="status in statuses" :key="status" :value="status">{{ status }}</c-radio>
  </c-radio-group>
  <c-steps content-placement="bottom" :status="currentStatus">
    <c-step description="This is a description">Succeeded</c-step>
    <c-step description="This is a description">Processing</c-step>
    <c-step description="This is a description">Pending</c-step>
  </c-steps>
</template>
<script setup lang="ts">
import { ref } from 'vue'

const statuses = ['wait', 'process', 'finish', 'error'] as const
const currentStatus = ref<(typeof statuses)[number]>('process')
</script>
```

### Vertical

- `status`: Selects the semantic state.

Example source: src/steps/__demos__/vertical.vue

```vue
<template>
  <div class="frame-bg">
    <c-radio-group v-model="currentStatus" variant="button" style="margin-bottom: 16px">
      <c-radio v-for="status in statuses" :key="status" :value="status">{{ status }}</c-radio>
    </c-radio-group>
    <div class="frame-body">
      <div class="frame-aside">
        <c-steps :model-value="current" :status="currentStatus" orientation="vertical">
          <c-step>Succeeded</c-step>
          <c-step>Processing</c-step>
          <c-step>Pending</c-step>
        </c-steps>
      </div>
      <div class="frame-main">
        <div class="main-content">The content of this step.</div>
        <div class="main-bottom">
          <c-button :disabled="current === 1" @click="onPrev">
            <c-icon-left />
            Back
          </c-button>
          <c-button :disabled="current === 3" @click="onNext">
            Next
            <c-icon-right />
          </c-button>
        </div>
      </div>
    </div>
  </div>
</template>
<script lang="ts">
import { ref } from 'vue'

export default {
  setup() {
    const current = ref(1)
    const statuses = ['wait', 'process', 'finish', 'error'] as const
    const currentStatus = ref<(typeof statuses)[number]>('process')

    const onPrev = () => {
      current.value = Math.max(1, current.value - 1)
    }

    const onNext = () => {
      current.value = Math.min(3, current.value + 1)
    }

    return {
      current,
      statuses,
      currentStatus,
      onPrev,
      onNext,
    }
  },
}
</script>
```

## Content and presentation

### Description

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `status` | Current step status | Description, Line Less |
| `show-line` | Whether to show connectors | Line Less |
<!-- demo-config-notes:end -->


- `status`: Selects the semantic state.

Example source: src/steps/__demos__/description.vue

```vue
<template>
  <c-radio-group
    v-model="currentStatus"
    variant="button"
    style="margin-bottom: 16px"
  >
    <c-radio v-for="status in statuses" :key="status" :value="status">{{
      status
    }}</c-radio>
  </c-radio-group>
  <c-steps :model-value="2" :status="currentStatus">
    <c-step>Succeeded</c-step>
    <c-step>Processing</c-step>
    <c-step>Pending</c-step>
  </c-steps>
  <c-divider />
  <div style="line-height: 140px; color: #c9cdd4; text-align: center">
    Step 2 Content
  </div>
</template>
<script setup lang="ts">
import { ref } from "vue";

const statuses = ["wait", "process", "finish", "error"] as const;
const currentStatus = ref<(typeof statuses)[number]>("process");
</script>
```

### Line Less

- `status`: Selects the semantic state.

Example source: src/steps/__demos__/line-less.vue

```vue
<template>
  <c-radio-group v-model="currentStatus" variant="button" style="margin-bottom: 16px">
    <c-radio v-for="status in statuses" :key="status" :value="status">{{ status }}</c-radio>
  </c-radio-group>
  <c-steps :model-value="2" :status="currentStatus" :show-line="false">
    <c-step description="This is a description">Succeeded</c-step>
    <c-step description="This is a description">Processing</c-step>
    <c-step description="This is a description">Pending</c-step>
  </c-steps>
</template>
<script setup lang="ts">
import { ref } from 'vue'

const statuses = ['wait', 'process', 'finish', 'error'] as const
const currentStatus = ref<(typeof statuses)[number]>('process')
</script>
```

## Customization and slots

### Custom Icon

- `status`: Selects the semantic state.

Example source: src/steps/__demos__/custom-icon.vue

```vue
<template>
  <c-radio-group v-model="currentStatus" variant="button" style="margin-bottom: 16px">
    <c-radio v-for="status in statuses" :key="status" :value="status">{{ status }}</c-radio>
  </c-radio-group>
  <c-steps :status="currentStatus">
    <c-step description="This is a description">
      Succeeded
      <template #icon>
        <c-icon-home />
      </template>
    </c-step>
    <c-step description="This is a description">
      Processing
      <template #icon>
        <c-icon-loading />
      </template>
    </c-step>
    <c-step description="This is a description">
      Pending
      <template #icon>
        <c-icon-thumb-up />
      </template>
    </c-step>
  </c-steps>
</template>
<script setup lang="ts">
import { ref } from 'vue'

const statuses = ['wait', 'process', 'finish', 'error'] as const
const currentStatus = ref<(typeof statuses)[number]>('process')
</script>
```

## Interaction and control

### Changeable

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `changeable` | Whether clicking can change steps | Changeable |
| `status` | Current step status | Changeable |
<!-- demo-config-notes:end -->


- `status`: Selects the semantic state.

Example source: src/steps/__demos__/changeable.vue

```vue
<template>
  <div>
    <c-radio-group v-model="currentStatus" variant="button" style="margin-bottom: 16px">
      <c-radio v-for="status in statuses" :key="status" :value="status">{{ status }}</c-radio>
    </c-radio-group>
    <c-steps changeable :model-value="current" :status="currentStatus" @change="setCurrent">
      <c-step description="This is a description">Succeeded</c-step>
      <c-step description="This is a description">Processing</c-step>
      <c-step description="This is a description">Pending</c-step>
    </c-steps>
    <div
      :style="{
        width: '100%',
        height: '200px',
        textAlign: 'center',
        background: 'var(--color-bg-2)',
        color: '#C2C7CC',
      }"
    >
      <div style="line-height: 160px">Step{{ current }} Content</div>
      <c-space size="lg">
        <c-button status="secondary" :disabled="current <= 1" @click="onPrev">
          <c-icon-left />
          Back
        </c-button>
        <c-button status="primary" :disabled="current >= 3" @click="onNext">
          Next
          <c-icon-right />
        </c-button>
      </c-space>
    </div>
  </div>
</template>
<script lang="ts">
import { ref } from 'vue'

export default {
  setup() {
    const current = ref(1)
    const statuses = ['wait', 'process', 'finish', 'error'] as const
    const currentStatus = ref<(typeof statuses)[number]>('process')
    const onPrev = () => {
      current.value = Math.max(1, current.value - 1)
    }
    const onNext = () => {
      current.value = Math.min(3, current.value + 1)
    }

    const setCurrent = (step: number) => {
      current.value = step
    }

    return {
      current,
      statuses,
      currentStatus,
      onPrev,
      onNext,
      setCurrent,
    }
  },
}
</script>
```

## API

Use ordinary `v-model`. `modelValue` is the current step, starting at 1. `defaultValue` initializes uncontrolled state once; later changes do not reset it. Initialization emits no `update:modelValue`. When supplied, `modelValue` is controlled by the parent.

### Steps Props

| Prop | Description | Type | Default |
| -------------------- | ------------------------ | ----------------------------------------------------- | -------------- |
| type | Steps appearance type | `'default'` \| `'arrow'` \| `'dot'` \| `'navigation'` | `'default'` |
| orientation | Horizontal/vertical axis of the step flow, default horizontal; arrow and navigation variants remain horizontal | `'horizontal'` \| `'vertical'` | `'horizontal'` |
| content-placement | Content side relative to the step node: right or bottom, default right. Dot steps derive it from orientation; navigation steps always use right | `'right'` \| `'bottom'` | `'right'` |
| model-value(**v-model**) | Current step number | `number` | `-` |
| default-value | Default uncontrolled step number | `number` | `1` |
| status | Current step status | `'wait'` \| `'process'` \| `'finish'` \| `'error'` | `'process'` |
| show-line | Whether to show connectors | `boolean` | `true` |
| size | Steps size | `'sm'` \| `'md'` | `'md'` |
| changeable | Whether clicking can change steps | `boolean` | `false` |

### Steps Events

| Event | Description | Arguments |
| ------------------- | ------------------------------ | ---------------------------- |
| change | Emitted when the step number changes; requires `changeable` | current:`number`<br/>previous:`number`<br/>ev:`Event` |
| update:modelValue | `v-model` sync | step:`number` |

### Steps Slots

| Slot | Description |
| ----------- | ------------ |
| default | Step content |
| finish-icon | Finished status icon |
| error-icon | Error status icon |

### Step Props

| Prop | Description | Type | Default |
| ----------- | ------------ | -------------------------------------------------- | ------- |
| title | Step title | `string` | `-` |
| description | Step description | `string` | `-` |
| status | Step status | `'wait'` \| `'process'` \| `'finish'` \| `'error'` | `-` |
| disabled | Whether the step is disabled | `boolean` | `false` |

### Step Slots

| Slot | Description | Arguments |
| ----------- | ---- | --------------------------------- |
| default | Title | `index`、`status`、`active`、`disabled` |
| title | Title | `index`、`status`、`active`、`disabled` |
| node | Node | `index`、`status`、`active`、`disabled` |
| icon | Icon | `index`、`status`、`active`、`disabled` |
| description | Description | `index`、`status`、`active`、`disabled` |

## Type definitions

The component exports the following types

```ts
import type {
  StepsProps,
  StepProps,
  StepsType,
  StepStatus,
  StepsSize,
  StepsContentPlacement,
  StepsInstance,
  StepsStepInstance,
} from '@cedar-design/ui'
```

## Shared implementation and platform boundaries

Each platform maintains a complete local implementation. They do not import a common core or share component instances or reactive state. Changes must update both implementations. Component bodies, props, key styles and paired tests have read-only source consistency checks; theme tokens and installation entries remain local to each library.

Steps/Step bodies, props, context protocol and styles are source copies. Injection Symbols are defined separately per library, not shared. The four types and existing status/event contracts remain.

`active` indicates only whether the current one-based step index matches modelValue, independently of wait/process/finish/error status. A current error step remains `active`. Focus/hover do not change `active`.


### Placement semantics and configuration

content-placement shares side vocabulary and spelling, not an identical set across all components. Steps implements only right/bottom; dot and navigation variants have derived rules. Unsupported sides are not added for naming uniformity.


## Reading direction and keyboard interaction

Steps inherits the nearest native `dir` and supports live changes. Horizontal layout and directional geometry follow reading order; vertical progression stays top to bottom. With `changeable`, arrow keys move focus, Home/End reach the first/last enabled step, and Enter/Space activate it. Focus navigation and direction changes do not update progress.

---

Document: llms/en-US/components/style-provider.md

<!-- Source: src/style-provider/README.en-US.md; locale: en-US; page: /en/components/style-provider/ -->

# Style Provider

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

Preview configuration: `tag="section"`, `:style-vars="active ? { '--c-demo-color': 'teal' } : null"`, `:style-vars="{ '--c-demo-color': 'coral' }"`.

Example source: src/style-provider/__demos__/basic.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'

const active = ref(true)
</script>

<template>
  <div>
    <c-button variant="outline" @click="active = !active">切换局部变量 / Toggle local variables</c-button>
    <c-style-provider tag="section" :style-vars="active ? { '--c-demo-color': 'teal' } : null">
      <p style="color: var(--c-demo-color, currentColor)">局部颜色 / Local color</p>
      <c-style-provider :style-vars="{ '--c-demo-color': 'coral' }">
        <p style="color: var(--c-demo-color)">嵌套覆盖 / Nested override</p>
      </c-style-provider>
    </c-style-provider>
    <p>外部不受影响 / Outside remains unchanged</p>
  </div>
</template>
```

## Global calls

```ts
import { StyleProvider, Themes } from '@cedar-design/ui'

StyleProvider.setStyleVars(Themes.default.dark)
StyleProvider.setStyleVars(Themes.maple.light)
StyleProvider.setStyleVars(null)
```

Each call replaces previous injected values rather than merging cumulatively. Values already equal to base styles are not written again.
`dark` sets `html[cedar-theme="dark"]`; `light` removes it. Without color-scheme, existing theme attributes remain. `null` removes this library's injection/theme attributes without affecting the other library. SSR calls have no side effects.

Variables accept full CSS names or camelCase such as `cColorScheme`. Library prefixes are not added automatically. Prefer full `--c-*` names.

## Installation and defaults

```ts
import { StyleProvider } from '@cedar-design/ui'

app.use(StyleProvider)

StyleProvider.setPropsDefaults({
  tag: 'section',
  styleVars: () => ({ '--c-demo-color': 'teal' }),
})
```

Set defaults during initialization before mounting; mounted instances are not retroactively updated. Explicit props take precedence. Object defaults are copied per instance; factories/`null` are supported. Defaults are local to each library, not shared.
Installation always registers `CStyleProvider` without modifying app global config. For aliases, use `app.component('MyStyleProvider', StyleProvider)`.

## API

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| `style-vars` | Local CSS variables; null clears local overrides | `Record<string, string> \| null` | `{}` |
| `tag` | Wrapper tag | `string` | `div` |

The default slot supplies component content. No events.

## Type definitions

Exports `StyleVars`, `StyleProviderProps`, `StyleProviderDefaults` and `StyleProviderInstance`. `StyleProvider` is the only public component entry; `styleProviderProps` and resolver-facing `_StyleProviderComponent` are also exported.

No component-specific theme tokens. Variable values are strings; numeric dimensions should be unit-bearing strings.

---

Document: llms/en-US/components/style/atomic-css.md

<!-- Source: src/style/atomic-css/README.en-US.md; locale: en-US; page: /en/components/style/atomic-css/ -->

# Style Atomic Css

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Starter

Example source: src/style/atomic-css/__demos__/starter.vue

```vue
<template>
  <div class="starter-card">
    <div class="starter-title">第一张原子化卡片</div>
    <div class="starter-description">
      组合小类完成布局，不需要另外写组件样式。
    </div>

    <div class="starter-row">
      <span class="starter-tag">c-flex c-items-center c-gap-8</span>
      <span class="starter-status">Success</span>
    </div>

    <c-button class="starter-button"
      >c-bg-primary · hover:c-opacity-80</c-button
    >
  </div>
</template>

<style scoped>
/* 文档站的等价视觉预览；业务项目中的样式由 UnoCSS 或 Tailwind 生成。 */
.starter-card {
  display: flex;
  flex-direction: column;
  gap: 12px;
  max-width: 420px;
  padding: 16px;
  border: 1px solid var(--c-color-border-2);
  border-radius: 8px;
  background: var(--c-color-body);
}

.starter-title {
  color: var(--c-color-primary);
  font-size: var(--c-font-size-lg);
  font-weight: 600;
}

.starter-description {
  color: var(--c-color-text-3);
}

.starter-row {
  display: flex;
  align-items: center;
  justify-content: space-between;
  gap: 8px;
  padding: 12px;
  border-radius: 6px;
  background: var(--c-color-fill-2);
}

.starter-tag {
  color: var(--c-color-text-2);
  font-family: monospace;
  font-size: 12px;
}

.starter-status {
  color: var(--c-color-success);
}

.starter-button {
  padding: 8px 16px;
  border: 0;
  border-radius: 6px;
  color: #fff;
  background: var(--c-color-primary);
  cursor: pointer;
  transition: opacity 0.2s;
}

.starter-button:hover {
  opacity: 0.8;
}
</style>
```

### Overview

Preview configuration: `:columns="columns"`, `:data="data"`, `:pagination="false"`.

Example source: src/style/atomic-css/__demos__/overview.vue

```vue
<template>
  <c-space direction="column" block size="md">
    <c-alert status="info">
      Preset 在构建期注入主题；固定工具类是现成 CSS。二者可同时使用。
    </c-alert>
    <c-table :columns="columns" :data="data" :pagination="false" />
  </c-space>
</template>

<script lang="ts" setup>
const columns = [
  { title: "能力", dataIndex: "kind" },
  { title: "例子", dataIndex: "example" },
  { title: "说明", dataIndex: "note" },
];

const data = [
  {
    kind: "Preset 颜色",
    example: "c-bg-primary / c-text-success",
    note: "需配置 @cedar-design/preset-*",
  },
  {
    kind: "Preset 字号",
    example: "c-text-xs / c-text-lg",
    note: "挂 --c-font-size-*",
  },
  {
    kind: "Preset 断点",
    example: "sm: / md: / lg: / xl:",
    note: "数值与设计对齐",
  },
  {
    kind: "固定 Utilities",
    example: "c-text-1 / c-fill-1",
    note: "utilities 语义色，不经 Uno/TW",
  },
];
</script>
```

## Colors, typography and spacing

### Colors

Example source: src/style/atomic-css/__demos__/colors.vue

```vue
<template>
  <c-space direction="column" fill size="lg">
    <div>
      <div class="label">背景 c-bg-*</div>
      <div class="row">
        <div
          v-for="item in bgItems"
          :key="item.cls"
          class="swatch"
          :style="item.style"
        >
          <code>{{ item.cls }}</code>
        </div>
      </div>
    </div>
    <div>
      <div class="label">文字 c-text-*</div>
      <div class="row text-row">
        <span
          v-for="item in textItems"
          :key="item.cls"
          class="text-chip"
          :style="item.style"
        >
          {{ item.cls }}
        </span>
      </div>
    </div>
    <div>
      <div class="label">边框 c-border-*</div>
      <div class="row">
        <div
          v-for="item in borderItems"
          :key="item.cls"
          class="border-chip"
          :style="item.style"
        >
          <code>{{ item.cls }}</code>
        </div>
      </div>
    </div>
  </c-space>
</template>

<script lang="ts" setup>
const bgItems = [
  {
    cls: "c-bg-body",
    style: {
      background: "var(--c-color-body)",
      color: "var(--c-color-text-1)",
    },
  },
  {
    cls: "c-bg-primary",
    style: { background: "var(--c-color-primary)", color: "#fff" },
  },
  {
    cls: "c-bg-info",
    style: { background: "var(--c-color-info)", color: "#fff" },
  },
  {
    cls: "c-bg-success",
    style: { background: "var(--c-color-success)", color: "#fff" },
  },
  {
    cls: "c-bg-warning",
    style: { background: "var(--c-color-warning)", color: "#fff" },
  },
  {
    cls: "c-bg-danger",
    style: { background: "var(--c-color-danger)", color: "#fff" },
  },
  {
    cls: "c-bg-disabled",
    style: {
      background: "var(--c-color-disabled)",
      color: "var(--c-color-text-1)",
    },
  },
];

const textItems = [
  { cls: "c-text-primary", style: { color: "var(--c-color-primary)" } },
  { cls: "c-text-info", style: { color: "var(--c-color-info)" } },
  { cls: "c-text-success", style: { color: "var(--c-color-success)" } },
  { cls: "c-text-warning", style: { color: "var(--c-color-warning)" } },
  { cls: "c-text-danger", style: { color: "var(--c-color-danger)" } },
  { cls: "c-text-disabled", style: { color: "var(--c-color-disabled)" } },
];

const borderItems = [
  { cls: "c-border-primary", style: { borderColor: "var(--c-color-primary)" } },
  { cls: "c-border-info", style: { borderColor: "var(--c-color-info)" } },
  { cls: "c-border-success", style: { borderColor: "var(--c-color-success)" } },
  { cls: "c-border-warning", style: { borderColor: "var(--c-color-warning)" } },
  { cls: "c-border-danger", style: { borderColor: "var(--c-color-danger)" } },
];
</script>

<style scoped lang="scss">
.label {
  margin-bottom: 8px;
  color: var(--c-color-text-3);
}

.row {
  display: flex;
  flex-wrap: wrap;
  gap: 8px;
}

.swatch {
  min-width: 110px;
  padding: 10px 12px;
  border-radius: 4px;
  border: 1px solid var(--c-color-border-2);
  font-size: 12px;
  text-align: center;
}

.text-row {
  gap: 16px;
  align-items: center;
}

.text-chip {
  font-size: 14px;
  font-weight: 500;
}

.border-chip {
  min-width: 110px;
  padding: 10px 12px;
  border-width: 2px;
  border-style: solid;
  border-radius: 4px;
  text-align: center;
}
</style>
```

### Font Size

Example source: src/style/atomic-css/__demos__/font-size.vue

```vue
<template>
  <c-space direction="column" fill size="md">
    <div
      v-for="item in items"
      :key="item.className"
      class="line"
      :style="{ fontSize: item.size }"
    >
      <code class="tag">{{ item.className }}</code>
      <span>Cedar Design — {{ item.label }}</span>
    </div>
  </c-space>
</template>

<script lang="ts" setup>
const items = [
  { label: "xs / 10px", className: "c-text-xs", size: "var(--c-font-size-xs)" },
  { label: "sm / 12px", className: "c-text-sm", size: "var(--c-font-size-sm)" },
  { label: "md / 14px", className: "c-text-md", size: "var(--c-font-size-md)" },
  { label: "lg / 16px", className: "c-text-lg", size: "var(--c-font-size-lg)" },
];
</script>

<style scoped lang="scss">
.line {
  display: flex;
  flex-wrap: wrap;
  align-items: baseline;
  gap: 8px;
  color: var(--c-color-text-1);
}

.tag {
  font-size: 12px;
  padding: 2px 6px;
  border-radius: 4px;
  background: var(--c-color-fill-2);
  color: var(--c-color-text-2);
}
</style>
```

### Spacing

Example source: src/style/atomic-css/__demos__/spacing.vue

```vue
<template>
  <div class="spacing-demo">
    <div class="spacing-row">
      <code>c-p-4 · 4px</code>
      <div class="spacing-stage"><div class="spacing-box c-p-4">内容</div></div>
    </div>
    <div class="spacing-row">
      <code>c-p-8 · 8px</code>
      <div class="spacing-stage"><div class="spacing-box c-p-8">内容</div></div>
    </div>
    <div class="spacing-row">
      <code>c-p-16 · 16px</code>
      <div class="spacing-stage">
        <div class="spacing-box c-p-16">内容</div>
      </div>
    </div>
    <div class="spacing-row">
      <code>c-px-24 c-py-8 · 24px / 8px</code>
      <div class="spacing-stage">
        <div class="spacing-box c-px-24 c-py-8">内容</div>
      </div>
    </div>
  </div>
</template>

<style scoped>
.spacing-demo {
  display: grid;
  gap: 16px;
}

.spacing-row {
  display: grid;
  grid-template-columns: minmax(210px, 1fr) 2fr;
  align-items: center;
  gap: 16px;
}

.spacing-stage {
  background: var(--c-color-fill-2);
  border-radius: 4px;
}

.spacing-box {
  width: fit-content;
  color: #fff;
  background: var(--c-color-primary);
}

/* 文档站未接入 preset 时的等价预览，业务项目由 Uno / Tailwind 生成。 */
.c-p-4 {
  padding: 4px;
}
.c-p-8 {
  padding: 8px;
}
.c-p-16 {
  padding: 16px;
}
.c-px-24 {
  padding-right: 24px;
  padding-left: 24px;
}
.c-py-8 {
  padding-top: 8px;
  padding-bottom: 8px;
}

@media (max-width: 600px) {
  .spacing-row {
    grid-template-columns: 1fr;
    gap: 8px;
  }
}
</style>
```

## Responsive layout and composition

### Breakpoints

Preview configuration: `:columns="columns"`, `:data="rows"`, `:pagination="false"`.

Example source: src/style/atomic-css/__demos__/breakpoints.vue

```vue
<template>
  <c-space direction="column" fill size="md">
    <div class="hint">
      缩小浏览器窗口可观察当前命中的断点；类名形如
      <code>sm:c-bg-info</code>。
    </div>
    <div class="box">
      <div class="label">当前 ≥</div>
      <strong class="value">{{ active }}</strong>
    </div>
    <c-table :columns="columns" :data="rows" :pagination="false" />
  </c-space>
</template>

<script lang="ts" setup>
import { computed, onMounted, onUnmounted, ref } from "vue";

const width = ref(typeof window !== "undefined" ? window.innerWidth : 0);

const onResize = () => {
  width.value = window.innerWidth;
};

onMounted(() => {
  width.value = window.innerWidth;
  window.addEventListener("resize", onResize);
});

onUnmounted(() => {
  window.removeEventListener("resize", onResize);
});

const active = computed(() => {
  const w = width.value;
  if (w >= 1920) return "xl (1920px)";
  if (w >= 1200) return "lg (1200px)";
  if (w >= 992) return "md (992px)";
  if (w >= 768) return "sm (768px)";
  return "base (< sm)";
});

const columns = [
  { title: "前缀", dataIndex: "prefix" },
  { title: "最小宽度", dataIndex: "min" },
  { title: "示例类", dataIndex: "cls" },
];

const rows = [
  { prefix: "sm:", min: "768px", cls: "sm:c-bg-info" },
  { prefix: "md:", min: "992px", cls: "md:c-bg-warning" },
  { prefix: "lg:", min: "1200px", cls: "lg:c-bg-danger" },
  { prefix: "xl:", min: "1920px", cls: "xl:c-bg-success" },
];
</script>

<style scoped lang="scss">
.hint {
  font-size: 13px;
  color: var(--c-color-text-3);
}

.box {
  display: flex;
  align-items: baseline;
  gap: 8px;
  padding: 12px 16px;
  border-radius: 4px;
  background: var(--c-color-primary);
  color: #fff;
}

.label {
  opacity: 0.85;
  font-size: 13px;
}

.value {
  font-size: 18px;
}
</style>
```

### Combined

Example source: src/style/atomic-css/__demos__/combined.vue

```vue
<template>
  <div class="demo">
    <div class="card body">
      <div class="title">c-bg-body + c-text-md</div>
      <div class="row">
        <span class="primary">c-text-primary</span>
        <span class="success">c-text-success</span>
        <span class="danger">c-text-danger</span>
      </div>
      <div class="banner">
        <div class="banner-inner">
          c-bg-primary · Uno / TW <code>c-text-lg</code>
          <div class="sub">
            叠加：sm:c-bg-info → md:c-bg-warning → lg:c-bg-danger →
            xl:c-bg-success
          </div>
        </div>
      </div>
    </div>
  </div>
</template>

<style scoped lang="scss">
.demo {
  font-size: var(--c-font-size-md);
}

.card {
  padding: 16px;
  border-radius: 8px;
  border: 1px solid var(--c-color-border-2);
}

.body {
  background: var(--c-color-body);
  color: var(--c-color-text-1);
}

.title {
  margin-bottom: 12px;
  font-weight: 600;
}

.row {
  display: flex;
  flex-wrap: wrap;
  gap: 12px;
  margin-bottom: 16px;
}

.primary {
  color: var(--c-color-primary);
}

.success {
  color: var(--c-color-success);
}

.danger {
  color: var(--c-color-danger);
}

.banner {
  padding: 16px;
  border-radius: 4px;
  background: var(--c-color-primary);
  color: #fff;
  font-size: var(--c-font-size-lg);

  @media (min-width: 768px) {
    background: var(--c-color-info);
  }

  @media (min-width: 992px) {
    background: var(--c-color-warning);
  }

  @media (min-width: 1200px) {
    background: var(--c-color-danger);
  }

  @media (min-width: 1920px) {
    background: var(--c-color-success);
  }
}

.sub {
  margin-top: 6px;
  font-size: var(--c-font-size-sm);
  opacity: 0.9;
}

code {
  font-size: 12px;
  opacity: 0.95;
}
</style>
```

## UnoCSS

### Installation

```shell
pnpm add -D @cedar-design/preset-unocss unocss
```

### Configuration

```js
// uno.config.ts
import { defineConfig } from "unocss";
import { presetCedar } from "@cedar-design/preset-unocss";

export default defineConfig({
  presets: [presetCedar()],
});
```

Optional `presetCedar({ colors, fontSize, breakpoints })`; `false` disables a section.

### Load theme variables first

```js
import "@cedar-design/ui/dist/index.css";
// Or import a theme stylesheet containing --c-* variables
```

---

## Tailwind CSS

### Installation

```shell
pnpm add -D @cedar-design/preset-tailwindcss tailwindcss
```

### Tailwind v3

```js
// tailwind.config.js
import { presetCedar } from "@cedar-design/preset-tailwindcss";

export default {
  content: ["./index.html", "./src/**/*.{vue,js,ts,jsx,tsx}"],
  presets: [presetCedar()],
};
```

### Tailwind v4

```js
// tailwind.config.js
import { presetCedar } from "@cedar-design/preset-tailwindcss";

export default {
  presets: [presetCedar()],
};
```

```css
/* src/style.css */
@import "tailwindcss";
@config '../tailwind.config.js';
```

---

See [Common patterns](llms/en-US/components/style/atomic-usage.md) for all Flex/spacing/sizing/overflow/radius classes. Only utilities mapped to Cedar tokens are listed below.

## Optional configuration

```js
presetCedar({
  colors: true, // or false / partial key overrides
  fontSize: true, // false disables it; custom fontSize maps are accepted
  // Uno:
  breakpoints: true,
  // TW:
  // screens: true,
});
```

### Custom theme mapping

`colors`/`fontSize` may override part of the defaults; omitted keys retain default mappings:

```js
presetCedar({
  colors: {
    primary: "var(--app-color-brand)",
    danger: "var(--app-color-error)",
  },
  fontSize: {
    md: "15px",
  },
});
```

`false` disables the corresponding Cedar theme mapping. Generator-native utilities may still exist but no longer bind Cedar variables.

---

## Corresponding Maple configuration

Maple's UnoCSS preset includes `presetUno` with an `mp-` prefix:

```js
import { defineConfig } from "unocss";
import { presetMaple } from "@nio-pow/maple-preset-unocss";

export default defineConfig({
  presets: [presetMaple()],
});
```

Both Maple UnoCSS/Tailwind presets generate `mp-bg-primary`, `mp-text-primary` and `mp-border mp-border-primary` without unprefixed aliases.

Tailwind `prefix` is global; one Tailwind instance should not load Cedar/Maple presets with different prefixes simultaneously.

---

## Notes

- The preset includes the framework's full atomic classes with `c-` prefixes, e.g. `c-flex`/`c-p-16`.
- Classes must start with `c-`, e.g. `c-bg-primary`; no unprefixed aliases.
- Choose UnoCSS or Tailwind CSS; do not enable both generators in one app.
- Cedar/Maple share theme key names. Even with different UnoCSS utility prefixes, avoid merging both themes in one config or matching colors may overwrite by preset order.

---

Document: llms/en-US/components/style/atomic-usage.md

<!-- Source: src/style/atomic-usage/README.en-US.md; locale: en-US; page: /en/components/style/atomic-usage/ -->

# Style Atomic Usage

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Combined

Example source: src/style/atomic-css/__demos__/combined.vue

```vue
<template>
  <div class="demo">
    <div class="card body">
      <div class="title">c-bg-body + c-text-md</div>
      <div class="row">
        <span class="primary">c-text-primary</span>
        <span class="success">c-text-success</span>
        <span class="danger">c-text-danger</span>
      </div>
      <div class="banner">
        <div class="banner-inner">
          c-bg-primary · Uno / TW <code>c-text-lg</code>
          <div class="sub">
            叠加：sm:c-bg-info → md:c-bg-warning → lg:c-bg-danger →
            xl:c-bg-success
          </div>
        </div>
      </div>
    </div>
  </div>
</template>

<style scoped lang="scss">
.demo {
  font-size: var(--c-font-size-md);
}

.card {
  padding: 16px;
  border-radius: 8px;
  border: 1px solid var(--c-color-border-2);
}

.body {
  background: var(--c-color-body);
  color: var(--c-color-text-1);
}

.title {
  margin-bottom: 12px;
  font-weight: 600;
}

.row {
  display: flex;
  flex-wrap: wrap;
  gap: 12px;
  margin-bottom: 16px;
}

.primary {
  color: var(--c-color-primary);
}

.success {
  color: var(--c-color-success);
}

.danger {
  color: var(--c-color-danger);
}

.banner {
  padding: 16px;
  border-radius: 4px;
  background: var(--c-color-primary);
  color: #fff;
  font-size: var(--c-font-size-lg);

  @media (min-width: 768px) {
    background: var(--c-color-info);
  }

  @media (min-width: 992px) {
    background: var(--c-color-warning);
  }

  @media (min-width: 1200px) {
    background: var(--c-color-danger);
  }

  @media (min-width: 1920px) {
    background: var(--c-color-success);
  }
}

.sub {
  margin-top: 6px;
  font-size: var(--c-font-size-sm);
  opacity: 0.9;
}

code {
  font-size: 12px;
  opacity: 0.95;
}
</style>
```

## Spacing and responsive layout

### Spacing

Example source: src/style/atomic-css/__demos__/spacing.vue

```vue
<template>
  <div class="spacing-demo">
    <div class="spacing-row">
      <code>c-p-4 · 4px</code>
      <div class="spacing-stage"><div class="spacing-box c-p-4">内容</div></div>
    </div>
    <div class="spacing-row">
      <code>c-p-8 · 8px</code>
      <div class="spacing-stage"><div class="spacing-box c-p-8">内容</div></div>
    </div>
    <div class="spacing-row">
      <code>c-p-16 · 16px</code>
      <div class="spacing-stage">
        <div class="spacing-box c-p-16">内容</div>
      </div>
    </div>
    <div class="spacing-row">
      <code>c-px-24 c-py-8 · 24px / 8px</code>
      <div class="spacing-stage">
        <div class="spacing-box c-px-24 c-py-8">内容</div>
      </div>
    </div>
  </div>
</template>

<style scoped>
.spacing-demo {
  display: grid;
  gap: 16px;
}

.spacing-row {
  display: grid;
  grid-template-columns: minmax(210px, 1fr) 2fr;
  align-items: center;
  gap: 16px;
}

.spacing-stage {
  background: var(--c-color-fill-2);
  border-radius: 4px;
}

.spacing-box {
  width: fit-content;
  color: #fff;
  background: var(--c-color-primary);
}

/* 文档站未接入 preset 时的等价预览，业务项目由 Uno / Tailwind 生成。 */
.c-p-4 {
  padding: 4px;
}
.c-p-8 {
  padding: 8px;
}
.c-p-16 {
  padding: 16px;
}
.c-px-24 {
  padding-right: 24px;
  padding-left: 24px;
}
.c-py-8 {
  padding-top: 8px;
  padding-bottom: 8px;
}

@media (max-width: 600px) {
  .spacing-row {
    grid-template-columns: 1fr;
    gap: 8px;
  }
}
</style>
```

### Breakpoints

Preview configuration: `:columns="columns"`, `:data="rows"`, `:pagination="false"`.

Example source: src/style/atomic-css/__demos__/breakpoints.vue

```vue
<template>
  <c-space direction="column" fill size="md">
    <div class="hint">
      缩小浏览器窗口可观察当前命中的断点；类名形如
      <code>sm:c-bg-info</code>。
    </div>
    <div class="box">
      <div class="label">当前 ≥</div>
      <strong class="value">{{ active }}</strong>
    </div>
    <c-table :columns="columns" :data="rows" :pagination="false" />
  </c-space>
</template>

<script lang="ts" setup>
import { computed, onMounted, onUnmounted, ref } from "vue";

const width = ref(typeof window !== "undefined" ? window.innerWidth : 0);

const onResize = () => {
  width.value = window.innerWidth;
};

onMounted(() => {
  width.value = window.innerWidth;
  window.addEventListener("resize", onResize);
});

onUnmounted(() => {
  window.removeEventListener("resize", onResize);
});

const active = computed(() => {
  const w = width.value;
  if (w >= 1920) return "xl (1920px)";
  if (w >= 1200) return "lg (1200px)";
  if (w >= 992) return "md (992px)";
  if (w >= 768) return "sm (768px)";
  return "base (< sm)";
});

const columns = [
  { title: "前缀", dataIndex: "prefix" },
  { title: "最小宽度", dataIndex: "min" },
  { title: "示例类", dataIndex: "cls" },
];

const rows = [
  { prefix: "sm:", min: "768px", cls: "sm:c-bg-info" },
  { prefix: "md:", min: "992px", cls: "md:c-bg-warning" },
  { prefix: "lg:", min: "1200px", cls: "lg:c-bg-danger" },
  { prefix: "xl:", min: "1920px", cls: "xl:c-bg-success" },
];
</script>

<style scoped lang="scss">
.hint {
  font-size: 13px;
  color: var(--c-color-text-3);
}

.box {
  display: flex;
  align-items: baseline;
  gap: 8px;
  padding: 12px 16px;
  border-radius: 4px;
  background: var(--c-color-primary);
  color: #fff;
}

.label {
  opacity: 0.85;
  font-size: 13px;
}

.value {
  font-size: 18px;
}
</style>
```

## Colors and typography

### Colors

Example source: src/style/atomic-css/__demos__/colors.vue

```vue
<template>
  <c-space direction="column" fill size="lg">
    <div>
      <div class="label">背景 c-bg-*</div>
      <div class="row">
        <div
          v-for="item in bgItems"
          :key="item.cls"
          class="swatch"
          :style="item.style"
        >
          <code>{{ item.cls }}</code>
        </div>
      </div>
    </div>
    <div>
      <div class="label">文字 c-text-*</div>
      <div class="row text-row">
        <span
          v-for="item in textItems"
          :key="item.cls"
          class="text-chip"
          :style="item.style"
        >
          {{ item.cls }}
        </span>
      </div>
    </div>
    <div>
      <div class="label">边框 c-border-*</div>
      <div class="row">
        <div
          v-for="item in borderItems"
          :key="item.cls"
          class="border-chip"
          :style="item.style"
        >
          <code>{{ item.cls }}</code>
        </div>
      </div>
    </div>
  </c-space>
</template>

<script lang="ts" setup>
const bgItems = [
  {
    cls: "c-bg-body",
    style: {
      background: "var(--c-color-body)",
      color: "var(--c-color-text-1)",
    },
  },
  {
    cls: "c-bg-primary",
    style: { background: "var(--c-color-primary)", color: "#fff" },
  },
  {
    cls: "c-bg-info",
    style: { background: "var(--c-color-info)", color: "#fff" },
  },
  {
    cls: "c-bg-success",
    style: { background: "var(--c-color-success)", color: "#fff" },
  },
  {
    cls: "c-bg-warning",
    style: { background: "var(--c-color-warning)", color: "#fff" },
  },
  {
    cls: "c-bg-danger",
    style: { background: "var(--c-color-danger)", color: "#fff" },
  },
  {
    cls: "c-bg-disabled",
    style: {
      background: "var(--c-color-disabled)",
      color: "var(--c-color-text-1)",
    },
  },
];

const textItems = [
  { cls: "c-text-primary", style: { color: "var(--c-color-primary)" } },
  { cls: "c-text-info", style: { color: "var(--c-color-info)" } },
  { cls: "c-text-success", style: { color: "var(--c-color-success)" } },
  { cls: "c-text-warning", style: { color: "var(--c-color-warning)" } },
  { cls: "c-text-danger", style: { color: "var(--c-color-danger)" } },
  { cls: "c-text-disabled", style: { color: "var(--c-color-disabled)" } },
];

const borderItems = [
  { cls: "c-border-primary", style: { borderColor: "var(--c-color-primary)" } },
  { cls: "c-border-info", style: { borderColor: "var(--c-color-info)" } },
  { cls: "c-border-success", style: { borderColor: "var(--c-color-success)" } },
  { cls: "c-border-warning", style: { borderColor: "var(--c-color-warning)" } },
  { cls: "c-border-danger", style: { borderColor: "var(--c-color-danger)" } },
];
</script>

<style scoped lang="scss">
.label {
  margin-bottom: 8px;
  color: var(--c-color-text-3);
}

.row {
  display: flex;
  flex-wrap: wrap;
  gap: 8px;
}

.swatch {
  min-width: 110px;
  padding: 10px 12px;
  border-radius: 4px;
  border: 1px solid var(--c-color-border-2);
  font-size: 12px;
  text-align: center;
}

.text-row {
  gap: 16px;
  align-items: center;
}

.text-chip {
  font-size: 14px;
  font-weight: 500;
}

.border-chip {
  min-width: 110px;
  padding: 10px 12px;
  border-width: 2px;
  border-style: solid;
  border-radius: 4px;
  text-align: center;
}
</style>
```

Example source: src/style/atomic-css/__demos__/font-size.vue

```vue
<template>
  <c-space direction="column" fill size="md">
    <div
      v-for="item in items"
      :key="item.className"
      class="line"
      :style="{ fontSize: item.size }"
    >
      <code class="tag">{{ item.className }}</code>
      <span>Cedar Design — {{ item.label }}</span>
    </div>
  </c-space>
</template>

<script lang="ts" setup>
const items = [
  { label: "xs / 10px", className: "c-text-xs", size: "var(--c-font-size-xs)" },
  { label: "sm / 12px", className: "c-text-sm", size: "var(--c-font-size-sm)" },
  { label: "md / 14px", className: "c-text-md", size: "var(--c-font-size-md)" },
  { label: "lg / 16px", className: "c-text-lg", size: "var(--c-font-size-lg)" },
];
</script>

<style scoped lang="scss">
.line {
  display: flex;
  flex-wrap: wrap;
  align-items: baseline;
  gap: 8px;
  color: var(--c-color-text-1);
}

.tag {
  font-size: 12px;
  padding: 2px 6px;
  border-radius: 4px;
  background: var(--c-color-fill-2);
  color: var(--c-color-text-2);
}
</style>
```

---

Document: llms/en-US/components/style/color.md

<!-- Source: src/style/color/README.en-US.md; locale: en-US; page: /en/components/style/color/ -->

# Style Color

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Fill

Preview configuration: `:columns="columns"`, `:data="data"`, `:pagination="false"`.

Example source: src/style/color/__demos__/fill.vue

```vue
<template>
  <c-table :columns="columns" :data="data" :pagination="false" />
</template>

<script lang="ts" setup>
import { reactive } from "vue";
import { columns } from "./columns";

const data = reactive([
  {
    properties: "var(--c-color-fill-1)",
    description: "浅/禁用",
    class: "c-fill-1",
  },
  {
    properties: "var(--c-color-fill-2)",
    description: "常规/白底悬浮",
    class: "c-fill-2",
  },
  {
    properties: "var(--c-color-fill-3)",
    description: "深/灰底悬浮",
    class: "c-fill-3",
  },
  {
    properties: "var(--c-color-fill-4)",
    description: "重/特殊场景",
    class: "c-fill-4",
  },
]);
</script>
<style lang="scss" scoped></style>
```

## Applying colors

### Border

Preview configuration: `:columns="columns"`, `:data="data"`, `:pagination="false"`.

Example source: src/style/color/__demos__/border.vue

```vue
<template>
  <c-table :columns="columns" :data="data" :pagination="false" />
</template>

<script lang="ts" setup>
import { reactive } from "vue";
import { columns } from "./columns";

const data = reactive([
  {
    properties: "var(--c-color-border-1)",
    description: "浅色",
    class: "c-color-border-1",
  },
  {
    properties: "var(--c-color-border-2)",
    description: "一般",
    class: "c-color-border-2",
  },
  {
    properties: "var(--c-color-border-3)",
    description: "深/悬浮",
    class: "c-color-border-3",
  },
  {
    properties: "var(--c-color-border-4)",
    description: "重/按钮描边",
    class: "c-color-border-4",
  },
]);
</script>
<style lang="scss" scoped></style>
```

### Text

Preview configuration: `:columns="columns"`, `:data="data"`, `:pagination="false"`.

Example source: src/style/color/__demos__/text.vue

```vue
<template>
  <c-table :columns="columns" :data="data" :pagination="false" />
</template>

<script lang="ts" setup>
import { reactive } from "vue";
import { columns } from "./columns";

const data = reactive([
  {
    properties: "var(--c-color-text-1)",
    description: "强调/正文标题、一级文字",
    class: "c-text-1",
  },
  {
    properties: "var(--c-color-text-2)",
    description: "次强调/正文标题、二级文字 图标",
    class: "c-text-2",
  },
  {
    properties: "var(--c-color-text-3)",
    description: "次要信息、三级文字",
    class: "c-text-3",
  },
  {
    properties: "var(--c-color-text-4)",
    description: "置灰禁用 / 占位",
    class: "c-text-4",
  },
]);
</script>
<style lang="scss" scoped></style>
```

### Background

Preview configuration: `:columns="columns"`, `:data="data"`, `:pagination="false"`.

Example source: src/style/color/__demos__/background.vue

```vue
<template>
  <c-table :columns="columns" :data="data" :pagination="false" />
</template>

<script lang="ts" setup>
import { reactive } from "vue";
import { columns } from "./columns";

const data = reactive([
  {
    properties: "var(--c-color-bg-white)",
    description: "顶层的白色背景",
    class: "c-bg-0",
  },
  {
    properties: "var(--c-color-bg-1)",
    description: "一般/常规",
    class: "c-bg-1",
  },
  {
    properties: "var(--c-color-bg-2)",
    description: "重/特殊场景",
    class: "c-bg-2",
  },
]);
</script>
<style lang="scss" scoped></style>
```

---

Document: llms/en-US/components/style/elevation.md

<!-- Source: src/style/elevation/README.en-US.md; locale: en-US; page: /en/components/style/elevation/ -->

# Style Elevation

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Class

Preview configuration: `:columns="columns"`, `:data="data"`, `:pagination="false"`.

Example source: src/style/elevation/__demos__/class.vue

```vue
<template>
  <c-space direction="column" fill size="lg">
    <c-table :columns="columns" :data="data" :pagination="false" />
  </c-space>
</template>
<script lang="ts" setup>
import { h } from "vue";
import { Message } from "@cedar-design/ui";

const columns = [
  {
    title: "Class",
    dataIndex: "class",
    render: (data) => {
      return h(
        "div",
        {
          style: {
            cursor: "pointer",
          },
          onClick: () => {
            navigator.clipboard
              .writeText(data.record.class)
              .then(() => {
                Message.success("copy success");
              })
              .catch(() => {
                Message.fail("copy fail");
              });
          },
        },
        data.record.class,
      );
    },
  },
  {
    title: "Properties",
    dataIndex: "properties",
  },
];

const data = Array.from({ length: 25 }, (_, i) => ({
  class: `c-elevation--${i}`,
  properties: `Material elevation level ${i}`,
}));
</script>
```

## Shadow composition

### Demo

Example source: src/style/elevation/__demos__/demo.vue

```vue
<template>
  <c-space class="elevation-demo" :size="[24, 24]" wrap>
    <div
      v-for="level in 25"
      :key="level"
      class="elevation-item"
      :class="`c-elevation--${level - 1}`"
    >
      {{ level - 1 }}
    </div>
  </c-space>
</template>

<style lang="scss">
.elevation-demo {
  margin-top: 8px;
}

.elevation-item {
  display: flex;
  justify-content: center;
  align-items: center;
  width: 72px;
  height: 72px;
  border-radius: 4px;
  background: var(--c-color-bg-1);
}
</style>
```

---

Document: llms/en-US/components/style/typography.md

<!-- Source: src/style/typography/README.en-US.md; locale: en-US; page: /en/components/style/typography/ -->

# Style Typography

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Font

Preview configuration: `:columns="columns2"`, `:data="dataFont"`, `:pagination="false"`.

Example source: src/style/typography/__demos__/font.vue

```vue
<template>
  <c-table :columns="columns2" :data="dataFont" :pagination="false" />
</template>
<script lang="ts" setup>
import { h } from "vue";
import { Message } from "@cedar-design/ui";

const columns2 = [
  {
    title: "Class",
    dataIndex: "class",
    render: (data) => {
      return h(
        "div",
        {
          style: {
            cursor: "pointer",
          },
          onClick: () => {
            navigator.clipboard
              .writeText(data.record.class)
              .then(() => {
                Message.success("copy success");
              })
              .catch((err) => {
                Message.fail("copy fail");
              });
          },
        },
        data.record.class,
      );
    },
  },
  {
    title: "Properties/Effective CSS",
    dataIndex: "properties",
    render: (data) => {
      return [
        h("div", {
          innerHTML: `<div>${data.record.properties.replaceAll("\n", "<br/>")}</div>`, // 等效于 v-html
        }),
        h("div", {
          class: data.record.class,
          style: "margin-top: 10px;",
          innerHTML: `<div>${data.record.effective?.replaceAll("\n", "<br/>")}</div>`, // 等效于 v-html
        }),
      ];
    },
  },
];
const dataFont = [
  {
    class: "c-text-body-2-regular",
    properties:
      "font-family: var(--c-font-regular);\nfont-size: var(--c-font-size-body-1);\nfont-weight: var(--c-font-weight-regular);\nline-height: var(--c-line-height-default);",
    effective:
      "font-family:Auto;\nfont-size: 12px;\nfont-weight: 400;\nline-height: 1.5;",
  },
  {
    class: "c-text-body-2-semibold",
    properties:
      "font-family: var(--c-font-regular);\nfont-size: var(--c-font-size-body-1);\nfont-weight: var(--c-font-weight-semibold);\nline-height: var(--c-line-height-default);",
    effective:
      "font-family:Auto;\nfont-size: 12px;\nfont-weight: 600;\nline-height: 1.5;",
  },
  {
    class: "c-text-body-1-regular",
    properties:
      "font-family: var(--c-font-regular);\nfont-size: var(--c-font-size-body-2);\nfont-weight: var(--c-font-weight-regular);\nline-height: var(--c-line-height-default);",
    effective:
      "font-family:Auto;\nfont-size: 14px;\nfont-weight: 400;\nline-height: 1.5;",
  },
  {
    class: "c-text-body-1-semibold",
    properties:
      "font-family: var(--c-font-regular);\nfont-size: var(--c-font-size-body-2);\nfont-weight: var(--c-font-weight-semibold);\nline-height: var(--c-line-height-default);",
    effective:
      "font-family:Auto;\nfont-size: 14px;\nfont-weight: 600;\nline-height: 1.5;",
  },
  {
    class: "c-text-subtitle-2-regular",
    properties:
      "font-family: var(--c-font-regular);\nfont-size: var(--c-font-size-subtitle-1);\nfont-weight: var(--c-font-weight-regular);\nline-height: var(--c-line-height-default);",
    effective:
      "font-family:Auto;\nfont-size: 16px;\nfont-weight: 400;\nline-height: 1.5;",
  },
  {
    class: "c-text-subtitle-2-semibold",
    properties:
      "font-family: var(--c-font-regular);\nfont-size: var(--c-font-size-subtitle-1);\nfont-weight: var(--c-font-weight-semibold);\nline-height: var(--c-line-height-default);",
    effective:
      "font-family:Auto;\nfont-size: 16px;\nfont-weight: 600;\nline-height: 1.5;",
  },
  {
    class: "c-text-subtitle-1-regular",
    properties:
      "font-family: var(--c-font-regular);\nfont-size: var(--c-font-size-subtitle-2);\nfont-weight: var(--c-font-weight-regular);\nline-height: var(--c-line-height-default);",
    effective:
      "font-family:Auto;\nfont-size: 18px;\nfont-weight: 400;\nline-height: 1.5;",
  },
  {
    class: "c-text-subtitle-1-semibold",
    properties:
      "font-family: var(--c-font-regular);\nfont-size: var(--c-font-size-subtitle-2);\nfont-weight: var(--c-font-weight-semibold);\nline-height: var(--c-line-height-default);",
    effective:
      "font-family:Auto;\nfont-size: 18px;\nfont-weight: 600;\nline-height: 1.5;",
  },
  {
    class: "c-text-heading-4-semibold",
    properties:
      "font-family: var(--c-font-regular);\nfont-size: var(--c-font-size-heading-1);\nfont-weight: var(--c-font-weight-semibold);\nline-height: var(--c-line-height-default);",
    effective:
      "font-family:Auto;\nfont-size: 20px;\nfont-weight: 600;\nline-height: 1.5;",
  },
  {
    class: "c-text-heading-3-semibold",
    properties:
      "font-family: var(--c-font-regular);\nfont-size: var(--c-font-size-heading-2);\nfont-weight: var(--c-font-weight-semibold);\nline-height: var(--c-line-height-default);",
    effective:
      "font-family:Auto;\nfont-size: 24px;\nfont-weight: 600;\nline-height: 1.5;",
  },
  {
    class: "c-text-heading-2-semibold",
    properties:
      "font-family: var(--c-font-regular);\nfont-size: var(--c-font-size-heading-3);\nfont-weight: var(--c-font-weight-semibold);\nline-height: var(--c-line-height-default);",
    effective:
      "font-family:Auto;\nfont-size: 32px;\nfont-weight: 600;\nline-height: 1.5;",
  },
  {
    class: "c-text-heading-1-semibold",
    properties:
      "font-family: var(--c-font-regular);\nfont-size: var(--c-font-size-heading-4);\nfont-weight: var(--c-font-weight-semibold);\nline-height: var(--c-line-height-default);",
    effective:
      "font-family:Auto;\nfont-size: 40px;\nfont-weight: 600;\nline-height: 1.5;",
  },
  {
    class: "text-number-7-regular",
    properties:
      "font-family: var(--c-font-number-regular);\nfont-size: var(--c-font-size-body-2);\nfont-weight: var(--c-font-weight-regular);\nline-height: var(--c-line-height-default);",
    effective:
      "font-family: Barlow;\nfont-size: 14px;\nfont-weight: 400;\nline-height: 1.5;",
  },
  {
    class: "text-number-7-bold",
    properties:
      "font-family: var(--c-font-number-bold);\nfont-size: var(--c-font-size-body-2);\nfont-weight: var(--c-font-weight-blod);\nline-height: var(--c-line-height-default);",
    effective:
      "font-family: Barlow;\nfont-size: 14px;\nfont-weight: 700;\nline-height: 1.5;",
  },
  {
    class: "text-number-6-regular",
    properties:
      "font-family: var(--c-font-number-regular);\nfont-size: var(--c-font-size-subtitle-1);\nfont-weight: var(--c-font-weight-regular);\nline-height: var(--c-line-height-default);",
    effective:
      "font-family: Barlow;\nfont-size: 16px;\nfont-weight: 400;\nline-height: 1.5;",
  },
  {
    class: "text-number-6-bold",
    properties:
      "font-family: var(--c-font-number-bold);\nfont-size: var(--c-font-size-subtitle-1);\nfont-weight: var(--c-font-weight-bold);\nline-height: var(--c-line-height-default);",
    effective:
      "font-family: Barlow;\nfont-size: 16px;\nfont-weight: 700;\nline-height: 1.5;",
  },
  {
    class: "text-number-5-bold",
    properties:
      "font-family: var(--c-font-number-bold);\nfont-size: var(--c-font-size-subtitle-2);\nfont-weight: var(--c-font-weight-bold);\nline-height: var(--c-line-height-default);",
    effective:
      "font-family: Barlow;\nfont-size: 18px;\nfont-weight: 700;\nline-height: 1.5;",
  },
  {
    class: "text-number-4-bold",
    properties:
      "font-family: var(--c-font-number-bold);\nfont-size: var(--c-font-size-heading-1);\nfont-weight: var(--c-font-weight-bold);\nline-height: 24px;",
    effective:
      "font-family: Barlow;\nfont-size: 20px;\nfont-weight: 700;\nline-height: 1;",
  },
  {
    class: "text-number-3-bold",
    properties:
      "font-family: var(--c-font-number-bold);\nfont-size: var(--c-font-size-heading-2);\nfont-weight: var(--c-font-weight-bold);\nline-height: 29px;",
    effective:
      "font-family: Barlow;\nfont-size: 24px;\nfont-weight: 700;\nline-height: 1;",
  },
  {
    class: "text-number-2-bold",
    properties:
      "font-family: var(--c-font-number-bold);\nfont-size: var(--c-font-size-heading-3);\nfont-weight: var(--c-font-weight-bold);\nline-height: 38px;",
    effective:
      "font-family: Barlow;\nfont-size: 32px;\nfont-weight: 700;\nline-height: 1;",
  },
  {
    class: "text-number-1-bold",
    properties:
      "font-family: var(--c-font-number-bold);\nfont-size: var(--c-font-size-heading-4);\nfont-weight: var(--c-font-weight-bold);\nline-height: 48px;",
    effective:
      "font-family: Barlow;\nfont-size: 40px;\nfont-weight: 700;\nline-height: 1;",
  },
];
</script>

<style lang="scss">
.table-line-height-unset .c-table-td {
  line-height: unset;
}
</style>
```

## Font size and face

### Font Size

Preview configuration: `:columns="columns"`, `:data="dataSize"`, `:pagination="false"`.

Example source: src/style/typography/__demos__/font-size.vue

```vue
<template>
  <c-table
    :columns="columns"
    :data="dataSize"
    :pagination="false"
    class="table-line-height-unset"
  />
</template>
<script lang="ts" setup>
import { columns } from "./columns";

const dataSize = [
  {
    class: "font-size-body-1",
    properties: "font-size: var(--c-font-size-body-1);",
    effective: "font-size: 12px;",
  },
  {
    class: "font-size-body-2",
    properties: "font-size: var(--c-font-size-body-2);",
    effective: "font-size: 14px;",
  },
  {
    class: "font-size-subtitle-1",
    properties: "font-size: var(--c-font-size-subtitle-1);",
    effective: "font-size: 16px;",
  },
  {
    class: "font-size-subtitle-2",
    properties: "font-size: var(--c-font-size-subtitle-2);",
    effective: "font-size: 18px;",
  },
  {
    class: "font-size-heading-1",
    properties: "font-size: var(--c-font-size-heading-1);",
    effective: "font-size: 20px;",
  },
  {
    class: "font-size-heading-2",
    properties: "font-size: var(--c-font-size-heading-2);",
    effective: "font-size: 24px;",
  },
  {
    class: "font-size-heading-3",
    properties: "font-size: var(--c-font-size-heading-3);",
    effective: "font-size: 32px;",
  },
  {
    class: "font-size-heading-4",
    properties: "font-size: var(--c-font-size-heading-4);",
    effective: "font-size: 40px;",
  },
  {
    class: "font-size-display-1",
    properties: "font-size: var(--c-font-size-display-1);",
    effective: "font-size: 48px;",
  },
  {
    class: "font-size-display-2",
    properties: "font-size: var(--c-font-size-display-2);",
    effective: "font-size: 56px;",
  },
];
</script>

<style lang="scss">
.table-line-height-unset .c-table-td {
  line-height: unset;
}
</style>
```

### Font Family

Preview configuration: `:columns="columns"`, `:data="dataFamily"`, `:pagination="false"`.

Example source: src/style/typography/__demos__/font-family.vue

```vue
<template>
  <c-table :columns="columns" :data="dataFamily" :pagination="false" />
</template>
<script lang="ts" setup>
import { columns } from "./columns";

const dataFamily = [
  {
    class: "font-regular",
    properties: "font-family: var(--c-font-regular);",
    effective: "font-family: Auto;",
  },
  {
    class: "font-number",
    properties: "font-family: var(--c-font-number-bold);",
    effective: "font-family: Barlow-Bold;",
  },
  {
    class: "font-number-regular",
    properties: "font-family: var(--c-font-number-regular);",
    effective: "font-family: Barlow-Regular;",
  },
  {
    class: "font-number-bold",
    properties: "font-family: var(--c-font-number-bold);",
    effective: "font-family: Barlow-Bold;",
  },
];
</script>

<style lang="scss">
.table-line-height-unset .c-table-td {
  line-height: unset;
}
</style>
```

### Font Weight

Preview configuration: `:columns="columns"`, `:data="dataWeight"`, `:pagination="false"`.

Example source: src/style/typography/__demos__/font-weight.vue

```vue
<template>
  <c-table :columns="columns" :data="dataWeight" :pagination="false" />
</template>
<script lang="ts" setup>
import { columns } from "./columns";

const dataWeight = [
  {
    class: "font-weight-thin",
    properties: "font-weight: var(--c-font-weight-thin);",
    effective: "font-weight: 100;",
  },
  {
    class: "font-weight-x-light",
    properties: "font-weight: var(--c-font-weight-x-light);",
    effective: "font-weight: 200;",
  },
  {
    class: "font-weight-light",
    properties: "font-weight: var(--c-font-weight-light);",
    effective: "font-weight: 300;",
  },
  {
    class: "font-weight-regular",
    properties: "font-weight: var(--c-font-weight-regular);",
    effective: "font-weight: 400;",
  },
  {
    class: "font-weight-medium",
    properties: "font-weight: var(--c-font-weight-medium);",
    effective: "font-weight: 500;",
  },
  {
    class: "font-weight-semibold",
    properties: "font-weight: var(--c-font-weight-semibold);",
    effective: "font-weight: 600;",
  },
  {
    class: "font-weight-bold",
    properties: "font-weight: var(--c-font-weight-bold);",
    effective: "font-weight: 700;",
  },
  {
    class: "font-weight-x-bold",
    properties: "font-weight: var(--c-font-weight-x-bold);",
    effective: "font-weight: 800;",
  },
  {
    class: "font-weight-xx-bold",
    properties: "font-weight: var(--c-font-weight-xx-bold);",
    effective: "font-weight: 900;",
  },
];
</script>

<style lang="scss"></style>
```

## Alignment and line height

### Text Align

Preview configuration: `:columns="columns"`, `:data="data"`, `:pagination="false"`.

Example source: src/style/typography/__demos__/text-align.vue

```vue
<template>
  <c-table :columns="columns" :data="data" :pagination="false" />
</template>
<script lang="ts" setup>
import { h } from "vue";
import { Message } from "@cedar-design/ui";

const columns = [
  {
    title: "Class",
    dataIndex: "class",
    render: (data) => {
      return h(
        "div",
        {
          style: {
            cursor: "pointer",
          },
          onClick: () => {
            navigator.clipboard
              .writeText(data.record.class)
              .then(() => {
                Message.success("copy success");
              })
              .catch((err) => {
                Message.fail("copy fail");
              });
          },
        },
        data.record.class,
      );
    },
  },
  {
    title: "Effective CSS",
    dataIndex: "effective",
    render: (data) => {
      return h("div", {
        innerHTML: `<div>${data.record.effective?.replaceAll("\n", "<br/>")}</div>`, // 等效于 v-html
      });
    },
  },
];
const data = [
  {
    class: "c-text-left",
    properties: "text-align: left !important;",
    effective: "text-align: left !important;",
  },
  {
    class: "c-text-center",
    properties: "text-align: center !important;",
    effective: "text-align: center !important;",
  },
  {
    class: "c-text-right",
    properties: "text-align: right !important;",
    effective: "text-align: right !important;",
  },
  {
    class: "c-text-justify",
    properties: "text-align: justify !important;",
    effective: "text-align: justify !important;",
  },
];
</script>

<style lang="scss"></style>
```

### Line Height

Preview configuration: `:columns="columns"`, `:data="dataLineHeight"`, `:pagination="false"`.

Example source: src/style/typography/__demos__/line-height.vue

```vue
<template>
  <c-table :columns="columns" :data="dataLineHeight" :pagination="false" />
</template>
<script lang="ts" setup>
import { columns } from "./columns";

const dataLineHeight = [
  {
    class: "line-height-1",
    properties: "line-height: var(--c-line-height-default);",
    effective: "line-height: 1.5;",
  },
];
</script>

<style lang="scss"></style>
```

---

Document: llms/en-US/components/style/utilities.md

<!-- Source: src/style/utilities/README.en-US.md; locale: en-US; page: /en/components/style/utilities/ -->

# Style Utilities

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Overview

Example source: src/style/utilities/__demos__/overview.vue

```vue
<template>
  <div class="overview">
    <section class="block">
      <div class="label c-text-3">Color text</div>
      <div class="row c-flex c-items-center">
        <span class="c-text-1 c-mr-16">c-text-1</span>
        <span class="c-text-2 c-mr-16">c-text-2</span>
        <span class="c-text-3 c-mr-16">c-text-3</span>
        <span class="c-text-4">c-text-4</span>
      </div>
    </section>

    <section class="block c-mt-24">
      <div class="label c-text-3">Background</div>
      <div class="row c-flex c-items-center">
        <div class="swatch c-bg-0 border-box c-p-8 c-mr-8">c-bg-0</div>
        <div class="swatch c-bg-1 c-p-8 c-mr-8">c-bg-1</div>
        <div class="swatch c-bg-2 c-p-8">c-bg-2</div>
      </div>
    </section>

    <section class="block c-mt-24">
      <div class="label c-text-3">Spacing</div>
      <div class="spacing-stage c-fill-2 c-p-16">
        <div class="box c-fill-2 c-mt-16 c-px-8">
          <div class="inner c-bg-0">c-mt-16 c-px-8</div>
        </div>
        <div class="box c-fill-3 c-mx-16 c-py-8">
          <div class="inner c-bg-0">c-mx-16 c-py-8</div>
        </div>
        <div class="box c-fill-4 c-p-24">
          <div class="inner c-bg-0">c-p-24</div>
        </div>
      </div>
    </section>

    <section class="block c-mt-24">
      <div class="label c-text-3">Flex</div>
      <div class="c-flex c-justify-between c-items-center c-fill-2 c-p-16">
        <div class="chip c-fill-1 c-p-8">start</div>
        <div class="chip c-fill-2 c-p-8">between</div>
        <div class="chip c-fill-3 c-p-8">end</div>
      </div>
    </section>
  </div>
</template>

<script lang="ts" setup></script>

<style lang="scss" scoped>
.overview {
  font-size: 13px;
}

.label {
  margin-bottom: 8px;
}

.swatch {
  min-width: 72px;
  text-align: center;
  border: 1px solid var(--c-color-border-2);
}

.border-box {
  border: 1px solid var(--c-color-border-2);
}

.spacing-stage {
  display: flex;
  flex-wrap: wrap;
  gap: 8px;
}

.box {
  display: inline-block;
}

.inner {
  min-width: 88px;
  text-align: center;
  line-height: 32px;
}

.chip {
  min-width: 64px;
  text-align: center;
}
</style>
```

---

Document: llms/en-US/components/switch.md

<!-- Source: src/switch/README.en-US.md; locale: en-US; page: /en/components/switch/ -->

# Switch

The same scenarios, parameters and interactions as Cedar. Only component prefixes differ; themes and site shells remain independent.

## Reading direction

Switch inherits source dir: its unchecked handle starts at inline start and moves toward inline end when checked. Space/Enter still toggle. Direction changes do not modify values; disabled, readonly and loading states block commits.

## Basic examples

### Controlled and default value

Example source: src/switch/__demos__/basic.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const enabled = ref(false)
</script>

<template>
  <c-space wrap
    ><c-switch v-model="enabled" aria-label="Enable notifications" /><output>{{ enabled }}</output
    ><c-switch :default-value="true" aria-label="Initially enabled"
  /></c-space>
</template>
```

## Appearance and states

### Appearance configuration comparison

Choose a dimension to compare all its values side by side while keeping other settings and content identical. Change the other settings to inspect combinations; input specimens share one model.

Example source: src/switch/__demos__/appearance-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref(false);
const __demoAppearance = __demoReactive({ variant: "circle", size: "md" });

import { computed as demoComputed, ref as demoRef } from 'vue'
const demoCompareFields = [{"name":"variant","values":["circle","round","line","tonal"]},{"name":"size","values":["sm","md","lg"]}]
const demoCompareAxis = demoRef("variant")
const demoComparedOptions = demoComputed(() => demoCompareFields.find(field => field.name === demoCompareAxis.value)?.values ?? [])
</script>
<template>
  <c-space direction="column" :size="16">
    <c-form layout="vertical">
      <c-form-item layout="vertical" size="sm" label="variant">
        <c-radio-group
          v-model="__demoAppearance['variant']"
          aria-label="variant"
          :options="[
            { label: 'circle', value: 'circle' },
            { label: 'round', value: 'round' },
            { label: 'line', value: 'line' },
            { label: 'tonal', value: 'tonal' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
      <c-form-item layout="vertical" size="sm" label="size">
        <c-radio-group
          v-model="__demoAppearance['size']"
          aria-label="size"
          :options="[
            { label: 'sm', value: 'sm' },
            { label: 'md', value: 'md' },
            { label: 'lg', value: 'lg' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
    </c-form>
    <p class="demo-config-comparison-hint"><span lang="zh-CN">选择一个对比维度；其他配置和内容保持一致。输入类示例共享同一个值，便于比较外观。</span><span lang="en-US">Compare one dimension while keeping the other settings and content identical. Input specimens share the same value.</span></p>
<c-radio-group v-model="demoCompareAxis" aria-label="Compare configuration" :options="demoCompareFields.map(field => ({ label: field.name, value: field.name }))" />
<div class="demo-config-comparison">
<section v-for="sample in demoComparedOptions" :key="String(sample)">
<p><code>{{ demoCompareAxis }}={{ sample }}</code></p>
<c-switch v-model="value" v-bind="{ ...__demoAppearance, [demoCompareAxis]: sample }"></c-switch>
</section>
</div>
  </c-space>
</template>

<style scoped>
.demo-config-comparison { display: grid; grid-template-columns: repeat(auto-fit, minmax(min(100%, 220px), 1fr)); gap: 20px; min-width: 0; max-width: 100%; }
.demo-config-comparison > section { min-width: 0; }
.demo-config-comparison p { margin: 0 0 8px; }
html:not([lang='en-US']) .demo-config-comparison-hint > [lang='en-US'],
html[lang='en-US'] .demo-config-comparison-hint > [lang='zh-CN'] { display: none; }
</style>
```

## Customization and slots

### Custom colors

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration     | Purpose               | Related examples            |
| ----------------- | --------------------- | --------------------------- |
| `variant`         | Appearance            | Custom text, Custom icons   |
| `checked-color`   | Checked track color   | Custom colors               |
| `unchecked-color` | Unchecked track color | Custom colors               |
| `checked-text`    | Checked label         | Custom text                 |
| `unchecked-text`  | Unchecked label       | Custom text                 |
| `ripple`          | Click ripple          | Ripple and handle elevation |

<!-- demo-config-notes:end -->

Example source: src/switch/__demos__/custom-color.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const enabled = ref(false)
</script>

<template>
  <c-switch
    v-model="enabled"
    checked-color="#005f73"
    unchecked-color="#9b2226"
    aria-label="Custom color switch"
  />
</template>
```

### Custom text

Example source: src/switch/__demos__/custom-text.vue

```vue
<template>
  <c-space wrap
    ><c-switch checked-text="ON" unchecked-text="OFF" aria-label="Text props" /><c-switch
      variant="round"
      aria-label="Text slots"
      ><template #checked>ON</template><template #unchecked>OFF</template></c-switch
    ></c-space
  >
</template>
```

### Custom icons

Example source: src/switch/__demos__/custom-icon.vue

```vue
<script setup lang="ts">
const variants = ['circle', 'round', 'line', 'tonal'] as const
</script>

<template>
  <c-space wrap
    ><c-switch v-for="variant in variants" :key="variant" :variant="variant" :aria-label="variant"
      ><template #checked-icon>✓</template><template #unchecked-icon>×</template></c-switch
    ></c-space
  >
</template>
```

### Ripple and handle elevation

Example source: src/switch/__demos__/custom.vue

```vue
<template>
  <c-space wrap
    ><c-switch :ripple="false" :handle-elevation="false" aria-label="No ripple or shadow" /><c-switch
      :handle-elevation="4"
      aria-label="Elevated handle"
  /></c-space>
</template>
```

## Interaction and control

### Interaction state comparison

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration   | Purpose                                                      | Related examples             |
| --------------- | ------------------------------------------------------------ | ---------------------------- |
| `disabled`      | Disable interaction, including inherited form disabled state | Interaction state comparison |
| `readonly`      | Read only; focus and click remain available without toggling | Interaction state comparison |
| `variant`       | Appearance                                                   | Loading                      |
| `loading`       | Loading; blocks clicks and changes                           | Loading                      |
| `default-value` | Initial uncontrolled value; falls back to uncheckedValue     | Loading                      |
| `size`          | Size; omitted value follows platform rules below             | Focus and event order        |

<!-- demo-config-notes:end -->

Toggle disabled, read-only and error states, then interact with the same instance. Recovery controls remain outside the target; error appearance alone does not validate data.

Example source: src/switch/__demos__/state-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref(false);
const __demoState = __demoReactive({ disabled: false, readonly: false });
</script>
<template>
  <c-space direction="column" :size="16">
    <c-space wrap>
      <c-checkbox v-model="__demoState['disabled']">disabled</c-checkbox>
      <c-checkbox v-model="__demoState['readonly']">readonly</c-checkbox>
    </c-space>
    <c-switch v-model="value" v-bind="__demoState"></c-switch>
  </c-space>
</template>
```

### Loading

Example source: src/switch/__demos__/loading.vue

```vue
<script setup lang="ts">
const variants = ['circle', 'round', 'line', 'tonal'] as const
</script>

<template>
  <c-space wrap
    ><template v-for="variant in variants" :key="variant"
      ><c-switch :variant="variant" loading :aria-label="variant + ' off'" /><c-switch
        :variant="variant"
        :default-value="true"
        loading
        :aria-label="variant + ' on'" /></template
  ></c-space>
</template>
```

### Focus and event order

Example source: src/switch/__demos__/events.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const value = ref(false)
const events = ref<string[]>([])
function record(name: string) {
  events.value = [...events.value.slice(-7), name]
}
</script>

<template>
  <p>Use Tab to focus, then Space or Enter to toggle.</p>
  <c-switch
    v-model="value"
    size="md"
    aria-label="Event sequence"
    @focus="record('focus')"
    @blur="record('blur')"
    @click="record('click')"
    @update:model-value="record(`update: ${$event}`)"
    @change="record(`change: ${$event}`)"
  />
  <p aria-live="polite">{{ events.join(' → ') || 'No events yet' }}</p>
  <c-button @click="events = []">Clear events</c-button>
</template>
```

### Custom values and events

Example source: src/switch/__demos__/custom-value.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const value = ref('disabled')
const lastChange = ref('—')
</script>

<template>
  <c-space direction="column"
    ><c-switch
      v-model="value"
      checked-value="enabled"
      unchecked-value="disabled"
      aria-label="String value"
      @change="lastChange = String($event)"
    /><output aria-live="polite">Value: {{ value }}; change: {{ lastChange }}</output></c-space
  >
</template>
```

## Async and dynamic data

### Async allow, deny and rejection

Example source: src/switch/__demos__/switch-interception.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const result = ref('Ready')
const wait = () => new Promise<void>((resolve) => setTimeout(resolve, 500))
async function allow() {
  await wait()
  result.value = 'Allowed'
  return true
}
async function deny() {
  await wait()
  result.value = 'Blocked'
  return false
}
async function reject() {
  await wait()
  result.value = 'Rejected'
  throw new Error('Demo rejection')
}
</script>

<template>
  <c-space direction="column">
    <label>Allow after 500ms <c-switch :before-change="allow" aria-label="Async allow" /></label>
    <label>Return false <c-switch :before-change="deny" aria-label="Async deny" /></label>
    <label>Reject Promise <c-switch :before-change="reject" aria-label="Async rejection" /></label>
    <output aria-live="polite">{{ result }}</output>
  </c-space>
</template>
```

## API

### Empty values and reading placeholders

`empty-values` recognizes empty data; `empty-value` keeps existing clear output. `empty-text` defaults to `'-'` under `read-pretty`, with Field > FormItem > Form precedence and custom read slots first. With explicit empty-values, built-in required uses the policy; custom validators receive original data. See the [shared guide](llms/en-US/guide/empty-values.md).

| Prop         | Type               | Default and scope                                                           |
| ------------ | ------------------ | --------------------------------------------------------------------------- |
| empty-values | readonly unknown[] | Field > FormItem > Form > component-family default; replaces the whole list |
| empty-text   | string             | Field > FormItem > Form > '-'; explicit '' is valid                         |

These props belong to field presentation; pure panels do not gain reading mode. Form and FormItem provide inherited settings. The existing empty-value type and clear fallback remain component-specific.

### Value and default value

Use ordinary `v-model`. `modelValue` is the actual switch value and matches checkedValue/uncheckedValue types. `defaultValue` initializes uncontrolled state once; later changes do not reset it. Explicit binding takes precedence, with no initialization `update:modelValue`.

<!-- same-source-api:start -->

### Props

| Prop             | Meaning                                                                                                 | Type                                                                 | Default   |
| ---------------- | ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | --------- |
| model-value      | Controlled value; managed internally when omitted                                                       | string / number / boolean                                            | undefined |
| default-value    | Initial uncontrolled value; falls back to uncheckedValue                                                | string / number / boolean                                            | undefined |
| clearable        | Show clearing in popup editing                                                                          | boolean                                                              | false     |
| empty-value      | Value committed after clearing; accepts a value or factory                                              | SwitchValue \| null \| (() => SwitchValue \| null)                   | undefined |
| edit-mode        | Editing mode; inherits FormItem/Form when unset. See editing-mode guidance for platform-specific values | FieldEditMode                                                        | undefined |
| read-pretty      | Plain reading display, independent of readonly                                                          | boolean                                                              | undefined |
| before-commit    | Cancelable interceptor before saving the editor                                                         | BeforeFieldCommit                                                    | undefined |
| open             | Controlled editor open state                                                                            | boolean                                                              | undefined |
| default-open     | Initial uncontrolled editor state                                                                       | boolean                                                              | false     |
| popup-container  | Editor mount container                                                                                  | PopupContainer                                                       | undefined |
| checked-value    | Checked value                                                                                           | string / number / boolean                                            | true      |
| unchecked-value  | Unchecked value                                                                                         | string / number / boolean                                            | false     |
| variant          | Appearance                                                                                              | circle / round / line / tonal                                        | circle    |
| size             | Size; omitted value follows platform rules below                                                        | sm / md / lg                                                         | undefined |
| disabled         | Disable interaction, including inherited form disabled state                                            | boolean                                                              | undefined |
| readonly         | Read only; focus and click remain available without toggling                                            | boolean                                                              | undefined |
| loading          | Loading; blocks clicks and changes                                                                      | boolean                                                              | false     |
| before-change    | Switch interceptor, not an event                                                                        | (payload, done, context) => boolean / void / Promise<boolean / void> | —         |
| checked-text     | Checked label                                                                                           | string                                                               | —         |
| unchecked-text   | Unchecked label                                                                                         | string                                                               | —         |
| checked-color    | Checked track color                                                                                     | string                                                               | —         |
| unchecked-color  | Unchecked track color                                                                                   | string                                                               | —         |
| loading-color    | Loading-icon color                                                                                      | string                                                               | —         |
| ripple           | Click ripple                                                                                            | boolean                                                              | true      |
| handle-elevation | Thumb elevation: true means level 2; numbers are integer-clamped to 0–24                                | boolean / number                                                     | true      |

before-change returning false, throwing or rejecting cancels switching. Other normal completion allows it. While awaiting a Promise or done, loading is automatic and repeated input is blocked.
Pending results become stale after unmount, KeepAlive deactivation, external value updates or changes to disabled/readonly/loading.
Controlled mode only requests updates. Selection changes after the parent updates model-value. Without model-value, internal state is used.

### Events

| Event              | Arguments and timing                                                   |
| ------------------ | ---------------------------------------------------------------------- |
| click              | (event: Event), before interception when clicking is allowed           |
| update:model-value | (nextValue: SwitchValue), after switching is allowed and before change |
| change             | (nextValue: SwitchValue, event: Event), once per commit                |
| focus              | (event: FocusEvent), on focus                                          |
| blur               | (event: FocusEvent), on blur                                           |

Supports Enter/Space without repeated toggles on key repeat. disabled/loading emit neither click nor value changes; readonly may emit click without running the interceptor.
External model-value updates do not emit an extra change.

### Slots

| Slot           | Description                                                   | Arguments |
| -------------- | ------------------------------------------------------------- | --------- |
| checked        | Checked label; overrides checked-text; hidden for line/sm     | —         |
| unchecked      | Unchecked label; overrides unchecked-text; hidden for line/sm | —         |
| checked-icon   | Checked thumb icon; replaced while loading                    | —         |
| unchecked-icon | Unchecked thumb icon; replaced while loading                  | —         |

### Methods

No public methods.

### Platform notes

Props, event arguments and slots match. Cedar inherits omitted size from Form/global settings: xs/sm map to sm; lg/xl map to lg. Maple defaults to md. Both inherit disabled/readonly from field > FormItem > Form, with explicit false overriding the parent. Form integration is local to each platform.
<!-- same-source-api:end -->

### Types

SwitchProps, SwitchVariant, SwitchSize, SwitchValue, SwitchBeforeChange and SwitchInstance are exported from both root and component entries.

### Style variables

| Token: Cedar uses --c-, Maple uses --mp-                  | Default                                                 |
| --------------------------------------------------------- | ------------------------------------------------------- |
| --c-switch-width / height / handle-size                   | 40px / 24px / 16px                                      |
| --c-switch-size-sm-scale / size-lg-scale                  | .8 / 1.2                                                |
| --c-switch-tonal-width / tonal-height / tonal-handle-size | 52px / 32px / 24px                                      |
| --c-switch-line-height / line-handle-size                 | 12px / 20px                                             |
| --c-switch-hit-area                                       | 0px; outward hit-area expansion without changing layout |
| --c-switch-track-background / track-active-background     | Neutral / theme color                                   |
| --c-switch-handle-background / handle-color               | White / theme color                                     |
| --c-switch-disabled-opacity                               | .5                                                      |
| --c-switch-round-radius / gap                             | 4px / 4px                                               |

See style/token.less for all variables. Legacy platform-specific Switch geometry tokens are not guaranteed to remain.

## Migration

Maple standard becomes line. Omitting variant now selects circle. Both platforms use four variants; standard is not retained as an alias.
lazy-change is removed. before-change moves from a (value, change) callback to return-value/Promise control; applications no longer call change manually.
Maple change now includes the original event as its second argument. checked-color/unchecked-color control the track consistently; tokens customize thumbs.

### Color variables and tonal foreground migration

| Variable suffix: --c-switch- | Default system role | Responsibility                                                   |
| ---------------------------- | ------------------- | ---------------------------------------------------------------- |
| track-background             | content-secondary   | Ordinary unchecked solid track                                   |
| track-active-background      | content-brand       | Checked track and keyboard-focus ring                            |
| track-error-background       | content-danger      | Interactive error track and tonal error border                   |
| handle-background            | surface-default     | Ordinary/checked/error thumb fill                                |
| handle-color                 | content-brand       | Ordinary/checked/error thumb icon color                          |
| text-color                   | surface-default     | Text on a solid track                                            |
| checked-text-color           | switch-text-color   | Checked-track text; error retains existing foreground precedence |
| tonal-track-background       | surface-muted       | Tonal unchecked-track background                                 |
| tonal-border-color           | content-secondary   | Tonal unchecked border and thumb fill                            |
| tonal-text-color             | content-secondary   | Added: tonal unchecked-track text                                |
| tonal-handle-color           | surface-default     | Added: tonal unchecked-thumb icon                                |

Defaults reference matching system roles, e.g. var(--c-sys-color-content-secondary). Unchecked tonal uses tonal-text-color / tonal-handle-color; customize both ordinary and tonal foregrounds for all variants. Interactive errors use ordinary text/thumb pairing; disabled/loading suppress error colors. Custom tracks require foreground-contrast checks. Shadows, geometry and motion are outside this color contract.

### Theme names and variant names

Theme entries are Themes.default.light/dark and Themes.maple.light/dark. Switch tonal is a variant, not a theme. Public variants and eight dedicated variables consistently use tonal without old-name aliases.

### Motion variables

Built-in motion follows `prefers-reduced-motion: reduce`. Reduced motion does not prevent loading-state or close-event updates.

| Token                         | Default |
| ----------------------------- | ------- |
| `--c-switch-loading-duration` | `1s`    |

### Form field presentation and confirmation

This component supports `edit-mode` with field > FormItem > Form precedence. When unset, it defaults to `direct` and preserves `direct` editing. Supported values: `direct / click / dblclick`. Non-`direct` modes open the editor through the field value trigger and keep one draft; v-model updates only after confirmation. Cancel, reset or enabling readPretty discards the draft.

Cedar uses edit-mode="click" / "dblclick" to open an editor popup near the field. Enter/F2 also opens it; cancel/Escape discards the draft, and confirmation commits it. readPretty is an independent reading setting, separate from readonly and disabled.

`before-commit(value, { previousValue, signal })` can reject an overlay save. FormItem validates the candidate first and keeps the editor open on failure. `open / default-open / update:open` control the editor. Use `#read="{ value, text }"` to customize display. See the full field comparison in Form.

`read-pretty` is an independent boolean alongside `readonly` and `disabled`. It inherits from field to FormItem to Form; explicit `false` overrides the parent. The default is `false`. Reading mode renders no editor.

### Form state inheritance

Omitted `disabled` / `readonly` inherit FormItem, then Form; an explicit `false` overrides inherited state. Becoming `disabled` or read-only invalidates a pending `beforeChange`, so a late result cannot toggle the value. Outside a form, omitted values behave as `false`.

## Inheriting Form disabled state

The default disabled=undefined means inheritance, resolved as local ?? FormItem ?? Form ?? false. Explicit false remains effective, allowing one field to stay enabled while unspecified fields follow Form. Form disabled is the form-wide default, not a lock preventing child overrides.

`empty-value` accepts explicit `null` (or `() => null`). Clearing publishes `null` unchanged; omitted values preserve the existing default. Editors render `null` as blank without converting ordinary empty-string input to `null`. In popup editing, clearing changes the draft; confirm commits it and cancel preserves the original model.

```vue
<c-switch v-model="flag" :before-change="beforeChange" />
```

```ts
const beforeChange = (next, done) => {
  canChange(next).then((allowed) => done(allowed));
};
```

Cancellable hooks use `(payload, done, context)`: closure payloads contain `{ action }`, change/commit payloads contain `{ value, previousValue }`, and Popup uses `{ reason }`. Context provides `signal` and an optional original `event`. Return a boolean/Promise, or call done()/done(false). Synchronous void waits for done; Promise&lt;void&gt; allows the operation. First completion wins. Pending state controls loading/disabled automatically. Cancellation invalidates stale results. Button refs are not exposed.

### Before-hook waiting feedback

Before-hook waits show visible feedback and aria-busy. Rejected or failed operations recover; duplicate submissions do not start another copy. Notification event Promises never drive loading.

---

Document: llms/en-US/components/table-column-manager.md

<!-- Source: src/table-column-manager/README.en-US.md; locale: en-US; page: /en/components/table-column-manager/ -->

# Table Column Manager

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

- `options`: Supplies the available options.

Example source: src/table-column-manager/__demos__/basic.vue

```vue
<template>
  <c-space>
    <c-button @click="openDrawer = true">抽屉中管理列</c-button>
    <c-button @click="openDialog = true">弹窗中管理列</c-button>
  </c-space>

  <c-table-column-manager
    v-model:open="openDrawer"
    v-model="items"
    :columns="columns"
    :options="columnDefinitions"
    :fallback-item="fallbackItem"
    @confirm="applyResult"
  />

  <c-dialog v-model:open="openDialog" title="列管理" :width="720" :body-padding="false" unmount-on-close>
    <div style="height: 480px">
      <c-table-column-manager
        inline
        v-model="items"
        :columns="columns"
        :options="columnDefinitions"
      />
    </div>
  </c-dialog>

  <pre style="margin-top: 16px; font-size: 12px">
items: {{ items }}
columns: {{ columns.map((c) => c.dataIndex).join(', ') }}</pre
  >
</template>

<script setup lang="ts">
import { ref } from 'vue'
import type {
  ColumnDefinition,
  ColumnDefinitions,
  ColumnManagerItem,
  ColumnManagerResult,
  TableColumnData,
} from '@cedar-design/ui'

const openDrawer = ref(false)
const openDialog = ref(false)

const items = ref<ColumnManagerItem[]>([
  { dataIndex: 'connectorId', fixed: 'left' },
  { dataIndex: 'connectorName' },
  { dataIndex: 'deviceName' },
])

const columns = ref<TableColumnData[]>([
  { dataIndex: 'connectorId', title: '枪ID', width: 100, fixed: 'left' },
  { dataIndex: 'connectorName', title: '枪名称', width: 120 },
  { dataIndex: 'deviceName', title: '设备名称', width: 120 },
])

const columnDefinitions = ref<ColumnDefinitions>([
  {
    title: '基本信息',
    key: 'basic',
    children: [
      {
        dataIndex: 'connectorId',
        title: '枪ID',
        required: true,
        tip: '必选列',
      },
      {
        dataIndex: 'connectorName',
        title: '枪名称',
      },
      {
        dataIndex: 'areaCompany',
        title: '区域公司区域公司区域公司区域公司区域公司区域公司',
        tip: '区域公司说明',
      },
    ],
  },
  {
    title: '设备信息',
    key: 'device',
    children: [
      { dataIndex: 'deviceId', title: '设备ID' },
      { dataIndex: 'deviceName', title: '设备名称' },
      { dataIndex: 'lockStatus', title: '地锁' },
    ],
  },
  { dataIndex: 'workingStatus', title: '工作状态' },
  { dataIndex: 'connectStatus', title: '连接状态' },
])

const fallbackItem = (dataIndex: string): ColumnDefinition => {
  return { dataIndex, title: dataIndex }
}

const applyResult = (result: ColumnManagerResult) => {
  columns.value = result.columns
  items.value = result.items
}
</script>
```

## Table integration and persistence

### With Table Ungrouped

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `open` | Drawer visibility; `v-model:open` | With Table |
| `columns` | Current Table columns; assembled back into full definitions on confirmation | With Table |
| `options` | Left-side column definitions | With Table |
| `drawer-title` | Drawer title | With Table |
| `inline` | Render only the inline panel without a drawer | With Table |
<!-- demo-config-notes:end -->


Preview configuration: `v-model:columns="columns"`, `extra-column`, `column-resizable`, `:data="data"`.

Example source: src/table-column-manager/__demos__/with-table-ungrouped.vue

```vue
<template>
  <c-space direction="column" size="md">
    <c-alert type="info" :show-icon="false">
      不分组列示例：目录就是普通数组。工号为必选左冻结列，备注和入职日期默认隐藏；支持搜索、显隐、拖拽排序、冻结、删除、重命名和列宽记忆。
    </c-alert>

    <div class="demo-toolbar">
      <c-button status="secondary" size="sm" @click="open">管理列</c-button>
      <c-link @click="resetToDefault">恢复默认</c-link>
      <span class="demo-summary"
        >已展示 {{ leafColumns.length }} /
        {{ columnDefinitions.length }} 列</span
      >
    </div>

    <c-table
      v-model:columns="columns"
      extra-column
      column-resizable
      :data="data"
      :pagination="false"
      :bordered="{ cell: true, headerCell: true }"
      size="xs"
      @column-resize="handleColumnResize"
    >
      <template #extra-column-header>
        <c-button variant="text" size="xs" aria-label="管理列" @click="open"
          ><c-icon-settings
        /></c-button>
      </template>
      <template #extra-column-cell />

      <template #header-cell-actions="{ column, dataIndex }">
        <HeaderAction :data-index="dataIndex" :column="column" />
      </template>

      <template #status="{ record }">
        <c-tag :color="record.status === '在职' ? 'green' : 'gray'" size="sm">{{
          record.status
        }}</c-tag>
      </template>
    </c-table>

    <c-table-column-manager v-bind="managerProps" />
  </c-space>
</template>

<script setup lang="ts">
import { ref } from "vue";
import { useTableColumnManager } from "@cedar-design/ui";
import type { ColumnDefinitions, ManagedTableColumn } from "@cedar-design/ui";

const defaultColumns: ManagedTableColumn[] = [
  {
    dataIndex: "employeeId",
    title: "工号",
    manager: { required: true },
    fixed: "left",
    width: 110,
  },
  { dataIndex: "name", title: "姓名", minWidth: 140 },
  { dataIndex: "department", title: "部门", width: 140 },
  { dataIndex: "position", title: "职位", minWidth: 160 },
  { dataIndex: "phone", title: "手机号", width: 150 },
  { dataIndex: "status", title: "状态", width: 100, slotName: "status" },
];

const columnDefinitions: ColumnDefinitions = [
  {
    dataIndex: "employeeId",
    title: "工号",
    tip: "必选规则来自 defaultColumns",
  },
  { dataIndex: "name", title: "姓名" },
  { dataIndex: "department", title: "部门" },
  { dataIndex: "position", title: "职位" },
  { dataIndex: "phone", title: "手机号" },
  { dataIndex: "status", title: "状态" },
  { dataIndex: "joinedAt", title: "入职日期" },
  { dataIndex: "remark", title: "备注", tip: "不在默认列中，可从弹窗添加" },
];

const {
  columns,
  managerProps,
  leafColumns,
  open,
  handleColumnResize,
  HeaderAction,
  resetToDefault,
} = useTableColumnManager({
  defaultColumns,
  columnDefinitions,
  columnDefaults: { width: 130, ellipsis: true },
  createColumn: (definition) =>
    definition.dataIndex === "remark"
      ? {
          dataIndex: definition.dataIndex,
          title: definition.title,
          minWidth: 220,
          width: undefined,
        }
      : { dataIndex: definition.dataIndex, title: definition.title },
});

const data = ref([
  {
    employeeId: "E-1001",
    name: "张三",
    department: "产品研发部",
    position: "前端工程师",
    phone: "138****1024",
    status: "在职",
    joinedAt: "2023-04-18",
    remark: "负责组件库和中后台基础设施",
  },
  {
    employeeId: "E-1002",
    name: "李四",
    department: "质量保障部",
    position: "测试工程师",
    phone: "139****3072",
    status: "在职",
    joinedAt: "2022-11-07",
    remark: "负责自动化测试平台",
  },
  {
    employeeId: "E-1003",
    name: "王五",
    department: "数据平台部",
    position: "数据分析师",
    phone: "136****8841",
    status: "离职",
    joinedAt: "2021-08-23",
    remark: "历史项目成员",
  },
]);
</script>

<style scoped>
.demo-toolbar {
  display: flex;
  align-items: center;
  gap: 12px;
}

.demo-summary {
  margin-left: auto;
  color: var(--c-color-text-3);
}
</style>
```

### With Table Header Menu

Preview configuration: `checked-text="fit"`, `unchecked-text="fit"`, `size="sm"`, `checked-text="fixed"`.

Example source: src/table-column-manager/__demos__/with-table-header-menu.vue

```vue
<template>
  <c-space direction="column" size="md">
    <c-alert type="info" :show-icon="false">
      分组列示例：左侧 <code>优先级</code> 冻结，右侧 <code>状态</code> 冻结；
      <code>名称</code>、<code>更新时间</code> 只设
      <code>min-width</code> 作为弹性列。表格始终铺满父容器：<code>fit</code>
      开启时剩余空间按 min-width
      比例分给弹性列，关闭时按各列宽度比例放大；extra-column 固定 28px
      不参与分配。<code>table-layout="auto"</code> 时 colgroup 不渲染
      <code>col</code>，列宽交给浏览器按内容分配，且不显示拖拽把手（拖拽仅
      <code>fixed</code> 布局可用）。
    </c-alert>

    <c-space wrap size="16px" align="center">
      <c-button status="secondary" size="sm" @click="open">列管理</c-button>
      <c-link @click="resetToDefault">重置</c-link>
      <c-switch
        v-model="fit"
        checked-text="fit"
        unchecked-text="fit"
        size="sm"
      />
      <c-switch
        v-model="isFixedLayout"
        checked-text="fixed"
        unchecked-text="auto"
        size="sm"
      />
      <span style="color: var(--c-color-text-3); margin-left: 8px">
        当前 {{ leafColumns.length }} 列
      </span>
    </c-space>

    <c-space wrap size="8px" align="center">
      <c-tag
        v-for="col in leafColumns"
        :key="col.dataIndex"
        size="sm"
        color="gray"
      >
        {{ col.title }}
        <template v-if="col.width"> · {{ col.width }}px</template>
        <template v-if="col.fixed"
          >（{{ col.fixed === "left" ? "左冻" : "右冻" }}）</template
        >
      </c-tag>
    </c-space>

    <c-table
      v-model:columns="columns"
      extra-column
      column-resizable
      :data="data"
      :pagination="false"
      :bordered="{ cell: true, headerCell: true }"
      :fit="fit"
      :table-layout="tableLayout"
      size="xs"
      @column-resize="handleColumnResize"
    >
      <template #extra-column-header>
        <c-button variant="text" size="xs" aria-label="管理列" @click="open">
          <c-icon-settings />
        </c-button>
      </template>
      <template #extra-column-cell />

      <template #header-cell-actions="{ column, dataIndex }">
        <HeaderAction :data-index="dataIndex" :column="column" />
      </template>

      <template #priority="{ record }">
        <c-tag :color="priorityColor(record.priority)" size="sm">{{
          record.priority
        }}</c-tag>
      </template>
      <template #status="{ record }">
        <c-tag :color="statusColor(record.status)" size="sm">{{
          record.status
        }}</c-tag>
      </template>
    </c-table>

    <!-- 列管理抽屉 + 插入/编辑弹窗 -->
    <c-table-column-manager v-bind="managerProps" />
  </c-space>
</template>

<script lang="ts" setup>
import { computed, onMounted, ref, watch } from "vue";
import { useTableColumnManager } from "@cedar-design/ui";
import type { ColumnDefinitions, ManagedTableColumn } from "@cedar-design/ui";

const STORAGE_KEY = "cedar-demo:table-column-manager:with-table-header-menu";
let storage: Storage | undefined;
const storageReady = ref(false);

const fit = ref(true);
// fixed：列宽由布局引擎计算写入 col，不被内容撑开；auto：不渲染 col，交给浏览器按内容分配
const tableLayout = ref<"fixed" | "auto">("fixed");
const isFixedLayout = computed({
  get: () => tableLayout.value === "fixed",
  set: (val: boolean) => {
    tableLayout.value = val ? "fixed" : "auto";
  },
});

const defaultColumns: ManagedTableColumn[] = [
  {
    title: "基本信息",
    children: [
      {
        dataIndex: "priority",
        title: "优先级",
        manager: { required: true },
        fixed: "left",
        width: 120,
        slotName: "priority",
      },
      {
        dataIndex: "name",
        title: "名称",
        minWidth: 200,
      },
      {
        dataIndex: "bizLine",
        title: "业务线",
        width: 120,
      },
    ],
  },
  {
    title: "人员与状态",
    children: [
      {
        dataIndex: "owner",
        title: "负责人",
        width: 100,
      },
      {
        dataIndex: "updatedAt",
        title: "更新时间",
        minWidth: 140,
      },
      {
        dataIndex: "status",
        title: "状态",
        fixed: "right",
        width: 120,
        slotName: "status",
      },
    ],
  },
];

// 候选定义只服务于弹窗展示和搜索，不重复配置 Table 宽度、插槽或必选规则。
const columnDefinitions: ColumnDefinitions = [
  {
    key: "base",
    title: "基本信息",
    children: [
      {
        dataIndex: "priority",
        title: "优先级",
        tip: "必选规则来自 defaultColumns",
      },
      { dataIndex: "name", title: "名称" },
      { dataIndex: "bizLine", title: "业务线" },
      {
        dataIndex: "description",
        title: "任务描述",
        tip: "候选的新列，通过 createColumn 设置特殊宽度",
      },
    ],
  },
  {
    key: "people",
    title: "人员与状态",
    children: [
      { dataIndex: "owner", title: "负责人" },
      { dataIndex: "updatedAt", title: "更新时间" },
      { dataIndex: "status", title: "状态" },
      { dataIndex: "deadline", title: "截止时间" },
    ],
  },
];

// ---------- 核心：一行接入列管理 ----------

const manager = useTableColumnManager({
  defaultColumns,
  columnDefinitions,
  // 普通新增列统一使用该默认 Table 配置。
  columnDefaults: { width: 140, ellipsis: true },
  // 少量特殊候选列在这里补充本地渲染配置。
  createColumn: (definition) =>
    definition.dataIndex === "description"
      ? {
          dataIndex: definition.dataIndex,
          title: definition.title,
          minWidth: 240,
          width: undefined,
        }
      : { dataIndex: definition.dataIndex, title: definition.title },
});
const {
  columns,
  state,
  restore,
  managerProps,
  leafColumns,
  open,
  handleColumnResize,
  HeaderAction,
  resetToDefault: resetManagerToDefault,
} = manager;

// 持久化属于业务层：组件和 useTableColumnManager 不读写 localStorage。
onMounted(async () => {
  storage = window.localStorage;
  try {
    const raw = storage.getItem(STORAGE_KEY);
    if (raw) await restore(JSON.parse(raw));
  } catch {
    storage.removeItem(STORAGE_KEY);
  } finally {
    storageReady.value = true;
  }
});

watch(
  state,
  (value) => {
    if (!storageReady.value) return;
    storage?.setItem(STORAGE_KEY, JSON.stringify(value));
  },
  { deep: true },
);

const resetToDefault = () => {
  storage?.removeItem(STORAGE_KEY);
  resetManagerToDefault();
};

// ---------- 渲染辅助 ----------

const priorityColor = (value: string) => {
  if (value === "P0") return "red";
  if (value === "P1") return "orange";
  return "gray";
};

const statusColor = (value: string) => {
  if (value === "进行中") return "blue";
  if (value === "已完成") return "green";
  if (value === "已阻塞") return "red";
  return "gray";
};

const data = ref([
  {
    priority: "P0",
    name: "任务 A",
    bizLine: "交易",
    description: "修复支付链路并补充异常监控",
    owner: "张三",
    updatedAt: "2026-07-21 10:30",
    status: "进行中",
    deadline: "2026-08-10",
  },
  {
    priority: "P1",
    name: "任务 B",
    bizLine: "物流",
    description: "优化仓配系统的库存同步效率",
    owner: "李四",
    updatedAt: "2026-07-22 14:00",
    status: "已完成",
    deadline: "2026-08-05",
  },
  {
    priority: "P0",
    name: "任务 C",
    bizLine: "交易",
    description: "排查高峰期订单重复提交问题",
    owner: "王五",
    updatedAt: "2026-07-25 09:15",
    status: "已阻塞",
    deadline: "2026-08-12",
  },
]);
</script>
```

### With Table

- `options`: Supplies the available options.

Example source: src/table-column-manager/__demos__/with-table.vue

```vue
<template>
  <c-space direction="column" size="md">
    <c-alert type="info" :show-icon="false">
      <code>c-table-column-manager</code> 自身包含抽屉；弹窗场景传入
      <code>inline</code> 后以内联面板形式放入自定义容器。
    </c-alert>

    <c-space wrap size="8px" justify="flex-end">
      <c-button variant="outline" @click="openAs('drawer')"
        >抽屉管理列</c-button
      >
      <c-button variant="outline" @click="openAs('dialog')"
        >弹窗管理列</c-button
      >
    </c-space>

    <c-table
      v-model:columns="columns"
      :data="data"
      :pagination="false"
      size="xs"
    />

    <!-- 抽屉模式：组件自带抽屉 -->
    <c-table-column-manager
      v-if="container === 'drawer'"
      v-model:open="visible"
      v-model="items"
      :columns="columns"
      :options="columnDefinitions"
      drawer-title="列管理"
      @confirm="handleConfirm"
    />

    <!-- 弹窗模式：inline 内联面板放入 c-dialog -->
    <c-dialog
      v-else
      v-model:open="visible"
      title="列管理"
      :width="720"
      :body-padding="false"
      unmount-on-close
    >
      <div style="height: 480px">
        <c-table-column-manager
          inline
          v-model:open="visible"
          v-model="items"
          :columns="columns"
          :options="columnDefinitions"
          @confirm="handleConfirm"
        />
      </div>
    </c-dialog>
  </c-space>
</template>

<script setup lang="ts">
import { ref, watch } from "vue";
import { stateFromColumns } from "@cedar-design/ui";
import type {
  ColumnDefinitions,
  ColumnManagerResult,
  TableColumnData,
} from "@cedar-design/ui";

const visible = ref(false);
const container = ref<"drawer" | "dialog">("drawer");
const items = ref([]);

const columns = ref<TableColumnData[]>([
  { dataIndex: "name", title: "姓名", width: 120, fixed: "left" },
  { dataIndex: "salary", title: "薪资", width: 100 },
  { dataIndex: "address", title: "地址" },
]);

const columnDefinitions: ColumnDefinitions = [
  {
    title: "基础信息",
    key: "basic",
    children: [
      { dataIndex: "name", title: "姓名", required: true, tip: "必选列" },
      { dataIndex: "salary", title: "薪资" },
      { dataIndex: "email", title: "邮箱" },
    ],
  },
  {
    title: "扩展信息",
    key: "extra",
    children: [
      { dataIndex: "address", title: "地址" },
      { dataIndex: "department", title: "部门" },
      {
        dataIndex: "action",
        title: "操作",
      },
    ],
  },
];

const syncManagerState = () => {
  const state = stateFromColumns(columns.value, columnDefinitions);
  items.value = state.items;
};

watch(visible, (val) => {
  if (val) syncManagerState();
});

const openAs = (type: "drawer" | "dialog") => {
  container.value = type;
  visible.value = true;
};

const handleConfirm = (result: ColumnManagerResult) => {
  columns.value = result.columns;
};
</script>
```

## Async catalog and search

### Remote

Preview configuration: `v-model:columns="columns"`, `:data="data"`, `:pagination="false"`, `size="xs"`.

Example source: src/table-column-manager/__demos__/remote.vue

```vue
<template>
  <c-space direction="column" size="md">
    <c-alert type="info" :show-icon="false">
      弹窗候选列由 <code>columnSource.search</code> 远程搜索；恢复缓存遇到本地未知列时，通过
      <code>columnSource.resolve</code> 批量反显。远程接口只返回 dataIndex、title 和分组信息。
    </c-alert>

    <div class="demo-toolbar">
      <c-button status="secondary" size="sm" @click="open">远程管理列</c-button>
      <c-link @click="resetToDefault">恢复本地默认列</c-link>
    </div>

    <c-table v-model:columns="columns" :data="data" :pagination="false" size="xs" />
    <c-table-column-manager v-bind="managerProps" />
  </c-space>
</template>

<script setup lang="ts">
import { onMounted, ref } from 'vue'
import { useTableColumnManager } from '@cedar-design/ui'
import type { ColumnDefinition, ColumnDefinitionSource, ManagedTableColumn } from '@cedar-design/ui'

const defaultColumns: ManagedTableColumn[] = [
  { dataIndex: 'id', title: '编号', width: 100, fixed: 'left', manager: { required: true } },
  { dataIndex: 'name', title: '名称', minWidth: 180 },
]

// 模拟服务端保存的轻量字段目录。
const remoteFields: Array<ColumnDefinition & { group?: string }> = [
  { dataIndex: 'id', title: '编号', group: '基础信息' },
  { dataIndex: 'name', title: '名称', group: '基础信息' },
  { dataIndex: 'owner', title: '负责人', group: '基础信息' },
  { dataIndex: 'remoteConfig1', title: '远程配置 1', group: '远程配置' },
  { dataIndex: 'remoteConfig2', title: '远程配置 2', group: '远程配置' },
  { dataIndex: 'remoteStatus', title: '远程状态', group: '远程配置' },
]

const wait = (duration: number) => new Promise((resolve) => setTimeout(resolve, duration))
const groupDefinitions = (items: typeof remoteFields) =>
  [...new Set(items.map((item) => item.group ?? '其他'))].map((group) => ({
    key: group,
    title: group,
    children: items
      .filter((item) => (item.group ?? '其他') === group)
      .map(({ group: _group, ...definition }) => definition),
  }))

const columnSource: ColumnDefinitionSource = {
  async search({ keyword }) {
    await wait(300)
    const normalized = keyword.trim().toLowerCase()
    const matched = normalized
      ? remoteFields.filter(
          (item) => item.title.toLowerCase().includes(normalized) || item.dataIndex.toLowerCase().includes(normalized)
        )
      : remoteFields
    return { items: groupDefinitions(matched), total: matched.length }
  },
  async resolve(dataIndexes) {
    await wait(200)
    const keys = new Set(dataIndexes)
    return remoteFields.filter((item) => keys.has(item.dataIndex)).map(({ group: _group, ...item }) => item)
  },
}

const { columns, managerProps, open, restore, resetToDefault } = useTableColumnManager({
  defaultColumns,
  columnSource,
  columnDefaults: { width: 140, ellipsis: true },
  createColumn: (definition) =>
    definition.dataIndex === 'remoteStatus'
      ? { dataIndex: definition.dataIndex, title: definition.title, width: 110 }
      : { dataIndex: definition.dataIndex, title: definition.title },
})

onMounted(async () => {
  // 模拟缓存中包含一个不在本地 defaultColumns 里的远程列。
  await restore({
    version: 2,
    items: [{ dataIndex: 'id', fixed: 'left' }, { dataIndex: 'name' }, { dataIndex: 'remoteConfig2' }],
  })
})

const data = ref([
  {
    id: 'T-001',
    name: '远程字段示例',
    owner: '张三',
    remoteConfig1: '配置 A',
    remoteConfig2: '配置 B',
    remoteStatus: '已同步',
  },
])
</script>

<style scoped>
.demo-toolbar {
  display: flex;
  align-items: center;
  gap: 12px;
}
</style>
```

## API

### State and persistence structure

Column order, titles and fixed positions are stored together in `items`. The component/`useTableColumnManager` do not cache state. Business code may persist
the following state to localStorage, Pinia or a server:

```ts
const state: ColumnManagerState = {
  version: 2,
  items: [
    { dataIndex: 'id', fixed: 'left', width: 120 },
    { dataIndex: 'name', title: 'User name' },
  ],
  layout: [],
}
```

This is a major breaking change: legacy `keys`, `fixedMap` and `titleMap` structures are no longer read.

```ts
const { state, restore } = useTableColumnManager({ defaultColumns, columnDefinitions })
const storageReady = ref(false)

onMounted(async () => {
  const raw = window.localStorage.getItem(STORAGE_KEY)
  if (raw) await restore(JSON.parse(raw))
  storageReady.value = true
})

watch(
  state,
  (value) => {
    if (!storageReady.value) return
    window.localStorage.setItem(STORAGE_KEY, JSON.stringify(value))
  },
  { deep: true }
)
```

`restore()` validates versions, removes stale/duplicate columns, cleans invalid widths/layouts, adds `required` columns and repairs fixed-region ordering.
`state` records only user-renamed titles and widths changed through `handleColumnResize`. Debounce server persistence in business code if needed.

### Default columns and candidate definitions

`defaultColumns` supplies complete initial Table columns and the reset baseline. `columnDefinitions` supplies popup candidates only and may contain just
`dataIndex`, `title`, grouping and hints:

```ts
const defaultColumns: ManagedTableColumn[] = [
  {
    title: 'Basic information',
    children: [
      {
        dataIndex: 'id',
        title: 'ID',
        fixed: 'left',
        width: 120,
        manager: { required: true },
      },
      { dataIndex: 'name', title: 'Name', minWidth: 180 },
    ],
  },
]

const columnDefinitions: ColumnDefinitions = [
  {
    key: 'base',
    title: 'Basic information',
    children: [
      { dataIndex: 'id', title: 'ID' },
      { dataIndex: 'name', title: 'Name' },
      { dataIndex: 'remark', title: 'Notes', tip: 'Optional column' },
    ],
  },
]

const manager = useTableColumnManager({
  defaultColumns,
  columnDefinitions,
  columnDefaults: { width: 140, ellipsis: true },
  createColumn: (definition) => ({ dataIndex: definition.dataIndex, title: definition.title }),
})
```

- `defaultColumns` determines initial display, reset, default width, fixed position, slots, rendering and `manager.required`.
- `columnDefinitions` determines popup candidates, not Table rendering configuration.
- `columnDefaults` supplies common Table defaults for new ordinary columns.
- `createColumn` handles a few candidates requiring special width, slots or rendering.
- For remote data, `columnSource.search` searches and `columnSource.resolve` restores unknown selected columns. `restore()` then returns a Promise.

### `<TableColumnManager>` Props

| Parameter | Description | Type | Default |
| ------------- | ---------------------------------- | ------------------------------------------------------- | ---------- |
| model-value | Complete ordered selected-column state, including titles/fixed positions | `ColumnManagerItem[]` | `-` |
| default-value | Initial uncontrolled selected state | `ColumnManagerItem[]` | `-` |
| columns | Current Table columns; assembled back into full definitions on confirmation | `TableColumnData[]` | `[]` |
| options | Left-side column definitions | `ColumnDefinitions` | `[]` |
| load-options | Asynchronously load column definitions | `() => Promise<ColumnDefinitions>` | `-` |
| remote-search | Remote search; hides top select-all when provided | `(keyword: string) => Promise<void>` | `-` |
| fallback-item | Resolve display for values absent from definitions | `(dataIndex: string) => ColumnDefinition \| undefined` | `-` |
| insert-at | Insertion context determining where new columns land | `{ dataIndex: string; side: 'left' \| 'right' }` | `-` |
| open | Drawer visibility; `v-model:open` | `boolean` | `-` |
| drawer-title | Drawer title | `string` | `自定义列` |
| drawer-width | Drawer width | `number \| string` | `720` |
| inline | Render only the inline panel without a drawer | `boolean` | `false` |
| placeholder | Search placeholder | `string` | `-` |

### Events

| Event | Description | Arguments |
| ----------------- | ------------------------------- | --------------------- |
| update:model-value | Complete selected-state changes | `ColumnManagerItem[]` |
| update:open | Drawer visibility changes | `boolean` |
| confirm | Assembled result after drawer/dialog confirmation | `ColumnManagerResult` |
| change | Selection, order, fixed-position or title changes | `ColumnManagerItem[]` |

### Methods

| Method | Description | Returns |
| ----------- | ------------------------ | --------------------- |
| getResult | Assemble Table columns from current selection | `ColumnManagerResult` |
| loadCatalog | Manually invoke `loadOptions` | `Promise<void>` |

### `useTableColumnManager`

Recommended with `c-table`. Returns `columns`, `state`, `restore`, `managerProps`, `HeaderAction` and others.
`HeaderAction` obtains context directly through `inject`; templates only need:

```vue
<template #header-cell-actions="{ column, dataIndex }">
  <HeaderAction :data-index="dataIndex" :column="column" />
</template>
```

`headerActions` configures visible header-action keys; all are shown by default.

Header-action behavior:

- Insert left/right: new columns enter the anchor's first-level group, preserving group titles/`colspan`. If the anchor is fixed, new columns inherit its fixed position.
- Fix/unfix: reorder leaf columns so fixed columns collect at the left/right edge.
- Edit columns: edit first-level group titles and column names; adjacent equal-name groups merge automatically.

Required rules need declaration only in `defaultColumns`. Transfer, clearing and header deletion all follow them:

```ts
{
  dataIndex: 'priority',
  title: 'Priority',
  manager: { required: true },
  fixed: 'left',
  width: 120,
  slotName: 'priority',
}
```

`columnDefinitions` need not duplicate width, fixed-position or required rules. User-resized widths persist in `items[].width`.

### Extra-column width

`c-table` `extra-column`, e.g. a settings control, defaults to 28px. Override with `extraColumn: { width: number }`.

### Utility functions in the column-management package

`buildColumnsResult` / `stateFromColumns` / `applyColumnEdit` / `applyColumnFixed` / `applyInsertToLayout` / `mapLeafColumns` support external assembly, group editing, fixed reordering and insertion. Traverse `columns` in business code for flat leaf lists; Table exports are unnecessary.

Catalog loading and remote searching own independent pending state; older completion cannot unlock newer work. loadOptions runs at creation, loader replacement and explicit loadCatalog calls. Manual calls retain Promise rejection; automatic reads use the Vue error path. Hook catalog/search jobs share current catalog ownership, restore has its own ownership, and newer column edits or disposal invalidate older restore results.

---

Document: llms/en-US/components/table.md

<!-- Source: src/table/README.en-US.md; locale: en-US; page: /en/components/table/ -->

# Table

## Basic examples

### Basic usage

Example source: src/table/__demos__/basic.vue

```vue
<script setup lang="ts">
const columns = [
  { title: 'Name', dataIndex: 'name' },
  { title: 'Salary', dataIndex: 'salary' },
  { title: 'Address', dataIndex: 'address' },
]
const data = [
  { key: '1', name: 'Jane Doe', salary: 23000, address: '32 Park Road, London' },
  { key: '2', name: 'Alisa Ross', salary: 25000, address: '35 Park Road, London' },
  { key: '3', name: 'Kevin Sandra', salary: 22000, address: '31 Park Road, London' },
]
</script>
<template>
  <c-table :columns="columns" :data="data" :pagination="false" />
</template>
```

### Manual loading

Boolean/object loading applies to both data and native-slot modes. Object options require `loading: true`. Rows and drafts remain mounted; notifications do not manage loading.

Example source: src/table/__demos__/loading.vue

```vue
<template>
  <c-space direction="column" style="width: 100%">
    <c-space
      ><c-switch v-model="loading" edit-mode="direct" /><span
        >手动控制两种表格的加载状态</span
      ></c-space
    >
    <c-table
      :columns="columns"
      :data="data"
      :loading="loading"
      :pagination="false"
    />
    <c-table :loading="loading" :pagination="false">
      <thead>
        <tr>
          <th>原生插槽</th>
          <th>保留编辑内容</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <td>切换加载不会重建行</td>
          <td><input v-model="draft" aria-label="表格草稿" /></td>
        </tr>
      </tbody>
    </c-table>
    <small>loading 仅由业务状态控制。输入草稿后切换加载，内容继续保留。</small>
  </c-space>
</template>
<script setup lang="ts">
import { ref } from "vue";
const loading = ref(false);
const draft = ref("可编辑草稿");
const columns = [{ title: "数据模式", dataIndex: "name" }];
const data = [{ key: "row", name: "与原生插槽使用相同的 loading 合同" }];
</script>
```

### Empty State

- `columns`: Column info of the table
- `data`: Table data
- `pagination`: Pagination properties configuration

Example source: src/table/__demos__/empty-state.vue

```vue
<script setup lang="ts">
const columns = [{ title: 'Name', dataIndex: 'name' }, { title: 'Address', dataIndex: 'address' }]
</script>
<template>
  <c-table :columns="columns" :data="[]" :pagination="false">
    <template #empty>暂无记录，请调整筛选条件后重试。</template>
  </c-table>
</template>
```

## Column widths, layout and fixed columns

### Column width scenarios

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `columns` | Column info of the table | Column width scenarios, Fixed columns, Grouped headers with fixed columns |
| `data` | Table data | Column width scenarios, Fixed columns, Grouped headers with fixed columns |
| `pagination` | Pagination properties configuration | Column width scenarios, Layout, sizing and column resizing |
| `bordered` | Whether to show border | Grouped headers with fixed columns, Layout, sizing and column resizing |
| `sticky-pagination` | Sticky pagination relative to the page/outer scroller; numeric values are bottom offsets in px | Column width scenarios |
| `row-selection` | Table row selector configuration | Column width scenarios |
<!-- demo-config-notes:end -->


Container width and column width are separate settings. Use `style="width: 100%"` or `style="width: 480px"` for the container, and `columns[].width` / `minWidth` for individual columns. No `scroll.x` or `scroll.y` configuration is required.

Compare seven combinations and switch between 100%, 480px and 360px to observe recalculation and horizontal overflow.

| Configuration | Distribution with default `table-layout="fixed"`, `fit=true` |
| --- | --- |
| No column width | Each column starts at 80px and shares remaining space proportionally |
| `minWidth` | Base width of a flexible column; overflow preserves this width |
| `width` plus flexible columns | Explicit widths remain exact; flexible columns share remaining space in proportion to their base widths |
| Every column has `width` | Preserve widths on overflow; proportionally enlarge ordinary data columns when they do not fill the container |
| `fit=false` | Still fill the container; distribute remaining space proportionally across ordinary data columns |
| Selection / extra columns | Preserve selection operation width; exclude the extra column from proportional expansion |

Flexible columns have no explicit `width`. `minWidth` does not turn an explicit-width column into a flexible column. These distribution rules apply to `fixed` layout.

Example source: src/table/__demos__/column-width-scenarios.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
import type { TableColumnData } from '@cedar-design/ui'

const tableWidth = ref('100%')
const data = [{ key: '1', name: '设备巡检', owner: '张三', status: '进行中' }]
const base: TableColumnData[] = [
  { title: '任务', dataIndex: 'name' },
  { title: '负责人', dataIndex: 'owner' },
  { title: '状态', dataIndex: 'status' },
]
const scenarios = [
  { title: '不指定列宽', description: '每列以 80px 为基础，均分剩余空间。', columns: base },
  { title: '全部使用 minWidth', description: '按 160 : 80 : 80 的基础宽度比例分配剩余空间。', columns: base.map((column, index) => ({ ...column, minWidth: index === 0 ? 160 : 80 })) },
  { title: '定宽列与弹性列混合', description: '负责人、状态各保持 120px，任务列吸收剩余空间。', columns: base.map((column, index) => ({ ...column, ...(index === 0 ? { minWidth: 160 } : { width: 120 }) })) },
  { title: '全部指定 width', description: '列宽之和不足容器时，Cedar 按比例放大普通数据列以铺满容器。', columns: base.map((column, index) => ({ ...column, width: index === 0 ? 160 : 80 })) },
  { title: '列宽之和超出容器', description: '三列各 280px，保留列宽并自动出现横向滚动条，无需 scroll.x。', columns: base.map(column => ({ ...column, width: 280 })) },
  { title: '左右固定列与混合列宽', description: '左右各固定 140px、120px，中间列 minWidth 为 440px；无需 scroll.x，底部粘性滚动条随表格悬浮显示。', columns: [{ ...base[0], width: 140, fixed: 'left' as const }, { ...base[1], minWidth: 440 }, { ...base[2], width: 120, fixed: 'right' as const }], sticky: true },
  { title: '选择列、弹性列与扩展列', description: '选择列保持 40px，扩展列保持 28px，任务列分配剩余空间。', columns: base.map((column, index) => ({ ...column, ...(index === 0 ? { minWidth: 160 } : { width: 120 }) })), operations: true },
]
</script>

<template>
  <div class="column-width-scenarios">
    <c-radio-group v-model="tableWidth" type="button" aria-label="表格宽度">
      <c-radio value="480px">定宽 480px</c-radio>
      <c-radio value="100%">100% 宽度</c-radio>
      <c-radio value="360px">窄屏 360px</c-radio>
    </c-radio-group>
    <section v-for="scenario in scenarios" :key="scenario.title">
      <h4>{{ scenario.title }}</h4>
      <p>{{ scenario.description }}</p>
      <c-table
        :columns="scenario.columns"
        :data="data"
        :style="{ width: tableWidth }"
        :pagination="scenario.sticky ? { pageSize: 5 } : false"
        :sticky-pagination="scenario.sticky ? 0 : false"
        :row-selection="scenario.operations ? { width: 40 } : undefined"
        :extra-column="scenario.operations"
      />
    </section>
  </div>
</template>

<style scoped>
.column-width-scenarios { width: 640px; max-width: 100%; }
.column-width-scenarios > section { margin-top: 24px; }
h4 { margin: 0 0 8px; }
p { margin: 0 0 12px; }
</style>
```

### Fixed columns

Set `fixed: 'left'` or `fixed: 'right'` on a column. Explicit widths are recommended. Horizontal overflow is detected automatically.

Example source: src/table/__demos__/fixed.vue

```vue
<template>
  <c-table :columns="columns" :data="data" :height="200" :expandable="expandable" />
</template>

<script lang="ts" setup>
import { reactive } from 'vue'
const columns = [
  {
    title: 'Name',
    dataIndex: 'name',
    fixed: 'left',
    width: 140,
  },
  {
    title: 'Salary',
    dataIndex: 'salary',
    minWidth: 200,
  },
  {
    title: 'Address',
    dataIndex: 'address',
    minWidth: 400,
  },
  {
    title: 'Email',
    dataIndex: 'email',
    fixed: 'right',
    width: 200,
  },
]

const expandable = {
  title: 'Expand',
  width: 80,
}

const data = reactive([
  {
    key: '1',
    name: 'Jane Doe',
    salary: 23000,
    address: '32 Park Road, London',
    email: 'jane.doe@example.com',
    expand: 'Expand Content',
  },
  {
    key: '2',
    name: 'Alisa Ross',
    salary: 25000,
    address: '35 Park Road, London',
    email: 'alisa.ross@example.com',
  },
  {
    key: '3',
    name: 'Kevin Sandra',
    salary: 22000,
    address: '31 Park Road, London',
    email: 'kevin.sandra@example.com',
  },
  {
    key: '4',
    name: 'Ed Hellen',
    salary: 17000,
    address: '42 Park Road, London',
    email: 'ed.hellen@example.com',
  },
  {
    key: '5',
    name: 'William Smith',
    salary: 27000,
    address: '62 Park Road, London',
    email: 'william.smith@example.com',
  },
])
</script>
```

### Grouped headers with fixed columns

Configure fixed positions on leaf columns. Mark a whole group as fixed only when all its leaf columns belong to the same fixed side.

Example source: src/table/__demos__/columns-children-and-fixed.vue

```vue
<template>
  <c-table :columns="columns" :data="data" :bordered="{ cell: true }" />
</template>

<script lang="ts" setup>
import { reactive } from 'vue'
const columns = [
  {
    title: 'Name',
    dataIndex: 'name',
    fixed: 'left',
    width: 140,
  },
  {
    title: 'User Info',
    children: [
      {
        title: 'Birthday',
        dataIndex: 'birthday',
        fixed: 'left',
        width: 200,
      },
      {
        title: 'Address',
        children: [
          {
            title: 'City',
            dataIndex: 'city',
            fixed: 'left',
            width: 100,
          },
          {
            title: 'Road',
            dataIndex: 'road',
            minWidth: 200,
          },
          {
            title: 'No.',
            dataIndex: 'no',
            minWidth: 120,
          },
        ],
      },
    ],
  },
  {
    title: 'Information',
    children: [
      {
        title: 'Email',
        dataIndex: 'email',
        minWidth: 240,
      },
      {
        title: 'Phone',
        dataIndex: 'phone',
        minWidth: 160,
      },
    ],
  },
  {
    title: 'Salary',
    dataIndex: 'salary',
    fixed: 'right',
    width: 120,
  },
]
const data = reactive([
  {
    key: '1',
    name: 'Jane Doe',
    salary: 23000,
    birthday: '1994-04-21',
    city: 'London',
    road: 'Park',
    no: '34',
    phone: '12345678',
    email: 'jane.doe@example.com',
  },
  {
    key: '2',
    name: 'Alisa Ross',
    salary: 25000,
    birthday: '1994-05-21',
    city: 'London',
    road: 'Park',
    no: '37',
    phone: '12345678',
    email: 'alisa.ross@example.com',
  },
  {
    key: '3',
    name: 'Kevin Sandra',
    salary: 22000,
    birthday: '1992-02-11',
    city: 'Paris',
    road: 'Cedar',
    no: '67',
    phone: '12345678',
    email: 'kevin.sandra@example.com',
  },
  {
    key: '4',
    name: 'Ed Hellen',
    salary: 17000,
    birthday: '1991-06-21',
    city: 'London',
    road: 'Park',
    no: '317',
    phone: '12345678',
    email: 'ed.hellen@example.com',
  },
  {
    key: '5',
    name: 'William Smith',
    salary: 27000,
    birthday: '1996-08-21',
    city: 'Paris',
    road: 'Park',
    no: '114',
    phone: '12345678',
    email: 'william.smith@example.com',
  },
])
</script>
```

### Layout, sizing and column resizing

Compare the same columns by switching layout, fit, grouped headers, resizing and container width in one table.

| Configuration | Behavior |
| --- | --- |
| `table-layout="fixed"` (default) | Computed widths are written to `<col>`; long content does not stretch columns arbitrarily |
| `table-layout="auto"` | The browser allocates actual widths based on content; fixed-column offsets use measured widths |
| `column-resizable` | Resize handles appear only in `fixed` layout; resized widths participate in recalculation |
| `max-height` or column `ellipsis` | Force `fixed` layout |

An explicit `width` stays exact with flexible columns and `fit=true`. If every column has a width, or `fit=false`, proportional expansion still fills the container.

Example source: src/table/__demos__/en-US/column-sizing-playground.vue

```vue
<script setup lang="ts">
import ColumnSizingPlayground from '../column-sizing-playground.vue'
</script>
<template>
  <ColumnSizingPlayground english />
</template>
```

### Automatic scrolling and height

Horizontal overflow follows computed total column width and available container width. Use `height` for a fixed body height or `max-height` for a shrinking body that scrolls when needed. Without either constraint, the page or outer container owns vertical scrolling. Sticky positioning is controlled separately by `sticky-header` / `sticky-pagination`. With horizontal overflow and sticky pagination enabled, hovering over Table or focusing inside Table reveals the synchronized bottom scrollbar.

See the next group for height, header and pagination combinations.

## Headers and column structure

### Columns Children

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `columns` | Column info of the table | Columns Children, Ellipsis And Tooltip, Span Method |
| `data` | Table data | Columns Children, Ellipsis And Tooltip, Span Method |
| `bordered` | Whether to show border | Columns Children, Span Method |
| `span-method` | Cell merge method (The index starts counting from the data item) | Span Method |
| `row-selection` | Table row selector configuration | Span Method |
| `span-all` | Whether to make the index of the span method contain all | Span Method |
<!-- demo-config-notes:end -->


- `columns`: Column info of the table
- `data`: Table data
- `bordered`: Whether to show the border

Example source: src/table/__demos__/columns-children.vue

```vue
<template>
  <c-table :columns="columns" :data="data" :bordered="{ headerCell: true }" />
</template>

<script lang="ts" setup>
import { reactive } from 'vue'
const columns = [
  {
    title: 'Name',
    dataIndex: 'name',
    fixed: 'left',
    width: 140,
  },
  {
    title: 'User Info',
    children: [
      {
        title: 'Birthday',
        dataIndex: 'birthday',
      },
      {
        title: 'Address',
        children: [
          {
            title: 'City',
            dataIndex: 'city',
          },
          {
            title: 'Road',
            dataIndex: 'road',
          },
          {
            title: 'No.',
            dataIndex: 'no',
          },
        ],
      },
    ],
  },
  {
    title: 'Information',
    children: [
      {
        title: 'Email',
        dataIndex: 'email',
      },
      {
        title: 'Phone',
        dataIndex: 'phone',
      },
    ],
  },
  {
    title: 'Salary',
    dataIndex: 'salary',
    fixed: 'right',
    width: 120,
  },
]
const data = reactive([
  {
    key: '1',
    name: 'Jane Doe',
    salary: 23000,
    birthday: '1994-04-21',
    city: 'London',
    road: 'Park',
    no: '34',
    phone: '12345678',
    email: 'jane.doe@example.com',
  },
  {
    key: '2',
    name: 'Alisa Ross',
    salary: 25000,
    birthday: '1994-05-21',
    city: 'London',
    road: 'Park',
    no: '37',
    phone: '12345678',
    email: 'alisa.ross@example.com',
  },
  {
    key: '3',
    name: 'Kevin Sandra',
    salary: 22000,
    birthday: '1992-02-11',
    city: 'Paris',
    road: 'Cedar',
    no: '67',
    phone: '12345678',
    email: 'kevin.sandra@example.com',
  },
  {
    key: '4',
    name: 'Ed Hellen',
    salary: 17000,
    birthday: '1991-06-21',
    city: 'London',
    road: 'Park',
    no: '317',
    phone: '12345678',
    email: 'ed.hellen@example.com',
  },
  {
    key: '5',
    name: 'William Smith',
    salary: 27000,
    birthday: '1996-08-21',
    city: 'Paris',
    road: 'Park',
    no: '114',
    phone: '12345678',
    email: 'william.smith@example.com',
  },
])
</script>
```

### Ellipsis And Tooltip

- `columns`: Column info of the table
- `data`: Table data

Example source: src/table/__demos__/ellipsis-and-tooltip.vue

```vue
<template>
  <c-table :columns="columns" :data="data" />
</template>

<script lang="ts" setup>
import { reactive } from 'vue'
const columns = [
  {
    title: 'Name',
    dataIndex: 'name',
    ellipsis: true,
    tooltip: true,
    width: 100,
  },
  {
    title: 'Salary',
    dataIndex: 'salary',
  },
  {
    title: 'Address',
    dataIndex: 'address',
    ellipsis: true,
    width: 150,
  },
  {
    title: 'Email',
    dataIndex: 'email',
    ellipsis: true,
    tooltip: { placement: 'left' },
    width: 200,
  },
]
const data = reactive([
  {
    key: '1',
    name: 'Jane Doe',
    salary: 23000,
    address: '32 Park Road, London',
    email: 'jane.doe@example.com',
  },
  {
    key: '2',
    name: 'Alisa Ross',
    salary: 25000,
    address: '35 Park Road, London',
    email: 'alisa.ross@example.com',
  },
  {
    key: '3',
    name: 'Kevin Sandra',
    salary: 22000,
    address: '31 Park Road, London',
    email: 'kevin.sandra@example.com',
  },
  {
    key: '4',
    name: 'Ed Hellen',
    salary: 17000,
    address: '42 Park Road, London',
    email: 'ed.hellen@example.com',
  },
  {
    key: '5',
    name: 'William Smith',
    salary: 27000,
    address: '62 Park Road, London',
    email: 'william.smith@example.com',
  },
])
</script>
```

### Span Method

- `columns`: Column info of the table
- `data`: Table data
- `span-method`: Cell merge method (The index starts counting from the data item)
- `bordered`: Whether to show the border

Example source: src/table/__demos__/span-method.vue

```vue
<template>
  <c-space direction="column" size="lg" style="width: 100%">
    <c-table :columns="columns" :data="data" :span-method="spanMethod" />
    <c-table :columns="columns" :data="data" :span-method="dataSpanMethod" :bordered="{ wrapper: true, cell: true }" />
    <c-table
      :columns="columns"
      :data="data"
      :row-selection="{ type: 'checkbox' }"
      :span-method="spanMethodAll"
      span-all
      :bordered="{ wrapper: true, cell: true }" />
  </c-space>
</template>

<script lang="ts" setup>
const spanMethod = ({ rowIndex, columnIndex }) => {
  if (rowIndex === 1 && columnIndex === 1) {
    return {
      rowspan: 2,
      colspan: 3,
    }
  }
}
const dataSpanMethod = ({ record, column }) => {
  if (record.name === 'Alisa Ross' && column.dataIndex === 'salary') {
    return {
      rowspan: 2,
    }
  }
}
const spanMethodAll = ({ rowIndex, columnIndex }) => {
  if (rowIndex === 1 && columnIndex === 0) {
    return { rowspan: 2 }
  }

  if (rowIndex === 1 && columnIndex === 2) {
    return {
      rowspan: 2,
      colspan: 3,
    }
  }
}
const columns = [
  {
    title: 'Name',
    dataIndex: 'name',
  },
  {
    title: 'Salary',
    dataIndex: 'salary',
  },
  {
    title: 'Address',
    dataIndex: 'address',
  },
  {
    title: 'Email',
    dataIndex: 'email',
  },
]
const data = [
  {
    key: '1',
    name: 'Jane Doe',
    salary: 23000,
    address: '32 Park Road, London',
    email: 'jane.doe@example.com',
  },
  {
    key: '2',
    name: 'Alisa Ross',
    salary: 25000,
    address: '35 Park Road, London',
    email: 'alisa.ross@example.com',
  },
  {
    key: '3',
    name: 'Kevin Sandra',
    salary: 22000,
    address: '31 Park Road, London',
    email: 'kevin.sandra@example.com',
  },
  {
    key: '4',
    name: 'Ed Hellen',
    salary: 17000,
    address: '42 Park Road, London',
    email: 'ed.hellen@example.com',
  },
  {
    key: '5',
    name: 'William Smith',
    salary: 27000,
    address: '62 Park Road, London',
    email: 'william.smith@example.com',
  },
]
</script>
```

### Summary

- `columns`: Column info of the table
- `data`: Table data
- `summary`: Show footer summary row
- `summary-span-method`: Cell Merge Method for Summarizing Rows

Example source: src/table/__demos__/summary.vue

```vue
<template>
  <c-table :columns="columns" :data="data" :summary="true" :summary-span-method="spanMethod" />
  <c-table :columns="columns" :data="data" :height="200" :expandable="expandable" :summary="summary">
    <template #summary-cell="{ column, record, rowIndex }">
      <div :style="getColorStyle(column, record)">{{ record[column.dataIndex] }}</div>
    </template>
  </c-table>
</template>

<script lang="ts" setup>
import { reactive } from 'vue'
const expandable = {
  title: 'Expand',
  width: 80,
}
const columns = reactive([
  {
    title: 'Name',
    dataIndex: 'name',
    fixed: 'left',
    width: 140,
  },
  {
    title: 'Salary',
    dataIndex: 'salary',
    minWidth: 200,
    summaryCellStyle: (record) => {
      if (record.salary > 100000) {
        return {
          backgroundColor: 'rgb(var(--brand-6))',
          color: '#fff',
        }
      }
    },
  },
  {
    title: 'Data1',
    dataIndex: 'data1',
    minWidth: 300,
  },
  {
    title: 'Data2',
    dataIndex: 'data2',
    minWidth: 300,
  },
])
const data = reactive([
  {
    key: '1',
    name: 'Jane Doe',
    salary: 23000,
    data1: 10,
    data2: 8,
    expand: 'Expand Content',
  },
  {
    key: '2',
    name: 'Alisa Ross',
    salary: 25000,
    data1: 9,
    data2: -12,
  },
  {
    key: '3',
    name: 'Kevin Sandra',
    salary: 22000,
    data1: 15,
    data2: -2,
  },
  {
    key: '4',
    name: 'Ed Hellen',
    salary: 17000,
    data1: 2,
    data2: 3,
  },
  {
    key: '5',
    name: 'William Smith',
    salary: 27000,
    data1: 11,
    data2: 0,
  },
])

const summary = ({ columns, data }) => {
  let countData = {
    salary: 0,
    data1: 0,
    data2: 0,
  }
  data.forEach((record) => {
    countData.salary += record.salary
    countData.data1 += record.data1
    countData.data2 += record.data2
  })

  return [
    {
      name: 'Avg',
      salary: countData.salary / data.length,
      data1: countData.data1 / data.length,
      data2: countData.data2 / data.length,
    },
    {
      name: 'Sum',
      salary: countData.salary,
      data1: countData.data1,
      data2: countData.data2,
    },
  ]
}

const getColorStyle = (column, record) => {
  if (['data1', 'data2'].includes(column.dataIndex)) {
    return { color: record[column.dataIndex] > 0 ? 'red' : 'green' }
  }
  return undefined
}

const spanMethod = ({ rowIndex, columnIndex }) => {
  if (rowIndex === 0 && columnIndex === 1) {
    return {
      colspan: 2,
    }
  }
}
</script>
```

## Scrolling and sticky positioning

### Scroll

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `columns` | Column info of the table | Scroll, Fluid Height, Fixed Column And Header |
| `data` | Table data | Scroll, Fluid Height, Fixed Column And Header |
| `pagination` | Pagination properties configuration | Scroll, Fluid Height, Fixed Column And Header |
| `height` | Table height; fixes the header and scrolls the body. Numbers are px | Scroll, Fixed Column And Header |
| `sticky-header` | Sticky header relative to the page/outer scroller; numeric values are top offsets in px | Sticky Header, Sticky header, pagination and horizontal scrolling |
| `sticky-pagination` | Sticky pagination relative to the page/outer scroller; numeric values are bottom offsets in px | Sticky Panation, Sticky header, pagination and horizontal scrolling |
<!-- demo-config-notes:end -->


- `columns`: Column info of the table
- `data`: Table data
- `height`: Table height. Fixes the header and scrolls the body when set. Number values are in px
- `pagination`: Pagination properties configuration

Example source: src/table/__demos__/scroll.vue

```vue
<template>
  <div style="margin-bottom: 16px">
    <c-switch v-model="scrollbar" />
    Virtual Scrollbar
  </div>
  <p style="margin-bottom: 8px">固定高度 <code>height</code>：表头固定，表体纵向滚动。</p>
  <c-table :columns="columns" :data="data" :height="200" :pagination="false" :scrollbar="scrollbar" />
  <br />
  <p style="margin-bottom: 8px">百分比高度：外层定高，表格 <code>height="100%"</code> 填满。</p>
  <div style="height: 220px">
    <c-table :columns="columns" :data="data" height="100%" :pagination="false" :scrollbar="scrollbar" />
  </div>
</template>

<script lang="ts" setup>
import { reactive, ref } from 'vue'

const scrollbar = ref(true)

const columns = [
  {
    title: 'Name',
    dataIndex: 'name',
    width: 140,
  },
  {
    title: 'Salary',
    dataIndex: 'salary',
    minWidth: 120,
  },
  {
    title: 'Address',
    dataIndex: 'address',
    minWidth: 200,
  },
  {
    title: 'Email',
    dataIndex: 'email',
    minWidth: 180,
  },
]

const data = reactive(
  Array.from({ length: 8 }, (_, index) => ({
    key: String(index + 1),
    name: `User ${index + 1}`,
    salary: 17000 + index * 1000,
    address: `${30 + index} Park Road, London`,
    email: `user.${index + 1}@example.com`,
  })),
)
</script>
```

### Fluid Height

- `columns`: Column info of the table
- `data`: Table data
- `max-height`: Table max height. Table shrinks when content is short; body scrolls when exceeded. Number values are in px
- `pagination`: Pagination properties configuration

Example source: src/table/__demos__/fluid-height.vue

```vue
<template>
  <p style="margin-bottom: 8px">
    <code>max-height</code> 场景下会强制 <code>table-layout: fixed</code>（与 Element 一致）。内容少时表格收缩，超出后表体滚动；可点按钮增减行观察。
  </p>
  <c-table :columns="columns" :data="data" :max-height="250" :pagination="false" />
  <c-button style="margin-top: 12px; width: 100%" @click="onAddItem">Add Item</c-button>
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const columns = [
  {
    title: 'Date',
    dataIndex: 'date',
    fixed: 'left',
    width: 150,
  },
  {
    title: 'Name',
    dataIndex: 'name',
    width: 120,
  },
  {
    title: 'State',
    dataIndex: 'state',
    width: 120,
  },
  {
    title: 'City',
    dataIndex: 'city',
    width: 120,
  },
  {
    title: 'Address',
    dataIndex: 'address',
    width: 600,
  },
  {
    title: 'Zip',
    dataIndex: 'zip',
    width: 120,
  },
  {
    title: 'Operations',
    dataIndex: 'operations',
    fixed: 'right',
    minWidth: 120,
  },
]

let seed = 3
const data = ref([
  {
    key: '1',
    date: '2016-05-01',
    name: 'Tom',
    state: 'California',
    city: 'Los Angeles',
    address: 'No. 189, Grove St, Los Angeles',
    zip: 'CA 90036',
    operations: 'Remove',
  },
  {
    key: '2',
    date: '2016-05-02',
    name: 'Tom',
    state: 'California',
    city: 'Los Angeles',
    address: 'No. 189, Grove St, Los Angeles',
    zip: 'CA 90036',
    operations: 'Remove',
  },
  {
    key: '3',
    date: '2016-05-03',
    name: 'Tom',
    state: 'California',
    city: 'Los Angeles',
    address: 'No. 189, Grove St, Los Angeles',
    zip: 'CA 90036',
    operations: 'Remove',
  },
])

const onAddItem = () => {
  seed += 1
  data.value.push({
    key: String(seed),
    date: `2016-05-${String(seed).padStart(2, '0')}`,
    name: 'Tom',
    state: 'California',
    city: 'Los Angeles',
    address: 'No. 189, Grove St, Los Angeles',
    zip: 'CA 90036',
    operations: 'Remove',
  })
}
</script>
```

### Fixed Column And Header

- `columns`: Column info of the table
- `data`: Table data
- `height`: Table height. Fixes the header and scrolls the body when set. Number values are in px
- `pagination`: Pagination properties configuration

Example source: src/table/__demos__/fixed-column-and-header.vue

```vue
<template>
  <p style="margin-bottom: 8px">
    同时设置 <code>height</code> 与左右 <code>fixed</code> 列：表头固定 + 横向滚动时固定列保持可见。
  </p>
  <c-table :columns="columns" :data="data" :height="250" :pagination="false" />
</template>

<script lang="ts" setup>
import { reactive } from 'vue'

const columns = [
  {
    title: 'Date',
    dataIndex: 'date',
    fixed: 'left',
    width: 150,
  },
  {
    title: 'Name',
    dataIndex: 'name',
    width: 120,
  },
  {
    title: 'State',
    dataIndex: 'state',
    width: 120,
  },
  {
    title: 'City',
    dataIndex: 'city',
    width: 120,
  },
  {
    title: 'Address',
    dataIndex: 'address',
    minWidth: 600,
  },
  {
    title: 'Zip',
    dataIndex: 'zip',
    width: 120,
  },
  {
    title: 'Operations',
    dataIndex: 'operations',
    fixed: 'right',
    width: 120,
  },
]

const data = reactive(
  Array.from({ length: 10 }, (_, index) => ({
    key: String(index + 1),
    date: `2016-05-${String(index + 1).padStart(2, '0')}`,
    name: 'Tom',
    state: 'California',
    city: 'Los Angeles',
    address: 'No. 189, Grove St, Los Angeles',
    zip: 'CA 90036',
    operations: 'Detail',
  })),
)
</script>
```

### Sticky Header

- `columns`: Column info of the table
- `data`: Table data
- `sticky-header`: Sticky header relative to the page/outer scroll container (not table body scroll). Number is top offset in px
- `pagination`: Pagination properties configuration

Example source: src/table/__demos__/sticky-header.vue

```vue
<template>
  <p style="margin-bottom: 8px; color: var(--color-text-3); font-size: 13px">
    <code>sticky-header</code> 相对页面/外层滚动容器吸顶。传数字可指定距顶部偏移，例如导航高度
    <code>60</code> → <code>top: 60px</code>。请滚动文档页查看效果。
  </p>
  <c-table :columns="columns" :data="data" :sticky-header="60" :pagination="false" />
</template>

<script lang="ts" setup>
import { reactive } from 'vue'

const columns = [
  {
    title: 'Name',
    dataIndex: 'name',
    width: 140,
  },
  {
    title: 'Salary',
    dataIndex: 'salary',
    minWidth: 120,
  },
  {
    title: 'Address',
    dataIndex: 'address',
    minWidth: 200,
  },
  {
    title: 'Email',
    dataIndex: 'email',
    minWidth: 180,
  },
]

const data = reactive(
  Array.from({ length: 40 }, (_, index) => ({
    key: String(index + 1),
    name: `User ${index + 1}`,
    salary: 17000 + index * 500,
    address: `${30 + (index % 20)} Park Road, London`,
    email: `user.${index + 1}@example.com`,
  })),
)
</script>
```

### Sticky Panation

- `columns`: Column info of the table
- `data`: Table data
- `sticky-pagination`: Sticky pagination relative to the page/outer scroll container. Number is bottom offset in px
- `pagination`: Pagination properties configuration

Example source: src/table/__demos__/sticky-panation.vue

```vue
<template>
  <p style="margin-bottom: 8px; color: var(--color-text-3); font-size: 13px">
    <code>sticky-pagination</code> 相对<strong>页面/外层滚动容器</strong>吸底。适合长列表翻页时分页条常驻视口底部；数字为距底部偏移（px）。
  </p>
  <c-table
    :columns="columns"
    :data="data"
    sticky-pagination
    :pagination="{ pageSize: 20 }"
  />
</template>

<script lang="ts" setup>
import { reactive } from 'vue'

const columns = [
  {
    title: 'Name',
    dataIndex: 'name',
    width: 140,
  },
  {
    title: 'Salary',
    dataIndex: 'salary',
    minWidth: 120,
  },
  {
    title: 'Address',
    dataIndex: 'address',
    minWidth: 200,
  },
  {
    title: 'Email',
    dataIndex: 'email',
    minWidth: 180,
  },
]

const data = reactive(
  Array.from({ length: 80 }, (_, index) => ({
    key: String(index + 1),
    name: `User ${index + 1}`,
    salary: 17000 + index * 500,
    address: `${30 + (index % 20)} Park Road, London`,
    email: `user.${index + 1}@example.com`,
  })),
)
</script>
```

### Sticky header, pagination and horizontal scrolling

Example source: src/table/__demos__/en-US/sticky-layout.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const pageScroll = ref(false)
const custom = ref(false)
const external = ref(false)
const pagerHost = ref<HTMLElement>()
const page = ref(1)
const rows = Array.from({ length: 160 }, (_, index) => ({ key: index + 1, name: `User ${index + 1}`, city: 'Shanghai', email: `user${index + 1}@example.com`, description: `Rightmost field ${index + 1}` }))
const columns = [{ title: 'Name', dataIndex: 'name', width: 200 }, { title: 'City', dataIndex: 'city', width: 200 }, { title: 'Email', dataIndex: 'email', width: 360 }, { title: 'Description', dataIndex: 'description', width: 480 }]
</script>
<template>
 <c-space direction="column">
  <c-space>
   <c-checkbox v-model="pageScroll">Page scrolling</c-checkbox>
   <c-checkbox v-model="custom">Custom pagination</c-checkbox>
   <c-checkbox v-model="external">Move footer outside Table</c-checkbox>
  </c-space>
  <p>The outer container scrolls; Table has no height or vertical scroll setting. Switch to page scrolling to verify the same header/footer.</p>
  <p role="status">Page: {{ page }}</p>
  <div :class="['sticky-table-demo', { 'sticky-table-demo--page': pageScroll }]">
   <c-table
    :columns="columns" :data="rows"
    :sticky-header="0" :sticky-pagination="0"
    :pagination="{ modelValue: page, pageSize: 40, container: external ? pagerHost : undefined }"
    @page-change="page = $event"
   >
    <template v-if="custom" #pagination="{ page: current, pageSize, total, onChange }">
     <c-space>
      <c-button :disabled="current <= 1" @click="onChange(current - 1)">Previous</c-button>
      <span>{{ current }} / {{ Math.max(1, Math.ceil(total / pageSize)) }}</span>
      <c-button :disabled="current * pageSize >= total" @click="onChange(current + 1)">Next</c-button>
     </c-space>
    </template>
   </c-table>
   <div ref="pagerHost" class="sticky-table-pagination-host" />
  </div>
 </c-space>
</template>
<style scoped>
.sticky-table-demo { max-height: 420px; overflow: auto; isolation: isolate; }
.sticky-table-demo--page { max-height: none; overflow: visible; }
.sticky-table-pagination-host { display: contents; }
</style>
```

sticky-header and sticky-pagination follow the page or outer scroll container. A numeric zero enables the feature with zero offset. This differs from using height/max-height to constrain internal body scrolling. Avoid an extra overflow:hidden ancestor that interrupts sticky positioning.

Built-in sticky pagination keeps a synchronized horizontal rail above the pagination in the same sticky footer. The rail follows body scroll in both directions, and is omitted when content fits. Pagination no longer obscures the only reachable horizontal scroll control.

| Property | Behavior |
| --- | --- |
| pagination=true | Built-in pagination with its defaults |
| pagination={ pageSize, total, ... } | Configure built-in pagination; total does not fetch server data |
| pagination=false | No built-in pagination UI or slicing; the caller owns the current-page rows |
| sticky-header=true or number | Stick the header; a number sets its top offset |
| sticky-pagination=true or number | Stick the pagination and horizontal rail; a number sets its bottom offset |
| style="width: 100%" | Set the table container width; column widths determine horizontal overflow automatically |

For external pagination, pass pagination=false and render a separate Pagination component. Slice local data before passing it to Table, or request a server page. The business layout owns positioning and scrollbar clearance in that mode. The example switches between built-in sticky pagination and this fully external mode.

### Replace pagination content inside the managed footer

The pagination slot receives { page, pageSize, total, onChange, onPageSizeChange }. Render a business pagination component there to replace the built-in widget while Table keeps data slicing and the scrollbar-above-pagination layout. Keep this content in normal flow inside the footer. pagination=false instead disables the entire built-in pagination protocol.

`--c-table-sticky-scrollbar-height` sets the minimum horizontal rail height (16px by default); intrinsic sizing also reserves the native scrollbar height.

### Mount pagination externally

`pagination.container` accepts a CSS selector or HTMLElement. Omitting it keeps the footer inside Table. Only placement changes: page state, slicing, events and the sticky horizontal rail remain managed by Table. No slot or separate pager state is required. Keep the host in the same scroll context and use display: contents when needed. The target must exist; Vue 3.5 defer supports targets created in the same render batch. SSR hosts must handle Teleport output. pagination=false still disables Table pagination and slicing entirely.

```vue
<c-table
  :data="rows" :columns="columns"
  :sticky-header="0" :sticky-pagination="0"
  :pagination="{ pageSize: 10, total: 500, container: '#table-pagination' }"
/>
<div id="table-pagination" style="display: contents" />
```

The sticky layout demo provides an outer scrolling container. Table itself has no height/max-height or vertical scroll limit. Toggle page scrolling, custom pagination, and an external footer host. The Table-owned footer groups the synchronized horizontal scrollbar and the pagination slot, and moves them together when pagination.container is set. The external host must remain in the intended scrolling/layout boundary; arbitrary destinations do not remove CSS sticky constraints.

Sticky pagination suppresses the internal horizontal thumb/native scrollbar and reuses the shared Scrollbar in embed mode above the footer. It appears while the pointer is over Table or keyboard focus is inside Table, including when the footer is mounted externally; dragging, track clicks and trackpad scrolling remain synchronized. Vertical scrolling remains owned by the demo container unless Table height/max-height is explicitly set.

## Selection and data interaction

### Row Selection

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `columns` | Column info of the table | Row Selection, Row Selection Single, Expandable |
| `data` | Table data | Row Selection, Row Selection Single, Expandable |
| `row-selection` | Table row selector configuration | Row Selection, Row Selection Single, Tree Children |
| `draggable` | Table drag and drop sorting configuration | Droppable Table, Droppable Anchor |
| `selected-keys` | Selected row (controlled mode) takes precedence over `rowSelection` | Row Selection |
| `pagination` | Pagination properties configuration | Row Selection |
<!-- demo-config-notes:end -->


- `selected-keys`: Selected row (controlled mode) takes precedence over `rowSelection`
- `columns`: Column info of the table
- `data`: Table data
- `pagination`: Pagination properties configuration

Example source: src/table/__demos__/row-selection.vue

```vue
<template>
  <c-space direction="column" fill size="lg">
    <div>
      <span>OnlyCurrent:</span>
      <c-switch v-model="rowSelection.onlyCurrent" />
    </div>
    <c-table
      v-model:selectedKeys="selectedKeys"
      :columns="columns"
      :data="data"
      :pagination="pagination"
      :row-selection="rowSelection"
      row-key="name" />
  </c-space>
</template>

<script lang="ts" setup>
import { reactive, ref } from 'vue'
const selectedKeys = ref(['Jane Doe', 'Alisa Ross'])

const rowSelection = reactive({
  type: 'checkbox',
  showCheckedAll: true,
  onlyCurrent: false,
})
const pagination = { pageSize: 5 }

const columns = [
  {
    title: 'Name',
    dataIndex: 'name',
  },
  {
    title: 'Salary',
    dataIndex: 'salary',
  },
  {
    title: 'Address',
    dataIndex: 'address',
  },
  {
    title: 'Email',
    dataIndex: 'email',
  },
]
const data = reactive([
  {
    key: '1',
    name: 'Jane Doe',
    salary: 23000,
    address: '32 Park Road, London',
    email: 'jane.doe@example.com',
  },
  {
    key: '2',
    name: 'Alisa Ross',
    salary: 25000,
    address: '35 Park Road, London',
    email: 'alisa.ross@example.com',
  },
  {
    key: '3',
    name: 'Kevin Sandra',
    salary: 22000,
    address: '31 Park Road, London',
    email: 'kevin.sandra@example.com',
    disabled: true,
  },
  {
    key: '4',
    name: 'Ed Hellen',
    salary: 17000,
    address: '42 Park Road, London',
    email: 'ed.hellen@example.com',
  },
  {
    key: '5',
    name: 'William Smith',
    salary: 27000,
    address: '62 Park Road, London',
    email: 'william.smith@example.com',
  },
  {
    key: '6',
    name: 'Jane Doe 2',
    salary: 15000,
    address: '32 Park Road, London',
    email: 'jane.doe@example.com',
  },
  {
    key: '7',
    name: 'Alisa Ross 2',
    salary: 28000,
    address: '35 Park Road, London',
    email: 'alisa.ross@example.com',
  },
  {
    key: '8',
    name: 'Kevin Sandra 2',
    salary: 26000,
    address: '31 Park Road, London',
    email: 'kevin.sandra@example.com',
  },
  {
    key: '9',
    name: 'Ed Hellen 2',
    salary: 18000,
    address: '42 Park Road, London',
    email: 'ed.hellen@example.com',
  },
  {
    key: '10',
    name: 'William Smith 2',
    salary: 12000,
    address: '62 Park Road, London',
    email: 'william.smith@example.com',
  },
])
</script>
```

### Row Selection Single

- `columns`: Column info of the table
- `data`: Table data
- `row-selection`: Table row selector configuration

Example source: src/table/__demos__/row-selection-single.vue

```vue
<template>
  <c-table :columns="columns" :data="data" :row-selection="rowSelection" />
</template>

<script lang="ts" setup>
import { reactive } from 'vue'
const rowSelection = {
  type: 'radio',
}
const columns = [
  {
    title: 'Name',
    dataIndex: 'name',
  },
  {
    title: 'Salary',
    dataIndex: 'salary',
  },
  {
    title: 'Address',
    dataIndex: 'address',
  },
  {
    title: 'Email',
    dataIndex: 'email',
  },
]
const data = reactive([
  {
    key: '1',
    name: 'Jane Doe',
    salary: 23000,
    address: '32 Park Road, London',
    email: 'jane.doe@example.com',
  },
  {
    key: '2',
    name: 'Alisa Ross',
    salary: 25000,
    address: '35 Park Road, London',
    email: 'alisa.ross@example.com',
  },
  {
    key: '3',
    name: 'Kevin Sandra',
    salary: 22000,
    address: '31 Park Road, London',
    email: 'kevin.sandra@example.com',
  },
  {
    key: '4',
    name: 'Ed Hellen',
    salary: 17000,
    address: '42 Park Road, London',
    email: 'ed.hellen@example.com',
  },
  {
    key: '5',
    name: 'William Smith',
    salary: 27000,
    address: '62 Park Road, London',
    email: 'william.smith@example.com',
  },
])
</script>
```

### Expandable

- `columns`: Column info of the table
- `data`: Table data
- `expandable`: Expand row configuration of the table

Example source: src/table/__demos__/expandable.vue

```vue
<template>
  <c-table :columns="columns" :data="data" :expandable="expandable" />
</template>

<script lang="ts" setup>
import { reactive } from 'vue'
const expandable = reactive({
  title: 'Expand',
  width: 80,
  expandedRowRender: (record) => {
    if (record.key === '3') {
      return `My Name is ${record.name}`
    }
  },
})

const columns = [
  {
    title: 'Name',
    dataIndex: 'name',
  },
  {
    title: 'Salary',
    dataIndex: 'salary',
  },
  {
    title: 'Address',
    dataIndex: 'address',
  },
  {
    title: 'Email',
    dataIndex: 'email',
  },
]

const data = reactive([
  {
    key: '1',
    name: 'Jane Doe',
    salary: 23000,
    address: '32 Park Road, London',
    email: 'jane.doe@example.com',
    expand: 'Expand Data',
  },
  {
    key: '2',
    name: 'Alisa Ross',
    salary: 25000,
    address: '35 Park Road, London',
    email: 'alisa.ross@example.com',
  },
  {
    key: '3',
    name: 'Kevin Sandra',
    salary: 22000,
    address: '31 Park Road, London',
    email: 'kevin.sandra@example.com',
  },
  {
    key: '4',
    name: 'Ed Hellen',
    salary: 17000,
    address: '42 Park Road, London',
    email: 'ed.hellen@example.com',
  },
  {
    key: '5',
    name: 'William Smith',
    salary: 27000,
    address: '62 Park Road, London',
    email: 'william.smith@example.com',
  },
])
</script>
```

### Tree Children

- `columns`: Column info of the table
- `data`: Table data
- `expanded-keys`: Displayed Expanded Row, Subtree (Controlled Mode) takes precedence over `expandable`
- `row-selection`: Table row selector configuration

Example source: src/table/__demos__/tree-children.vue

```vue
<template>
  <c-space>
    <span>checkStrictly:</span>
    <c-switch v-model="rowSelection.checkStrictly" />
  </c-space>
  <c-table
    :columns="columns"
    :data="data"
    v-model:expandedKeys="expandedKeys"
    :row-selection="rowSelection"
    show-empty-tree
    style="margin-top: 20px" />
</template>

<script lang="ts" setup>
import { ref, reactive } from 'vue'
const expandedKeys = ref([])

const rowSelection = reactive({
  type: 'checkbox',
  showCheckedAll: true,
  checkStrictly: true,
})

const columns = [
  {
    title: 'Name',
    dataIndex: 'name',
  },
  {
    title: 'Salary',
    dataIndex: 'salary',
  },
  {
    title: 'Address',
    dataIndex: 'address',
  },
  {
    title: 'Email',
    dataIndex: 'email',
  },
]
const data = [
  {
    key: '1',
    name: 'Jane Doe',
    salary: 23000,
    address: '32 Park Road, London',
    email: 'jane.doe@example.com',
    children: [
      {
        key: '2',
        name: 'Alisa Ross',
        salary: 25000,
        address: '35 Park Road, London',
        email: 'alisa.ross@example.com',
        children: [
          {
            key: '3',
            name: 'Ed Hellen',
            salary: 17000,
            address: '42 Park Road, London',
            email: 'ed.hellen@example.com',
          },
          {
            key: '4',
            name: 'William Smith',
            salary: 27000,
            address: '62 Park Road, London',
            email: 'william.smith@example.com',
          },
        ],
      },
      {
        key: '5',
        name: 'Alisa Ross',
        salary: 25000,
        address: '35 Park Road, London',
        email: 'alisa.ross@example.com',
      },
    ],
  },
  {
    key: '6',
    name: 'Alisa Ross',
    salary: 25000,
    address: '35 Park Road, London',
    email: 'alisa.ross@example.com',
  },
  {
    key: '7',
    name: 'Kevin Sandra',
    salary: 22000,
    address: '31 Park Road, London',
    email: 'kevin.sandra@example.com',
  },
  {
    key: '8',
    name: 'Ed Hellen',
    salary: 17000,
    address: '42 Park Road, London',
    email: 'ed.hellen@example.com',
  },
  {
    key: '9',
    name: 'William Smith',
    salary: 27000,
    address: '62 Park Road, London',
    email: 'william.smith@example.com',
    children: [],
  },
]
</script>
```

### Sort And Filter

- `columns`: Column info of the table
- `data`: Table data
- `filter-icon-align-left`: Whether the filter icon is aligned to the left

Example source: src/table/__demos__/sort-and-filter.vue

```vue
<template>
  <c-space direction="column" size="lg" fill>
    <c-space>
      <c-switch v-model="alignLeft" />
      <span>Filter icon align left: {{ alignLeft }}</span>
    </c-space>
    <c-table :columns="columns" :data="data" :filter-icon-align-left="alignLeft" @change="handleChange" />
  </c-space>
</template>

<script lang="ts" setup>
import { reactive, ref } from 'vue'
const alignLeft = ref(false)

const columns = [
  {
    title: 'Name',
    dataIndex: 'name',
    sortable: {
      sortDirections: ['ascend', 'descend'],
    },
  },
  {
    title: 'Salary',
    dataIndex: 'salary',
    sortable: {
      sortDirections: ['ascend'],
    },
    filterable: {
      filters: [
        {
          text: '> 20000',
          value: '20000',
        },
        {
          text: '> 30000',
          value: '30000',
        },
      ],
      filter: (value, record) => record.salary > value,
      multiple: true,
    },
  },
  {
    title: 'Address',
    dataIndex: 'address',
    filterable: {
      filters: [
        {
          text: 'London',
          value: 'London',
        },
        {
          text: 'Paris',
          value: 'Paris',
        },
      ],
      filter: (value, row) => row.address.includes(value),
    },
  },
  {
    title: 'Email',
    dataIndex: 'email',
  },
]
const data = reactive([
  {
    key: '1',
    name: 'Jane Doe',
    salary: 23000,
    address: '32 Park Road, London',
    email: 'jane.doe@example.com',
  },
  {
    key: '2',
    name: 'Alisa Ross',
    salary: 25000,
    address: '35 Park Road, London',
    email: 'alisa.ross@example.com',
  },
  {
    key: '3',
    name: 'Kevin Sandra',
    salary: 22000,
    address: '31 Park Road, London',
    email: 'kevin.sandra@example.com',
  },
  {
    key: '4',
    name: 'Ed Hellen',
    salary: 17000,
    address: '42 Park Road, London',
    email: 'ed.hellen@example.com',
  },
  {
    key: '5',
    name: 'William Smith',
    salary: 27000,
    address: '62 Park Road, London',
    email: 'william.smith@example.com',
  },
])

const handleChange = (data, extra, currentDataSource) => {
  console.log('change', data, extra, currentDataSource)
}
</script>
```

### Droppable Table

- `columns`: Column info of the table
- `data`: Table data
- `draggable`: Table drag and drop sorting configuration

Example source: src/table/__demos__/droppable-table.vue

```vue
<template>
  <c-table :columns="columns" :data="data" @change="handleChange" :draggable="{}"></c-table>
</template>

<script lang="ts" setup>
import { reactive, ref } from 'vue'
const columns = reactive([
  {
    title: 'Name',
    dataIndex: 'name',
  },
  {
    title: 'Salary',
    dataIndex: 'salary',
  },
  {
    title: 'Address',
    dataIndex: 'address',
  },
  {
    title: 'Email',
    dataIndex: 'email',
  },
])
const data = ref([
  {
    key: '1',
    name: 'Jane Doe',
    salary: 23000,
    address: '32 Park Road, London',
    email: 'jane.doe@example.com',
  },
  {
    key: '2',
    name: 'Alisa Ross',
    salary: 25000,
    address: '35 Park Road, London',
    email: 'alisa.ross@example.com',
  },
  {
    key: '3',
    name: 'Kevin Sandra',
    salary: 22000,
    address: '31 Park Road, London',
    email: 'kevin.sandra@example.com',
  },
  {
    key: '4',
    name: 'Ed Hellen',
    salary: 17000,
    address: '42 Park Road, London',
    email: 'ed.hellen@example.com',
  },
  {
    key: '5',
    name: 'William Smith',
    salary: 27000,
    address: '62 Park Road, London',
    email: 'william.smith@example.com',
  },
])
const handleChange = (_data) => {
  console.log(_data)
  data.value = _data
}
</script>
```

### Droppable Anchor

- `columns`: Column info of the table
- `data`: Table data
- `draggable`: Table drag and drop sorting configuration

Example source: src/table/__demos__/droppable-anchor.vue

```vue
<template>
  <c-table :columns="columns" :data="data" @change="handleChange" :draggable="{ type: 'handle', width: 40 }" />
</template>

<script lang="ts" setup>
import { reactive, ref } from 'vue'
const columns = reactive([
  {
    title: 'Name',
    dataIndex: 'name',
  },
  {
    title: 'Salary',
    dataIndex: 'salary',
  },
  {
    title: 'Address',
    dataIndex: 'address',
  },
  {
    title: 'Email',
    dataIndex: 'email',
  },
])
const data = ref([
  {
    key: '1',
    name: 'Jane Doe',
    salary: 23000,
    address: '32 Park Road, London',
    email: 'jane.doe@example.com',
  },
  {
    key: '2',
    name: 'Alisa Ross',
    salary: 25000,
    address: '35 Park Road, London',
    email: 'alisa.ross@example.com',
  },
  {
    key: '3',
    name: 'Kevin Sandra',
    salary: 22000,
    address: '31 Park Road, London',
    email: 'kevin.sandra@example.com',
  },
  {
    key: '4',
    name: 'Ed Hellen',
    salary: 17000,
    address: '42 Park Road, London',
    email: 'ed.hellen@example.com',
  },
  {
    key: '5',
    name: 'William Smith',
    salary: 27000,
    address: '62 Park Road, London',
    email: 'william.smith@example.com',
  },
])
const handleChange = (_data) => {
  console.log(_data)
  data.value = _data
}
</script>
```

### Editable Form

- `columns`: Column info of the table
- `data`: Table data

Example source: src/table/__demos__/editable-form.vue

```vue
<template>
  <c-table :columns="columns" :data="data">
    <template #name="{ rowIndex }">
      <c-input v-model="data[rowIndex].name" />
    </template>
    <template #province="{ rowIndex }">
      <c-form-item layout="vertical" hide-label>
        <c-select
          v-model="data[rowIndex].province"
          @change="() => handleChange(rowIndex)"
        >
          <c-option v-for="value of Object.keys(options)">{{ value }}</c-option>
        </c-select>
      </c-form-item>
    </template>
    <template #city="{ rowIndex }">
      <c-form-item layout="vertical" hide-label>
        <c-select
          :options="options[data[rowIndex].province] || []"
          v-model="data[rowIndex].city"
        />
      </c-form-item>
    </template>
  </c-table>
  <!-- support from v2.25.0  -->
  <c-table :columns="columns" :data="data" style="margin-top: 20px">
    <template #name="{ record, rowIndex }">
      <c-input v-model="record.name" />
    </template>
    <template #province="{ record, rowIndex }">
      <c-form-item layout="vertical" hide-label>
        <c-select
          v-model="record.province"
          @change="
            () => {
              record.city = '';
            }
          "
        >
          <c-option v-for="value of Object.keys(options)">{{ value }}</c-option>
        </c-select>
      </c-form-item>
    </template>
    <template #city="{ record, rowIndex }">
      <c-form-item layout="vertical" hide-label>
        <c-select
          :options="options[record.province] || []"
          v-model="record.city"
        />
      </c-form-item>
    </template>
  </c-table>
</template>

<script lang="ts" setup>
import { reactive } from "vue";
const options = {
  Beijing: ["Haidian", "Chaoyang", "Changping"],
  Sichuan: ["Chengdu", "Mianyang", "Aba"],
  Guangdong: ["Guangzhou", "Shenzhen", "Shantou"],
};
const columns = [
  {
    title: "Name",
    dataIndex: "name",
    slotName: "name",
  },
  {
    title: "Salary",
    dataIndex: "salary",
  },
  {
    title: "Address",
    dataIndex: "address",
  },
  {
    title: "Province",
    dataIndex: "province",
    slotName: "province",
  },
  {
    title: "City",
    dataIndex: "city",
    slotName: "city",
  },
  {
    title: "Email",
    dataIndex: "email",
  },
];

const data = reactive([
  {
    key: "1",
    name: "Jane Doe",
    salary: 23000,
    address: "32 Park Road, London",
    province: "Beijing",
    city: "Haidian",
    email: "jane.doe@example.com",
  },
  {
    key: "2",
    name: "Alisa Ross",
    salary: 25000,
    address: "35 Park Road, London",
    email: "alisa.ross@example.com",
  },
  {
    key: "3",
    name: "Kevin Sandra",
    salary: 22000,
    address: "31 Park Road, London",
    province: "Sichuan",
    city: "Mianyang",
    email: "kevin.sandra@example.com",
  },
  {
    key: "4",
    name: "Ed Hellen",
    salary: 17000,
    address: "42 Park Road, London",
    email: "ed.hellen@example.com",
  },
  {
    key: "5",
    name: "William Smith",
    salary: 27000,
    address: "62 Park Road, London",
    email: "william.smith@example.com",
  },
]);

const handleChange = (rowIndex) => {
  data[rowIndex].city = "";
};
</script>
```

## Column management and rendering

### Column Manager Basic

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `columns` | Column info of the table | Column Manager Basic, Custom Filter, Custom Rendering |
| `data` | Table data | Column Manager Basic, Custom Filter, Custom Rendering |
| `pagination` | Pagination properties configuration | Column Manager Basic |
| `size` | The size of the table | Column Manager Basic |
| `row-class` | Class for table-row elements | Customize Table Elements |
<!-- demo-config-notes:end -->


- `columns`: Column info of the table
- `data`: Table data
- `pagination`: Pagination properties configuration
- `size`: The size of the table

Example source: src/table/__demos__/column-manager-basic.vue

```vue
<template>
  <c-space wrap justify="flex-end" style="margin-bottom: 8px">
    <c-link @click="visible = true">列管理</c-link>
  </c-space>

  <c-table
    v-model:columns="columns"
    :data="data"
    :pagination="false"
    size="xs"
  />

  <c-drawer
    v-model:open="visible"
    title="列管理"
    :width="720"
    unmount-on-close
    @confirm="handleConfirm"
  >
    <div style="height: calc(100vh - 120px)">
      <c-table-column-manager
        ref="mgrRef"
        v-model="items"
        :columns="columns"
        :options="columnDefinitions"
      />
    </div>
  </c-drawer>
</template>

<script setup lang="ts">
import { ref, watch } from "vue";
import { stateFromColumns } from "@cedar-design/ui";
import type {
  ColumnDefinitions,
  TableColumnData,
  TableColumnManagerInstance,
} from "@cedar-design/ui";

const visible = ref(false);
const mgrRef = ref<TableColumnManagerInstance>();
const items = ref([]);

const columns = ref<TableColumnData[]>([
  { dataIndex: "name", title: "姓名", width: 120 },
  { dataIndex: "salary", title: "薪资", width: 100 },
  { dataIndex: "address", title: "地址", width: 180 },
]);

const columnDefinitions: ColumnDefinitions = [
  {
    title: "基础",
    key: "basic",
    children: [
      { dataIndex: "name", title: "姓名", required: true },
      { dataIndex: "salary", title: "薪资" },
      { dataIndex: "email", title: "邮箱" },
      { dataIndex: "address", title: "地址" },
    ],
  },
];

watch(visible, (val) => {
  if (!val) return;
  const state = stateFromColumns(columns.value, columnDefinitions);
  items.value = state.items;
});

const handleConfirm = () => {
  const result = mgrRef.value?.getResult?.();
  if (result) columns.value = result.columns;
  visible.value = false;
};

const data = ref([
  { name: "Jane", salary: 23000, address: "London", email: "jane@example.com" },
  {
    name: "Alisa",
    salary: 25000,
    address: "Paris",
    email: "alisa@example.com",
  },
]);
</script>
```

Example source: src/table/__demos__/custom-table-columns.vue

```vue
<template>
  <c-space wrap size="12px" justify="flex-end" style="margin-bottom: 8px">
    <c-link @click="open">列管理</c-link>
    <c-link @click="resetColumns">重置列</c-link>
  </c-space>

  <c-table
    v-model:columns="columns"
    :data="data"
    :pagination="false"
    size="xs"
  />

  <c-table-column-manager v-bind="managerProps" />
</template>

<script lang="ts" setup>
import { onMounted, ref, watch } from "vue";
import { useTableColumnManager } from "@cedar-design/ui";
import type { ColumnDefinitions, ManagedTableColumn } from "@cedar-design/ui";

const STORAGE_KEY = "cedar-demo-table-columns";
let storage: Storage | undefined;
const storageReady = ref(false);

const defaultColumns: ManagedTableColumn[] = [
  {
    dataIndex: "connectorId",
    title: "枪ID",
    width: 100,
    fixed: "left",
    manager: { required: true },
  },
  { dataIndex: "connectorName", title: "枪名称", width: 120 },
  {
    dataIndex: "deviceName",
    title: "设备名称",
    width: 140,
    manager: { required: true },
  },
];

const columnDefinitions: ColumnDefinitions = [
  {
    title: "枪基本信息",
    key: "connectorBasicInfo",
    children: [
      {
        dataIndex: "connectorId",
        title: "枪ID",
        tip: "必选列",
      },
      { dataIndex: "connectorName", title: "枪名称" },
      { dataIndex: "connectorNo", title: "枪序号" },
      { dataIndex: "workingStatus", title: "工作状态" },
      { dataIndex: "connectStatus", title: "连接状态" },
      { dataIndex: "parkNo", title: "停车位" },
    ],
  },
  {
    title: "桩基本信息",
    key: "chargerBasicInfo",
    children: [
      { dataIndex: "deviceId", title: "设备ID" },
      {
        dataIndex: "deviceName",
        title: "设备名称",
        tip: "必选规则来自 defaultColumns",
      },
      { dataIndex: "lockStatus", title: "地锁" },
      { dataIndex: "ratedVoltage", title: "额定电压" },
    ],
  },
  {
    title: "其他信息",
    key: "other",
    children: [
      { dataIndex: "batteryStatus", title: "电池状态" },
      { dataIndex: "temperature", title: "温度" },
      { dataIndex: "current", title: "电流" },
      { dataIndex: "power", title: "功率" },
      { dataIndex: "action", title: "操作" },
    ],
  },
];

const { columns, state, restore, managerProps, open, resetToDefault } =
  useTableColumnManager({
    defaultColumns,
    columnDefinitions,
    columnDefaults: { width: 110, ellipsis: true },
    createColumn: (definition) => ({
      dataIndex: definition.dataIndex,
      title: definition.title,
      ...(definition.dataIndex === "action"
        ? { width: 100, fixed: "right" }
        : {}),
    }),
  });

onMounted(async () => {
  storage = window.localStorage;
  try {
    const raw = storage.getItem(STORAGE_KEY);
    if (raw) await restore(JSON.parse(raw));
  } catch {
    storage.removeItem(STORAGE_KEY);
  } finally {
    storageReady.value = true;
  }
});

watch(
  state,
  (value) => {
    if (!storageReady.value) return;
    storage?.setItem(STORAGE_KEY, JSON.stringify(value));
  },
  { deep: true },
);

const resetColumns = () => {
  try {
    storage?.removeItem(STORAGE_KEY);
  } catch {
    // ignore
  }
  resetToDefault();
};

const data = ref([
  {
    connectorId: "1",
    connectorName: "Jane Doe",
    connectorNo: "001",
    workingStatus: "正常",
    connectStatus: "连接中",
    parkNo: "A1",
    deviceId: "D001",
    deviceName: "Device A",
    lockStatus: "解锁",
    ratedVoltage: "220V",
    batteryStatus: "良好",
    temperature: "36",
    current: "10A",
    power: "2kW",
    action: "详情",
  },
]);
</script>
```

### Custom Filter

- `columns`: Column info of the table
- `data`: Table data

Example source: src/table/__demos__/custom-filter.vue

```vue
<template>
  <c-table :columns="columns" :data="data" @change="handleChange">
    <template #name-filter="{ filterValue, setFilterValue, handleFilterConfirm, handleFilterReset }">
      <div class="custom-filter">
        <c-space direction="column">
          <c-input :model-value="filterValue[0]" @input="(value) => setFilterValue([value])" />
          <div class="custom-filter-footer">
            <c-button @click="handleFilterConfirm">Confirm</c-button>
            <c-button @click="handleFilterReset">Reset</c-button>
          </div>
        </c-space>
      </div>
    </template>
  </c-table>
</template>

<script lang="ts" setup>
import { reactive, h } from 'vue'
import { Search } from '@cedar-design/ui'
const columns = [
  {
    title: 'Name',
    dataIndex: 'name',
    filterable: {
      filter: (value, record) => record.name.includes(value),
      slotName: 'name-filter',
      icon: () => h(Search),
    },
  },
  {
    title: 'Salary',
    dataIndex: 'salary',
    sortable: {
      sortDirections: ['ascend'],
    },
  },
  {
    title: 'Address',
    dataIndex: 'address',
  },
  {
    title: 'Email',
    dataIndex: 'email',
  },
]
const data = reactive([
  {
    key: '1',
    name: 'Jane Doe',
    salary: 23000,
    address: '32 Park Road, London',
    email: 'jane.doe@example.com',
  },
  {
    key: '2',
    name: 'Alisa Ross',
    salary: 25000,
    address: '35 Park Road, London',
    email: 'alisa.ross@example.com',
  },
  {
    key: '3',
    name: 'Kevin Sandra',
    salary: 22000,
    address: '31 Park Road, London',
    email: 'kevin.sandra@example.com',
  },
  {
    key: '4',
    name: 'Ed Hellen',
    salary: 17000,
    address: '42 Park Road, London',
    email: 'ed.hellen@example.com',
  },
  {
    key: '5',
    name: 'William Smith',
    salary: 27000,
    address: '62 Park Road, London',
    email: 'william.smith@example.com',
  },
])

const handleChange = (data, extra, currentDataSource) => {
  console.log('change', data, extra, currentDataSource)
}
</script>

<style>
.custom-filter {
  padding: 20px;
  background: var(--color-bg-5);
  border: 1px solid var(--color-neutral-3);
  border-radius: var(--border-radius-medium);
  box-shadow: 0 2px 5px rgb(0 0 0 / 10%);
}

.custom-filter-footer {
  display: flex;
  justify-content: space-between;
}
</style>
```

### Custom Rendering

- `columns`: Column info of the table
- `data`: Table data

Example source: src/table/__demos__/custom-rendering.vue

```vue
<template>
  <c-table :columns="columns" :data="data">
    <template #optional="{ record }">
      <c-button @click="$dialog.info({ title: 'Name', content: record.name })">view</c-button>
    </template>
  </c-table>
  <c-table :data="data" style="margin-top: 30px">
    <template #columns>
      <c-table-column title="Name">
        <c-table-column data-index="first" title="First Name"></c-table-column>
        <c-table-column data-index="last" title="Last Name"></c-table-column>
      </c-table-column>
      <c-table-column data-index="salary" title="Salary"></c-table-column>
      <c-table-column data-index="address" title="Address"></c-table-column>
      <c-table-column data-index="email" title="Email"></c-table-column>
      <c-table-column title="Optional">
        <template #cell="{ record }">
          <c-button @click="$dialog.info({ title: 'Name', content: record.name })">view</c-button>
        </template>
      </c-table-column>
    </template>
  </c-table>
</template>

<script>
import { ref } from 'vue'
export default {
  setup() {
    const show = ref(true)

    const columns = [
      {
        title: 'Name',
        dataIndex: 'name',
      },
      {
        title: 'Salary',
        dataIndex: 'salary',
      },
      {
        title: 'Address',
        dataIndex: 'address',
      },
      {
        title: 'Email',
        dataIndex: 'email',
      },
      {
        title: 'Optional',
        slotName: 'optional',
      },
    ]
    const data = [
      {
        key: '1',
        name: 'Jane Doe',
        first: 'Jane',
        last: 'Doe',
        salary: 23000,
        address: '32 Park Road, London',
        email: 'jane.doe@example.com',
      },
      {
        key: '2',
        name: 'Alisa Ross',
        first: 'Alisa',
        last: 'Ross',
        salary: 25000,
        address: '35 Park Road, London',
        email: 'alisa.ross@example.com',
      },
      {
        key: '3',
        name: 'Kevin Sandra',
        first: 'Kevin',
        last: 'Sandra',
        salary: 22000,
        address: '31 Park Road, London',
        email: 'kevin.sandra@example.com',
      },
      {
        key: '4',
        name: 'Ed Hellen',
        first: 'Ed',
        last: 'Hellen',
        salary: 17000,
        address: '42 Park Road, London',
        email: 'ed.hellen@example.com',
      },
      {
        key: '5',
        name: 'William Smith',
        first: 'William',
        last: 'Smith',
        salary: 27000,
        address: '62 Park Road, London',
        email: 'william.smith@example.com',
      },
    ]

    return {
      columns,
      data,
      show,
    }
  },
}
</script>
```

### Customize Table Elements

- `columns`: Column info of the table
- `data`: Table data
- `row-class`: The class name of the table row element. The `2.34.0` version adds support for function values.

Example source: src/table/__demos__/customize-table-elements.vue

```vue
<template>
  <c-table :columns="columns" :data="data" row-class="common-row">
    <template #tr>
      <tr class="my-tr" @contextmenu.prevent="onContextMenu" />
    </template>
    <template #td>
      <td class="my-td" />
    </template>
  </c-table>
  <c-tag>行右键回调：{{ contextMenus }}</c-tag>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
const contextMenus = ref(0)
const onContextMenu = () => {
  contextMenus.value++
}

const columns = [
  {
    title: 'Name',
    dataIndex: 'name',
  },
  {
    title: 'Salary',
    dataIndex: 'salary',
  },
  {
    title: 'Address',
    dataIndex: 'address',
  },
  {
    title: 'Email',
    dataIndex: 'email',
  },
]
const data = [
  {
    key: '1',
    name: 'Jane Doe',
    salary: 23000,
    address: '32 Park Road, London',
    email: 'jane.doe@example.com',
  },
  {
    key: '2',
    name: 'Alisa Ross',
    salary: 25000,
    address: '35 Park Road, London',
    email: 'alisa.ross@example.com',
  },
  {
    key: '3',
    name: 'Kevin Sandra',
    salary: 22000,
    address: '31 Park Road, London',
    email: 'kevin.sandra@example.com',
  },
  {
    key: '4',
    name: 'Ed Hellen',
    salary: 17000,
    address: '42 Park Road, London',
    email: 'ed.hellen@example.com',
  },
  {
    key: '5',
    name: 'William Smith',
    salary: 27000,
    address: '62 Park Road, London',
    email: 'william.smith@example.com',
  },
]
</script>
```

## Async and large datasets

### Load More

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `columns` | Column info of the table | Load More, Column Manager Async, Virtual List Props |
| `data` | Table data | Load More, Column Manager Async, Virtual List Props |
| `pagination` | Pagination properties configuration | Column Manager Async, Virtual List Props |
| `load-more` | Load children asynchronously; call done(children), or done() to allow retry | Load More |
| `size` | The size of the table | Column Manager Async |
| `row-selection` | Table row selector configuration | Virtual List Props |
<!-- demo-config-notes:end -->


- `columns`: Column info of the table
- `data`: Table data
- `load-more`: Data lazy loading function, open the lazy loading function when it is passed in

Example source: src/table/__demos__/load-more.vue

```vue
<template>
  <c-table :columns="columns" :data="data" :load-more="loadMore" />
</template>

<script lang="ts" setup>
import { reactive } from 'vue'
const columns = [
  {
    title: 'Name',
    dataIndex: 'name',
  },
  {
    title: 'Salary',
    dataIndex: 'salary',
  },
  {
    title: 'Address',
    dataIndex: 'address',
  },
  {
    title: 'Email',
    dataIndex: 'email',
  },
]
const data = reactive([
  {
    key: '1',
    name: 'Jane Doe',
    salary: 23000,
    address: '32 Park Road, London',
    email: 'jane.doe@example.com',
    children: [
      {
        key: '2',
        name: 'Alisa Ross',
        salary: 25000,
        address: '35 Park Road, London',
        email: 'alisa.ross@example.com',
      },
      {
        key: '5',
        name: 'Alisa Ross',
        salary: 25000,
        address: '35 Park Road, London',
        email: 'alisa.ross@example.com',
        isLeaf: true,
      },
    ],
  },
  {
    key: '6',
    name: 'Alisa Ross',
    salary: 25000,
    address: '35 Park Road, London',
    email: 'alisa.ross@example.com',
  },
  {
    key: '7',
    name: 'Kevin Sandra',
    salary: 22000,
    address: '31 Park Road, London',
    email: 'kevin.sandra@example.com',
    isLeaf: true,
  },
  {
    key: '8',
    name: 'Ed Hellen',
    salary: 17000,
    address: '42 Park Road, London',
    email: 'ed.hellen@example.com',
    isLeaf: true,
  },
  {
    key: '9',
    name: 'William Smith',
    salary: 27000,
    address: '62 Park Road, London',
    email: 'william.smith@example.com',
    isLeaf: true,
  },
])

const loadMore = (record, done) => {
  window.setTimeout(() => {
    done([
      {
        key: `${record.key}-1`,
        name: 'Ed Hellen',
        salary: 17000,
        address: '42 Park Road, London',
        email: 'ed.hellen@example.com',
        isLeaf: true,
      },
      {
        key: `${record.key}-2`,
        name: 'William Smith',
        salary: 27000,
        address: '62 Park Road, London',
        email: 'william.smith@example.com',
        isLeaf: true,
      },
    ])
  }, 2000)
}
</script>
```

### Column Manager Async

- `columns`: Column info of the table
- `data`: Table data
- `pagination`: Pagination properties configuration
- `size`: The size of the table

Example source: src/table/__demos__/column-manager-async.vue

```vue
<template>
  <c-space wrap justify="flex-end" style="margin-bottom: 8px">
    <c-link @click="visible = true">列管理</c-link>
  </c-space>

  <c-table
    v-model:columns="columns"
    :data="data"
    :pagination="false"
    size="xs"
  />

  <c-drawer
    v-model:open="visible"
    title="列管理"
    :width="720"
    unmount-on-close
    @confirm="handleConfirm"
  >
    <div style="height: calc(100vh - 120px)">
      <c-table-column-manager
        ref="mgrRef"
        v-model="items"
        :columns="columns"
        :load-options="loadOptions"
      />
    </div>
  </c-drawer>
</template>

<script setup lang="ts">
import { ref, watch } from "vue";
import { stateFromColumns } from "@cedar-design/ui";
import type {
  ColumnDefinitions,
  TableColumnData,
  TableColumnManagerInstance,
} from "@cedar-design/ui";

const visible = ref(false);
const mgrRef = ref<TableColumnManagerInstance>();
const items = ref([]);

const columns = ref<TableColumnData[]>([
  { dataIndex: "name", title: "姓名", width: 120 },
  { dataIndex: "salary", title: "薪资", width: 100 },
]);

const loadOptions = async (): Promise<ColumnDefinitions> => {
  await new Promise((r) => setTimeout(r, 400));
  return [
    {
      title: "基础",
      key: "basic",
      children: [
        { dataIndex: "name", title: "姓名", required: true },
        { dataIndex: "salary", title: "薪资" },
        { dataIndex: "email", title: "邮箱" },
        { dataIndex: "address", title: "地址" },
      ],
    },
  ];
};

watch(visible, async (val) => {
  if (!val) return;
  const columnDefinitions = await loadOptions();
  const state = stateFromColumns(columns.value, columnDefinitions);
  items.value = state.items;
});

const handleConfirm = () => {
  const result = mgrRef.value?.getResult?.();
  if (result) columns.value = result.columns;
  visible.value = false;
};

const data = ref([
  { name: "Jane", salary: 23000, address: "London", email: "jane@example.com" },
]);
</script>
```

### Virtual List Props

- `columns`: Column info of the table
- `data`: Table data
- `row-selection`: Table row selector configuration
- `virtual-list-props`: Pass the virtual list attribute, pass in this parameter to turn on virtual scrolling [VirtualListProps](#VirtualListProps)

Example source: src/table/__demos__/virtual-list-props.vue

```vue
<template>
  <c-table
    :columns="columns"
    :data="data"
    :row-selection="rowSelection"
    :virtual-list-props="{ height: 400 }"
    :pagination="false" />
</template>

<script lang="ts" setup>
import { reactive } from 'vue'
const columns = [
  {
    title: 'Name',
    dataIndex: 'name',
    fixed: 'left',
    width: 140,
  },
  {
    title: 'Address',
    dataIndex: 'address',
    minWidth: 400,
  },
  {
    title: 'Email',
    dataIndex: 'email',
    minWidth: 300,
  },
]
const data = reactive(
  Array(1000)
    .fill(null)
    .map((_, index) => ({
      key: String(index),
      name: `User ${index + 1}`,
      address: '32 Park Road, London',
      email: `user.${index + 1}@example.com`,
    })),
)
const rowSelection = {
  type: 'checkbox',
  showCheckedAll: true,
}
</script>
```

## Business workflows

### Typed Config

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `columns` | Column info of the table | Task Workbench, Form Attribute |
| `data` | Table data | Task Workbench, Form Attribute |
| `pagination` | Pagination properties configuration | Task Workbench |
| `bordered` | Whether to show border | Form Attribute |
| `hoverable` | Whether to show the hover effect | Form Attribute |
| `stripe` | Whether to enable the stripe effect | Form Attribute |
<!-- demo-config-notes:end -->


Example source: src/table/__demos__/typed-config.vue

```vue
<script setup lang="ts">
import { computed, ref } from 'vue'
import { defineTableConfig } from '@cedar-design/ui'
interface User {
  id: string
  name: string
  age: number
  profile: { city: string }
}
const rows = ref<User[]>([
  { id: 'alice', name: 'Alice', age: 28, profile: { city: '杭州' } },
  { id: 'bob', name: 'Bob', age: 16, profile: { city: '宁波' } },
])
const config = computed(() => defineTableConfig<User>({
  rowKey: 'id',
  data: rows.value,
  pagination: false,
  columns: [
    { title: '姓名', dataIndex: 'name', render: ({ record }) => record.name.toUpperCase() },
    { title: '城市', dataIndex: 'profile.city' },
    { title: '年龄', dataIndex: 'age',
      sortable: { sortDirections: ['ascend', 'descend'], sorter: (a, b) => a.age - b.age },
      filterable: { filters: [{ text: '仅成年人', value: 'adult' }], filter: (values, record) => !values.length || !values.includes('adult') || record.age >= 18 },
    },
  ],
}))
function addRow() {
  if (rows.value.length < 3) rows.value = [...rows.value, { id: 'carol', name: 'Carol', age: 35, profile: { city: '上海' } }]
}
</script>
<template>
  <c-space direction="column" fill>
    <c-button :disabled="rows.length >= 3" @click="addRow">增加一行</c-button>
    <c-table v-bind="config" />
    <p role="status">业务数据：{{ rows.length }} 行；年龄列支持排序和筛选。</p>
  </c-space>
</template>
```

### Task Workbench

- `columns`: Column info of the table
- `data`: Table data
- `pagination`: Pagination properties configuration

Example source: src/table/__demos__/task-workbench.vue

```vue
<script setup>
import { computed, ref } from "vue";
const original = () => [
  { key: "01", name: "展厅设备巡检", department: "运营部", status: "待处理" },
  { key: "02", name: "网站交互验收", department: "研发部", status: "进行中" },
  { key: "03", name: "品牌物料审核", department: "设计部", status: "待处理" },
  { key: "04", name: "移动端体验走查", department: "研发部", status: "已完成" },
  { key: "05", name: "会议室设备维护", department: "运营部", status: "进行中" },
];
const rows = ref(original());
const keyword = ref("");
const status = ref("全部");
const applied = ref({ keyword: "", status: "全部" });
const message = ref("显示全部任务。输入条件后点击查询。");
const options = ["全部", "待处理", "进行中", "已完成"].map((value) => ({
  value,
  label: value,
}));
const filtered = computed(() =>
  rows.value.filter(
    (row) =>
      (!applied.value.keyword ||
        `${row.name} ${row.department}`.includes(applied.value.keyword)) &&
      (applied.value.status === "全部" || row.status === applied.value.status),
  ),
);
const completed = computed(
  () => rows.value.filter((row) => row.status === "已完成").length,
);
const columns = [
  { title: "任务", dataIndex: "name" },
  { title: "部门", dataIndex: "department" },
  { title: "状态", dataIndex: "status" },
  { title: "操作", slotName: "action" },
];
function search() {
  applied.value = { keyword: keyword.value.trim(), status: status.value };
  message.value = `查询完成，找到 ${filtered.value.length} 条任务。`;
}
function clear() {
  keyword.value = "";
  status.value = "全部";
  applied.value = { keyword: "", status: "全部" };
  message.value = "已清空筛选条件。";
}
function finish(row) {
  row.status = "已完成";
  message.value = `已完成“${row.name}”，统计与列表已同步。`;
}
function reset() {
  rows.value = original();
  clear();
  message.value = "任务和筛选已恢复，可以重新演示。";
}
</script>
<template>
  <section class="task-workbench" aria-label="巡检任务数据联动">
    <div class="task-workbench__metrics">
      <span
        >全部 <strong>{{ rows.length }}</strong></span
      ><span
        >已完成 <strong>{{ completed }}</strong></span
      ><span
        >当前结果 <strong>{{ filtered.length }}</strong></span
      >
    </div>
    <c-form :model="applied" layout="vertical" @submit="search">
      <c-form-item label="搜索任务或部门"
        ><c-input
          v-model="keyword"
          edit-mode="direct"
          placeholder="搜索任务或部门"
          clearable
      /></c-form-item>
      <c-form-item label="任务状态"
        ><c-select v-model="status" :options="options" edit-mode="direct"
      /></c-form-item>
      <c-space wrap
        ><c-button html-type="submit" status="primary">查询任务</c-button
        ><c-button @click="clear">清空筛选</c-button
        ><c-button @click="reset">恢复全部任务</c-button></c-space
      >
    </c-form>
    <p role="status" aria-live="polite">{{ message }}</p>
    <c-table :columns="columns" :data="filtered" :pagination="false"
      ><template #action="{ record }"
        ><c-button
          :disabled="record.status === '已完成'"
          :aria-label="`完成${record.name}`"
          @click="finish(record)"
          >完成</c-button
        ></template
      ></c-table
    >
    <p v-if="!filtered.length">
      没有匹配任务。修改关键词或点击“清空筛选”恢复结果。
    </p>
    <small
      >先查询“运营部”，完成一条任务，再用状态过滤；统计与结果来自同一份本地任务数据。</small
    >
  </section>
</template>
<style scoped>
.task-workbench {
  min-width: 0;
  width: 100%;
}
.task-workbench__metrics {
  display: flex;
  flex-wrap: wrap;
  gap: 12px;
  margin-bottom: 16px;
}
.task-workbench__metrics > span {
  padding: 12px 16px;
  background: var(--c-color-fill-1);
  border-radius: 8px;
}
.task-workbench__metrics strong {
  margin-left: 8px;
  color: var(--c-color-primary);
}
.task-workbench small {
  display: block;
  margin-top: 8px;
  color: var(--c-color-text-2);
}
</style>
```

### Form Attribute

- `columns`: Column info of the table
- `data`: Table data
- `bordered`: Whether to show the border
- `hoverable`: Whether to show the hover effect

Example source: src/table/__demos__/form-attribute.vue

```vue
<template>
  <c-form layout="inline" :model="form">
    <c-form-item label="Border" field="border">
      <c-switch v-model="form.border" />
    </c-form-item>
    <c-form-item label="Hover" field="hover">
      <c-switch v-model="form.hover" />
    </c-form-item>
    <c-form-item label="stripe" field="stripe">
      <c-switch v-model="form.stripe" />
    </c-form-item>
    <c-form-item label="checkbox" field="checkbox">
      <c-switch v-model="form.checkbox" />
    </c-form-item>
    <c-form-item label="checkAll" field="checkAll">
      <c-switch v-model="rowSelection.showCheckedAll" />
    </c-form-item>
    <c-form-item label="loading" field="loading">
      <c-switch v-model="form.loading" />
    </c-form-item>
    <c-form-item label="tableHeader" field="tableHeader">
      <c-switch v-model="form.tableHeader" />
    </c-form-item>
    <c-form-item label="noData" field="noData">
      <c-switch v-model="form.noData" />
    </c-form-item>
  </c-form>
  <c-table
    :columns="columns"
    :data="form.noData ? [] : data"
    :bordered="form.border"
    :hoverable="form.hover"
    :stripe="form.stripe"
    :loading="form.loading"
    :show-header="form.tableHeader"
    :row-selection="form.checkbox ? rowSelection : undefined" />
</template>

<script lang="ts" setup>
import { reactive } from 'vue'
const form = reactive({
  border: true,
  borderCell: false,
  hover: true,
  stripe: false,
  checkbox: true,
  loading: false,
  tableHeader: true,
  noData: false,
})

const rowSelection = reactive({
  type: 'checkbox',
  showCheckedAll: true,
})

const columns = [
  {
    title: 'Name',
    dataIndex: 'name',
  },
  {
    title: 'Salary',
    dataIndex: 'salary',
  },
  {
    title: 'Address',
    dataIndex: 'address',
  },
  {
    title: 'Email',
    dataIndex: 'email',
  },
]

const data = [
  {
    key: '1',
    name: 'Jane Doe',
    salary: 23000,
    address: '32 Park Road, London',
    email: 'jane.doe@example.com',
  },
  {
    key: '2',
    name: 'Alisa Ross',
    salary: 25000,
    address: '35 Park Road, London',
    email: 'alisa.ross@example.com',
  },
  {
    key: '3',
    name: 'Kevin Sandra',
    salary: 22000,
    address: '31 Park Road, London',
    email: 'kevin.sandra@example.com',
  },
  {
    key: '4',
    name: 'Ed Hellen',
    salary: 17000,
    address: '42 Park Road, London',
    email: 'ed.hellen@example.com',
  },
  {
    key: '5',
    name: 'William Smith',
    salary: 27000,
    address: '62 Park Road, London',
    email: 'william.smith@example.com',
  },
]
</script>
```

## API

### `<Table>` Props

| Parameter | Description | Type | Default |
| --------------------------- | ------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------: |
| columns | Column info of the table | `TableColumnData[]` | `[]` |
| data | Table data | `TableData[]` | `[]` |
| bordered | Whether to show border | `boolean \| TableBorder` | `true` |
| hoverable | Whether to show the hover effect | `boolean` | `true` |
| stripe | Whether to enable the stripe effect | `boolean` | `false` |
| size | The size of the table | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` |
| table-layout | Table layout algorithm, matching CSS `table-layout`. Defaults to `fixed`; calculated column widths are not expanded by content | `'fixed' \| 'auto'` | `'fixed'` |
| loading | Loading state | `boolean\|object` | `false` |
| row-selection | Table row selector configuration | `TableRowSelection` | `-` |
| expandable | Expand row configuration of the table | `TableExpandable` | `-` |
| height | Table height; fixes the header and scrolls the body. Numbers are px | `number \| string` | `-` |
| max-height | Maximum table height; shrinks for short content and scrolls the body on overflow. Numbers are px | `number \| string` | `-` |
| fit | Remaining-space allocation; the table always fills at least its parent `width`. `true` assigns it to flexible columns without `width`; `false` expands columns proportionally to their base widths | `boolean` | `true` |
| pagination | Pagination properties configuration | `boolean \| TablePaginationConfig` | `true` |
| page-position | Pagination region inside the table, currently tl/top/tr/bl/bottom/br; not the page-size dropdown placement | `'tl' \| 'top' \| tr' \| 'bl' \| 'bottom' \| 'br'` | `'br'` |
| indent-size | The indentation distance of the tree table | `number` | `16` |
| row-key | Value field of table row `key` | `string` | `'key'` |
| show-header | Whether to show the header | `boolean` | `true` |
| virtual-list-props | Virtual-list props; providing them enables virtual scrolling. See VirtualListProps | `VirtualListProps` | `-` |
| span-method | Cell merge method (The index starts counting from the data item) | `(data: {  record: TableData;  column: TableColumnData \| TableOperationColumn;  rowIndex: number;  columnIndex: number;}) => { rowspan?: number; colspan?: number } \| void` | `-` |
| span-all | Whether to make the index of the span method contain all | `boolean` | `false` |
| load-more | Load children asynchronously; call done(children), or done() to allow retry | `(record: TableData, done: (children?: TableData[]) => void) => void` | `-` |
| filter-icon-align-left | Whether the filter icon is aligned to the left | `boolean` | `false` |
| hide-expand-button-on-empty | Whether to hide expand button when subtree is empty | `boolean` | `false` |
| row-class | Class for table-row elements | `string\| any[]\| Record<string, any>\| ((record: TableData, rowIndex: number) => any)` | `-` |
| draggable | Table drag and drop sorting configuration | `TableDraggable` | `-` |
| column-resizable | Whether columns can be resized; drag handles render only under `table-layout: fixed` | `boolean` | `false` |
| summary | Show footer summary row | `boolean\| ((params: {    columns: TableColumnData[];    data: TableData[];  }) => TableData[])` | `-` |
| summary-text | The first column of text in the summary line | `string` | `'Summary'` |
| summary-span-method | Cell Merge Method for Summarizing Rows | `(data: {  record: TableData;  column: TableColumnData \| TableOperationColumn;  rowIndex: number;  columnIndex: number;}) => { rowspan?: number; colspan?: number } \| void` | `-` |
| selected-keys | Selected row (controlled mode) takes precedence over `rowSelection` | `(string \| number)[]` | `-` |
| default-selected-keys | The selected row by default (uncontrolled mode) takes precedence over `rowSelection` | `(string \| number)[]` | `-` |
| expanded-keys | Displayed Expanded Row, Subtree (Controlled Mode) takes precedence over `expandable` | `(string \| number)[]` | `-` |
| default-expanded-keys | Expand row, Subtree displayed by default (Uncontrolled mode) takes precedence over `expandable` | `(string \| number)[]` | `-` |
| default-expand-all-rows | Whether to expand all rows by default | `boolean` | `false` |
| sticky-header | Sticky header relative to the page/outer scroller; numeric values are top offsets in px | `boolean \| number` | `false` |
| sticky-pagination | Sticky pagination relative to the page/outer scroller; numeric values are bottom offsets in px | `boolean \| number` | `false` |
| scrollbar | Whether to enable virtual scroll bar | `boolean \| ScrollbarProps` | `true` |
| show-empty-tree | Whether to display empty subtrees | `boolean` | `false` |
| extra-column | Append an extra final column, e.g. settings; slots supply its content | `boolean \| TableExtraColumnConfig` | `false` |
| empty-type | Empty-state type | <br/>`default`\|`network`\|`unknown`\|`success` <br/> <br/> | `default` |
| empty-text | Empty-state text | <br/>`string` <br/> <br/> | `-` |

### `<Table>` Events

| Event | Description | Arguments |
| ---------------- | ------------------------------ | ---------------------------------------------------------------------------------- |
| expand | Emitted when an expandable row is clicked | rowKey: `string \| number`<br>record: `TableData` |
| expanded-change | Emitted when expanded rows change | rowKeys: `(string \| number)[]` |
| select | Emitted when a row selector is clicked | rowKeys: `string \| number[]`<br>rowKey: `string \| number`<br>record: `TableData` |
| select-all | Emitted when the select-all control is clicked | checked: `boolean` |
| selection-change | Emitted when selected rows change | rowKeys: `(string \| number)[]` |
| sorter-change | Emitted when sorting changes | dataIndex: `string`<br>direction: `string` |
| filter-change | Emitted when filtering changes | dataIndex: `string`<br>filteredValues: `string[]` |
| page-change | Emitted when table page changes | page: `number` |
| page-size-change | Emitted when table page size changes | pageSize: `number` |
| change | Emitted when table data changes | data: `TableData[]`<br>extra: `TableChangeExtra`<br>currentData: `TableData[]` |
| update:columns | Emitted when column configuration changes; supports v-model:columns | columns: `TableColumnData[]` |
| cell-mouse-enter | Emitted on cell hover enter | record: `TableData`<br>column: `TableColumnData`<br>ev: `Event` |
| cell-mouse-leave | Emitted on cell hover leave | record: `TableData`<br>column: `TableColumnData`<br>ev: `Event` |
| cell-click | Emitted when a cell is clicked | record: `TableData`<br>column: `TableColumnData`<br>ev: `Event` |
| row-click | Emitted when a row is clicked | record: `TableData`<br>ev: `Event` |
| header-click | Emitted when a header is clicked | column: `TableColumnData`<br>ev: `Event` |
| column-resize | Emitted when a column is resized | dataIndex: `string`<br>width: `number` |
| row-dblclick | Emitted when a row is double-clicked | record: `TableData`<br>ev: `Event` |
| cell-dblclick | Emitted when a cell is double-clicked | record: `TableData`<br>column: `TableColumnData`<br>ev: `Event` |
| row-contextmenu | Emitted when a row is right-clicked | record: `TableData`<br>ev: `Event` |
| cell-contextmenu | Emitted when a cell is right-clicked | record: `TableData`column: `TableColumnData`<br>ev: `Event` |

### `<Table>` Methods

| Method | Description | Arguments | Returns |
| ------------ | ---------------- | ------------------------------------------------------------------------ | ------ |
| selectAll | Set select-all state | checked: `boolean` | - |
| select | Set row-selection state | rowKey: `string \| number \| (string \| number)[]`<br>checked: `boolean` | - |
| expandAll | Set all rows’ expansion state | checked: `boolean` | - |
| expand | Set expansion state | rowKey: `string \| number \| (string \| number)[]`<br>checked: `boolean` | - |
| resetFilters | Reset column filters | dataIndex: `string \| string[]` | - |
| clearFilters | Clear column filters | dataIndex: `string \| string[]` | - |
| resetSorters | Reset column sorting | - | - |
| clearSorters | Clear column sorting | - | - |

### `<Table>` Slots

| Slot | Description | Arguments |
| ---------------- | :-----------------------------------: | ---------------------------------------------------------------------- |
| th | Custom th element | column: `TableColumnData` |
| thead | Custom thead element | - |
| empty | Empty content | - |
| summary-cell | Summary row | column: `TableColumnData`<br>record: `TableData`<br>rowIndex: `number` |
| pagination-right | Content to the right of pagination | - |
| pagination-left | Content to the left of pagination | - |
| td | Custom td element | column: `TableColumnData`<br>record: `TableData`<br>rowIndex: `number` |
| tr | Custom tr element | record: `TableData`<br>rowIndex: `number` |
| tbody | Custom tbody element | - |
| drag-handle-icon | Drag-anchor icon | - |
| footer | Table footer | - |
| expand-row | Expanded-row content | record: `TableData` |
| expand-icon | Expanded-row icon | expanded: `boolean`<br>record: `TableData` |
| columns | Declarative columns; when used, override columns | - |
| extra-column-header | Extra final-column header content | - |
| extra-column-cell | Extra final-column cell content | record / rowIndex, etc. |
| header-cell-actions | Header-side actions for leaf columns; entirely controlled by the caller | column / dataIndex |

### `<TableColumn>` Props

| Parameter | Description | Type | Default |
| ------------------ | ----------------------------------- | --------------------------------------------------------- | :-----: |
| data-index | Column identifier matching a TableData field | `string` | `-` |
| title | Column title | `string` | `-` |
| width | Column width | `number` | `-` |
| min-width | Minimum column width | `number` | `80` |
| align | Alignment | `TableColumnData['align']` | `-` |
| fixed | Fixed position | `TableColumnData['fixed']` | `-` |
| ellipsis | Whether to truncate with an ellipsis | `boolean` | `false` |
| sortable | Sorting options | `TableSortable` | `-` |
| filterable | Filtering options | `TableFilterable` | `-` |
| cell-class | Custom cell class | `ClassName` | `-` |
| header-cell-class | Custom header-cell class | `ClassName` | `-` |
| body-cell-class | Custom body-cell class | `ClassName \| ((record: TableData) => ClassName)` | `-` |
| summary-cell-class | Custom summary-cell class | `ClassName \| ((record: TableData) => ClassName)` | `-` |
| cell-style | Custom cell style | `CSSProperties` | `-` |
| header-cell-style | Custom header-cell style | `CSSProperties` | `-` |
| body-cell-style | Custom body-cell style | `CSSProperties \| ((record: TableData) => CSSProperties)` | `-` |
| summary-cell-style | Custom summary-cell style | `CSSProperties \| ((record: TableData) => CSSProperties)` | `-` |
| index | Manually specify the option index | `number` | `-` |
| tooltip | Whether to show a text tooltip when truncated | `boolean\|object` | `false` |

### `<TableColumn>` Slots

| Slot | Description | Arguments |
| -------------- | :------------------: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filter-icon | Filter-button icon | - |
| filter-content | Custom filter-popup content | filterValue: `string[]`<br>setFilterValue: `(filterValue: string[]) => void`<br>handleFilterConfirm: `(event: Event) => void`<br>handleFilterReset: `(event: Event) => void` |
| title | Title | - |
| cell | Cell | record: `TableData`<br>column: `TableColumnData`<br>rowIndex: `number` |

### TableData

| Parameter | Description | Type | Default |
| -------- | ---------------- | -------------------------- | :-----: |
| key | Row key | `string` | `-` |
| expand | Expanded-row content | `string \| RenderFunction` | `-` |
| children | Child data | `TableData[]` | `-` |
| disabled | Whether row selection is disabled | `boolean` | `false` |
| isLeaf | Whether this is a leaf node | `boolean` | `false` |

### TableSortable

| Parameter | Description | Type | Default |
| ---------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | :----: |
| sortDirections | Supported sort directions | `('ascend' \| 'descend')[]` | `-` |
| sorter | Sort comparator; `true` disables internal sorting | `((        a: TableData,        b: TableData,        extra: { dataIndex: string; direction: 'ascend' \| 'descend' }      ) => number)    \| boolean` | `-` |
| sortOrder | Sort direction | `'ascend' \| 'descend' \| ''` | `-` |
| defaultSortOrder | Default sort direction in uncontrolled mode | `'ascend' \| 'descend' \| ''` | `-` |

### TableFilterData

| Parameter | Description | Type | Default |
| ------ | ------------------ | -------------------------- | :----: |
| text | Filter-option content | `string \| RenderFunction` | `-` |
| value | Filter-option value | `string` | `-` |

### TableFilterable

| Parameter | Description | Type | Default |
| -------------------- | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-----: |
| filters | Filter data | `TableFilterData[]` | `-` |
| filter | Filter callback, similar to Array.prototype.filter | `(filteredValue: string[], <br/>record:TableData)=> boolean` | `-` |
| multiple | Whether to support multiple selection | `boolean` | `false` |
| filteredValue | Selected filters | `string[]` | `-` |
| defaultFilteredValue | Default selected filters | `string[]` | `-` |
| renderContent | Filter-popup content | `(data: {    filterValue: string[];    setFilterValue: (filterValue: string[]) => void;    handleFilterConfirm: (event: Event) => void;    handleFilterReset: (event: Event) => void;  }) => VNodeChild` | `-` |
| icon | Filter-button icon | `RenderFunction` | `-` |
| triggerProps | Filter-popup configuration | `TriggerProps` | `-` |
| alignLeft | Whether the filter icon is aligned to the left | `boolean` | `false` |

### TableColumnData

| Parameter | Description | Type | Default |
| ---------------- | ------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | :-----: |
| dataIndex | Column identifier matching data in `TableData` | `string` | `-` |
| title | Column title | `string \| RenderFunction` | `-` |
| width | Base column width. Fixed when flexible columns exist and fit=true; if all columns are fixed and narrower than the container, expanded proportionally | `number` | `-` |
| minWidth | Minimum `width`. Columns without `width` share remaining space proportionally. Default 80 | `number` | `80` |
| align | Alignment | `'left' \| 'center' \| 'right'` | `-` |
| fixed | Fixed position | `'left' \| 'right'` | `-` |
| ellipsis | Whether to show an ellipsis | `boolean` | `false` |
| tooltip | Whether truncation shows a tooltip; accepts Tooltip props | `boolean \| Record<string, any>` | `-` |
| sortable | Sorting options | `TableSortable` | `-` |
| filterable | Filtering options | `TableFilterable` | `-` |
| children | Child header data for grouped headers | `TableColumnData[]` | `-` |
| cellClass | Custom cell class | `ClassName` | `-` |
| headerCellClass | Custom header-cell class | `ClassName` | `-` |
| bodyCellClass | Custom body-cell class | `ClassName \| ((record: TableData) => ClassName)` | `-` |
| summaryCellClass | Custom summary-cell class | `ClassName \| ((record: TableData) => ClassName)` | `-` |
| cellStyle | Custom cell style | `CSSProperties` | `-` |
| headerCellStyle | Custom header-cell style | `CSSProperties` | `-` |
| bodyCellStyle | Custom body-cell style | `CSSProperties \| ((record: TableData) => CSSProperties)` | `-` |
| summaryCellStyle | Custom summary-cell style | `CSSProperties \| ((record: TableData) => CSSProperties)` | `-` |
| render | Custom column-cell renderer | `(data: {    record: TableData;    column: TableColumnData;    rowIndex: number;  }) => VNodeChild` | `-` |
| slotName | Named render slot for this column; same arguments as #cell | `string` | `-` |
| titleSlotName | Named title-rendering slot for this column | `string` | `-` |

### TableBorder

| Parameter | Description | Type | Default |
| ---------- | ------------------------------- | --------- | :-----: |
| wrapper | Whether to show the outer border | `boolean` | `false` |
| cell | Whether to show header/body cell borders | `boolean` | `false` |
| headerCell | Whether to show header-cell borders | `boolean` | `false` |
| bodyCell | Whether to show body-cell borders | `boolean` | `false` |

### TableRowSelection

| Parameter | Description | Type | Default |
| ---------------------- | ---------------------------------------------- | ----------------------- | :-----: |
| type | Row-selection type | `'checkbox' \| 'radio'` | `-` |
| selectedRowKeys | Selected rows in controlled mode | `BaseType[]` | `-` |
| defaultSelectedRowKeys | Default selected rows in uncontrolled mode | `BaseType[]` | `-` |
| showCheckedAll | Whether to show select all | `boolean` | `false` |
| title | Column title | `string` | `-` |
| width | Column width | `number` | `-` |
| fixed | Whether fixed | `boolean` | `false` |
| checkStrictly | Allow parent selection; unlink parent/child checks | `boolean` | `true` |
| onlyCurrent | Keep only current-page keys; clear them when changing pages | `boolean` | `false` |

### TableExpandable

| Parameter | Description | Type | Default |
| ---------------------- | ------------------------------ | ------------------------------------------------------ | :-----: |
| expandedRowKeys | Expanded rows in controlled mode | `BaseType[]` | `-` |
| defaultExpandedRowKeys | Default expanded rows in uncontrolled mode | `BaseType[]` | `-` |
| defaultExpandAllRows | Whether to expand all rows by default | `boolean` | `false` |
| expandedRowRender | Custom expanded-row content | `(record: TableData) => VNodeChild` | `-` |
| icon | Expand icon | `(expanded: boolean, record: TableData) => VNodeChild` | `-` |
| title | Column title | `string` | `-` |
| width | Column width | `number` | `-` |
| fixed | Whether fixed | `boolean` | `false` |

### TableDraggable

| Parameter | Description | Type | Default |
| ------ | -------- | ------------------- | :-----: |
| type | Drag type | `'row' \| 'handle'` | `-` |
| title | Column title | `string` | `-` |
| width | Column width | `number` | `-` |
| fixed | Whether fixed | `boolean` | `false` |

### TableChangeExtra

| Parameter | Description | Type | Default |
| ---------- | ---------- | ------------------------------------------------ | :----: |
| type | Trigger type | `'pagination' \| 'sorter' \| 'filter' \| 'drag'` | `-` |
| page | Page number | `number` | `-` |
| pageSize | Items per page | `number` | `-` |
| sorter | Sorting information | `Sorter` | `-` |
| filters | Filtering information | `Filters` | `-` |
| dragTarget | Drag information | `TableData` | `-` |

### VirtualListProps

| Parameter | Description | Type | Default |
| :----------------- | ------------------------------------------------------------------ | ------------------ | :-----: |
| height | Viewport height | `number \| string` | `-` |
| threshold | Item-count threshold for virtual scrolling; counts below it do not enable virtualization | `number` | `-` |
| isStaticItemHeight | Removed: use `fixedSize` instead of the old fixed-height flag | `boolean` | `false` |
| fixedSize | Whether item heights are fixed | `boolean` | `false` |
| estimatedSize | Estimated item height when heights vary | `number` | `-` |
| buffer | Number of items premounted beyond viewport boundaries | `number` | `10` |

### TableExtraColumnConfig

| Parameter | Description | Type | Default |
| :----- | ---- | ---- | :----: |
| width | Column width; follows table size when omitted | `number` | xs 28 / sm 32 / md·lg·xl 36 |
| fixed | Fixed position | `'left' \| 'right'` | `'right'` |
| align | Alignment | `'left' \| 'center' \| 'right'` | `'center'` |
| dataIndex | Column identifier | `string` | `__cedar_table_extra__` |

### Pagination configuration type

`TablePaginationConfig = Omit<PaginationProps, 'total'> & { total?: number }`. When `pagination.total` is omitted, Table derives it from the effective data count. Remote pagination can still provide `total` explicitly. Existing `PaginationProps` objects remain accepted by Table; standalone `Pagination` still requires `total`. `TablePaginationConfig` is exported from root/table entries.


### Existing precedence of forwarded configuration (F07)

Column filterable.triggerProps is spread after internal Trigger settings, so nested fields such as open can currently override filter-popup state. F07 preserves this order/type for compatibility without automatically forbidding existing capabilities. Future restrictions require separate migration assessment of filter/popup states.


## Optional business-row type configuration (F08-A)

```ts
import { defineTableConfig } from '@cedar-design/ui'
import type { TypedTableConfig, TypedTableColumn, TableDataPath } from '@cedar-design/ui/table'

interface User { id: string; name: string; age: number }
const users: User[] = [{ id: 'a', name: 'Alice', age: 20 }]
const config = defineTableConfig<User>({
  rowKey: 'id', data: users,
  columns: [{ dataIndex: 'age', render: ({ record }) => record.age.toFixed(0) }],
})
```

Use the config with `<c-table v-bind="config" />` or TSX `<Table {...config} />`. Business-side as any is unnecessary. Existing TableData, TableColumnData, TableProps and component props remain. The new entry validates inputs and returns existing TableProps for old components. Runtime returns the same object without copying rows/columns, changing sorting/filtering or wrapping components.

| Associated scope | New type rules |
| --- | --- |
| data / columns | The same Row type recursively applies to tree children |
| dataIndex | Validates fields/nested paths such as profile.city, tags[0].label and tags.0.label, up to five business-structure levels. Dynamic strings/deeper paths retain the old entry |
| render / sortable / filterable | record, comparators and filters receive Row, including grouped child columns |
| Row callbacks | Cell styles/classes, rowClass, expandable, loadMore, spanMethod and custom summaries associate with Row |
| rowKey | Explicitly provide a Row field whose value is string/number; this is a field name, not a nested path |
| summary | May be omitted, false or a custom function returning complete Row. Automatic summary=true is not guaranteed to be a business row, so the new entry rejects it; existing Table configuration still supports it |

Business interfaces normally need not extend TableData explicitly; its any index broadens keyof and weakens spelling checks. Use ordinary business interfaces and generic constraints to validate reserved Table metadata compatibility. Business code still validates backend contents; types do not ensure unique IDs.

Type association covers only this configuration. Component template slots/events and custom components extensions do not automatically become Row-generic. Returned TableProps remains the old broad type; arbitrary later mutations are not Row-validated. If reactive sources replace arrays, use `computed(() => defineTableConfig<Row>(...))`; passing rows.value once is not an ongoing ref subscription.

Automatic summary rows may contain text, totals and missing fields; render(record: User) must not assume a complete User. Keep the old broad configuration for automatic summaries or heterogeneous tree rows. The new custom-summary entry requires a complete business row. Neither entry changes Table runtime behavior.

Platform scope: Maple Table is a native-table display container without data/columns API, so no associated-config entry is added there. Select/Cascader type associations require separate assessment.


## Reading direction and interaction

Table inherits native reading direction. Normal columns follow reading order; explicit fixed left/right sides stay physical through stable visual partitions. Mixed frozen group headers are projected into matching physical sections without mutating source columns or business indexes. Default cell alignment follows reading start; explicit left/right alignment stays physical. Header/body/summary/sticky rail share a normalized nonnegative inline scroll distance, including native negative RTL scrollLeft. Virtual row positioning preserves horizontal distance. Teleported footers retain source direction. Resize handles support directional pointer and keyboard input; sticky rails support arrows and Home/End. Direction switches preserve business state and cancel stale resize gestures.

Lazy children belong to the source node identity and row key, rather than to a reused key alone. Replacing the node, row key or loader invalidates old work/cache. Deactivation or unmount invalidates pending cell callbacks. `done()` releases pending for retry; `done([])` accepts an empty result. Only the first completion is accepted. Synchronous loader exceptions release pending and remain observable through Vue. Keep the callback-based `load-more` protocol; returned notification Promises do not control this work.

If a callback-style loader returns a Promise, its rejection releases pending and reaches the Vue error path; a fulfilled return value is ignored and does not replace `done`. This is error reporting for an explicit loader Prop, not Promise collection from `expand` or other notification events.

---

Document: llms/en-US/components/tabs.md

<!-- Source: src/tabs/README.en-US.md; locale: en-US; page: /en/components/tabs/ -->

# Tabs

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

Preview configuration: `default-value="overview"`, `name="overview"`, `title="概览"`, `name="details"`.

Example source: src/tabs/__demos__/basic.vue

```vue
<template>
  <c-tabs default-value="overview">
    <c-tab-pane name="overview" title="概览">概览内容</c-tab-pane>
    <c-tab-pane name="details" title="详情">详情内容</c-tab-pane>
    <c-tab-pane name="settings" title="设置">设置内容</c-tab-pane>
  </c-tabs>
</template>
```

## Appearance and states

### Appearance Lab

Preview configuration: `layout="vertical"`, `:clearable="false"`, `options`, `aria-label="variant"`.

Example source: src/tabs/__demos__/appearance-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";

const __demoAppearance = __demoReactive({ variant: "line", size: "md" });

import { computed as demoComputed, ref as demoRef } from 'vue'
const demoCompareFields = [{"name":"variant","values":["line","card","outline","plain","capsule","enclosed"]},{"name":"size","values":["xs","sm","md","lg","xl"]}]
const demoCompareAxis = demoRef("variant")
const demoComparedOptions = demoComputed(() => demoCompareFields.find(field => field.name === demoCompareAxis.value)?.values ?? [])
</script>
<template>
  <c-space direction="column" :size="16">
    <c-form layout="vertical">
      <c-form-item layout="vertical" size="sm" label="variant">
        <c-select
          v-model="__demoAppearance['variant']"
          :clearable="false"
          :options="[
            { label: 'line', value: 'line' },
            { label: 'card', value: 'card' },
            { label: 'outline', value: 'outline' },
            { label: 'plain', value: 'plain' },
            { label: 'capsule', value: 'capsule' },
            { label: 'enclosed', value: 'enclosed' },
          ]"
          aria-label="variant"
        />
      </c-form-item>
      <c-form-item layout="vertical" size="sm" label="size">
        <c-radio-group
          v-model="__demoAppearance['size']"
          aria-label="size"
          :options="[
            { label: 'xs', value: 'xs' },
            { label: 'sm', value: 'sm' },
            { label: 'md', value: 'md' },
            { label: 'lg', value: 'lg' },
            { label: 'xl', value: 'xl' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
    </c-form>
    <p class="demo-config-comparison-hint"><span lang="zh-CN">选择一个对比维度；其他配置和内容保持一致。输入类示例共享同一个值，便于比较外观。</span><span lang="en-US">Compare one dimension while keeping the other settings and content identical. Input specimens share the same value.</span></p>
<c-radio-group v-model="demoCompareAxis" aria-label="Compare configuration" :options="demoCompareFields.map(field => ({ label: field.name, value: field.name }))" />
<div class="demo-config-comparison">
<section v-for="sample in demoComparedOptions" :key="String(sample)">
<p><code>{{ demoCompareAxis }}={{ sample }}</code></p>
<c-tabs default-value="overview" v-bind="{ ...__demoAppearance, [demoCompareAxis]: sample }">
      <c-tab-pane name="overview" title="概览">概览内容</c-tab-pane>
      <c-tab-pane name="details" title="详情">详情内容</c-tab-pane>
      <c-tab-pane name="settings" title="设置">设置内容</c-tab-pane>
    </c-tabs>
</section>
</div>
  </c-space>
</template>

<style scoped>
.demo-config-comparison { display: grid; grid-template-columns: repeat(auto-fit, minmax(min(100%, 220px), 1fr)); gap: 20px; min-width: 0; max-width: 100%; }
.demo-config-comparison > section { min-width: 0; }
.demo-config-comparison p { margin: 0 0 8px; }
html:not([lang='en-US']) .demo-config-comparison-hint > [lang='en-US'],
html[lang='en-US'] .demo-config-comparison-hint > [lang='zh-CN'] { display: none; }
</style>
```

## Appearance and direction

### Type

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `orientation` | Horizontal/vertical axis of tab navigation, default horizontal; affects navigation layout and arrow-key behavior | Type, Position |
| `item-style` | `StyleValue` | No Padding, Custom Style |
| `default-value` | `string / number` | No Padding, Custom Style |
| `variant` | `line / card / outline / plain / capsule / enclosed` | Type |
| `size` | `xs / sm / md / lg / xl` | Type |
| `editable` | `boolean` | Type |
<!-- demo-config-notes:end -->


- `variant`: Selects the visual variant.
- `size`: Controls the component size.

Example source: src/tabs/__demos__/type.vue

```vue
<template>
  <c-space direction="column" size="lg">
    <c-radio-group v-model="isVertical" type="button">
      <c-radio value="horizontal">Horizontal</c-radio>
      <c-radio value="vertical">Vertical</c-radio>
    </c-radio-group>
    <c-radio-group v-model="variant" type="button">
      <c-radio value="line">Line</c-radio>
      <c-radio value="card">Card</c-radio>
      <c-radio value="outline">Outline</c-radio>
      <c-radio value="plain">Plain</c-radio>
      <c-radio value="capsule">Capsule</c-radio>
      <c-radio value="enclosed">Enclosed</c-radio>
    </c-radio-group>
    <c-radio-group v-model="size" type="button">
      <c-radio value="xs">Xs</c-radio>
      <c-radio value="sm">Sm</c-radio>
      <c-radio value="md">Md</c-radio>
      <c-radio value="lg">Lg</c-radio>
      <c-radio value="xl">Xl</c-radio>
    </c-radio-group>
  </c-space>
  <c-tabs
    :variant="variant"
    :size="size"
    :orientation="isVertical"
    :editable="true"
    @add="handleAdd"
    @delete="handleDelete"
    show-add-button
    auto-switch
    :style="isVertical !== 'vertical' ? { height: '240px' } : undefined"
  >
    <c-tabs-navs>
      <c-tab-nav v-for="(item, index) of data" :key="item.key" :name="item.key" :title="item.title" :closable="index !== 2" />
      <template #prefix><c-button size="xs">Action</c-button></template>
      <template #suffix>suffix</template>
    </c-tabs-navs>
    <c-tabs-items>
      <c-tab-item v-for="(item, index) of data" :key="item.key" :name="item.key">{{ item?.content }}</c-tab-item>
    </c-tabs-items>
  </c-tabs>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
const variant = ref('line')
const size = ref('md')
const isVertical = ref('horizontal')
const data = ref([
  {
    key: '1',
    title: 'Tab 1',
    content: 'Content of Tab Panel 1',
  },
  {
    key: '2',
    title: 'Tab 2',
    content: 'Content of Tab Panel 2',
  },
  {
    key: '3',
    title: 'Tab 3',
    content: 'Content of Tab Panel 3',
  },
  {
    key: '4',
    title: 'Tab 4',
    content: 'Content of Tab Panel 4',
  },
])
let count = 5
const handleAdd = () => {
  const number = count++
  data.value = data.value.concat({
    key: `${number}`,
    title: `New Tab ${number}`,
    content: `Content of New Tab Panel ${number}`,
  })
}
const handleDelete = (key) => {
  data.value = data.value.filter((item) => item.key !== key)
}
</script>
```

### Position

Preview configuration: `type="button"`, `value="normal"`, `value="reverse"`, `value="horizontal"`.

Example source: src/tabs/__demos__/position.vue

```vue
<template>
  <c-space direction="column" size="lg">
    <c-radio-group v-model="indicatorPosition" type="button">
      <c-radio value="normal">Normal (bottom/right)</c-radio>
      <c-radio value="reverse">Reverse (top/left)</c-radio>
    </c-radio-group>
    <c-radio-group v-model="vertical" type="button">
      <c-radio value="horizontal">Horizontal</c-radio>
      <c-radio value="vertical">Vertical</c-radio>
    </c-radio-group>
    <c-radio-group v-model="componentOrder" type="button">
      <c-radio value="nav-first">TabsNavs → TabsItems</c-radio>
      <c-radio value="items-first">TabsItems → TabsNavs</c-radio>
    </c-radio-group>
    <c-tabs :indicator-position="indicatorPosition" :orientation="vertical">
      <template v-if="componentOrder === 'items-first'">
        <c-tabs-items>
          <c-tab-item name="1">Content of Tab Panel 1</c-tab-item>
          <c-tab-item name="2">Content of Tab Panel 2</c-tab-item>
          <c-tab-item name="3">Content of Tab Panel 3</c-tab-item>
        </c-tabs-items>
        <c-tabs-navs>
          <c-tab-nav name="1" title="Tab 1" />
          <c-tab-nav name="2" title="Tab 2" />
          <c-tab-nav name="3" title="Tab 3" />
        </c-tabs-navs>
      </template>
      <template v-else>
        <c-tabs-navs>
          <c-tab-nav name="1" title="Tab 1" />
          <c-tab-nav name="2" title="Tab 2" />
          <c-tab-nav name="3" title="Tab 3" />
        </c-tabs-navs>
        <c-tabs-items>
          <c-tab-item name="1">Content of Tab Panel 1</c-tab-item>
          <c-tab-item name="2">Content of Tab Panel 2</c-tab-item>
          <c-tab-item name="3">Content of Tab Panel 3</c-tab-item>
        </c-tabs-items>
      </template>
    </c-tabs>
  </c-space>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
const indicatorPosition = ref('normal')
const vertical = ref('horizontal')
const componentOrder = ref('nav-first')
</script>
```

### Icon Tabs

Preview configuration: `name="1"`, `name="2"`, `name="3"`, `item-vertical`.

Example source: src/tabs/__demos__/icon-tabs.vue

```vue
<template>
  <c-space direction="column" size="lg">
    <c-tabs>
      <c-tabs-navs>
        <c-tab-nav name="1">
          <template #icon> <c-icon-calendar /> </template>
          <template #title>Tab 1</template>
        </c-tab-nav>
        <c-tab-nav name="2">
          <template #icon> <c-icon-clock-circle /> </template>
          <template #title>Tab 2</template>
        </c-tab-nav>
        <c-tab-nav name="3">
          <template #icon> <c-icon-user /> </template>
          <template #title>Tab 3</template>
        </c-tab-nav>
      </c-tabs-navs>
      <c-tabs-items>
        <c-tab-item name="1"> Content of Tab Panel 1</c-tab-item>
        <c-tab-item name="2"> Content of Tab Panel 2</c-tab-item>
        <c-tab-item name="3"> Content of Tab Panel 3</c-tab-item>
      </c-tabs-items>
    </c-tabs>

    <c-tabs>
      <c-tabs-navs>
        <c-tab-nav name="1" item-vertical>
          <template #icon> <c-icon-calendar /> </template>
          <template #title>日历</template>
        </c-tab-nav>
        <c-tab-nav name="2" item-vertical>
          <template #icon> <c-icon-clock-circle /> </template>
          <template #title>时钟</template>
        </c-tab-nav>
        <c-tab-nav name="3" item-vertical>
          <template #icon> <c-icon-user /> </template>
          <template #title>用户</template>
        </c-tab-nav>
      </c-tabs-navs>
      <c-tabs-items>
        <c-tab-item name="1"> Content of Tab Panel 1</c-tab-item>
        <c-tab-item name="2"> Content of Tab Panel 2</c-tab-item>
        <c-tab-item name="3"> Content of Tab Panel 3</c-tab-item>
      </c-tabs-items>
    </c-tabs>
  </c-space>
</template>

<script lang="ts" setup>
</script>
```

### No Padding

Preview configuration: `:item-style="{ padding: 0 }"`, `default-value="2"`, `name="1"`, `title="Tab 1"`.

Example source: src/tabs/__demos__/no-padding.vue

```vue
<template>
  <c-tabs :item-style="{ padding: 0 }" default-value="2">
    <c-tabs-navs :style="{ paddingInline: 0 }">
      <c-tab-nav name="1" title="Tab 1" />
      <c-tab-nav name="2" title="Tab 2" />
      <c-tab-nav name="3">
        <template #title>Tab 3</template>
      </c-tab-nav>
    </c-tabs-navs>
    <c-tabs-items>
      <c-tab-item name="1">
        <div class="p-24">通过 item-style 设置内容间距，并通过 TabsNavs 的 style 去掉导航两端内边距</div>
      </c-tab-item>
      <c-tab-item name="2"> Content of Tab Panel 2</c-tab-item>
      <c-tab-item name="3">Content of Tab Panel 3</c-tab-item>
    </c-tabs-items>
  </c-tabs>
</template>

<script lang="ts" setup>
</script>
```

### Custom Style

Preview configuration: `default-value="overview"`, `item-class="custom-tab-content"`, `:item-style="{ padding: '16px' }"`, `item-wrapper-class="custom-tab-panel"`.

Example source: src/tabs/__demos__/custom-style.vue

```vue
<template>
  <c-tabs
    default-value="overview"
    item-class="custom-tab-content"
    :item-style="{ padding: '16px' }"
    item-wrapper-class="custom-tab-panel"
    :item-wrapper-style="{ border: '1px solid currentColor', borderRadius: '8px' }"
    tab-class="custom-tab-label"
    :tab-style="{ borderRadius: '8px' }"
  >
    <c-tabs-navs :style="{ paddingInline: 0 }">
      <c-tab-nav name="overview" title="概览" />
      <c-tab-nav name="details" title="详情" />
    </c-tabs-navs>
    <c-tabs-items>
      <c-tab-item name="overview">统一设置导航、内容和内容外层样式。</c-tab-item>
      <c-tab-item name="details">自定义类名保留内置选中状态，样式支持响应式更新。</c-tab-item>
    </c-tabs-items>
  </c-tabs>
</template>
```

## Navigation and content composition

### Nav Content

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `default-value` | `string / number` | Nav Content |
| `swipeable` | `boolean` | Same Source |
| `lazy-load` | `boolean` | Same Source |
<!-- demo-config-notes:end -->


Preview configuration: `default-value="overview"`, `aria-label="内容分类"`, `name="overview"`, `title="概览"`.

Example source: src/tabs/__demos__/nav-content.vue

```vue
<template>
  <c-tabs default-value="overview">
    <c-tabs-navs aria-label="内容分类">
      <c-tab-nav name="overview" title="概览" />
      <c-tab-nav name="details" title="详情" />
      <c-tab-nav name="settings" title="设置" />
    </c-tabs-navs>
  </c-tabs>
</template>
```

### Same Source

Preview configuration: `swipeable`, `lazy-load`, `aria-label="内容分类"`, `:name="item.key"`.

Example source: src/tabs/__demos__/same-source.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const active = ref('overview')
const items = [{ key: 'overview', title: '概览' }, { key: 'details', title: '详情' }, { key: 'disabled', title: '不可用', disabled: true }]
</script>
<template>
  <c-tabs v-model="active" swipeable lazy-load>
    <c-tabs-navs aria-label="内容分类">
      <c-tab-nav v-for="item in items" :key="item.key" :name="item.key" :title="item.title" :disabled="item.disabled" />
    </c-tabs-navs>
    <c-tabs-items>
      <c-tab-item v-for="item in items" :key="item.key" :name="item.key">{{ item.title }}内容</c-tab-item>
    </c-tabs-items>
  </c-tabs>
</template>
```

### Suffix

Preview configuration: `name="1"`, `title="Tab 1"`, `name="2"`, `title="Tab 2"`.

Example source: src/tabs/__demos__/suffix.vue

```vue
<template>
  <c-tabs>
    <c-tabs-navs>
      <template #suffix>
        <c-button>Action</c-button>
      </template>
      <c-tab-nav name="1" title="Tab 1" />
      <c-tab-nav name="2" title="Tab 2" />
      <c-tab-nav name="3" title="Tab 3" />
    </c-tabs-navs>
    <c-tabs-items>
      <c-tab-item name="1"> Content of Tab Panel 1 </c-tab-item>
      <c-tab-item name="2"> Content of Tab Panel 2 </c-tab-item>
      <c-tab-item name="3"> Content of Tab Panel 3 </c-tab-item>
    </c-tabs-items>
  </c-tabs>
</template>

<script lang="ts" setup>
</script>
```

## Interaction and dynamic tabs

### Trigger

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `default-value` | `string / number` | Trigger, Lazy Load |
| `trigger` | `click / hover` | Trigger |
| `lazy-load` | `boolean` | Lazy Load |
| `variant` | `line / card / outline / plain / capsule / enclosed` | Editable |
| `editable` | `boolean` | Editable |
| `show-add-button` | `boolean` | Editable |
<!-- demo-config-notes:end -->


Preview configuration: `value="click"`, `value="hover"`, `default-value="1"`, `:trigger="trigger"`.

Example source: src/tabs/__demos__/trigger.vue

```vue
<template>
  <c-radio-group v-model="trigger">
    <c-radio value="click">click</c-radio>
    <c-radio value="hover">hover</c-radio>
  </c-radio-group>
  <c-tabs default-value="1" :trigger="trigger">
    <c-tabs-navs>
      <c-tab-nav name="1" title="Tab 1" />
      <c-tab-nav name="2" title="Tab 2" />
      <c-tab-nav name="3">
        <template #title>Tab 3</template>
      </c-tab-nav>
    </c-tabs-navs>
    <c-tabs-items>
      <c-tab-item name="1">Content of Tab Panel 1</c-tab-item>
      <c-tab-item name="2">Content of Tab Panel 2</c-tab-item>
      <c-tab-item name="3">Content of Tab Panel 3</c-tab-item>
    </c-tabs-items>
  </c-tabs>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
const trigger = ref('click')
</script>
```

### Lazy Load

Preview configuration: `default-value="2"`, `lazy-load`, `name="1"`, `title="Tab 1"`.

Example source: src/tabs/__demos__/lazy-load.vue

```vue
<template>
  <c-tabs default-value="2" lazy-load>
    <c-tabs-navs>
      <c-tab-nav name="1" title="Tab 1" />
      <c-tab-nav name="2" title="Tab 2" />
      <c-tab-nav name="3" title="Tab 3" />
    </c-tabs-navs>
    <c-tabs-items>
      <c-tab-item name="1"> Content of Tab Panel 1 </c-tab-item>
      <c-tab-item name="2"> Content of Tab Panel 2 </c-tab-item>
      <c-tab-item name="3"> Content of Tab Panel 3 </c-tab-item>
    </c-tabs-items>
  </c-tabs>
</template>

<script lang="ts" setup>
</script>
```

### Editable

- `variant`: Selects the visual variant.

Example source: src/tabs/__demos__/editable.vue

```vue
<template>
  <c-tabs variant="card" :editable="true" @add="handleAdd" @delete="handleDelete" show-add-button auto-switch>
    <c-tabs-navs>
      <template #suffix>
        <c-button>Action</c-button>
      </template>
      <c-tab-nav v-for="(item, index) of data" :key="item.key" :name="item.key" :title="item.title" :closable="index !== 2" />
    </c-tabs-navs>
    <c-tabs-items>
      <c-tab-item v-for="(item, index) of data" :key="item.key" :name="item.key">{{ item?.content }}</c-tab-item>
    </c-tabs-items>
  </c-tabs>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
let count = 5

const data = ref([
  {
    key: '1',
    title: 'Tab 1',
    content: 'Content of Tab Panel 1',
  },
  {
    key: '2',
    title: 'Tab 2',
    content: 'Content of Tab Panel 2',
  },
  {
    key: '3',
    title: 'Tab 3',
    content: 'Content of Tab Panel 3',
  },
  {
    key: '4',
    title: 'Tab 4',
    content: 'Content of Tab Panel 4',
  },
])

const handleAdd = () => {
  const number = count++
  data.value = data.value.concat({
    key: `${number}`,
    title: `New Tab ${number}`,
    content: `Content of New Tab Panel ${number}`,
  })
}
const handleDelete = (key: string | number) => {
  data.value = data.value.filter((item) => item.key !== key)
}
</script>
```

## API

TabPane, TabNav and TabItem all require unique names. Selection and navigation/panel association use `name`; Vue key controls only node reuse. Provide `:key` separately in loops.

Use ordinary `v-model`. `modelValue` is the selected tab name. `defaultValue` initializes uncontrolled state once without later resets or initialization `update:modelValue`. When provided, the parent value controls selection.

### Tabs Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| model-value | `string / number` | `undefined` | Current selected name; controlled when provided |
| default-value | `string / number` | `undefined` | Initial uncontrolled value; defaults to the first available item |
| variant | `line / card / outline / plain / capsule / enclosed` | `line` | Visual variant |
| size | `xs / sm / md / lg / xl` | Global value or md | Size |
| orientation | Horizontal/vertical axis of tab navigation, default horizontal; affects navigation layout and arrow-key behavior | `horizontal` | Navigation orientation |
| indicator-position | Indicator on the navigation side facing the content (normal) or the opposite side (reverse), default normal; does not use four-side values | `normal` | Indicator on the content side or opposite side |
| editable | `boolean` | `false` | Allow closing tabs |
| show-add-button | `boolean` | `false` | Show the add button in editable mode |
| auto-switch | `boolean` | `false` | Switch to the last available tab after adding |
| lazy-load | `boolean` | `false` | Mount on first activation |
| destroy-on-hide | `boolean` | `false` | Unmount content when hidden |
| justify | `boolean` | `false` | Fill container height in horizontal orientation |
| animation | `boolean` | `false` | Content fade-in animation |
| item-class | `string / object / array` | `undefined` | Inner class for each panel; merged with built-in classes |
| item-style | `StyleValue` | `undefined` | Inner style for each panel; supports string, object or array |
| item-wrapper-class | `string / object / array` | `undefined` | Outer class for each panel; merged with built-in classes |
| item-wrapper-style | `StyleValue` | `undefined` | Outer style for each panel; supports string, object or array |
| tab-class | `string / object / array` | `undefined` | Outer navigation-label class, including title/close button; merged with built-in classes |
| tab-style | `StyleValue` | `undefined` | Outer navigation-label style; supports string, object or array |
| hide-content | `boolean` | `false` | Hide the content area |
| trigger | `click / hover` | `click` | Mouse trigger mode; touch always uses click |
| scroll-position | Target position or numeric offset of the selected tab within the navigation scroll viewport, default auto; not popup placement | `auto` | Selected-tab scroll position; numbers are start offsets |
| scroll-buttons | `boolean / auto` | `auto` | Show arrows on overflow; auto hides them on touch devices |
| activation-mode | `automatic / manual` | `automatic` | Whether arrow keys immediately select |
| swipeable | `boolean` | `false` | Horizontal swipe between content panels; no looping |

### Tabs Events

| Event | Arguments | Description |
| --- | --- | --- |
| update:model-value | name: string / number | Request a selected-value update |
| change | name: string / number | Notify on selecting a different available item; controlled mode still requires parent modelValue updates |
| tab-click | name, event: Event | Click an available item, including repeat clicks; hover/arrows/swipes do not emit click |
| add | event: Event | Request adding a tab; the caller updates data |
| delete | name, event: Event | Request removing a tab; the caller updates data |

### TabPane Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| name **(required)** | string / number | — | Unique business identifier matching modelValue |
| title | string | undefined | Navigation title |
| disabled | boolean | false | Prevent selecting and closing |
| closable | boolean | true | Show the close button in editable mode |
| item-vertical | boolean | false | Vertical icon/text layout |
| lazy-load | boolean | undefined | Inherit Tabs; explicit false overrides it |
| destroy-on-hide | boolean | undefined | Inherit Tabs; explicit false overrides it |

### TabNav Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| name **(required)** | string / number | — | Unique business identifier matching modelValue |
| title | string | undefined | Title |
| disabled | boolean | false | Prevent selecting and closing |
| closable | boolean | true | Show the close button in editable mode |
| item-vertical | boolean | false | Vertical icon/text layout |

TabNav/TabItem associate through the same `name`. Names are unique within a group; number `1` and string `'1'` differ. Vue `key` controls node reuse only; provide `:key` in loops independently. It does not determine selection.

### TabItem Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| name **(required)** | string / number | — | Unique business identifier matching modelValue |
| lazy-load | boolean | undefined | Inherit Tabs; explicit false overrides it |
| destroy-on-hide | boolean | undefined | Inherit Tabs; explicit false overrides it |

Inactive panels always have hidden. The above props determine whether internal state survives. destroy-on-hide overrides lazy-load; active content remains mounted. TabsNavs/TabsItems have no business props.

### Slots

| Component | Slot | Description |
| --- | --- | --- |
| Tabs | default | TabPane list, or TabsNavs/TabsItems for advanced composition |
| TabPane | default / title | Panel content / custom navigation title |
| TabsNavs | default | TabNav list |
| TabsNavs | prefix / suffix / add-icon | Navigation prefix/suffix areas and add icon |
| TabNav | title / default / icon | title/default slots customize the title; icon supplies an icon |
| TabsItems | default | TabItem list |
| TabItem | default | Panel content |

### Expose

`TabsNavs.resize(): void` remeasures overflow and scrolls the selected tab into view. ResizeObserver watches size changes automatically.

### Keyboard and direction

Arrow keys skip disabled items and wrap; Home/End reach first/last. Delete requests closing editable tabs. Horizontal uses Left/Right, vertical uses Up/Down. Manual mode moves focus only; Enter/Space activates the native button. `dir="rtl"` supports right-to-left layout. Give TabsNavs an `aria-label` to name navigation.

### Types

Exports TabsName, TabsVariant, TabsTrigger, TabsIndicatorPosition, TabsScrollPosition, TabsActivationMode and Props/Instance/runtime props/`_XxxComponent` for all six components. Both platforms use the same prop definitions.

## Style variables

Matching token suffixes have matching meanings on both platforms, with platform-specific defaults. The variables and their defaults are listed below.

| Variable | Default |
| --- | --- |
| `--c-tabs-background` | `var(--c-sys-color-surface-default)` |
| `--c-tabs-title-text-color` | `var(--c-sys-color-content-secondary)` |
| `--c-tabs-title-text-color-active` | `var(--c-sys-color-content-brand)` |
| `--c-tabs-title-text-color-disabled` | `var(--c-sys-color-content-disabled)` |
| `--c-tabs-muted-background` | `var(--c-sys-color-surface-muted)` |
| `--c-tabs-border-color` | `var(--c-sys-color-border-default)` |
| `--c-tabs-hover-background` | `var(--c-sys-color-state-hover)` |
| `--c-tabs-nav-gap` | `var(--c-sys-space-2)` |
| `--c-tabs-tab-gap` | `var(--c-sys-space-2)` |
| `--c-tabs-header-padding` | `var(--c-sys-space-5)` |
| `--c-tabs-control-height` | `var(--c-sys-control-height-xs)` |
| `--c-tabs-touch-target` | `var(--c-sys-control-touch-target)` |
| `--c-tabs-border-width` | `1px` |
| `--c-tabs-focus-width` | `2px` |
| `--c-tabs-focus-offset` | `-3px` |
| `--c-tabs-radius` | `var(--c-sys-radius-md)` |
| `--c-tabs-icon-gap` | `var(--c-sys-space-3)` |
| `--c-tabs-content-padding` | `var(--c-sys-space-6)` |
| `--c-tabs-indicator-size` | `2px` |
| `--c-tabs-indicator-radius` | `1px` |
| `--c-tabs-animation-duration` | `var(--c-sys-motion-duration-standard)` |
| `--c-tabs-active-font-weight` | `var(--c-sys-font-weight-semibold)` |
| `--c-tabs-group-padding` | `var(--c-sys-space-2)` |
| `--c-tabs-capsule-radius` | `var(--c-sys-radius-pill)` |
| `--c-tabs-active-shadow` | `0 1px 3px rgba(0, 0, 0, 0.12)` |
| `--c-tabs-size-xs-tab-height` | `var(--c-sys-control-height-xs)` |
| `--c-tabs-size-xs-tab-padding` | `var(--c-sys-space-2) var(--c-sys-space-4)` |
| `--c-tabs-size-xs-tab-font-size` | `var(--c-sys-font-size-xs)` |
| `--c-tabs-size-sm-tab-height` | `var(--c-sys-control-height-sm)` |
| `--c-tabs-size-sm-tab-padding` | `var(--c-sys-space-3) var(--c-sys-space-5)` |
| `--c-tabs-size-sm-tab-font-size` | `var(--c-sys-font-size-sm)` |
| `--c-tabs-size-md-tab-height` | `var(--c-sys-control-height-md)` |
| `--c-tabs-size-md-tab-padding` | `var(--c-sys-space-4) var(--c-sys-space-6)` |
| `--c-tabs-size-md-tab-font-size` | `var(--c-sys-font-size-md)` |
| `--c-tabs-size-lg-tab-height` | `var(--c-sys-control-height-lg)` |
| `--c-tabs-size-lg-tab-padding` | `10px var(--c-sys-space-7)` |
| `--c-tabs-size-lg-tab-font-size` | `var(--c-sys-font-size-lg)` |
| `--c-tabs-size-xl-tab-height` | `var(--c-sys-control-height-xl)` |
| `--c-tabs-size-xl-tab-padding` | `var(--c-sys-space-5) var(--c-sys-space-8)` |
| `--c-tabs-size-xl-tab-font-size` | `var(--c-sys-font-size-xl)` |

Both platforms keep the same API, state, lifecycle and keyboard behavior. Desktop and mobile differences use style tokens and pointer media queries; the packages remain independent at runtime.

## Independent source copies and public types

Both platforms independently maintain Tabs, TabPane, TabsNavs, TabNav, TabsItems and TabItem without cross-library runtimes or generic platform configuration. All xs/sm/md/lg/xl sizes are implemented. Cedar inherits ConfigProvider size/rtl. Maple defaults to md and supports setPropsDefaults, explicit size and DOM dir. Panels use native hidden; InfiniteScroll observes visibility directly rather than old panel registration.

Public types include TabsEmits, TabsSlots, TabPaneSlots, TabsNavsSlots, TabNavSlots, TabsItemsSlots, TabItemSlots and TabsNavsExpose. Only TabsNavs has its own method, resize(). Other members have no own imperative methods/notification events; selection/editing events belong to Tabs.

---

Document: llms/en-US/components/tag.md

<!-- Source: src/tag/README.en-US.md; locale: en-US; page: /en/components/tag/ -->

# Tag

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

- `color`: Overrides the color.

Example source: src/tag/__demos__/basic.vue

```vue
<template>
  <c-space wrap fill>
    <c-tag>Default</c-tag>
    <c-tag>Tag 1</c-tag>
    <c-tag>Tag 2</c-tag>
    <c-tag>
      <template #icon>
        <c-icon-check-circle-fill />
      </template>
      Complete
    </c-tag>
  </c-space>
  <br />
  <c-space wrap fill>
    <c-tag>gray</c-tag>
    <c-tag color="brand">brand</c-tag>
    <c-tag color="green">green</c-tag>
    <c-tag color="orange">orange</c-tag>
    <c-tag color="red">red</c-tag>
    <c-tag color="blue">blue</c-tag>
  </c-space>
</template>

<script lang="ts" setup>
</script>
```

## Appearance and states

### Color

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `color` | Custom background (border color when outline) | Color |
| `closable` | Whether the tag can be closed | Color |
<!-- demo-config-notes:end -->


- `color`: Overrides the color.

Example source: src/tag/__demos__/color.vue

```vue
<template>
  <c-space wrap>
    <c-tag v-for="(color, index) of colors" :key="index" :color="color" closable>{{ color }}</c-tag>
  </c-space>
  <h3>Custom Color:</h3>
  <c-space wrap>
    <c-tag v-for="(color, index) of custom" :key="index" :color="color" closable>{{ color }}</c-tag>
  </c-space>
</template>

<script lang="ts" setup>
const colors = [
  'red',
  'orangered',
  'orange',
  'gold',
  'lime',
  'green',
  'cyan',
  'blue',
  'brand',
  'purple',
  'pinkpurple',
  'magenta',
  'gray',
]
const custom = [
  '#f53f3f',
  '#7816ff',
  '#00b42a',
  '#00BEBE',
  '#ff7d00',
  '#eb0aa4',
  '#7bc616',
  '#86909c',
  '#b71de8',
  '#0fc6c2',
  '#ffb400',
  '#168cff',
  '#ff5722',
]
</script>
```

### Appearance configuration comparison

Choose an axis to compare its available values with the same content and model. Other settings remain unchanged while comparing.

Example source: src/tag/__demos__/appearance-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";

const __demoAppearance = __demoReactive({
  variant: "default",
  status: "default",
  size: "md",
});

import { computed as demoComputed, ref as demoRef } from 'vue'
const demoCompareFields = [{"name":"variant","values":["default","outline"]},{"name":"status","values":["default","primary","secondary","tertiary","info","success","warning","danger"]},{"name":"size","values":["xs","sm","md","lg","xl"]}]
const demoCompareAxis = demoRef("variant")
const demoComparedOptions = demoComputed(() => demoCompareFields.find(field => field.name === demoCompareAxis.value)?.values ?? [])
</script>
<template>
  <c-space direction="column" :size="16">
    <c-form layout="vertical">
      <c-form-item layout="vertical" size="sm" label="variant">
        <c-radio-group
          v-model="__demoAppearance['variant']"
          aria-label="variant"
          :options="[
            { label: 'default', value: 'default' },
            { label: 'outline', value: 'outline' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
      <c-form-item layout="vertical" size="sm" label="status">
        <c-select
          v-model="__demoAppearance['status']"
          :clearable="false"
          :options="[
            { label: 'default', value: 'default' },
            { label: 'primary', value: 'primary' },
            { label: 'secondary', value: 'secondary' },
            { label: 'tertiary', value: 'tertiary' },
            { label: 'info', value: 'info' },
            { label: 'success', value: 'success' },
            { label: 'warning', value: 'warning' },
            { label: 'danger', value: 'danger' },
          ]"
          aria-label="status"
        />
      </c-form-item>
      <c-form-item layout="vertical" size="sm" label="size">
        <c-radio-group
          v-model="__demoAppearance['size']"
          aria-label="size"
          :options="[
            { label: 'xs', value: 'xs' },
            { label: 'sm', value: 'sm' },
            { label: 'md', value: 'md' },
            { label: 'lg', value: 'lg' },
            { label: 'xl', value: 'xl' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
    </c-form>
    <p class="demo-config-comparison-hint"><span lang="zh-CN">选择一个对比维度；其他配置和内容保持一致。输入类示例共享同一个值，便于比较外观。</span><span lang="en-US">Compare one dimension while keeping the other settings and content identical. Input specimens share the same value.</span></p>
<c-radio-group v-model="demoCompareAxis" aria-label="Compare configuration" :options="demoCompareFields.map(field => ({ label: field.name, value: field.name }))" />
<div class="demo-config-comparison">
<section v-for="sample in demoComparedOptions" :key="String(sample)">
<p><code>{{ demoCompareAxis }}={{ sample }}</code></p>
<c-tag v-bind="{ ...__demoAppearance, [demoCompareAxis]: sample }">gray</c-tag>
</section>
</div>
  </c-space>
</template>

<style scoped>
.demo-config-comparison { display: grid; grid-template-columns: repeat(auto-fit, minmax(min(100%, 220px), 1fr)); gap: 20px; min-width: 0; max-width: 100%; }
.demo-config-comparison > section { min-width: 0; }
.demo-config-comparison p { margin: 0 0 8px; }
html:not([lang='en-US']) .demo-config-comparison-hint > [lang='en-US'],
html[lang='en-US'] .demo-config-comparison-hint > [lang='zh-CN'] { display: none; }
</style>
```

## Content and presentation

### Checkable

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `color` | Custom background (border color when outline) | Checkable, Icon |
| `checkable` | Whether the tag is selectable | Checkable |
| `status` | Tag status `color`; mutually exclusive with `color`, which takes precedence | Checkable |
| `default-value` | Default checked state of a selectable tag | Checkable |
| `variant` | Tag variant, aligned with Button | Checkable |
| `loading` | Whether the tag is loading | Checkable |
<!-- demo-config-notes:end -->


- `status`: Selects the semantic state.
- `variant`: Selects the visual variant.
- `color`: Overrides the color.

Example source: src/tag/__demos__/checkable.vue

```vue
<template>
  <c-space wrap>
    <c-tag checkable>Awesome</c-tag>
    <c-tag checkable status="primary" :default-value="false">点击选中</c-tag>
    <c-tag checkable status="warning" variant="outline">描边状态</c-tag>
    <c-tag checkable status="success" loading>加载中</c-tag>
    <c-tag checkable color="red" :default-value="true">Toutiao</c-tag>
    <c-tag checkable color="brand" :default-value="true">Lark</c-tag>
  </c-space>
</template>

<script lang="ts" setup>
</script>
```

### Icon

- `color`: Overrides the color.

Example source: src/tag/__demos__/icon.vue

```vue
<template>
  <c-space wrap>
    <c-tag color="gray">
      <template #icon>
        <c-icon-github />
      </template>
      Github
    </c-tag>
    <c-tag color="orangered">
      <template #icon>
        <c-icon-gitlab />
      </template>
      Gitlab
    </c-tag>
    <c-tag color="blue">
      <template #icon>
        <c-icon-twitter />
      </template>
      Twitter
    </c-tag>
    <c-tag color="brand">
      <template #icon>
        <c-icon-facebook />
      </template>
      Facebook
    </c-tag>
  </c-space>
</template>

<script lang="ts" setup>
</script>
```

## Interaction and control

### Closable

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `closable` | Whether the tag can be closed | Closable, Dynamic Tag |
| `loading` | Whether the tag is loading | Loading |
<!-- demo-config-notes:end -->


Preview configuration: `closable`.

Example source: src/tag/__demos__/closable.vue

```vue
<template>
  <c-space wrap>
    <c-tag closable>Tag</c-tag>
    <c-tag closable>
      <template #icon>
        <c-icon-star />
      </template>
      Tag
    </c-tag>
  </c-space>
</template>

<script lang="ts" setup>
</script>
```

### Dynamic Tag

Preview configuration: `:closable="index !== 0"`, `size="xs"`.

Example source: src/tag/__demos__/dynamic-tag.vue

```vue
<template>
  <c-space wrap>
    <c-tag v-for="(tag, index) of tags" :key="tag" :closable="index !== 0" @close="handleRemove(tag)">
      {{ tag }}
    </c-tag>

    <c-input
      v-if="showInput"
      ref="inputRef"
      :style="{ width: '90px' }"
      size="xs"
      v-model.trim="inputVal"
      @keyup.enter="handleAdd"
      @blur="handleAdd" />
    <c-tag
      v-else
      :style="{
        width: '90px',
        backgroundColor: 'var(--color-fill-2)',
        border: '1px dashed var(--color-fill-3)',
        cursor: 'pointer',
      }"
      @click="handleEdit"
    >
      <template #icon>
        <c-icon-plus />
      </template>
      Add Tag
    </c-tag>
  </c-space>
</template>

<script lang="ts" setup>
import { ref, nextTick } from 'vue'
const tags = ref(['Tag 1', 'Tag 2', 'Tag 3'])
const inputRef = ref(null)
const showInput = ref(false)
const inputVal = ref('')

const handleEdit = () => {
  showInput.value = true

  nextTick(() => {
    if (inputRef.value) {
      inputRef.value.focus()
    }
  })
}

const handleAdd = () => {
  if (inputVal.value) {
    tags.value.push(inputVal.value)
    inputVal.value = ''
  }
  showInput.value = false
}

const handleRemove = (key) => {
  tags.value = tags.value.filter((tag) => tag !== key)
}
</script>
```

### Loading

Preview configuration: `loading`.

Example source: src/tag/__demos__/loading.vue

```vue
<template>
  <c-tag loading>Loading</c-tag>
</template>

<script lang="ts" setup>
</script>
```

## API

### Value and default value

Use ordinary `v-model`. `modelValue` is a selectable tag's boolean checked state. `defaultValue` initializes uncontrolled state once; later changes do not reset it. Explicit binding takes precedence, without initialization `update:modelValue`.

### `<Tag>` Props

| Prop | Description | Type | Default |
| --------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- |
| color | Custom background (border color when outline) | `string` | - |
| text-color | Custom text color | `string` | - |
| status | Tag status `color`; mutually exclusive with `color`, which takes precedence | `'default' \| 'primary' \| 'secondary' \| 'tertiary' \| 'info' \| 'success' \| 'warning' \| 'danger'` | `'default'` |
| variant | Tag variant, aligned with Button | `'default' \| 'outline'` | `'default'` |
| size | Tag size | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` |
| show **(v-model)** | Whether the tag is visible | `boolean` | - |
| default-show | Default tag visibility | `boolean` | `true` |
| loading | Whether the tag is loading | `boolean` | `false` |
| closable | Whether the tag can be closed | `boolean` | `false` |
| checkable | Whether the tag is selectable | `boolean` | `false` |
| model-value **(v-model)** | Whether a selectable tag is checked | `boolean` | - |
| default-value | Default checked state of a selectable tag | `boolean` | `true` |
| nowrap | Whether content is nowrap with ellipsis | `boolean` | `false` |
| round | Whether to use a pill shape | `boolean` | `false` |

### `<Tag>` Events

| Event | Description | Arguments |
| ------ | -------------------------------------- | --------------------------------------------- |
| close | Triggered when the Close button is clicked and can only be used when the Close button is displayed | `(event: MouseEvent) => void` |
| check | Emitted on user selection, only in selectable mode | `(check: boolean, event: MouseEvent) => void` |
| update:show | Visibility changed | `(show: boolean) => void` |
| update:model-value | Checked-state change | `(checked: boolean) => void` |

### `<Tag>` Slots

| Slot | Description | Arguments |
| ---------- | -------------- | ---- |
| default | Tag content | - |
| icon | Icon | - |
| close-icon | Close-button icon | - |

### Type definitions

The component exports the following types

```ts
import type { TagProps } from '@cedar-design/ui'
```

## Shared implementation and platform boundaries

Each platform maintains a complete local implementation. They do not import a common core or share component instances or reactive state. Changes must update both implementations. Component bodies, props, key styles and paired tests have read-only source consistency checks; theme tokens and installation entries remain local to each library.

Both retain independent show/checked state, with controlled values updated by callers. Fade-out remains; class/style fall through explicitly to the actual tag. Size configuration, RTL context and icons are locally adapted. Mobile touch dimensions remain in tokens.

### Complete variable defaults and boundaries

Status text and outline borders use readable system content colors; colored fills use palette level 1. Unchecked stays neutral; checked status colors override generic hover. Neutral fills use fill-2 → fill-3. color overrides status; preset colors are outside this contrast guarantee. Callers must check custom backgrounds and set text-color if needed. Platform dimensions remain distinct. All public declarations are listed; 15 unused preset-icon hover-background/size variables, custom-icon-bg-hover and old InputTag references are removed without aliases.

| Variable | Default |
| --- | --- |
| `--c-tag-status-primary-bg-color` | `rgb(var(--c-primary-1))` |
| `--c-tag-status-primary-text-color` | `var(--c-sys-color-content-brand)` |
| `--c-tag-status-secondary-bg-color` | `rgb(var(--c-gray-2))` |
| `--c-tag-status-secondary-text-color` | `var(--c-sys-color-content-secondary)` |
| `--c-tag-status-tertiary-bg-color` | `rgb(var(--c-gray-1))` |
| `--c-tag-status-tertiary-text-color` | `var(--c-sys-color-content-secondary)` |
| `--c-tag-status-info-bg-color` | `rgb(var(--c-blue-1))` |
| `--c-tag-status-info-text-color` | `var(--c-sys-color-content-info)` |
| `--c-tag-status-success-bg-color` | `rgb(var(--c-success-1))` |
| `--c-tag-status-success-text-color` | `var(--c-sys-color-content-success)` |
| `--c-tag-status-warning-bg-color` | `rgb(var(--c-warning-1))` |
| `--c-tag-status-warning-text-color` | `var(--c-sys-color-content-warning)` |
| `--c-tag-status-danger-bg-color` | `rgb(var(--c-danger-1))` |
| `--c-tag-status-danger-text-color` | `var(--c-sys-color-content-danger)` |
| `--c-tag-variant-outline-status-primary-color` | `var(--c-sys-color-content-brand)` |
| `--c-tag-variant-outline-status-secondary-color` | `var(--c-sys-color-content-secondary)` |
| `--c-tag-variant-outline-status-tertiary-color` | `var(--c-sys-color-content-secondary)` |
| `--c-tag-variant-outline-status-info-color` | `var(--c-sys-color-content-info)` |
| `--c-tag-variant-outline-status-success-color` | `var(--c-sys-color-content-success)` |
| `--c-tag-variant-outline-status-warning-color` | `var(--c-sys-color-content-warning)` |
| `--c-tag-variant-outline-status-danger-color` | `var(--c-sys-color-content-danger)` |
| `--c-tag-variant-outline-default-color` | `var(--c-sys-color-content-primary)` |
| `--c-tag-variant-outline-default-border-color` | `var(--c-sys-color-border-default)` |
| `--c-tag-border-width` | `1px` |
| `--c-tag-border-type` | `solid` |
| `--c-tag-padding-horizontal` | `var(--c-spacing-4)` |
| `--c-tag-padding-vertical` | `0` |
| `--c-tag-icon-margin-right` | `var(--c-spacing-2)` |
| `--c-tag-text-font-weight` | `var(--c-font-weight-500)` |
| `--c-tag-border-radius` | `var(--c-sys-radius-sm)` |
| `--c-tag-round-radius` | `100px` |
| `--c-tag-size-xs` | `var(--c-size-4)` |
| `--c-tag-size-sm` | `var(--c-size-5)` |
| `--c-tag-size-md` | `var(--c-size-6)` |
| `--c-tag-size-lg` | `var(--c-size-7)` |
| `--c-tag-size-xl` | `var(--c-size-8)` |
| `--c-tag-size-xs-font-size` | `var(--c-sys-font-size-xs)` |
| `--c-tag-size-sm-font-size` | `var(--c-sys-font-size-xs)` |
| `--c-tag-size-md-font-size` | `var(--c-sys-font-size-xs)` |
| `--c-tag-size-lg-font-size` | `var(--c-sys-font-size-md)` |
| `--c-tag-size-xl-font-size` | `var(--c-sys-font-size-md)` |
| `--c-tag-bg-not-checked-hover` | `var(--c-sys-color-state-hover)` |
| `--c-tag-custom-text-color` | `var(--c-sys-color-content-on-dark)` |
| `--c-tag-default-bg` | `var(--c-sys-color-state-hover)` |
| `--c-tag-default-bg-hover` | `var(--c-color-fill-3)` |
| `--c-tag-default-icon-color` | `var(--c-sys-color-content-secondary)` |
| `--c-tag-default-text-color` | `var(--c-sys-color-content-primary)` |
| `--c-tag-default-border-color` | `transparent` |
| `--c-tag-default-border-color-hover` | `transparent` |
| `--c-tag-red-bg` | `rgb(var(--c-red-1))` |
| `--c-tag-red-bg-hover` | `rgb(var(--c-red-2))` |
| `--c-tag-red-border-color` | `transparent` |
| `--c-tag-red-border-color-hover` | `transparent` |
| `--c-tag-red-icon-color` | `rgb(var(--c-red-9))` |
| `--c-tag-red-text-color` | `rgb(var(--c-red-9))` |
| `--c-tag-orangered-bg` | `rgb(var(--c-orangered-1))` |
| `--c-tag-orangered-bg-hover` | `rgb(var(--c-orangered-2))` |
| `--c-tag-orangered-border-color` | `transparent` |
| `--c-tag-orangered-border-color-hover` | `transparent` |
| `--c-tag-orangered-icon-color` | `rgb(var(--c-orangered-9))` |
| `--c-tag-orangered-text-color` | `rgb(var(--c-orangered-9))` |
| `--c-tag-orange-bg` | `rgb(var(--c-orange-1))` |
| `--c-tag-orange-bg-hover` | `rgb(var(--c-orange-2))` |
| `--c-tag-orange-border-color` | `transparent` |
| `--c-tag-orange-border-color-hover` | `transparent` |
| `--c-tag-orange-icon-color` | `rgb(var(--c-orange-9))` |
| `--c-tag-orange-text-color` | `rgb(var(--c-orange-9))` |
| `--c-tag-gold-bg` | `rgb(var(--c-gold-1))` |
| `--c-tag-gold-bg-hover` | `rgb(var(--c-gold-2))` |
| `--c-tag-gold-border-color` | `transparent` |
| `--c-tag-gold-border-color-hover` | `transparent` |
| `--c-tag-gold-icon-color` | `rgb(var(--c-gold-9))` |
| `--c-tag-gold-text-color` | `rgb(var(--c-gold-9))` |
| `--c-tag-lime-bg` | `rgb(var(--c-lime-1))` |
| `--c-tag-lime-bg-hover` | `rgb(var(--c-lime-2))` |
| `--c-tag-lime-border-color` | `transparent` |
| `--c-tag-lime-border-color-hover` | `transparent` |
| `--c-tag-lime-icon-color` | `rgb(var(--c-lime-9))` |
| `--c-tag-lime-text-color` | `rgb(var(--c-lime-9))` |
| `--c-tag-green-bg` | `rgb(var(--c-green-1))` |
| `--c-tag-green-bg-hover` | `rgb(var(--c-green-2))` |
| `--c-tag-green-border-color` | `transparent` |
| `--c-tag-green-border-color-hover` | `transparent` |
| `--c-tag-green-icon-color` | `rgb(var(--c-green-9))` |
| `--c-tag-green-text-color` | `rgb(var(--c-green-9))` |
| `--c-tag-cyan-bg` | `rgb(var(--c-cyan-1))` |
| `--c-tag-cyan-bg-hover` | `rgb(var(--c-cyan-2))` |
| `--c-tag-cyan-border-color` | `transparent` |
| `--c-tag-cyan-border-color-hover` | `transparent` |
| `--c-tag-cyan-icon-color` | `rgb(var(--c-cyan-9))` |
| `--c-tag-cyan-text-color` | `rgb(var(--c-cyan-9))` |
| `--c-tag-blue-bg` | `rgb(var(--c-blue-1))` |
| `--c-tag-blue-bg-hover` | `rgb(var(--c-blue-2))` |
| `--c-tag-blue-border-color` | `transparent` |
| `--c-tag-blue-border-color-hover` | `transparent` |
| `--c-tag-blue-icon-color` | `rgb(var(--c-blue-9))` |
| `--c-tag-blue-text-color` | `rgb(var(--c-blue-9))` |
| `--c-tag-brand-bg` | `rgb(var(--c-brand-1))` |
| `--c-tag-brand-bg-hover` | `rgb(var(--c-brand-2))` |
| `--c-tag-brand-border-color` | `transparent` |
| `--c-tag-brand-border-color-hover` | `transparent` |
| `--c-tag-brand-icon-color` | `rgb(var(--c-brand-9))` |
| `--c-tag-brand-text-color` | `rgb(var(--c-brand-9))` |
| `--c-tag-purple-bg` | `rgb(var(--c-purple-1))` |
| `--c-tag-purple-bg-hover` | `rgb(var(--c-purple-2))` |
| `--c-tag-purple-border-color` | `transparent` |
| `--c-tag-purple-border-color-hover` | `transparent` |
| `--c-tag-purple-icon-color` | `rgb(var(--c-purple-9))` |
| `--c-tag-purple-text-color` | `rgb(var(--c-purple-9))` |
| `--c-tag-pinkpurple-bg` | `rgb(var(--c-pinkpurple-1))` |
| `--c-tag-pinkpurple-bg-hover` | `rgb(var(--c-pinkpurple-2))` |
| `--c-tag-pinkpurple-border-color` | `transparent` |
| `--c-tag-pinkpurple-border-color-hover` | `transparent` |
| `--c-tag-pinkpurple-icon-color` | `rgb(var(--c-pinkpurple-9))` |
| `--c-tag-pinkpurple-text-color` | `rgb(var(--c-pinkpurple-9))` |
| `--c-tag-magenta-bg` | `rgb(var(--c-magenta-1))` |
| `--c-tag-magenta-bg-hover` | `rgb(var(--c-magenta-2))` |
| `--c-tag-magenta-border-color` | `transparent` |
| `--c-tag-magenta-border-color-hover` | `transparent` |
| `--c-tag-magenta-icon-color` | `rgb(var(--c-magenta-9))` |
| `--c-tag-magenta-text-color` | `rgb(var(--c-magenta-9))` |
| `--c-tag-gray-bg` | `rgb(var(--c-gray-2))` |
| `--c-tag-gray-bg-hover` | `rgb(var(--c-gray-3))` |
| `--c-tag-gray-border-color` | `transparent` |
| `--c-tag-gray-border-color-hover` | `transparent` |
| `--c-tag-gray-icon-color` | `var(--c-sys-color-content-secondary)` |
| `--c-tag-gray-text-color` | `var(--c-sys-color-content-secondary)` |
| `--c-tag-close-margin-left` | `var(--c-spacing-2)` |
| `--c-tag-close-font-size` | `var(--c-sys-font-size-xs)` |

### Color override boundaries

Preset outline stays transparent; loading does not trigger preset fill hover. Dark backgrounds consume bg/bg-hover with instance overrides. Preset icon-color is separate from text-color. Unchecked presets remain neutral, while an explicit color still applies. Preset/custom colors do not guarantee contrast on arbitrary backgrounds.

### Motion variables

Built-in motion follows `prefers-reduced-motion: reduce`. Reduced motion does not prevent loading-state or close-event updates.

| Token | Default |
| --- | --- |
| `--c-tag-fade-duration` | `var(--c-sys-motion-duration-fast)` |

---

Document: llms/en-US/components/textarea.md

<!-- Source: src/textarea/README.en-US.md; locale: en-US; page: /en/components/textarea/ -->

# Textarea

Multiline text input.

## Reading direction

The textarea inherits source `dir`, aligns text to inline start and its counter to inline end. Runtime direction changes retain the native editor, focus and selection; native caret and newline keys keep their meanings.

## Basic examples

### Basic usage

Example source: src/textarea/__demos__/basic.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const value = ref('')
const trimmed = ref('')
</script>
<template>
  <c-space direction="column">
    <c-textarea v-model="value" clearable placeholder="请输入多行文本" aria-label="受控文本" />
    <p role="status">当前值：{{ value || '（空）' }}</p>
    <c-textarea default-value="这是一段非受控初始文本" aria-label="非受控文本" />
    <c-textarea v-model.trim="trimmed" placeholder="输入首尾空白，失焦后去除" aria-label="去除首尾空白" />
    <p role="status">去除空白后的值：{{ JSON.stringify(trimmed) }}</p>
  </c-space>
</template>
```

## Appearance and states

### Status

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration   | Purpose                           | Related examples |
| --------------- | --------------------------------- | ---------------- |
| `placeholder`   | Placeholder text                  | Status           |
| `variant`       | `filled` / `outline` / `standard` | Status           |
| `default-value` | Uncontrolled initial value        | Status           |
| `readonly`      | Whether readonly                  | Status           |
| `disabled`      | Whether disabled                  | Status           |
| `error`         | Show the error state              | Status           |

<!-- demo-config-notes:end -->

- `variant`: Selects the visual variant.
- `readonly`: Displays the current value without allowing edits.
- `disabled`: Prevents user interaction.

Example source: src/textarea/__demos__/status.vue

```vue
<template>
  <c-space direction="column" size="lg" fill>
    <c-textarea placeholder="默认描边外观" />
    <c-textarea variant="filled" placeholder="填充外观" />
    <c-textarea variant="standard" placeholder="标准外观" />
    <c-textarea default-value="Readonly value" readonly />
    <c-textarea placeholder="Disabled status" disabled />
    <c-textarea placeholder="Error status" error />
  </c-space>
</template>
```

### Appearance Lab

Example source: src/textarea/__demos__/appearance-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref("这是一段可以编辑的多行内容。");
const __demoAppearance = __demoReactive({ variant: "filled", size: "md" });

import { computed as demoComputed, ref as demoRef } from 'vue'
const demoCompareFields = [{"name":"variant","values":["filled","outline","standard"]},{"name":"size","values":["xs","sm","md","lg","xl"]}]
const demoCompareAxis = demoRef("variant")
const demoComparedOptions = demoComputed(() => demoCompareFields.find(field => field.name === demoCompareAxis.value)?.values ?? [])
</script>
<template>
  <c-space direction="column" :size="16">
    <c-form layout="vertical">
      <c-form-item layout="vertical" size="sm" label="variant">
        <c-radio-group
          v-model="__demoAppearance['variant']"
          aria-label="variant"
          :options="[
            { label: 'filled', value: 'filled' },
            { label: 'outline', value: 'outline' },
            { label: 'standard', value: 'standard' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
      <c-form-item layout="vertical" size="sm" label="size">
        <c-radio-group
          v-model="__demoAppearance['size']"
          aria-label="size"
          :options="[
            { label: 'xs', value: 'xs' },
            { label: 'sm', value: 'sm' },
            { label: 'md', value: 'md' },
            { label: 'lg', value: 'lg' },
            { label: 'xl', value: 'xl' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
    </c-form>
    <p class="demo-config-comparison-hint"><span lang="zh-CN">选择一个对比维度；其他配置和内容保持一致。输入类示例共享同一个值，便于比较外观。</span><span lang="en-US">Compare one dimension while keeping the other settings and content identical. Input specimens share the same value.</span></p>
<c-radio-group v-model="demoCompareAxis" aria-label="Compare configuration" :options="demoCompareFields.map(field => ({ label: field.name, value: field.name }))" />
<div class="demo-config-comparison">
<section v-for="sample in demoComparedOptions" :key="String(sample)">
<p><code>{{ demoCompareAxis }}={{ sample }}</code></p>
<c-textarea v-model="value" v-bind="{ ...__demoAppearance, [demoCompareAxis]: sample }"></c-textarea>
</section>
</div>
  </c-space>
</template>

<style scoped>
.demo-config-comparison { display: grid; grid-template-columns: repeat(auto-fit, minmax(min(100%, 220px), 1fr)); gap: 20px; min-width: 0; max-width: 100%; }
.demo-config-comparison > section { min-width: 0; }
.demo-config-comparison p { margin: 0 0 8px; }
html:not([lang='en-US']) .demo-config-comparison-hint > [lang='en-US'],
html[lang='en-US'] .demo-config-comparison-hint > [lang='zh-CN'] { display: none; }
</style>
```

## Content and presentation

### Max Length

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration     | Purpose                                      | Related examples |
| ----------------- | -------------------------------------------- | ---------------- |
| `placeholder`     | Placeholder text                             | Max Length       |
| `max-length`      | Truncating or error-only length limit        | Max Length       |
| `clearable`       | Enables the clear action                     | Max Length       |
| `show-word-limit` | Show the character counter                   | Max Length       |
| `aria-label`      | Accessible name when no visible label exists | Native Attrs     |
| `rows`            | Native visible row count                     | Native Attrs     |

<!-- demo-config-notes:end -->

Example source: src/textarea/__demos__/max-length.vue

```vue
<template>
  <c-space direction="column" size="lg" fill>
    <p>长度按 UTF-16 码元计算；试着输入 123456789😀Z，默认截断保留 123456789，不拆开 emoji。</p>
    <c-textarea
      v-model="limited"
      placeholder="超过 10 个字符会截断"
      :max-length="10"
      clearable
      show-word-limit
    />
    <c-textarea
      v-model="errorOnly"
      placeholder="超过 10 个字符后保留内容并显示错误"
      :max-length="{ length: 10, errorOnly: true }"
      clearable
      show-word-limit
    />
  </c-space>
</template>

<script lang="ts" setup>
import { ref } from "vue";

const limited = ref("");
const errorOnly = ref("超过长度的内容会保留");
</script>
```

### Native Attrs

Example source: src/textarea/__demos__/native-attrs.vue

```vue
<template>
  <label for="feedback">反馈内容</label>
  <c-textarea
    v-model="value"
    aria-label="反馈内容"
    :rows="4"
    :textarea-attrs="{
      id: 'feedback',
      name: 'feedback',
      autocomplete: 'off',
      'aria-describedby': 'feedback-help',
    }"
  />
  <p id="feedback-help">请勿填写密码或其他敏感信息。</p>
</template>

<script lang="ts" setup>
import { ref } from "vue";

const value = ref("");
</script>
```

## Customization and slots

### Slots

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration | Purpose                  | Related examples |
| ------------- | ------------------------ | ---------------- |
| `clearable`   | Enables the clear action | Slots            |
| `placeholder` | Placeholder text         | Slots            |

<!-- demo-config-notes:end -->

Example source: src/textarea/__demos__/slots.vue

```vue
<template>
  <c-textarea v-model="value" clearable placeholder="带前后缀和自定义清除按钮">
    <template #prefix>说明</template>
    <template #suffix>Markdown</template>
    <template #clear-icon="{ clear }">
      <c-button html-type="button" aria-label="清空文本" @click="clear"
        >×</c-button
      >
    </template>
  </c-textarea>
</template>

<script lang="ts" setup>
import { ref } from "vue";

const value = ref("可清空内容");
</script>
```

## Interaction and control

### State Lab

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration | Purpose                                                | Related examples                      |
| ------------- | ------------------------------------------------------ | ------------------------------------- |
| `placeholder` | Placeholder text                                       | Auto Size, Interaction, Body Contract |
| `rows`        | Native visible row count                               | Auto Size, Body Contract              |
| `auto-size`   | Automatic height, optionally with minimum/maximum rows | Auto Size, Body Contract              |
| `clearable`   | Enables the clear action                               | Interaction, Body Contract            |
| `disabled`    | Whether disabled                                       | State Lab                             |
| `readonly`    | Whether readonly                                       | State Lab                             |

<!-- demo-config-notes:end -->

Example source: src/textarea/__demos__/state-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref("这是一段可以编辑的多行内容。");
const __demoState = __demoReactive({
  disabled: false,
  readonly: false,
  error: false,
});
</script>
<template>
  <c-space direction="column" :size="16">
    <c-space wrap>
      <c-checkbox v-model="__demoState['disabled']">disabled</c-checkbox>
      <c-checkbox v-model="__demoState['readonly']">readonly</c-checkbox>
      <c-checkbox v-model="__demoState['error']">error</c-checkbox>
    </c-space>
    <c-textarea v-model="value" v-bind="__demoState"></c-textarea>
  </c-space>
</template>
```

### Auto Size

Example source: src/textarea/__demos__/auto-size.vue

```vue
<template>
  <c-space direction="column" size="lg" fill>
    <c-textarea default-value="原生三行，可纵向拖动" :rows="3" />
    <c-textarea v-model="content" auto-size placeholder="随内容自动增高" />
    <c-textarea
      v-model="boundedContent"
      :auto-size="{ minRows: 2, maxRows: 5 }"
      placeholder="自动高度限制在 2 到 5 行"
    />
  </c-space>
</template>

<script lang="ts" setup>
import { ref } from "vue";

const content = ref("第一行");
const boundedContent = ref("第一行\n第二行");
</script>
```

### Interaction

Example source: src/textarea/__demos__/interaction.vue

```vue
<template>
  <c-space direction="column" size="lg" fill>
    <c-textarea
      v-model="value"
      clearable
      placeholder="输入、换行并失焦以观察事件"
      @input="record('input', $event)"
      @change="record('change', $event)"
      @keydown="record('keydown')"
      @clear="record('clear')"
      @blur="record('blur')"
    />
    <span>最近事件：{{ latest || "-" }}</span>
  </c-space>
</template>

<script lang="ts" setup>
import { ref } from "vue";

const value = ref("Cedar");
const latest = ref("");

const record = (name: string, value?: string) => {
  latest.value = value === undefined ? name : `${name}: ${value}`;
};
</script>
```

### Body Contract

Example source: src/textarea/__demos__/body-contract.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const value = ref('可编辑内容')
const events = ref<string[]>([])
const record = (name: string) => { events.value = [...events.value.slice(-7), name] }
</script>
<template>
  <div class="textarea-body-demo">
    <c-textarea v-model="value" hint clearable placeholder="工作备注" :auto-size="{ minRows: 2, maxRows: 5 }" :max-length="100" show-word-limit @clear="record('clear')" @input="record('input')" @update:model-value="record('update:modelValue')" @change="record('change')" />
    <c-textarea :line="false" hint placeholder="无边框提示" focus-color="#137547" :rows="2" />
    <p>Enter 保持换行；失焦提交 change；清空完整通知一次。</p>
    <output>{{ events.join(' → ') || '等待操作' }}</output>
  </div>
</template>
<style scoped>
.textarea-body-demo { display: flex; flex-direction: column; gap: 16px; }
.textarea-body-demo p { margin: 0; }
</style>
```

## Design notes

- Defaults to `outline` with `clearable` disabled.
- `input` means live editing; `change` commits on changed blur or clear. Enter remains a newline.
- `auto-size` lets content determine height, overriding visual effects of `rows`/manual `resize`.
- Form/FormItem own business validation/messages; Textarea supplies event signals/error appearance only.

### Shared field loading

`loading` displays the shared field indicator. `loading-mode` is `default` (indicator) or `line` (an indeterminate bottom line); it defaults to `default`. Rendering belongs to FieldDecorator. Loading does not implicitly disable editing or change readonly. Set those states separately.

## API

### Empty values and reading placeholders

`empty-values` recognizes empty data; `empty-value` keeps existing clear output. `empty-text` defaults to `'-'` under `read-pretty`, with Field > FormItem > Form precedence and custom read slots first. With explicit empty-values, built-in required uses the policy; custom validators receive original data. See the [shared guide](llms/en-US/guide/empty-values.md).

| Prop         | Type               | Default and scope                                                           |
| ------------ | ------------------ | --------------------------------------------------------------------------- |
| empty-values | readonly unknown[] | Field > FormItem > Form > component-family default; replaces the whole list |
| empty-text   | string             | Field > FormItem > Form > '-'; explicit '' is valid                         |

These props belong to field presentation; pure panels do not gain reading mode. Form and FormItem provide inherited settings. The existing empty-value type and clear fallback remain component-specific.

### Textarea Props

Supports Input-compatible hint, line, text-color, focus-color and blur-color. Omitted hint inherits InputGroup/library defaults. An outer FormItem label hides the internal floating hint.

| Prop                    | Description                                                      | Type                                                | Default   |
| ----------------------- | ---------------------------------------------------------------- | --------------------------------------------------- | --------- |
| model-value (`v-model`) | Controlled value                                                 | `string`                                            | `-`       |
| default-value           | Uncontrolled initial value                                       | `string`                                            | `''`      |
| model-modifiers         | Supports the `trim` model modifier                               | `{ trim?: boolean }`                                | `{}`      |
| placeholder             | Placeholder text                                                 | `string`                                            | `-`       |
| variant                 | `filled` / `outline` / `standard`                                | `FormControlVariant`                                | `outline` |
| size                    | `xs` / `sm` / `md` / `lg` / `xl`                                 | `ComponentSize`                                     | `md`      |
| clearable               | Enables the clear action                                         | `boolean`                                           | `false`   |
| disabled                | Whether disabled                                                 | `boolean`                                           | `false`   |
| readonly                | Whether readonly                                                 | `boolean`                                           | `false`   |
| error                   | Show the error state                                             | `boolean`                                           | `false`   |
| rows                    | Native visible row count                                         | `string \| number`                                  | `-`       |
| resize                  | Allows vertical manual resizing                                  | `boolean`                                           | `true`    |
| auto-size               | Automatic height, optionally with minimum/maximum rows           | `boolean \| { minRows?: number; maxRows?: number }` | `false`   |
| max-length              | Truncating or error-only length limit                            | `number \| { length: number; errorOnly?: boolean }` | `0`       |
| show-word-limit         | Show the character counter                                       | `boolean`                                           | `false`   |
| word-length             | Custom length function                                           | `(value: string) => number`                         | `-`       |
| word-slice              | Custom slice function                                            | `(value: string, maxLength: number) => string`      | `-`       |
| aria-label              | Accessible name when no visible label exists                     | `string`                                            | `-`       |
| autofocus               | Focus automatically after mount                                  | `boolean`                                           | `false`   |
| enterkeyhint            | Virtual keyboard Enter hint                                      | `string`                                            | `-`       |
| textarea-attrs          | Supplemental native textarea attributes                          | `Record<string, unknown>`                           | `-`       |
| hint                    | Floating hint; inherits InputGroup/library defaults when omitted | boolean                                             | undefined |
| line                    | Show border/underline                                            | boolean                                             | true      |
| text-color              | Instance text color                                              | string                                              | undefined |
| focus-color             | Instance focus color                                             | string                                              | undefined |
| blur-color              | Instance unfocused hint color                                    | string                                              | undefined |

### Textarea Events

| Event   | Description                                    | Arguments                  |
| ------- | ---------------------------------------------- | -------------------------- |
| input   | User input after IME composition               | `value: string, ev: Event` |
| change  | Changed value committed on blur                | `value: string, ev: Event` |
| keydown | Native keydown signal; Enter remains a newline | `ev: KeyboardEvent`        |
| clear   | Clear → input → update:model-value → change    | `ev: Event`                |
| focus   | Emitted on focus                               | `ev: FocusEvent`           |
| blur    | Emitted on blur                                | `ev: FocusEvent`           |

### Textarea Slots

| Slot       | Description          | Arguments                     |
| ---------- | -------------------- | ----------------------------- |
| prefix     | Prefix content       | `-`                           |
| suffix     | Suffix content       | `-`                           |
| clear-icon | Clear icon or button | `clear: (ev?: Event) => void` |

### Textarea Methods

| Method | Description                 |
| ------ | --------------------------- |
| focus  | Focus the internal textarea |
| blur   | Blur the internal textarea  |

## Type definitions

```ts
import type {
  TextareaAutoSize,
  TextareaMaxLength,
  TextareaProps,
  WordLength,
  WordSlice,
} from "@cedar-design/ui";
```

## Style variables

| Variable                          | Default                           |
| --------------------------------- | --------------------------------- |
| `--c-textarea-height`             | `auto`                            |
| `--c-textarea-min-height`         | `--c-sys-control-height-xl`       |
| `--c-textarea-font-size`          | `--c-sys-font-size-md`            |
| `--c-textarea-line-height`        | `--c-line-height`                 |
| `--c-textarea-padding-horizontal` | `--c-sys-space-3`                 |
| `--c-textarea-padding-vertical`   | `--c-sys-space-1`                 |
| `--c-textarea-placeholder-color`  | `--c-sys-color-content-secondary` |
| `--c-textarea-counter-color`      | `--c-sys-color-content-secondary` |
| `--c-textarea-counter-font-size`  | `--c-sys-font-size-xs`            |
| `--c-textarea-counter-margin-top` | `var(--c-sys-space-2)`            |

Both counters sit outside the textarea. counter-margin-top controls their gap and avoids covering text.

### Native layout and public types

size supports five FieldDecorator densities: xs/sm/md/lg/xl. rows, auto-size and Textarea tokens still control textarea height/text metrics. Cedar allows manual resize by default; Maple does not. InputGroup/Form state is inherited, with explicit child values taking precedence. Exposes focus(options?), blur(), select() and textareaRef.

`TextareaProps`、`TextareaVariant`、`TextareaMaxLength`、`TextareaAutoSize`、`TextareaEmits`、`TextareaSlots`、`TextareaExpose`、`TextareaInstance`。

Native methods: `focus(options?: FocusOptions)`, `blur()`, `select()`; `textareaRef` is the native element.

### Form field presentation and confirmation

This component supports `edit-mode` with field > FormItem > Form precedence. When unset, it defaults to `direct` and preserves `direct` editing. Supported values: `direct / click / dblclick`. Non-`direct` modes open the editor through the field value trigger and keep one draft; v-model updates only after confirmation. Cancel, reset or enabling readPretty discards the draft.

Cedar uses edit-mode="click" / "dblclick" to open an editor popup near the field. Enter/F2 also opens it; cancel/Escape discards the draft, and confirmation commits it. readPretty is an independent reading setting, separate from readonly and disabled.

`before-commit(value, { previousValue, signal })` can reject an overlay save. FormItem validates the candidate first and keeps the editor open on failure. `open / default-open / update:open` control the editor. Use `#read="{ value, text }"` to customize display. See the full field comparison in Form.

`read-pretty` is an independent boolean alongside `readonly` and `disabled`. It inherits from field to FormItem to Form; explicit `false` overrides the parent. The default is `false`. Reading mode renders no editor.

`--c-field-caret-color` sets the shared caret color, defaulting to `currentColor`. `--c-textarea-caret-color` overrides this component and defaults to `var(--c-field-caret-color)`.

## Configuring the cleared value

`empty-value` / `emptyValue` sets the model value produced by clearing. It accepts a value in the component model type or a zero-argument factory. Omission preserves the existing default; use `() => undefined` to distinguish omission from returning undefined. Arrays are shallow-copied on every clear; selected items that cannot be cleared remain. It does not redefine emptiness, alter Form reset defaults or treat 0/false as universally empty.
Text and person-ID models remain strings; use an empty string or a business-defined string sentinel.

`empty-value` accepts explicit `null` (or `() => null`). Clearing publishes `null` unchanged; omitted values preserve the existing default. Editors render `null` as blank without converting ordinary empty-string input to `null`. In popup editing, clearing changes the draft; confirm commits it and cancel preserves the original model.

---

Document: llms/en-US/components/time-picker.md

<!-- Source: src/time/picker/README.en-US.md; locale: en-US; page: /en/components/time-picker/ -->

# Time Picker

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

Preview configuration: `default-value="09:09:06"`.

Example source: src/time/picker/__demos__/basic.vue

```vue
<template>
  <c-time-picker default-value="09:09:06" />
</template>
```

## Format and presentation

### Format

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `format` | Display format | Format, Use12Hours |
| `use12-hours` | 12-hour clock | Use12Hours |
<!-- demo-config-notes:end -->


- `format`: Controls the displayed format.

Example source: src/time/picker/__demos__/format.vue

```vue
<template>
  <c-time-picker format="HH:mm" default-value="09:24" />
</template>
```

### Use12Hours

- `format`: Controls the displayed format.

Example source: src/time/picker/__demos__/use12Hours.vue

```vue
<template>
  <c-space>
    <c-time-picker use12-hours default-value="12:20:20 AM" format="hh:mm:ss A" />
    <c-time-picker use12-hours default-value="09:20:20 pm" format="hh:mm:ss a" />
    <c-time-picker use12-hours default-value="2:20 AM" format="h:mm A" />
  </c-space>
</template>
```

## Selection rules and interaction

### Disabled Parts

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `format` | Display format | Disabled Parts, Bounds, Panel Behavior |
| `disable-confirm` | Skip confirmation | No Confirm, Panel Behavior |
| `use12-hours` | 12-hour clock | Disabled Parts |
| `step` | Hour/minute/second steps | Step |
| `hide-disabled-options` | Hide disabled time options | Panel Behavior |
<!-- demo-config-notes:end -->


- `format`: Controls the displayed format.

Example source: src/time/picker/__demos__/disabled-parts.vue

```vue
<template>
  <p>12 小时显示；禁用回调始终使用 0–23 小时。下午 1 点禁用，下午 2 点的第 30 分钟禁用。</p>
  <c-time-picker
    default-value="02:20:00 pm"
    format="hh:mm:ss a"
    use12-hours
    :disabled-hours="() => [0, 13]"
    :disabled-minutes="(hour) => hour === 14 ? [30] : []"
    :disabled-seconds="(hour, minute) => hour === 14 && minute === 20 ? [15, 30, 45] : []"
  />
</template>
```

### Step

- `step`: Controls the allowed increment.

Example source: src/time/picker/__demos__/step.vue

```vue
<template>
  <c-time-picker
    default-value="10:25:30"
    :step="{
      hour: 2,
      minute: 5,
      second: 10,
    }"
  />
</template>
```

### Bounds

- `format`: Controls the displayed format.
- `min`: Sets the lower bound.
- `max`: Sets the upper bound.

Example source: src/time/__demos__/bounds.vue

```vue
<script setup>
import { ref } from "vue";

const value = ref("10:30:38");
const narrow = ref(false);
</script>

<template>
  <c-space direction="column" :size="12" style="width: 100%">
    <p>
      包含边界：10:30:38–10:31:02。收紧边界不会改写已有模型，但越界值无法确认。
    </p>
    <c-checkbox v-model="narrow"> 将下限调整为 10:30:40</c-checkbox>
    <c-time
      v-model="value"
      format="HH:mm:ss"
      :min="narrow ? '10:30:40' : '10:30:38'"
      max="10:31:02"
    />
    <c-time-picker
      v-model="value"
      format="HH:mm:ss"
      :min="narrow ? '10:30:40' : '10:30:38'"
      max="10:31:02"
    />
    <span>{{ value }}</span>
  </c-space>
</template>
```

### No Confirm

Preview configuration: `disable-confirm`.

Example source: src/time/picker/__demos__/no-confirm.vue

```vue
<template>
  <c-time-picker disable-confirm />
</template>
```

### Panel Behavior

- `format`: Controls the displayed format.
- `readonly`: Displays the current value without allowing edits.

Example source: src/time/picker/__demos__/panel-behavior.vue

```vue
<script setup>
import { ref } from "vue";

const value = ref("09:30");
const immediate = ref(false);
const confirmations = ref(0);
const hideDisabled = ref(false);
const readonly = ref(false);
const disabledHours = () => [0, 1, 2, 3, 4, 5, 6, 7];
</script>

<template>
  <c-space direction="column" size="12px" style="width: 100%">
    <c-checkbox v-model="immediate"> 跳过确认，选择即提交</c-checkbox>
    <c-checkbox v-model="hideDisabled"> 隐藏禁用小时（00–07）</c-checkbox>
    <c-checkbox v-model="readonly"> 只读（包括确认）</c-checkbox>
    <c-button variant="outline" @click="value = '13:45'"
      >外部更新为 13:45，覆盖未提交草稿</c-button
    >
    <c-time-picker
      v-model="value"
      @confirm="confirmations++"
      format="HH:mm"
      :disable-confirm="immediate"
      :hide-disabled-options="hideDisabled"
      :readonly="readonly"
      :disabled-hours="disabledHours"
    >
      <template #extra
        ><p>附加说明使用 extra 插槽；选择草稿后点击确认提交。</p></template
      >
    </c-time-picker>
    <span>有效确认次数: {{ confirmations }}</span>
    <span>已提交值: {{ value }}</span>
    <p>默认选择只修改草稿，点击确认后上方的已提交值才会更新。</p>
  </c-space>
</template>
```

## Reading direction

Inherits the nearest `dir="ltr|rtl"`. Direction changes neither change the time nor commit drafts. Time columns follow reading order; Left/Right moves focus visually between columns. Cedar Up/Down and Home/End move focus within a column, skipping disabled options; Enter/Space selects. Maple wheels retain their existing Up/Down and Home/End selection behavior. Existing confirmation settings control submission. Popovers inherit their source direction.

## API

The panel owns one draft/confirmation state, reused by its presentation. Examples show the extra slot and valid-confirm count. Confirming the same value again emits confirm without a duplicate change.

### Pure-panel event and slot boundaries

`TimePicker`/`TimeRangePicker` do not manage fields/popups. Pass `open`, `size`, `variant`, clearing and popup configuration to `Time`/`TimeRange`.

- `select(value, date)`: edit the draft.
- `change(value, date)`: valid confirmation with a changed value; updates the model.
- `confirm(value, date)`: every valid confirmation, including unchanged values. `disableConfirm` also emits it on valid selection commits. Disabled, readonly or invalid drafts do not emit it.
- `extra`: additional explanatory content.
- `actions({ confirm, canConfirm, value })`: replace default tools. `value` is the draft; call `confirm()` to commit and disable buttons according to `canConfirm`.

Single-time events carry formatted strings and Date objects; range events carry corresponding arrays. Pure panels no longer emit `open-change`, `update:open` or `clear`.

### Props

| Arguments | Description | Type | Default |
| --- | --- | --- | --- |
| `model-value` | Bound value | `string \| number \| Date` | `-` |
| `format` | Display format | `string` | `-` |
| `use12-hours` | 12-hour clock | `boolean` | `false` |
| `hide-disabled-options` | Hide disabled time options | `boolean` | `false` |
| `disable-confirm` | Skip confirmation | `boolean` | `false` |
| `disabled` | Disable interaction | `boolean` | `false` |
| `step` | Hour/minute/second steps | `object` | `-` |

---

Document: llms/en-US/components/time-range.md

<!-- Source: src/time-range/README.en-US.md; locale: en-US; page: /en/components/time-range/ -->

# TimeRange

A pair of time endpoints with explicit confirmation.

```ts
import type { TimeRangeProps, TimeRangeInstance } from "@cedar-design/ui";
```

`empty-value` accepts explicit `null` (or `() => null`). Clearing publishes null unchanged; omitted values preserve the existing default. Editors render null as blank without converting ordinary empty-string input to null. In popup editing, clearing changes the draft; confirm commits it and cancel preserves the original model.

## Basic examples

### Basic usage

Example source: src/time-range/__demos__/basic.vue

```vue
<template>
  <c-time-range v-model="range" style="width: 252px" clearable />
</template>

<script setup>
import { ref } from 'vue'

const range = ref()
</script>
```

## Appearance and presentation

### Size

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration   | Purpose                                                                                                        | Related examples                                                  |
| --------------- | -------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| `format`        | Display format                                                                                                 | Field Appearance, Range formats and 12-hour clocks, Show Next Day |
| `clearable`     | Show the clear action                                                                                          | Range formats and 12-hour clocks, Placeholder, Show Next Day      |
| `placeholder`   | Placeholder                                                                                                    | Field Appearance, Placeholder                                     |
| `show-next-day` | Allow end before start and show next day. Otherwise reversed ranges cannot commit. Endpoints are never swapped | Range formats and 12-hour clocks, Show Next Day                   |
| `size`          | Size                                                                                                           | Size                                                              |
| `variant`       | Field appearance                                                                                               | Field Appearance                                                  |

<!-- demo-config-notes:end -->

- `size`: Controls the component size.

Example source: src/time-range/__demos__/size.vue

```vue
<template>
  <c-space direction="column" fill>
    <c-time-range style="width: 252px" size="xs" />
    <c-time-range style="width: 252px" size="sm" />
    <c-time-range style="width: 252px" size="md" />
    <c-time-range style="width: 252px" size="lg" />
    <c-time-range style="width: 252px" size="xl" />
  </c-space>
</template>
```

### Field Appearance

- `format`: Controls the displayed format.
- `variant`: Input variant

Example source: src/time-range/__demos__/field-appearance.vue

```vue
<script setup>
import { ref } from "vue";

const value = ref(["09:00", "18:00"]);
const hint = ref(true);
const error = ref(false);
const line = ref(true);
</script>

<template>
  <c-space direction="column" :size="12" style="width: 100%">
    <c-checkbox v-model="hint"> 浮动提示</c-checkbox>
    <c-checkbox v-model="error"> 显式错误状态</c-checkbox>
    <c-checkbox v-model="line"> 边框 / 底线</c-checkbox>
    <c-time-range
      v-model="value"
      format="HH:mm"
      variant="outline"
      :placeholder="['开始时间', '结束时间']"
      :hint="hint"
      :error="error"
      :line="line"
      focus-color="#6750a4"
      separator=" → "
    />
    <span>{{ value }}</span>
  </c-space>
</template>
```

### Range formats and 12-hour clocks

Compare minute, second and 12-hour range displays and edit both endpoints. Next-day rules and model formats remain separate.

Example source: src/time-range/__demos__/format-comparison.vue

```vue
<script setup lang="ts">
import { ref } from "vue"
import { proxyRefs as demoProxyRefs } from 'vue'

const scene1 = demoProxyRefs((() => {


const range = ref(['09:30', '18:00'])

const literalRange = ref(['Time 09:30', 'Time 18:00'])

const rangeSeconds = ref(['09:30:20', '18:00:00'])
return { range, literalRange, rangeSeconds }
})())

const scene2 = demoProxyRefs((() => {

const value = ref(['11:30:00 pm', '12:30:00 am'])
return { value }
})())
</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="format">
    <h4><span lang="zh-CN">显示格式</span><span lang="en-US">format</span></h4>
    <c-space direction="column" fill>
        <c-time-range v-model="scene1.range" format="HH:mm" style="width: 100%; max-width: 360px" clearable />
        <c-time-range v-model="scene1.literalRange" format="[Time] HH:mm" style="width: 100%; max-width: 360px" clearable />
        <c-time-range
          v-model="scene1.rangeSeconds"
          format="HH:mm:ss"
          style="width: 100%; max-width: 360px"
          clearable
        />
      </c-space>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="ampm">
    <h4><span lang="zh-CN">十二小时制</span><span lang="en-US">ampm</span></h4>
    <c-space direction="column" :size="12" style="width: 100%">
        <p>分别切换起止端的 AM/PM；12 AM 是午夜，12 PM 是中午。</p>
        <c-time-range v-model="scene2.value" use12-hours show-next-day style="width: 100%; max-width: 360px" />
        
        <span>当前值: {{ scene2.value }}</span>
      </c-space>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

### Placeholder

Example source: src/time-range/__demos__/placeholder.vue

```vue
<template>
  <c-time-range
    v-model="range"
    style="width: 280px"
    :placeholder="['开始时间', '结束时间']"
    clearable
  />
</template>

<script setup>
import { ref } from 'vue'

const range = ref()
</script>
```

### Show Next Day

- `format`: Controls the displayed format.

Example source: src/time-range/__demos__/show-next-day.vue

```vue
<script setup lang="ts">
import { ref } from "vue";

const range = ref<string[] | undefined>(["22:00", "06:00"]);
const reset = () => {
  range.value = ["22:00", "06:00"];
};
</script>

<template>
  <section class="time-overnight-demo">
    <c-time-range
      v-model="range"
      format="HH:mm"
      input-editable
      show-next-day
      clearable
    />
    <output aria-label="Overnight model">{{
      range === undefined ? "undefined" : JSON.stringify(range)
    }}</output>
    <c-button @click="reset">重置</c-button>
  </section>
</template>

<style scoped>
.time-overnight-demo {
  display: flex;
  flex-direction: column;
  gap: 12px;
  max-width: 360px;
}
</style>
```

## Value model and selection rules

### Format Model

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration | Purpose        | Related examples           |
| ------------- | -------------- | -------------------------- |
| `format`      | Display format | Format Model, Step, Bounds |
| `use12-hours` | 12-hour clock  | Step                       |

<!-- demo-config-notes:end -->

- `format`: Controls the displayed format.

Example source: src/time-range/__demos__/format-model.vue

```vue
<script setup>
import { ref } from 'vue'

const date = new Date(2026, 8, 23, 13, 5, 9)
const later = new Date(2026, 8, 23, 18, 30, 0)
const value = ref([date, later.getTime()])
const literal = ref(['Time 09:30', 'Time 18:00'])
</script>

<template>
  <c-space direction="column" fill style="width: 100%">
    <p>Date 和时间戳按本地时间反显；选择后返回格式化字符串。</p>
    <c-time-range v-model="value" format="hh:mm A" style="width: 100%; max-width: 360px" />
    <span>当前模型: {{ value }}</span>
    <c-time-range v-model="literal" format="[Time] HH:mm" style="width: 100%; max-width: 360px" />
    <span>固定文字格式: {{ literal }}</span>
  </c-space>
</template>
```

### Step

- `format`: Controls the displayed format.
- `step`: Controls the allowed increment.

Example source: src/time-range/__demos__/step.vue

```vue
<script setup>
import { ref } from "vue";
const value = ref(["09:30:00", "17:00:00"]);
const step = { hour: 1, minute: 15, second: 10 };
const use12Hours = ref(false);
</script>

<template>
  <c-space direction="column" :size="12" style="width: 100%">
    <p>小时步长 1，分钟步长 15，秒步长 10。</p>
    <c-checkbox v-model="use12Hours">
      12 小时面板，模型仍为 HH:mm:ss</c-checkbox
    >
    <c-time-range
      v-model="value"
      format="HH:mm:ss"
      :use12-hours="use12Hours"
      :step="step"
      style="width: 100%; max-width: 360px"
    />
    <span>{{ value }}</span>
  </c-space>
</template>
```

### Bounds

- `format`: Controls the displayed format.
- `min`: Sets the lower bound.
- `max`: Sets the upper bound.

Example source: src/time-range/__demos__/bounds.vue

```vue
<script setup>
import { ref } from "vue";

const value = ref(["10:30:38", "10:31:02"]);
const narrow = ref(false);
</script>

<template>
  <c-space direction="column" :size="12" style="width: 100%">
    <p>
      包含边界：10:30:38–10:31:02。收紧边界不会改写已有模型，但越界值无法确认。
    </p>
    <c-checkbox v-model="narrow"> 将下限调整为 10:30:40</c-checkbox>
    <c-time-range
      v-model="value"
      format="HH:mm:ss"
      :min="narrow ? '10:30:40' : '10:30:38'"
      max="10:31:02"
    />
    <c-time-range-picker
      v-model="value"
      format="HH:mm:ss"
      :min="narrow ? '10:30:40' : '10:30:38'"
      max="10:31:02"
    />
    <span>{{ value }}</span>
  </c-space>
</template>
```

## Input and state control

### Interaction state comparison

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration    | Purpose                  | Related examples                                        |
| ---------------- | ------------------------ | ------------------------------------------------------- |
| `format`         | Display format           | Interaction state comparison, Text Entry, Default State |
| `clearable`      | Show the clear action    | Text Entry, Default State, Selection Events             |
| `disabled`       | Disable interaction      | Interaction state comparison, Selection Events          |
| `readonly`       | Read-only interaction    | Interaction state comparison, Selection Events          |
| `input-editable` | Allow desktop text input | Text Entry, Copying and editing                         |
| `model-value`    | Bound value              | Default State                                           |

<!-- demo-config-notes:end -->

Toggle the state, interact with the component, and restore editing using the controls outside the specimen. Error appearance alone does not run validation.

Example source: src/time-range/__demos__/state-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref(["09:30", "18:00"]);
const __demoState = __demoReactive({
  disabled: false,
  readonly: false,
  error: false,
});
</script>
<template>
  <c-space direction="column" :size="16">
    <c-space wrap>
      <c-checkbox v-model="__demoState['disabled']">disabled</c-checkbox>
      <c-checkbox v-model="__demoState['readonly']">readonly</c-checkbox>
      <c-checkbox v-model="__demoState['error']">error</c-checkbox>
    </c-space>
    <c-time-range
      v-model="value"
      format="HH:mm"
      v-bind="__demoState"
    ></c-time-range>
  </c-space>
</template>
```

### Text Entry

- `format`: Controls the displayed format.
- `min`: Sets the lower bound.
- `max`: Sets the upper bound.

Example source: src/time-range/__demos__/text-entry.vue

```vue
<script setup>
import { ref } from "vue";

const value = ref(["09:00", "10:00"]);
const editable = ref(true);
</script>

<template>
  <c-space direction="column" :size="12" style="width: 100%">
    <c-checkbox v-model="editable"> 允许手输</c-checkbox>
    <p>回车或失焦提交，Esc 撤销。合法范围为 08:00–18:00。</p>
    <c-time-range
      v-model="value"
      :input-editable="editable"
      format="HH:mm"
      min="08:00"
      max="18:00"
      clearable
    />
    <span>{{ value }}</span>
  </c-space>
</template>
```

### Default State

- `format`: Controls the displayed format.

Example source: src/time-range/__demos__/default-state.vue

```vue
<script setup>
import { ref } from "vue";
const value = ref(["09:00", "10:00"]);
const open = ref(false);
const acceptValue = ref(true);
const acceptOpen = ref(true);
const acceptClose = ref(true);
const commits = ref(0);
const proposal = ref();
const openProposal = ref();
const updateValue = (next) => {
  proposal.value = next;
  if (acceptValue.value) {
    value.value = next;
  }
};
const updateOpen = (next) => {
  openProposal.value = next;
  if (acceptOpen.value && (next || acceptClose.value)) {
    open.value = next;
  }
};
</script>

<template>
  <c-space direction="column" size="12px" style="width: 100%">
    <p>非受控初始值，无需绑定 v-model</p>
    <c-time-range
      :default-value="['09:00', '10:00']"
      format="HH:mm"
      clearable
    />
    <p>受控值与展开状态</p>
    <c-checkbox v-model="acceptValue"> 接受值更新</c-checkbox>
    <c-checkbox v-model="acceptOpen"> 接受展开更新</c-checkbox>
    <c-time-range
      :model-value="value"
      :open="open"
      format="HH:mm"
      clearable
      @update:model-value="updateValue"
      @update:open="updateOpen"
      @change="commits++"
    />
    <span>{{ value }} / {{ open }}</span>
    <c-checkbox v-model="acceptClose"> 接受关闭请求</c-checkbox>
    <output aria-label="Commit count">{{ commits }}</output>
    <output aria-label="Controlled proposals">{{
      JSON.stringify({ value: proposal, open: openProposal })
    }}</output>
  </c-space>
</template>
```

### Selection Events

- `readonly`: Displays the current value without allowing edits.
- `disabled`: Prevents user interaction.
- `format`: Controls the displayed format.

Example source: src/time-range/__demos__/selection-events.vue

```vue
<script setup>
import { ref } from "vue";

const value = ref(["09:00", "18:00"]);
const immediate = ref(false);
const readonly = ref(false);
const disabled = ref(false);
const events = ref([]);
function record(name, value, dates) {
  const times = Array.isArray(dates)
    ? dates.map((date) => date?.toLocaleTimeString())
    : dates?.toLocaleTimeString();
  events.value = [
    JSON.stringify({ event: name, value: value ?? null, time: times ?? null }),
    ...events.value,
  ].slice(0, 5);
}
</script>

<template>
  <c-space direction="column" size="12px" style="width: 100%">
    <c-checkbox v-model="readonly"> 只读：可聚焦，不可修改</c-checkbox>
    <c-checkbox v-model="disabled"> 禁用：释放焦点，不可修改</c-checkbox>
    <c-checkbox v-model="immediate"> 选择后立即提交</c-checkbox>
    <p>select 记录草稿，change 记录提交；取消不改模型，清除返回 undefined。</p>
    <c-time-range
      v-model="value"
      :disable-confirm="immediate"
      :readonly="readonly"
      :disabled="disabled"
      format="HH:mm"
      clearable
      @select="(value, dates) => record('select', value, dates)"
      @change="(value, dates) => record('change', value, dates)"
      @clear="record('clear')"
      @click="record('click')"
      @open-change="(open) => record('open-change', open)"
      @focus="record('focus')"
      @blur="record('blur')"
    />
    <span>模型: {{ value === undefined ? "undefined" : value }}</span>
    <c-button variant="outline" @click="value = ['15:30', '18:00']"
      >从外部替换模型</c-button
    >
    <small>外部替换会更新反显，不触发 select 或 change。</small>
    <div
      v-for="(event, index) in events"
      :key="index"
      style="overflow-wrap: anywhere"
    >
      {{ event }}
    </div>
  </c-space>
</template>
```

### Copying and editing

With open-trigger-target="icon", use the input area to edit or copy and the suffix button to open. Existing text remains copyable when editing or search is disabled.

Example source: src/time-range/__demos__/open-trigger-target.en-US.vue

```vue
<template>
  <c-space direction="column">
    <c-radio-group
      v-model="target"
      :options="[
        { label: 'Whole field', value: 'field' },
        { label: 'Suffix icon only', value: 'icon' },
      ]"
    />
    <label><c-switch v-model="editable" /> Allow editing / search</label>
    <c-time-range
      v-model="value"
      edit-mode="direct"
      :open-trigger-target="target"
      :input-editable="editable"
    />
    <p>
      Disable editing to copy existing text. In icon mode, editing does not open
      the panel.
    </p>
  </c-space>
</template>
<script setup lang="ts">
import { ref } from "vue";
const target = ref<"field" | "icon">("icon");
const editable = ref(true);
const value = ref(["09:30:00", "10:30:00"]);
</script>
```

### Shared field loading

`loading` displays the shared field indicator. `loading-mode` is `default` (indicator) or `line` (an indeterminate bottom line); it defaults to `default`. Rendering belongs to FieldDecorator. Loading does not implicitly disable editing or change readonly. Set those states separately.

## Reading direction

Range values remain `[start, end]`; direction changes preserve endpoint order, drafts and overnight semantics. Panels and time columns follow reading order, with visual Left/Right focus movement across endpoint columns. Cedar Up/Down moves focus and Enter/Space selects; Maple retains wheel selection with Up/Down. Existing confirmation settings control submission. Popovers inherit their source direction.

## API

### Empty values and reading placeholders

`empty-values` recognizes empty data; `empty-value` keeps existing clear output. `empty-text` defaults to `'-'` under `read-pretty`, with Field > FormItem > Form precedence and custom read slots first. With explicit empty-values, built-in required uses the policy; custom validators receive original data. See the [shared guide](llms/en-US/guide/empty-values.md).

| Prop         | Type               | Default and scope                                                           |
| ------------ | ------------------ | --------------------------------------------------------------------------- |
| empty-values | readonly unknown[] | Field > FormItem > Form > component-family default; replaces the whole list |
| empty-text   | string             | Field > FormItem > Form > '-'; explicit '' is valid                         |

These props belong to field presentation; pure panels do not gain reading mode. Form and FormItem provide inherited settings. The existing empty-value type and clear fallback remain component-specific.

### Popup configuration and field notifications

`popup-props` configures local Trigger positioning/appearance, e.g. `{ placement: 'top-start' }`, without overriding field open, disabled, trigger or other state/interaction. Top-level `popup-container`, including false, takes precedence. `input-editable` defaults to true and can disable desktop typing. `time-range-picker-props`, including class/style, controls panel appearance. Undeclared attrs no longer supply panel/popup configuration; id/aria-* fall through to the field.

`click(event)` notifies only clicks on non-disabled fields. Readonly may notify without expanding. Closing consistently listens to `open-change(false)`, a close request that controlled open still requires the parent to accept. Neither platform has a field close event; a close request is not a value commit.

`suffix-icon` receives `focus: boolean` and `popupOpen: boolean`. `focus(index = 0)` focuses start (0) or end (1) without committing; `blur()` removes focus and requests closing.

A `placeholder` string applies to both endpoints; arrays provide start/end text, with missing entries empty. Explicit empty strings do not fall back to default text.

### Props

| Arguments                 | Description                                                                                                                      | Type                                                | Default   |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | --------- |
| `open-trigger-target`     | Pointer opening target: the whole field or only the suffix icon. Explicit keyboard opening and controlled open remain available. | `'field' \| 'icon'`                                 | `'field'` |
| `model-value`             | Bound value                                                                                                                      | `(string \| number \| Date)[]`                      | `-`       |
| `open`                    | Controlled popup visibility                                                                                                      | `boolean`                                           | `-`       |
| `popup-props`             | Local Trigger presentation options; do not control field state                                                                   | `TimePopupPresentationProps<Partial<TriggerProps>>` | `{}`      |
| `input-editable`          | Allow desktop text input                                                                                                         | `boolean`                                           | `true`    |
| `clearable`               | Show the clear action                                                                                                            | `boolean`                                           | `true`    |
| `disabled`                | Disable interaction                                                                                                              | `boolean`                                           | `false`   |
| `readonly`                | Read-only interaction                                                                                                            | `boolean`                                           | `false`   |
| `size`                    | Size                                                                                                                             | `xs \| sm \| md \| lg \| xl`                        | `-`       |
| `variant`                 | Field appearance                                                                                                                 | `filled \| outline \| standard`                     | `filled`  |
| `placeholder`             | Placeholder                                                                                                                      | `string \| string[]`                                | `-`       |
| `format`                  | Display format                                                                                                                   | `string`                                            | `-`       |
| `use12-hours`             | 12-hour clock                                                                                                                    | `boolean`                                           | `false`   |
| `hide-disabled-options`   | Hide disabled time options                                                                                                       | `boolean`                                           | `false`   |
| `disable-confirm`         | Skip confirmation; valid selections commit immediately and request closing                                                       | `boolean`                                           | `false`   |
| `show-next-day`           | Allow end before start and show next day. Otherwise reversed ranges cannot commit. Endpoints are never swapped                   | `boolean`                                           | `false`   |
| `time-range-picker-props` | Forwarded to TimeRangePicker                                                                                                     | `object`                                            | `{}`      |

### Form field presentation and confirmation

This component supports `edit-mode` with field > FormItem > Form precedence. When unset, it defaults to `direct` and preserves `direct` editing. Supported values: `direct / click / dblclick`. Non-`direct` modes open the editor through the field value trigger and keep one draft; v-model updates only after confirmation. Cancel, reset or enabling readPretty discards the draft.

Cedar uses edit-mode="click" / "dblclick" to open an editor popup near the field. Enter/F2 also opens it; cancel/Escape discards the draft, and confirmation commits it. readPretty is an independent reading setting, separate from readonly and disabled.

`before-commit(value, { previousValue, signal })` can reject an overlay save. FormItem validates the candidate first and keeps the editor open on failure. `open / default-open / update:open` control the editor. Use `#read="{ value, text }"` to customize display. See the full field comparison in Form.

Inline date/time fields retain their existing confirmation policy. In click/dblclick editors, internal panels hide confirmation tools, and the edit layer supplies one confirm/cancel pair. Standalone DatePicker, DateRangePicker, TimePicker and TimeRangePicker retain panel APIs/confirmation and do not inherit Form field presentation.

`read-pretty` is an independent boolean alongside `readonly` and `disabled`. It inherits from field to FormItem to Form; explicit `false` overrides the parent. The default is `false`. Reading mode renders no editor.

### Forwarded configuration boundaries (F07)

Existing TimePopupPresentationProps and runtime filtering remain. Fields own open/defaultOpen, disabled, trigger, closeOnClickReference, preventFocus and expansion updates. Explicit top-level popup-container takes precedence, otherwise nested configuration is used. popupClass merges internal classes. Inline popupOffset stays 4; Maple also fixes unmountOnClose=true. Such fields in old types are not guaranteed to control final values. Existing Time types/runtime behavior are not narrowed here.

## Configuring the cleared value

`empty-value` / `emptyValue` sets the model value produced by clearing. It accepts a value in the component model type or a zero-argument factory. Omission preserves the existing default; use `() => undefined` to distinguish omission from returning undefined. Arrays are shallow-copied on every clear; selected items that cannot be cleared remain. It does not redefine emptiness, alter Form reset defaults or treat 0/false as universally empty.

`empty-value` accepts explicit `null` (or `() => null`). Clearing publishes `null` unchanged; omitted values preserve the existing default. Editors render `null` as blank without converting ordinary empty-string input to `null`. In popup editing, clearing changes the draft; confirm commits it and cancel preserves the original model.

---

Document: llms/en-US/components/time.md

<!-- Source: src/time/README.en-US.md; locale: en-US; page: /en/components/time/ -->

# Time

A time field with a separate draft and confirmation step.

```ts
import type { TimeProps, TimeInstance } from "@cedar-design/ui";
```

`empty-value` accepts explicit `null` (or `() => null`). Clearing publishes null unchanged; omitted values preserve the existing default. Editors render null as blank without converting ordinary empty-string input to null. In popup editing, clearing changes the draft; confirm commits it and cancel preserves the original model.

## Basic examples

### Basic usage

Example source: src/time/__demos__/basic.vue

```vue
<template>
  <c-time v-model="value" style="width: 200px" />
</template>

<script setup>
import { ref } from 'vue'

const value = ref()
</script>
```

## Appearance and presentation

### Size

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration | Purpose          | Related examples                                  |
| ------------- | ---------------- | ------------------------------------------------- |
| `size`        | Size             | Size, Control Sizes                               |
| `variant`     | Field appearance | Control Sizes, Field Appearance                   |
| `placeholder` | Placeholder      | Control Sizes, Field Appearance                   |
| `format`      | Display format   | Field Appearance, Time formats and 12-hour clocks |
| `use12-hours` | 12-hour clock    | Time formats and 12-hour clocks                   |

<!-- demo-config-notes:end -->

- `size`: Controls the component size.

Example source: src/time/__demos__/size.vue

```vue
<template>
  <c-space direction="column" fill>
    <c-time style="width: 200px" size="xs" />
    <c-time style="width: 200px" size="sm" />
    <c-time style="width: 200px" size="md" />
    <c-time style="width: 200px" size="lg" />
    <c-time style="width: 200px" size="xl" />
  </c-space>
</template>
```

### Control Sizes

- `size`: Controls the component size.
- `variant`: Input variant

Example source: src/field-decorator/__demos__/control-sizes.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
const sizes = ["xs", "sm", "md", "lg", "xl"] as const;
const variants = ["outline", "filled", "standard"] as const;
const size = ref<(typeof sizes)[number]>("md");
const variant = ref<(typeof variants)[number]>("outline");
const options = [
  { value: "beijing", label: "Beijing" },
  { value: "shanghai", label: "Shanghai" },
];
const cascaderOptions = [{ value: "china", label: "China", children: options }];

const inputValue = ref("Beijing");
const selectValue = ref("beijing");
const cascaderValue = ref("beijing");
const selectMultiple = ref(["beijing", "shanghai"]);
const cascaderMultiple = ref(["beijing", "shanghai"]);
const selectOverflow = ref(["long", "beijing", "shanghai"]);
const cascaderOverflow = ref(["long", "beijing", "shanghai"]);
const selectedOptions = [
  ...options,
  {
    value: "long",
    label:
      "A very long selected option label for overflow comparison — full text preview keeps the selected value unchanged.",
  },
];
const selectedCascaderOptions = [
  { value: "china", label: "China", children: selectedOptions },
];
function resetSelections() {
  inputValue.value = "Beijing";
  selectValue.value = "beijing";
  cascaderValue.value = "beijing";
  selectMultiple.value = ["beijing", "shanghai"];
  cascaderMultiple.value = ["beijing", "shanghai"];
  selectOverflow.value = ["long", "beijing", "shanghai"];
  cascaderOverflow.value = ["long", "beijing", "shanghai"];
}
</script>
<template>
  <section
    aria-label="Form control size comparison"
    class="control-size-comparison"
  >
    <c-space wrap :size="12">
      <c-radio-group v-model="size" aria-label="Comparison size">
        <c-radio v-for="item in sizes" :key="item" :value="item">{{
          item
        }}</c-radio>
      </c-radio-group>
      <c-radio-group v-model="variant" aria-label="Comparison variant">
        <c-radio v-for="item in variants" :key="item" :value="item">{{
          item
        }}</c-radio>
      </c-radio-group>
    </c-space>
    <div class="control-size-comparison__grid">
      <div data-control="Input">
        <p>Input</p>
        <c-input :size="size" :variant="variant" placeholder="Input" />
      </div>
      <div data-control="Button">
        <p>Button</p>
        <c-button :size="size" variant="outline">Button</c-button>
      </div>
      <div data-control="Select">
        <p>Select</p>
        <c-select
          :size="size"
          :variant="variant"
          :options="options"
          placeholder="Select"
        />
      </div>
      <div data-control="Date">
        <p>Date</p>
        <c-date :size="size" :variant="variant" placeholder="Date" />
      </div>
      <div data-control="Time">
        <p>Time</p>
        <c-time :size="size" :variant="variant" placeholder="Time" />
      </div>
      <div data-control="InputNumber">
        <p>InputNumber</p>
        <c-input-number :size="size" :variant="variant" placeholder="Number" />
      </div>
      <div data-control="AutoComplete">
        <p>AutoComplete</p>
        <c-auto-complete
          :size="size"
          :variant="variant"
          :options="options"
          placeholder="AutoComplete"
        />
      </div>
      <div data-control="Cascader">
        <p>Cascader</p>
        <c-cascader
          :size="size"
          :variant="variant"
          :options="cascaderOptions"
          placeholder="Cascader"
        />
      </div>
      <div data-control="DateRange">
        <p>DateRange</p>
        <c-date-range
          :size="size"
          :variant="variant"
          :placeholder="['Start', 'End']"
        />
      </div>
      <div data-control="TimeRange">
        <p>TimeRange</p>
        <c-time-range
          :size="size"
          :variant="variant"
          :placeholder="['Start', 'End']"
        />
      </div>
    </div>

    <section
      aria-label="Selected control size comparison"
      class="control-size-comparison__states"
    >
      <c-space wrap align="center" :size="12">
        <span>Selected / Clearable / Multiple — 有值、可清空与多选不换行</span>
        <span
          >Hover or focus truncated text; tap on touch screens /
          悬停或聚焦省略正文查看全文；触屏点按查看，点外部关闭</span
        >
        <c-button size="sm" variant="outline" @click="resetSelections"
          >Reset / 恢复选中值</c-button
        >
      </c-space>
      <div class="control-size-comparison__grid">
        <div data-control="InputValue">
          <p>Input · clearable</p>
          <c-input
            v-model="inputValue"
            :size="size"
            :variant="variant"
            clearable
            placeholder="Input value"
          />
        </div>
        <div data-control="ButtonReference">
          <p>Button · reference</p>
          <c-button :size="size" variant="outline">Button</c-button>
        </div>
        <div data-control="SelectValue">
          <p>Select · clearable</p>
          <c-select
            v-model="selectValue"
            :size="size"
            :variant="variant"
            :options="selectedOptions"
            clearable
            placeholder="Select value"
          />
        </div>
        <div data-control="CascaderValue">
          <p>Cascader · clearable</p>
          <c-cascader
            v-model="cascaderValue"
            :size="size"
            :variant="variant"
            :options="selectedCascaderOptions"
            clearable
            placeholder="Cascader value"
          />
        </div>
        <div data-control="SelectMultiple">
          <p>Select · multiple / nowrap</p>
          <c-select
            v-model="selectMultiple"
            :size="size"
            :variant="variant"
            :options="selectedOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Select multiple"
          />
        </div>
        <div data-control="CascaderMultiple">
          <p>Cascader · multiple / nowrap</p>
          <c-cascader
            v-model="cascaderMultiple"
            :size="size"
            :variant="variant"
            :options="selectedCascaderOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Cascader multiple"
          />
        </div>
        <div data-control="SelectOverflow">
          <p>Select · long values / nowrap</p>
          <c-select
            v-model="selectOverflow"
            edit-mode="direct"
            :size="size"
            :variant="variant"
            :options="selectedOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Select long values"
          />
        </div>
        <div data-control="CascaderOverflow">
          <p>Cascader · long values / nowrap</p>
          <c-cascader
            v-model="cascaderOverflow"
            edit-mode="direct"
            :size="size"
            :variant="variant"
            :options="selectedCascaderOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Cascader long values"
          />
        </div>
      </div>
    </section>
  </section>
</template>
<style scoped>
.control-size-comparison,
.control-size-comparison__states {
  display: grid;
  gap: 24px;
}
.control-size-comparison__grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
  align-items: start;
  gap: 24px 16px;
}
.control-size-comparison__grid > div {
  min-width: 0;
}
.control-size-comparison__grid p {
  margin: 0 0 12px;
  font-size: 14px;
  line-height: 20px;
}
.control-size-comparison__grid :deep(.c-input-number),
.control-size-comparison__grid :deep(.c-auto-complete) {
  width: 100%;
}
</style>
```

### Field Appearance

- `format`: Controls the displayed format.
- `variant`: Input variant

Example source: src/time/__demos__/field-appearance.vue

```vue
<script setup>
import { ref } from "vue";

const value = ref("09:00");
const hint = ref(true);
const error = ref(false);
const line = ref(true);
</script>

<template>
  <c-space direction="column" :size="12" style="width: 100%">
    <c-checkbox v-model="hint"> 浮动提示</c-checkbox>
    <c-checkbox v-model="error"> 显式错误状态</c-checkbox>
    <c-checkbox v-model="line"> 边框 / 底线</c-checkbox>
    <c-time
      v-model="value"
      format="HH:mm"
      variant="outline"
      placeholder="请选择时间"
      :hint="hint"
      :error="error"
      :line="line"
      focus-color="#6750a4"
    />
    <span>{{ value }}</span>
  </c-space>
</template>
```

### Time formats and 12-hour clocks

Compare minute, second and 12-hour displays. Distinguish midnight (12 AM) from noon (12 PM); model formats and step constraints remain separate.

Example source: src/time/__demos__/format-comparison.vue

```vue
<script setup lang="ts">
import { ref } from "vue"
import { proxyRefs as demoProxyRefs } from 'vue'

const scene1 = demoProxyRefs((() => {


const value = ref('09:30')

const valueSeconds = ref('09:30:20')

const literalValue = ref('Time 09:30')
return { value, valueSeconds, literalValue }
})())

const scene2 = demoProxyRefs((() => {

const value = ref('12:00:00 am')

const noon = ref('12:00:00 pm')
return { value, noon }
})())
</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="format">
    <h4><span lang="zh-CN">显示格式</span><span lang="en-US">format</span></h4>
    <c-space direction="column" fill>
        <c-time v-model="scene1.value" format="HH:mm" style="width: 100%; max-width: 320px" />
        <c-time v-model="scene1.valueSeconds" format="HH:mm:ss" style="width: 100%; max-width: 320px" />
        <c-time v-model="scene1.literalValue" format="[Time] HH:mm" style="width: 100%; max-width: 320px" />
      </c-space>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="ampm">
    <h4><span lang="zh-CN">十二小时制</span><span lang="en-US">ampm</span></h4>
    <c-space direction="column" :size="12" style="width: 100%">
        <p>12 AM 是午夜，12 PM 是中午。字段与面板联动展示。</p>
        <c-time v-model="scene2.value" use12-hours  style="width: 100%; max-width: 360px" />
        <c-time v-model="scene2.noon" use12-hours style="width: 100%; max-width: 360px" />
        <c-time-picker v-model="scene2.noon" use12-hours />
        <span>当前值: {{ scene2.value }}</span>
      </c-space>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

## Value model and selection rules

### Format Model

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration     | Purpose                  | Related examples           |
| ----------------- | ------------------------ | -------------------------- |
| `format`          | Display format           | Format Model, Step, Bounds |
| `model-value`     | Bound value              | Step                       |
| `use12-hours`     | 12-hour clock            | Step                       |
| `step`            | Hour/minute/second steps | Step                       |
| `disable-confirm` | No Confirm               | No Confirm                 |

<!-- demo-config-notes:end -->

- `format`: Controls the displayed format.

Example source: src/time/__demos__/format-model.vue

```vue
<script setup>
import { ref } from 'vue'

const date = new Date(2026, 8, 23, 13, 5, 9)
const timestamp = ref(date.getTime())
const value = ref(date)
const literal = ref('Time 09:30')
</script>

<template>
  <c-space direction="column" fill style="width: 100%">
    <p>Date 和时间戳按本地时间反显；选择后返回格式化字符串。</p>
    <c-time v-model="value" format="hh:mm A" style="width: 100%; max-width: 360px" />
    <span>当前模型: {{ value }}</span>
    <c-time v-model="timestamp" format="HH:mm:ss" style="width: 100%; max-width: 360px" />
    <span>时间戳模型: {{ timestamp }}</span>
    <c-time v-model="literal" format="[Time] HH:mm" style="width: 100%; max-width: 360px" />
    <span>固定文字格式: {{ literal }}</span>
  </c-space>
</template>
```

### Step

- `format`: Controls the displayed format.
- `step`: Controls the allowed increment.

Example source: src/time/__demos__/step.vue

```vue
<script setup>
import { computed, ref } from "vue";
const value = ref("09:30:00");
const coarse = ref(false);
const fiveHours = ref(false);
const blockAfternoon = ref(false);
const accept = ref(true);
const proposals = ref(0);
const disabledHours = () => (blockAfternoon.value ? [15] : []);
function update(next) {
  proposals.value++;
  if (accept.value) value.value = next;
}
const step = computed(() => ({
  hour: fiveHours.value ? 5 : 1,
  minute: coarse.value ? 30 : 15,
  second: 10,
}));
</script>

<template>
  <c-space
    class="time-step-demo"
    direction="column"
    :size="12"
    style="width: 100%"
  >
    <c-checkbox v-model="fiveHours"> 十二小时显示 + 5 小时步长</c-checkbox>
    <c-checkbox v-model="coarse"> 切换为 30 分钟步长</c-checkbox>
    <c-checkbox v-model="blockAfternoon"> 禁用 15 点（03 PM）</c-checkbox>
    <c-checkbox v-model="accept"> 父级接受更新</c-checkbox>
    <p>确认时按当前步长重新校验；切换规则不会自动修改已提交值。</p>
    <c-time
      :model-value="value"
      format="HH:mm:ss"
      :use12-hours="fiveHours"
      :step="step"
      :disabled-hours="disabledHours"
      style="width: 100%; max-width: 360px"
      @update:model-value="update"
    />
    <span>{{ value }}</span>
    <span role="status">提议次数：{{ proposals }}</span>
  </c-space>
</template>
```

### Bounds

- `format`: Controls the displayed format.
- `min`: Sets the lower bound.
- `max`: Sets the upper bound.

Example source: src/time/__demos__/bounds.vue

```vue
<script setup>
import { ref } from "vue";

const value = ref("10:30:38");
const narrow = ref(false);
</script>

<template>
  <c-space direction="column" :size="12" style="width: 100%">
    <p>
      包含边界：10:30:38–10:31:02。收紧边界不会改写已有模型，但越界值无法确认。
    </p>
    <c-checkbox v-model="narrow"> 将下限调整为 10:30:40</c-checkbox>
    <c-time
      v-model="value"
      format="HH:mm:ss"
      :min="narrow ? '10:30:40' : '10:30:38'"
      max="10:31:02"
    />
    <c-time-picker
      v-model="value"
      format="HH:mm:ss"
      :min="narrow ? '10:30:40' : '10:30:38'"
      max="10:31:02"
    />
    <span>{{ value }}</span>
  </c-space>
</template>
```

### No Confirm

Example source: src/time/__demos__/no-confirm.vue

```vue
<template>
  <c-time v-model="value" style="width: 200px" disable-confirm />
</template>

<script setup>
import { ref } from 'vue'

const value = ref()
</script>
```

## Input and state control

### Interaction state comparison

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration    | Purpose                     | Related examples                                                |
| ---------------- | --------------------------- | --------------------------------------------------------------- |
| `format`         | Display format              | Interaction state comparison, Text Entry, Default State         |
| `readonly`       | Read-only interaction       | Interaction state comparison, Selection Events, Multiple Fields |
| `clearable`      | Show the clear action       | Text Entry, Default State, Selection Events                     |
| `disabled`       | Disable interaction         | Interaction state comparison, Selection Events                  |
| `input-editable` | Allow desktop text input    | Text Entry, Copying and editing                                 |
| `open`           | Controlled popup visibility | Default State                                                   |

<!-- demo-config-notes:end -->

Toggle the state, interact with the component, and restore editing using the controls outside the specimen. Error appearance alone does not run validation.

Example source: src/time/__demos__/state-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref("09:30");
const __demoState = __demoReactive({
  disabled: false,
  readonly: false,
  error: false,
});
</script>
<template>
  <c-space direction="column" :size="16">
    <c-space wrap>
      <c-checkbox v-model="__demoState['disabled']">disabled</c-checkbox>
      <c-checkbox v-model="__demoState['readonly']">readonly</c-checkbox>
      <c-checkbox v-model="__demoState['error']">error</c-checkbox>
    </c-space>
    <c-time v-model="value" format="HH:mm" v-bind="__demoState"></c-time>
  </c-space>
</template>
```

### Text Entry

- `format`: Controls the displayed format.
- `min`: Sets the lower bound.
- `max`: Sets the upper bound.

Example source: src/time/__demos__/text-entry.vue

```vue
<script setup>
import { ref } from "vue";

const value = ref("09:00");
const editable = ref(true);
</script>

<template>
  <c-space direction="column" :size="12" style="width: 100%">
    <c-checkbox v-model="editable"> 允许手输</c-checkbox>
    <p>回车或失焦提交，Esc 撤销。合法范围为 08:00–18:00。</p>
    <c-time
      v-model="value"
      :input-editable="editable"
      format="HH:mm"
      min="08:00"
      max="18:00"
      clearable
    />
    <span>{{ value }}</span>
  </c-space>
</template>
```

### Default State

- `format`: Controls the displayed format.

Example source: src/time/__demos__/default-state.vue

```vue
<script setup>
import { ref } from "vue";
const value = ref("09:00");
const open = ref(false);
</script>

<template>
  <c-space direction="column" size="12px" style="width: 100%">
    <p>非受控初始值，无需绑定 v-model</p>
    <c-time :default-value="'09:00'" format="HH:mm" clearable />
    <p>受控值与展开状态</p>
    <c-time v-model="value" v-model:open="open" format="HH:mm" clearable />
    <span>{{ value }} / {{ open }}</span>
  </c-space>
</template>
```

### Selection Events

- `readonly`: Displays the current value without allowing edits.
- `disabled`: Prevents user interaction.
- `format`: Controls the displayed format.

Example source: src/time/__demos__/selection-events.vue

```vue
<script setup>
import { ref } from "vue";

const value = ref("09:00");
const immediate = ref(false);
const readonly = ref(false);
const disabled = ref(false);
const events = ref([]);
function record(name, value, dates) {
  const times = Array.isArray(dates)
    ? dates.map((date) => date?.toLocaleTimeString())
    : dates?.toLocaleTimeString();
  events.value = [
    JSON.stringify({ event: name, value: value ?? null, time: times ?? null }),
    ...events.value,
  ].slice(0, 5);
}
</script>

<template>
  <c-space direction="column" size="12px" style="width: 100%">
    <c-checkbox v-model="readonly"> 只读：可聚焦，不可修改</c-checkbox>
    <c-checkbox v-model="disabled"> 禁用：释放焦点，不可修改</c-checkbox>
    <c-checkbox v-model="immediate"> 选择后立即提交</c-checkbox>
    <p>select 记录草稿，change 记录提交；取消不改模型，清除返回 undefined。</p>
    <c-time
      v-model="value"
      :disable-confirm="immediate"
      :readonly="readonly"
      :disabled="disabled"
      format="HH:mm"
      clearable
      @select="(value, dates) => record('select', value, dates)"
      @change="(value, dates) => record('change', value, dates)"
      @clear="record('clear')"
      @click="record('click')"
      @open-change="(open) => record('open-change', open)"
      @focus="record('focus')"
      @blur="record('blur')"
    />
    <span>模型: {{ value === undefined ? "undefined" : value }}</span>
    <c-button variant="outline" @click="value = '15:30'"
      >从外部替换模型</c-button
    >
    <small>外部替换会更新反显，不触发 select 或 change。</small>
    <div
      v-for="(event, index) in events"
      :key="index"
      style="overflow-wrap: anywhere"
    >
      {{ event }}
    </div>
  </c-space>
</template>
```

### Multiple Fields

- `readonly`: Displays the current value without allowing edits.
- `format`: Controls the displayed format.

Example source: src/time/__demos__/multiple-fields.vue

```vue
<script setup>
import { ref } from "vue";
const lastEvent = ref("—");
const readonly = ref(false);
const start = ref("09:00:00");
const end = ref("18:00:00");
const range = ref(["09:00:00", "18:00:00"]);
</script>
<template>
  <c-space direction="column" :size="12" style="width: 100%">
    <c-checkbox v-model="readonly">
      只读字段仍可聚焦，但不能展开修改</c-checkbox
    >
    <c-input placeholder="在这里按 Enter，不会打开时间面板" />
    <small aria-live="polite">{{ lastEvent }}</small>
    <div aria-live="polite">
      <div>开始模型: {{ start ?? "undefined" }}</div>
      <div>结束模型: {{ end ?? "undefined" }}</div>
      <div>范围模型: {{ range ?? "undefined" }}</div>
    </div>
    <p>依次点击各个字段，之前的面板会关闭，不提交未确认草稿。</p>
    <c-time
      v-model="start"
      :readonly="readonly"
      @focus="lastEvent = 'start: focus'"
      @blur="lastEvent = 'start: blur'"
      format="HH:mm:ss"
      placeholder="开始时间"
      style="width: 100%; max-width: 360px"
    />
    <c-time
      v-model="end"
      :readonly="readonly"
      @focus="lastEvent = 'end: focus'"
      @blur="lastEvent = 'end: blur'"
      format="HH:mm:ss"
      placeholder="结束时间"
      style="width: 100%; max-width: 360px"
    />
    <c-time-range
      v-model="range"
      :readonly="readonly"
      @focus="lastEvent = 'range: focus'"
      @blur="lastEvent = 'range: blur'"
      format="HH:mm:ss"
      style="width: 100%; max-width: 360px"
    />
  </c-space>
</template>
```

### Copying and editing

With open-trigger-target="icon", use the input area to edit or copy and the suffix button to open. Existing text remains copyable when editing or search is disabled.

Example source: src/time/__demos__/open-trigger-target.en-US.vue

```vue
<template>
  <c-space direction="column">
    <c-radio-group
      v-model="target"
      :options="[
        { label: 'Whole field', value: 'field' },
        { label: 'Suffix icon only', value: 'icon' },
      ]"
    />
    <label><c-switch v-model="editable" /> Allow editing / search</label>
    <c-time
      v-model="value"
      edit-mode="direct"
      :open-trigger-target="target"
      :input-editable="editable"
    />
    <p>
      Disable editing to copy existing text. In icon mode, editing does not open
      the panel.
    </p>
  </c-space>
</template>
<script setup lang="ts">
import { ref } from "vue";
const target = ref<"field" | "icon">("icon");
const editable = ref(true);
const value = ref("09:30:00");
</script>
```

### Shared field loading

`loading` displays the shared field indicator. `loading-mode` is `default` (indicator) or `line` (an indeterminate bottom line); it defaults to `default`. Rendering belongs to FieldDecorator. Loading does not implicitly disable editing or change readonly. Set those states separately.

## Reading direction

Inherits the nearest `dir="ltr|rtl"`. Direction changes neither change the time nor commit drafts. Time columns follow reading order; Left/Right moves focus visually between columns. Cedar Up/Down and Home/End move focus within a column, skipping disabled options; Enter/Space selects. Maple wheels retain their existing Up/Down and Home/End selection behavior. Existing confirmation settings control submission. Popovers inherit their source direction.

## API

### Empty values and reading placeholders

`empty-values` recognizes empty data; `empty-value` keeps existing clear output. `empty-text` defaults to `'-'` under `read-pretty`, with Field > FormItem > Form precedence and custom read slots first. With explicit empty-values, built-in required uses the policy; custom validators receive original data. See the [shared guide](llms/en-US/guide/empty-values.md).

| Prop         | Type               | Default and scope                                                           |
| ------------ | ------------------ | --------------------------------------------------------------------------- |
| empty-values | readonly unknown[] | Field > FormItem > Form > component-family default; replaces the whole list |
| empty-text   | string             | Field > FormItem > Form > '-'; explicit '' is valid                         |

These props belong to field presentation; pure panels do not gain reading mode. Form and FormItem provide inherited settings. The existing empty-value type and clear fallback remain component-specific.

### Popup configuration and field notifications

`popup-props` configures local Trigger positioning/appearance, e.g. `{ placement: 'top-start' }`, without overriding field state/interaction such as open, disabled or trigger. Top-level `popup-container`, including false, takes precedence. `input-editable` defaults to true and can disable desktop typing. `time-picker-props`, including class/style, controls panel appearance. Undeclared attrs no longer supply panel/popup configuration; id/aria-* fall through to the field.

`click(event)` notifies only clicks on non-disabled fields. Readonly may notify without expanding. Closing consistently listens to `open-change(false)`, a close request that controlled open still requires the parent to accept. Neither platform has a field close event; a close request is not a value commit.

The field icon slot is `suffix-icon` with `focus: boolean` and `popupOpen: boolean`. `focus(index = 0)` focuses an endpoint without committing; `blur()` removes focus and requests closing.

### Props

| Arguments               | Description                                                                                                                      | Type                                                | Default   |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | --------- |
| `open-trigger-target`   | Pointer opening target: the whole field or only the suffix icon. Explicit keyboard opening and controlled open remain available. | `'field' \| 'icon'`                                 | `'field'` |
| `model-value`           | Bound value                                                                                                                      | `string \| number \| Date`                          | `-`       |
| `open`                  | Controlled popup visibility                                                                                                      | `boolean`                                           | `-`       |
| `popup-props`           | Local Trigger presentation options; do not control field state                                                                   | `TimePopupPresentationProps<Partial<TriggerProps>>` | `{}`      |
| `input-editable`        | Allow desktop text input                                                                                                         | `boolean`                                           | `true`    |
| `clearable`             | Show the clear action                                                                                                            | `boolean`                                           | `true`    |
| `disabled`              | Disable interaction                                                                                                              | `boolean`                                           | `false`   |
| `readonly`              | Read-only interaction                                                                                                            | `boolean`                                           | `false`   |
| `size`                  | Size                                                                                                                             | `xs \| sm \| md \| lg \| xl`                        | `-`       |
| `variant`               | Field appearance                                                                                                                 | `filled \| outline \| standard`                     | `filled`  |
| `placeholder`           | Placeholder                                                                                                                      | `string`                                            | `-`       |
| `format`                | Display format                                                                                                                   | `string`                                            | `-`       |
| `use12-hours`           | 12-hour clock                                                                                                                    | `boolean`                                           | `false`   |
| `hide-disabled-options` | Hide disabled time options                                                                                                       | `boolean`                                           | `false`   |
| `step`                  | Hour/minute/second steps                                                                                                         | `object`                                            | `-`       |
| `disable-confirm`       | Skip confirmation                                                                                                                | `boolean`                                           | `false`   |
| `time-picker-props`     | Forwarded to TimePicker                                                                                                          | `object`                                            | `{}`      |

### Form field presentation and confirmation

This component supports `edit-mode` with field > FormItem > Form precedence. When unset, it defaults to `direct` and preserves `direct` editing. Supported values: `direct / click / dblclick`. Non-`direct` modes open the editor through the field value trigger and keep one draft; v-model updates only after confirmation. Cancel, reset or enabling readPretty discards the draft.

Cedar uses edit-mode="click" / "dblclick" to open an editor popup near the field. Enter/F2 also opens it; cancel/Escape discards the draft, and confirmation commits it. readPretty is an independent reading setting, separate from readonly and disabled.

`before-commit(value, { previousValue, signal })` can reject an overlay save. FormItem validates the candidate first and keeps the editor open on failure. `open / default-open / update:open` control the editor. Use `#read="{ value, text }"` to customize display. See the full field comparison in Form.

Inline date/time fields retain their existing confirmation policy. In click/dblclick editors, internal panels hide confirmation tools, and the edit layer supplies one confirm/cancel pair. Standalone DatePicker, DateRangePicker, TimePicker and TimeRangePicker retain panel APIs/confirmation and do not inherit Form field presentation.

`read-pretty` is an independent boolean alongside `readonly` and `disabled`. It inherits from field to FormItem to Form; explicit `false` overrides the parent. The default is `false`. Reading mode renders no editor.

### Forwarded configuration boundaries (F07)

Existing TimePopupPresentationProps and runtime filtering remain. Fields own open/defaultOpen, disabled, trigger, closeOnClickReference, preventFocus and expansion updates. Explicit top-level popup-container takes precedence, otherwise nested configuration is used. popupClass merges internal classes. Inline popupOffset stays 4; Maple also fixes unmountOnClose=true. Such fields in old types are not guaranteed to control final values. Existing Time types/runtime behavior are not narrowed here.

## Configuring the cleared value

`empty-value` / `emptyValue` sets the model value produced by clearing. It accepts a value in the component model type or a zero-argument factory. Omission preserves the existing default; use `() => undefined` to distinguish omission from returning undefined. Arrays are shallow-copied on every clear; selected items that cannot be cleared remain. It does not redefine emptiness, alter Form reset defaults or treat 0/false as universally empty.

`empty-value` accepts explicit `null` (or `() => null`). Clearing publishes `null` unchanged; omitted values preserve the existing default. Editors render `null` as blank without converting ordinary empty-string input to `null`. In popup editing, clearing changes the draft; confirm commits it and cancel preserves the original model.

---

Document: llms/en-US/components/timeline.md

<!-- Source: src/timeline/README.en-US.md; locale: en-US; page: /en/components/timeline/ -->

# Timeline

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

- `reverse`: Whether reverse order

Example source: src/timeline/__demos__/basic.vue

```vue
<template>
  <div :style="{ marginBottom: '40px' }">
    <c-typography-text :style="{ verticalAlign: 'middle', marginRight: '8px' }"> Reverse </c-typography-text>
    <c-radio-group @change="onChange" :style="{ marginBottom: '30px' }" v-model="isReverse">
      <c-radio :value="false">No Reverse</c-radio>
      <c-radio :value="true">Reverse</c-radio>
    </c-radio-group>
  </div>
  <c-timeline :reverse="isReverse">
    <c-timeline-item label="2017-03-10">The first milestone</c-timeline-item>
    <c-timeline-item label="2018-05-12">The second milestone</c-timeline-item>
    <c-timeline-item label="2020-09-30">The third milestone</c-timeline-item>
  </c-timeline>
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const isReverse = ref(false)

const onChange = (bool) => {
  isReverse.value = bool
}
</script>
```

## Appearance and states

### Type

Preview configuration: `label="2017-03-10"`, `lineType="dashed"`, `type="secondary"`, `label="2018-05-12"`.

Example source: src/timeline/__demos__/type.vue

```vue
<template>
  <c-timeline>
    <c-timeline-item label="2017-03-10" lineType="dashed">
      The first milestone
      <br />
      <c-typography-text type="secondary" :style="{ fontSize: '12px', marginTop: '4px' }">
        This is a descriptive message
      </c-typography-text>
    </c-timeline-item>
    <c-timeline-item label="2018-05-12" lineType="dashed">
      The second milestone
      <br />
      <c-typography-text type="secondary" :style="{ fontSize: '12px', marginTop: '4px' }">
        This is a descriptive message
      </c-typography-text>
    </c-timeline-item>
    <c-timeline-item label="2020-09-30" lineType="dashed">
      The third milestone
      <br />
      <c-typography-text type="secondary" :style="{ fontSize: '12px', marginTop: '4px' }">
        This is a descriptive message
      </c-typography-text>
    </c-timeline-item>
  </c-timeline>
</template>

<script lang="ts" setup>
</script>
```

## Layout and arrangement

### Timeline direction and labels

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `mode` | The display mode of Timeline | Timeline direction and labels |
| `label-position` | Position of label text | Timeline direction and labels |
| `orientation` | Horizontal/vertical axis of the timeline line, default vertical; constrains valid item sides | Timeline direction and labels |
| `pending` | Whether to display ghost nodes. When set to true, only ghost nodes are displayed. When passed to ReactNode, it will be displayed as node content | Timeline direction and labels |
<!-- demo-config-notes:end -->


Compare orientation, sequence and label placement independently of pending states and custom nodes.

Example source: src/timeline/__demos__/layout-comparison.vue

```vue
<script setup lang="ts">
import { ref } from "vue"
import { proxyRefs as demoProxyRefs } from 'vue'

const scene1 = demoProxyRefs((() => {


const mode = ref('left')


const onChange = (_mode) => {
  mode.value = _mode
}
return { mode, onChange }
})())

const scene2 = demoProxyRefs((() => {


const mode = ref('top')


const onChange = (_mode) => {
  mode.value = _mode
}
return { mode, onChange }
})())

const scene3 = demoProxyRefs((() => {


const mode = ref('left')

const pos = ref('same')


const onLabelPositionChange = (_pos) => {
  pos.value = _pos
}


const onModeChange = (_mode) => {
  mode.value = _mode
}
return { mode, pos, onLabelPositionChange, onModeChange }
})())
</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="vertical">
    <h4><span lang="zh-CN">纵向时间轴</span><span lang="en-US">vertical</span></h4>
    <div>
        <c-row align="center" :style="{
      marginBottom: '24px'
    }">
          <c-typography-text>mode: &nbsp; &nbsp;</c-typography-text>
          <c-radio-group @change="scene1.onChange" :modelValue="scene1.mode">
            <c-radio value="left">left</c-radio>
            <c-radio value="right">right</c-radio>
            <c-radio value="alternate">alternate</c-radio>
          </c-radio-group>
        </c-row>
        <c-timeline :mode="scene1.mode" labelPosition="relative">
          <c-timeline-item label="2012-08">
            <c-row :style="{
      display: 'inline-flex',
      alignItems: 'center'
    }">
              <img
                width="40"
                :style="{
      marginRight: '16px',
      marginBottom: '12px'
    }"
                src="https://p1-arco.byteimg.com/tos-cn-i-uwbnlip3yd/b5d834b83708a269b4562924436eac48.png~tplv-uwbnlip3yd-png.png"
              />
              <div :style="{
      marginBottom: '12px'
    }">
                Toutiao
                <div :style="{
      fontSize: '12px',
      color: '#4E5969'
    }">Founded in 2012</div>
              </div>
            </c-row>
          </c-timeline-item>
          <c-timeline-item label="2017-05">
            <c-row :style="{
      display: 'inline-flex',
      alignItems: 'center'
    }">
              <img
                width="40"
                :style="{
      marginRight: '16px',
      marginBottom: '12px'
    }"
                src="https://p1-arco.byteimg.com/tos-cn-i-uwbnlip3yd/385ed540c359ec8a9b9ce2b5fe89b098.png~tplv-uwbnlip3yd-png.png"
              />
              <div :style="{
      marginBottom: '12px'
    }">
                Xigua Video
                <div :style="{
      fontSize: '12px',
      color: '#4E5969'
    }">Founded in 2017</div>
              </div>
            </c-row>
          </c-timeline-item>
          <c-timeline-item label="2018-07">
            <c-row :style="{
      display: 'inline-flex',
      alignItems: 'center'
    }">
              <img
                width="40"
                :style="{
      marginRight: '16px',
      marginBottom: '12px'
    }"
                src="https://p1-arco.byteimg.com/tos-cn-i-uwbnlip3yd/385ed540c359ec8a9b9ce2b5fe89b098.png~tplv-uwbnlip3yd-png.png"
              />
              <div :style="{
      marginBottom: '12px'
    }">
                Pipidance
                <div :style="{
      fontSize: '12px',
      color: '#4E5969'
    }">Founded in 2018</div>
              </div>
            </c-row>
          </c-timeline-item>
        </c-timeline>
      </div>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="direction">
    <h4><span lang="zh-CN">横向时间轴</span><span lang="en-US">direction</span></h4>
    <div>
        <c-row align="center" :style="{
      marginBottom: '24px'
    }">
          <c-typography-text>mode: &nbsp; &nbsp;</c-typography-text>
          <c-radio-group @change="scene2.onChange" :modelValue="scene2.mode">
            <c-radio value="top">top</c-radio>
            <c-radio value="bottom">bottom</c-radio>
            <c-radio value="alternate">alternate</c-radio>
          </c-radio-group>
        </c-row>
        <c-timeline orientation="horizontal" pending :mode="scene2.mode">
          <c-timeline-item label="2012-08">
            <c-row :style="{
      display: 'inline-flex',
      alignItems: 'center'
    }">
              <img
                width="40"
                :style="{
      marginRight: '16px',
      marginBottom: '12px'
    }"
                src="https://p1-arco.byteimg.com/tos-cn-i-uwbnlip3yd/b5d834b83708a269b4562924436eac48.png~tplv-uwbnlip3yd-png.png"
              />
              <div :style="{
      marginBottom: '12px'
    }">
                Toutiao
                <div :style="{
      fontSize: '12px',
      color: '#4E5969'
    }">Founded in 2012</div>
              </div>
            </c-row>
          </c-timeline-item>
          <c-timeline-item label="2017-05">
            <c-row :style="{
      display: 'inline-flex',
      alignItems: 'center'
    }">
              <img
                width="40"
                :style="{
      marginRight: '16px',
      marginBottom: '12px'
    }"
                src="https://p1-arco.byteimg.com/tos-cn-i-uwbnlip3yd/385ed540c359ec8a9b9ce2b5fe89b098.png~tplv-uwbnlip3yd-png.png"
              />
              <div :style="{
      marginBottom: '12px'
    }">
                Xigua Video
                <div :style="{
      fontSize: '12px',
      color: '#4E5969'
    }">Founded in 2017</div>
              </div>
            </c-row>
          </c-timeline-item>
          <c-timeline-item label="2018-07">
            <c-row :style="{
      display: 'inline-flex',
      alignItems: 'center'
    }">
              <img
                width="40"
                :style="{
      marginRight: '16px',
      marginBottom: '12px'
    }"
                src="https://p1-arco.byteimg.com/tos-cn-i-uwbnlip3yd/385ed540c359ec8a9b9ce2b5fe89b098.png~tplv-uwbnlip3yd-png.png"
              />
              <div :style="{
      marginBottom: '12px'
    }">
                Pipidance
                <div :style="{
      fontSize: '12px',
      color: '#4E5969'
    }">Founded in 2018</div>
              </div>
            </c-row>
          </c-timeline-item>
        </c-timeline>
      </div>
  </section>

  <section class="demo-comparison-case demo-comparison-case--3" data-comparison-scene="label">
    <h4><span lang="zh-CN">标签文本位置</span><span lang="en-US">label</span></h4>
    <div>
        <c-row align="center">
          <c-typography-text>labelPosition: &nbsp; &nbsp;</c-typography-text>
          <c-radio-group @change="scene3.onLabelPositionChange" :modelValue="scene3.pos">
            <c-radio value="same">same</c-radio>
            <c-radio value="relative">relative</c-radio>
          </c-radio-group>
        </c-row>
        <c-row align="center" :style="{
      margin: '20px 0px 24px'
    }">
          <c-typography-text>mode: &nbsp; &nbsp;</c-typography-text>
          <c-radio-group @change="scene3.onModeChange" :modelValue="scene3.mode">
            <c-radio value="left">left</c-radio>
            <c-radio value="right">right</c-radio>
            <c-radio value="alternate">alternate</c-radio>
          </c-radio-group>
        </c-row>
        <c-timeline :mode="scene3.mode" :labelPosition="scene3.pos">
          <c-timeline-item label="2017-03-10" dotColor="#52C419"> The first milestone </c-timeline-item>
          <c-timeline-item label="2018-05-12" dotColor="#F5222D" labelPosition="same"> The second milestone </c-timeline-item>
          <c-timeline-item label="2020-09-30" content-placement="bottom"> The third milestone </c-timeline-item>
        </c-timeline>
      </div>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

## Content and presentation

### Pending

Preview configuration: `align="center"`, `:checked="!!pendingProps.orientation"`, `:checked="!!pendingProps.reverse"`, `:checked="!!pendingProps.pending"`.

Example source: src/timeline/__demos__/pending.vue

```vue
<template>
  <c-row align="center" :style="{ marginBottom: '24px' }">
    <c-checkbox :checked="!!pendingProps.orientation" @change="(v) => onChange({ orientation: v ? 'horizontal' : '' })">
      horizontal &nbsp; &nbsp;
    </c-checkbox>
    <c-checkbox :checked="!!pendingProps.reverse" @change="(v) => onChange({ reverse: v })">
      reverse &nbsp; &nbsp;
    </c-checkbox>
    <c-checkbox
      :checked="!!pendingProps.pending"
      @change="(v) => onChange({ pending: v ? 'This is a pending dot' : false })"
    >
      pending &nbsp; &nbsp;
    </c-checkbox>
    <c-checkbox :checked="!!pendingProps.hasPendingDot" @change="(v) => onChange({ hasPendingDot: v })">
      custom pendingDot
    </c-checkbox>
  </c-row>
  <c-timeline v-bind="pendingProps">
    <template v-if="pendingProps.hasPendingDot" #dot>
      <c-icon-fire :style="{ color: '#e70a0a' }" />
    </template>
    <c-timeline-item label="2017-03-10" dotColor="#52C419"> The first milestone </c-timeline-item>
    <c-timeline-item label="2018-05-12" dotColor="#F5222D"> The second milestone </c-timeline-item>
    <c-timeline-item label="2020-09-30">The third milestone</c-timeline-item>
  </c-timeline>
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const pendingProps = ref({})

const onChange = (newProps) => {
  pendingProps.value = {
    ...pendingProps.value,
    ...newProps,
  }
}
</script>
```

### Mode

- `mode`: The display mode of Timeline

Example source: src/timeline/__demos__/mode.vue

```vue
<template>
  <c-row justify="space-between">
    <c-timeline mode="alternate" :style="{ flex: 1 }">
      <c-timeline-item label="2017-03-10">The first milestone</c-timeline-item>
      <c-timeline-item label="2018-05-12">The second milestone</c-timeline-item>
      <c-timeline-item label="2020-09-30" content-placement="bottom"> The third milestone </c-timeline-item>
    </c-timeline>
    <c-timeline mode="right" :style="{ flex: 1 }">
      <c-timeline-item label="2017-03-10">The first milestone</c-timeline-item>
      <c-timeline-item label="2018-05-12">The second milestone</c-timeline-item>
      <c-timeline-item label="2020-09-30" content-placement="bottom"> The third milestone </c-timeline-item>
    </c-timeline>
  </c-row>
</template>

<script lang="ts" setup>
</script>
```

## Customization and slots

### Icon

Preview configuration: `label="2017-03-10"`, `dotColor="#00B42A"`, `label="2018-05-22"`, `label="2020-06-22"`.

Example source: src/timeline/__demos__/icon.vue

```vue
<template>
  <c-timeline>
    <c-timeline-item label="2017-03-10" dotColor="#00B42A"> The first milestone </c-timeline-item>
    <c-timeline-item label="2018-05-22">The second milestone</c-timeline-item>
    <c-timeline-item label="2020-06-22" dotColor="#F53F3F">
      The third milestone
      <c-icon-exclamation-circle-fill :style="{ color: '#F53F3F', fontSize: '12px', marginLeft: '4px' }" />
    </c-timeline-item>
    <c-timeline-item label="2020-09-30" dotColor="#C9CDD4"> The fourth milestone </c-timeline-item>
  </c-timeline>
</template>

<script lang="ts" setup>
</script>
```

### Dot

Preview configuration: `label="2020-04-12"`, `dotColor="#00B42A"`, `label="2020-05-17"`, `label="2020-06-22"`.

Example source: src/timeline/__demos__/dot.vue

```vue
<template>
  <div :style="{ display: 'flex' }">
    <c-timeline :style="{ marginRight: '40px' }">
      <c-timeline-item label="2020-04-12" dotColor="#00B42A"> The first milestone </c-timeline-item>
      <c-timeline-item label="2020-05-17"> The second milestone </c-timeline-item>
      <c-timeline-item label="2020-06-22">
        <template #dot>
          <c-icon-clock-circle :style="{ fontSize: '12px', color: '#F53F3F' }" />
        </template>
        The third milestone
      </c-timeline-item>
      <c-timeline-item label="2020-06-22" dotColor="var(--color-fill-4)"> The third milestone </c-timeline-item>
    </c-timeline>

    <c-timeline :style="{ marginRight: '40px' }">
      <c-timeline-item label="2020-04-12">
        <template #dot>
          <c-icon-check
            :style="{
              fontSize: '12px',
              padding: '2px',
              boxSizing: 'border-box',
              borderRadius: '50%',
              backgroundColor: 'var(--color-primary-light-1)',
            }"
          />
        </template>
        The first milestone
      </c-timeline-item>
      <c-timeline-item label="2020-05-17">
        <template #dot>
          <c-icon-check
            :style="{
              fontSize: '12px',
              padding: '2px',
              boxSizing: 'border-box',
              borderRadius: '50%',
              backgroundColor: 'var(--color-primary-light-1)',
            }"
          />
        </template>
      </c-timeline-item>
      <c-timeline-item label="2020-06-22">The third milestone</c-timeline-item>
      <c-timeline-item label="2020-06-22" dotColor="var(--color-fill-4)"> The third milestone </c-timeline-item>
    </c-timeline>

    <c-timeline>
      <c-timeline-item label="2020-04-12">The first milestone</c-timeline-item>
      <c-timeline-item label="2020-05-17" dotColor="var(--color-fill-4)"> The second milestone </c-timeline-item>
      <c-timeline-item label="2020-06-22" dotColor="var(--color-fill-4)"> The third milestone </c-timeline-item>
    </c-timeline>
  </div>
</template>

<script lang="ts" setup>
</script>
```

### Custom

Example source: src/timeline/__demos__/custom.vue

```vue
<template>
  <c-timeline>
    <c-timeline-item>
      Code Review
      <template #label>
        <c-tag>
          <template #icon>
            <c-icon-check-circle-fill />
          </template>
          Passed
        </c-tag>
      </template>
    </c-timeline-item>
  </c-timeline>
</template>

<script lang="ts" setup>
</script>
```

## API

### `<timeline>` Props

| Parameter | Description | Type | Default |
| -------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------- | :----------: |
| reverse | Whether reverse order | `boolean` | `false` |
| orientation | Horizontal/vertical axis of the timeline line, default vertical; constrains valid item sides | `'horizontal' \| 'vertical'` | `'vertical'` |
| mode | The display mode of Timeline | `'left' \| 'right' \| 'top' \| 'bottom' \| 'alternate'` | `'left'` |
| pending | Whether to display ghost nodes. When set to true, only ghost nodes are displayed. When passed to ReactNode, it will be displayed as node content | `boolean\|string` | `-` |
| label-position | Position of label text | `'relative' \| 'same'` | `'same'` |

### `<timeline>` Slots

| Slot | Description | Arguments |
| ------ | :------: | ---- |
| dot | Ghost node | - |

### `<timeline-item>` Props

| Parameter | Description | Type | Default |
| ---------- | ---------------------------- | --------------------------------- | :-------: |
| dot-color | Node color | `string` | `-` |
| dot-type | Node type: outlined/filled circle | `'hollow' \| 'solid'` | `'solid'` |
| line-type | Timeline line style: solid/dashed/dotted | `'solid' \| 'dashed' \| 'dotted'` | `'solid'` |
| line-color | Timeline color | `string` | `-` |
| label | Label text | `string` | `-` |
| content-placement | Current per-item side relative to the timeline in alternate mode: left/right for vertical and top/bottom for horizontal. Constrained by mode and orientation | `TimelineItemContentPlacement` | `-` |

### `<timeline-item>` Slots

| Slot | Description | Arguments | Version |
| ------ | :--------: | ---- | :----- |
| dot | Custom node | - |  |
| label | Custom label | - | 2.50.0 |

### Type definitions

The component exports the following types

```ts
import type { MentionInstance } from '@cedar-design/ui'
```


## Reading direction and keyboard interaction

Horizontal timelines follow the inherited reading direction, including connecting lines. `reverse` independently controls visual reversal; switching direction does not reorder the data. Explicit vertical `left`/`right` sides retain their physical meaning.

---

Document: llms/en-US/components/tooltip.md

<!-- Source: src/tooltip/README.en-US.md; locale: en-US; page: /en/components/tooltip/ -->

# Tooltip

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

Preview configuration: `content="This is tooltip content"`, `content="This is a two-line tooltip content.This is a two-line tooltip content."`.

Example source: src/tooltip/__demos__/basic.vue

```vue
<template>
  <c-space wrap>
    <c-tooltip content="This is tooltip content">
      <c-button>Mouse over to display tooltip</c-button>
    </c-tooltip>
    <c-tooltip content="This is a two-line tooltip content.This is a two-line tooltip content.">
      <c-button>Mouse over to display tooltip</c-button>
    </c-tooltip>
  </c-space>
</template>
<script lang="ts" setup>
</script>
```

## Appearance and states

### Status

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `content` | Hint content | Status, Appearance configuration comparison |
| `color` | Background color | Status, Appearance configuration comparison |
| `status` | Panel intent | Status |
<!-- demo-config-notes:end -->


- `status`: Selects the semantic state.
- `color`: Overrides the color.

Example source: src/tooltip/__demos__/status.vue

```vue
<template>
  <c-space wrap>
    <c-tooltip v-for="status in statuses" :key="status" :status="status" :content="status">
      <c-button :status="status === 'default' ? undefined : status">{{ status }}</c-button>
    </c-tooltip>
  </c-space>
</template>

<script setup lang="ts">
import type { TooltipStatus } from '../props'

const statuses: TooltipStatus[] = ['default', 'primary', 'info', 'success', 'warning', 'danger']
</script>
```

Example source: src/tooltip/__demos__/color.vue

```vue
<template>
  <c-space wrap>
    <c-tooltip content="This is tooltip content" color="#3491FA">
      <c-button>#3491FA</c-button>
    </c-tooltip>
    <c-tooltip content="This is tooltip content" color="#165DFF">
      <c-button>#165DFF</c-button>
    </c-tooltip>
    <c-tooltip content="This is tooltip content" color="#722ED1">
      <c-button>#722ED1</c-button>
    </c-tooltip>
  </c-space>
</template>
<script lang="ts" setup>
</script>
```

### Appearance configuration comparison

Choose an axis to compare its available values with the same content and model. Other settings remain unchanged while comparing.

Example source: src/tooltip/__demos__/appearance-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";

const __demoAppearance = __demoReactive({ status: "default", size: "md" });

import { computed as demoComputed, ref as demoRef } from 'vue'
const demoCompareFields = [{"name":"status","values":["default","primary","info","success","warning","danger"]},{"name":"size","values":["xs","md"]}]
const demoCompareAxis = demoRef("status")
const demoComparedOptions = demoComputed(() => demoCompareFields.find(field => field.name === demoCompareAxis.value)?.values ?? [])
</script>
<template>
  <c-space direction="column" :size="16">
    <c-form layout="vertical">
      <c-form-item layout="vertical" size="sm" label="status">
        <c-select
          v-model="__demoAppearance['status']"
          :clearable="false"
          :options="[
            { label: 'default', value: 'default' },
            { label: 'primary', value: 'primary' },
            { label: 'info', value: 'info' },
            { label: 'success', value: 'success' },
            { label: 'warning', value: 'warning' },
            { label: 'danger', value: 'danger' },
          ]"
          aria-label="status"
        />
      </c-form-item>
      <c-form-item layout="vertical" size="sm" label="size">
        <c-radio-group
          v-model="__demoAppearance['size']"
          aria-label="size"
          :options="[
            { label: 'xs', value: 'xs' },
            { label: 'md', value: 'md' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
    </c-form>
    <p class="demo-config-comparison-hint"><span lang="zh-CN">选择一个对比维度；其他配置和内容保持一致。输入类示例共享同一个值，便于比较外观。</span><span lang="en-US">Compare one dimension while keeping the other settings and content identical. Input specimens share the same value.</span></p>
<c-radio-group v-model="demoCompareAxis" aria-label="Compare configuration" :options="demoCompareFields.map(field => ({ label: field.name, value: field.name }))" />
<div class="demo-config-comparison">
<section v-for="sample in demoComparedOptions" :key="String(sample)">
<p><code>{{ demoCompareAxis }}={{ sample }}</code></p>
<c-tooltip
      content="This is tooltip content"
      color="#3491FA"
      v-bind="{ ...__demoAppearance, [demoCompareAxis]: sample }"
    >
      <c-button>#3491FA</c-button>
    </c-tooltip>
</section>
</div>
  </c-space>
</template>

<style scoped>
.demo-config-comparison { display: grid; grid-template-columns: repeat(auto-fit, minmax(min(100%, 220px), 1fr)); gap: 20px; min-width: 0; max-width: 100%; }
.demo-config-comparison > section { min-width: 0; }
.demo-config-comparison p { margin: 0 0 8px; }
html:not([lang='en-US']) .demo-config-comparison-hint > [lang='en-US'],
html[lang='en-US'] .demo-config-comparison-hint > [lang='zh-CN'] { display: none; }
</style>
```

## Layout and arrangement

### Placement

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `content` | Hint content | Placement |
| `placement` | Preferred popup side relative to the trigger, default top. With the default auto-fit-position enabled, Trigger may flip and constrain it to the viewport when space is limited; this is not a fixed final position | Placement |
<!-- demo-config-notes:end -->


- `placement`: Chooses the position relative to the trigger.

Example source: src/tooltip/__demos__/placement.vue

```vue
<template>
  <div :style="{ position: 'relative', width: '440px', height: '280px' }">
    <c-tooltip content="This is a Tooltip" placement="top-start">
      <c-button class="button" :style="{ position: 'absolute', top: '0', left: '70px' }">TL</c-button>
    </c-tooltip>
    <c-tooltip content="This is a Tooltip" placement="top">
      <c-button class="button" :style="{ position: 'absolute', top: '0', left: '180px' }">TOP</c-button>
    </c-tooltip>
    <c-tooltip content="This is a Tooltip" placement="top-end">
      <c-button class="button" :style="{ position: 'absolute', top: '0', left: '290px' }">TR</c-button>
    </c-tooltip>
    <c-tooltip content="This is a Tooltip" placement="bottom-start">
      <c-button class="button" :style="{ position: 'absolute', top: '240px', left: '70px' }">BL</c-button>
    </c-tooltip>
    <c-tooltip content="This is a Tooltip" placement="bottom">
      <c-button class="button" :style="{ position: 'absolute', top: '240px', left: '180px' }">BOTTOM</c-button>
    </c-tooltip>
    <c-tooltip content="This is a Tooltip" placement="bottom-end">
      <c-button class="button" :style="{ position: 'absolute', top: '240px', left: '290px' }">BR</c-button>
    </c-tooltip>
    <c-tooltip content="This is a Tooltip" placement="left-start">
      <c-button class="button" :style="{ position: 'absolute', top: '60px', left: '10px' }">LT</c-button>
    </c-tooltip>
    <c-tooltip content="This is a Tooltip" placement="left">
      <c-button class="button" :style="{ position: 'absolute', top: '120px', left: '10px' }">LEFT</c-button>
    </c-tooltip>
    <c-tooltip content="This is a Tooltip" placement="left-end">
      <c-button class="button" :style="{ position: 'absolute', top: '180px', left: '10px' }">LB</c-button>
    </c-tooltip>
    <c-tooltip content="This is a Tooltip" placement="right-start">
      <c-button class="button" :style="{ position: 'absolute', top: '60px', left: '350px' }">RT</c-button>
    </c-tooltip>
    <c-tooltip content="This is a Tooltip" placement="right">
      <c-button class="button" :style="{ position: 'absolute', top: '120px', left: '350px' }">RIGHT</c-button>
    </c-tooltip>
    <c-tooltip content="This is a Tooltip" placement="right-end">
      <c-button class="button" :style="{ position: 'absolute', top: '180px', left: '350px' }">RB</c-button>
    </c-tooltip>
  </div>
</template>
<script lang="ts" setup>
</script>
<style scoped>
.button {
  width: 100px;
}
</style>
```

## Content and presentation

### Directive

Example source: src/tooltip/__demos__/directive.vue

```vue
<template>
  <div :style="{ position: 'relative', width: '440px', height: '280px' }">
    <c-button v-tooltip:top-start="'This is a Tooltip'" :style="{ position: 'absolute', top: '0', left: '70px' }" class="button"
      >TL
    </c-button>
    <c-button
      v-tooltip:top="'This is a Tooltip'"
      :style="{ position: 'absolute', top: '0', left: '180px' }"
      class="button"
      >TOP
    </c-button>
    <c-button v-tooltip:top-end="'This is a Tooltip'" :style="{ position: 'absolute', top: '0', left: '290px' }" class="button"
      >TR
    </c-button>
    <c-button
      v-tooltip:bottom-start="'This is a Tooltip'"
      :style="{ position: 'absolute', top: '240px', left: '70px' }"
      class="button"
      >BL
    </c-button>
    <c-button
      v-tooltip:bottom="'This is a Tooltip'"
      :style="{ position: 'absolute', top: '240px', left: '180px' }"
      class="button"
      >BOTTOM
    </c-button>
    <c-button
      v-tooltip:bottom-end="'This is a Tooltip'"
      :style="{ position: 'absolute', top: '240px', left: '290px' }"
      class="button"
      >BR
    </c-button>
    <c-button
      v-tooltip:left-start="'This is a Tooltip'"
      :style="{ position: 'absolute', top: '60px', left: '10px' }"
      class="button"
      >LT
    </c-button>
    <c-button
      v-tooltip:left="'This is a Tooltip'"
      :style="{ position: 'absolute', top: '120px', left: '10px' }"
      class="button"
      >LEFT
    </c-button>
    <c-button
      v-tooltip:left-end="'This is a Tooltip'"
      :style="{ position: 'absolute', top: '180px', left: '10px' }"
      class="button"
      >LB
    </c-button>
    <c-button
      v-tooltip:right-start="'This is a Tooltip'"
      :style="{ position: 'absolute', top: '60px', left: '350px' }"
      class="button"
      >RT
    </c-button>
    <c-button
      v-tooltip:right="'This is a Tooltip'"
      :style="{ position: 'absolute', top: '120px', left: '350px' }"
      class="button"
      >RIGHT
    </c-button>
    <c-button
      v-tooltip:right-end="'This is a Tooltip'"
      :style="{ position: 'absolute', top: '180px', left: '350px' }"
      class="button"
      >RB
    </c-button>
  </div>
</template>
<script lang="ts" setup>
</script>

<style scoped>
.button {
  width: 100px;
}
</style>
```

Example source: src/tooltip/__demos__/text-ellipsis.vue

```vue
<template>
  <c-space wrap class="Home">
    <div v-tooltip:ellipsis class="text-container">
      相见时难别亦难，东风无力百花残。 春蚕到死丝方尽，蜡炬成灰泪始干。 晓镜但愁云鬓改，夜吟应觉月光寒。
      蓬山此去无多路，青鸟殷勤为探看。
    </div>
    <div v-tooltip:ellipsis class="text-container">没溢出</div>
  </c-space>
</template>
<style scoped>
.text-container {
  width: 100px;
}
</style>
```

## API

Tooltip inherits Trigger positioning, containers, controlled state, closing policies and public methods.

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| content | Hint content | `string` | — |
| status | Panel intent | `default \| primary \| info \| success \| warning \| danger` | `default` |
| size | Implemented sizes | `xs \| md` | `md` |
| color | Background color | `string` | — |
| text-color | Custom text color | `string` | — |
| trigger | Interaction | `TriggerEvent \| TriggerEvent[]` | `['hover', 'focus']` |
| placement | Preferred popup side relative to the trigger, default top. With the default auto-fit-position enabled, Trigger may flip and constrain it to the viewport when space is limited; this is not a fixed final position | `TriggerPlacement` | `top` |
| show-arrow | Show the arrow | `boolean` | `true` |
| popup-offset | Main-axis distance | `number` | `10` |
| unmount-on-close | Unmount after close | `boolean` | `true` |

Events: `update:open`, `open-change`, `open`, `opened`, `close`, `closed`, `click-outside`. Slots: `default`, `content`. Exposes `open`, `close`, `resize`, `allowClose`, `getReference`, `setReference` and `focusReference`.

Content has `role="tooltip"`. Opening adds its ID to the actual trigger's `aria-describedby`; closing, changing external reference or unmounting removes it.

## Shared-source contract

Cedar/Maple independently maintain matching bodies, props, appearance mappings and structural styles. Only prefixes, local imports and theme-token values differ. No `backgroundColor` or boolean `xs` compatibility entry exists.

## Public CSS variables

These are actual :root defaults. Prefer component variables for business customization; internal positioning variables are not public API.

| Variable | Default | Meaning and use case |
| --- | --- | --- |
| `--c-tooltip-background` | `var(--c-sys-color-surface-tooltip)` | Content and arrow background |
| `--c-tooltip-text-color` | `var(--c-sys-color-content-on-dark)` | Body foreground |
| `--c-tooltip-status-primary-background` | `var(--c-sys-color-action-primary)` | Primary content/arrow background |
| `--c-tooltip-status-info-background` | `var(--c-sys-color-status-info)` | Info content/arrow background |
| `--c-tooltip-status-success-background` | `var(--c-sys-color-status-success)` | Success content/arrow background |
| `--c-tooltip-status-warning-background` | `var(--c-sys-color-status-warning)` | Warning content/arrow background |
| `--c-tooltip-status-danger-background` | `var(--c-sys-color-status-danger)` | Danger content/arrow background |
| `--c-tooltip-status-primary-text-color` | `var(--c-sys-color-content-on-dark)` | Primary text; set together with its background |
| `--c-tooltip-status-info-text-color` | `var(--c-sys-color-content-on-dark)` | Info text; set together with its background |
| `--c-tooltip-status-success-text-color` | `var(--c-sys-color-content-on-dark)` | Success text; set together with its background |
| `--c-tooltip-status-warning-text-color` | `var(--c-sys-color-content-on-dark)` | Warning text; set together with its background |
| `--c-tooltip-status-danger-text-color` | `var(--c-sys-color-content-on-dark)` | Danger text; set together with its background |
| `--c-tooltip-padding-horizontal` | `var(--c-sys-space-6)` | Horizontal content padding |
| `--c-tooltip-padding-vertical` | `var(--c-sys-space-4)` | Vertical content padding |
| `--c-tooltip-font-size` | `var(--c-sys-font-size-md)` | Content font size |
| `--c-tooltip-line-height` | `var(--c-line-height)` | Content line height |
| `--c-tooltip-border-radius` | `var(--c-sys-radius-md)` | Content border radius |
| `--c-tooltip-max-width` | `350px` | Maximum tooltip-content width |
| `--c-tooltip-opacity` | `1` | Content/arrow opacity; changes require contrast checks |
| `--c-tooltip-size-xs-padding-horizontal` | `var(--c-sys-space-4)` | xs horizontal content padding |
| `--c-tooltip-size-xs-padding-vertical` | `var(--c-sys-space-2)` | xs vertical content padding |
| `--c-tooltip-size-xs-font-size` | `var(--c-sys-font-size-xs)` | xs content font size |
| `--c-tooltip-animation-duration` | `var(--c-sys-motion-duration-standard)` | Enter/leave duration; reduced motion may override it |

All built-in themes use opacity 1. Colored solid text follows Button on-dark in both light/dark modes. Maple dark mode retains 4px radius, 14px font and 8px/16px vertical/horizontal padding. Neutral surfaces remain dark in both modes. `color` sets content/arrow backgrounds; `text-color` sets text. Explicit content-style/arrow-style override their respective nodes. Recheck custom colors/opacity.

With Teleport, variables must be in the actual popup scope, for example through `popup-style`. Trigger-button variables do not automatically inherit into popups.

---

Document: llms/en-US/components/transfer.md

<!-- Source: src/transfer/README.en-US.md; locale: en-US; page: /en/components/transfer/ -->

# Transfer

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

- `data`: Data of the transfer
- `default-value`: The default value in the target selection box (uncontrolled state)

Example source: src/transfer/__demos__/basic.vue

```vue
<template>
  <c-transfer :data="data" :default-value="value" />
</template>

<script lang="ts" setup>
const data = Array(8)
  .fill(undefined)
  .map((_, index) => ({
    value: `option${index + 1}`,
    label: `Option ${index + 1}`,
  }))
const value = [{ value: 'option1' }, { value: 'option3' }, { value: 'option5' }]
</script>
```

## Search and data structures

### Search

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration               | Purpose                                 | Related examples      |
| --------------------------- | --------------------------------------- | --------------------- |
| `data`                      | Data of the transfer                    | Search, Grouped, Tree |
| `source-filterable`         | Show the source search input            | Search, Grouped       |
| `default-value`             | Complete uncontrolled target-side state | Search, Tree          |
| `source-filter-placeholder` | Source search placeholder               | Search, Grouped       |
| `target-filterable`         | Show the target search input            | Search                |
| `target-filter-placeholder` | Target search placeholder               | Search                |

<!-- demo-config-notes:end -->

- `data`: Data of the transfer
- `default-value`: The default value in the target selection box (uncontrolled state)

Dragging a filtered target list reorders only visible positions in the complete target sequence. Hidden required items, selections absent from the current candidate page, and their metadata are retained.

Example source: src/transfer/__demos__/search.vue

```vue
<template>
  <c-transfer
    source-filterable
    target-filterable
    :data="data"
    v-model="value"
    target-draggable
    source-filter-placeholder="搜索待选项"
    target-filter-placeholder="搜索已选项"
  />
  <p role="status">当前顺序：{{ value.map(item => item.value).join(' → ') }}</p>
  <p>在已选项搜索 Option 后拖拽，隐藏的必选字段仍保留在完整列表中。</p>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
const data = Array(8)
  .fill(undefined)
  .map((_, index) => ({
    value: `option${index + 1}`,
    label: index === 2 ? '必选字段' : `Option ${index + 1}`,
    required: index === 2,
  }))
const value = ref([{ value: 'option1' }, { value: 'option3' }, { value: 'option5' }])
</script>
```

### Grouped

- `data`: Data of the transfer

Example source: src/transfer/__demos__/grouped.vue

```vue
<template>
  <div style="height: 520px">
    <c-transfer
      v-model="value"
      :data="data"
      :target-actions="targetActions"
      source-filterable
      target-draggable
      target-operation="menu"
      source-filter-placeholder="请输入关键词搜索"
      @target-action="handleTargetAction"
    />
  </div>
  <c-dialog v-model:open="customVisible" title="自定义操作" :width="420"> 当前操作项：{{ activeLabel }} </c-dialog>
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const data = [
  { value: 'gunId', label: '枪ID', group: '基本信息', disabled: true, tip: '系统必选字段' },
  { value: 'gunName', label: '枪名称', group: '基本信息' },
  { value: 'company', label: '区域公司区域公司区域公司', group: '基本信息', tip: '所属区域公司' },
  { value: 'deviceId', label: '设备ID', group: '设备信息' },
  { value: 'deviceName', label: '设备名称', group: '设备信息' },
  { value: 'lock', label: '地锁', group: '设备信息' },
  { value: 'workStatus', label: '工作状态', group: '设备信息' },
  { value: 'connectStatus', label: '连接状态', group: '设备信息' },
]

const value = ref([{ value: 'gunId' }, { value: 'gunName' }, { value: 'deviceName' }])
const customVisible = ref(false)
const activeLabel = ref('')
const targetActions = [{ key: 'custom', label: '自定义弹窗' }]

const handleTargetAction = (_key: string, item: (typeof data)[number]) => {
  activeLabel.value = item.label
  customVisible.value = true
}
</script>
```

### Tree

- `data`: Data of the transfer
- `default-value`: The default value in the target selection box (uncontrolled state)

Example source: src/transfer/__demos__/tree.vue

```vue
<template>
  <c-transfer :data="transferData" :default-value="value">
    <template #source="{ data, selectedKeys, onSelect }">
      <c-tree
        :checkable="true"
        checked-strategy="child"
        :checked-values="selectedKeys"
        :data="getTreeData(data)"
        @check="onSelect"
      />
    </template>
  </c-transfer>
</template>

<script lang="ts" setup>
const treeData = [
  {
    label: 'Trunk 0-0',
    value: '0-0',
    children: [
      {
        label: 'Leaf 0-0-1',
        value: '0-0-1',
      },
      {
        label: 'Branch 0-0-2',
        value: '0-0-2',
        children: [
          {
            label: 'Leaf 0-0-2-1',
            value: '0-0-2-1',
          },
          {
            label: 'Leaf 0-0-2-2',
            value: '0-0-2-2',
          },
        ],
      },
    ],
  },
  {
    label: 'Trunk 0-1',
    value: '0-1',
    children: [
      {
        label: 'Branch 0-1-1',
        value: '0-1-1',
        children: [
          {
            label: 'Leaf 0-1-1-1',
            value: '0-1-1-1',
          },
          {
            label: 'Leaf 0-1-1-2',
            value: '0-1-1-2',
          },
        ],
      },
      {
        label: 'Leaf 0-1-2',
        value: '0-1-2',
      },
    ],
  },
]

const getTransferData = (treeData = [], transferDataSource = []) => {
  treeData.forEach((item) => {
    if (item.children) getTransferData(item.children, transferDataSource)
    else transferDataSource.push({ label: item.label, value: item.value })
  })
  return transferDataSource
}

const getTreeData = (data = []) => {
  const values = data.map((item) => item.value)

  const travel = (_treeData = []) => {
    const treeDataSource = []
    _treeData.forEach((item) => {
      if (item.children || values.includes(item.value)) {
        treeDataSource.push({ label: item.label, value: item.value, children: travel(item.children) })
      }
    })
    return treeDataSource
  }

  return travel(treeData)
}

const transferData = getTransferData(treeData)

const value = [{ value: '0-0-2-1' }]
</script>
```

## Content customization

### Custom

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration   | Purpose                                 | Related examples      |
| --------------- | --------------------------------------- | --------------------- |
| `data`          | Data of the transfer                    | Custom, Custom Header |
| `default-value` | Complete uncontrolled target-side state | Custom, Custom Header |

<!-- demo-config-notes:end -->

- `data`: Data of the transfer
- `default-value`: The default value in the target selection box (uncontrolled state)

Example source: src/transfer/__demos__/custom.vue

```vue
<template>
  <c-transfer :data="data" :default-value="value">
    <template #item="{ label }">
      <c-icon-up />
      {{ label }}
    </template>
  </c-transfer>
</template>

<script lang="ts" setup>
const data = Array(8)
  .fill(undefined)
  .map((_, index) => ({
    value: `option${index + 1}`,
    label: `Option ${index + 1}`,
  }))
const value = [{ value: 'option1' }, { value: 'option3' }, { value: 'option5' }]
</script>
```

### Custom Header

- `data`: Data of the transfer
- `default-value`: The default value in the target selection box (uncontrolled state)

Example source: src/transfer/__demos__/custom-header.vue

```vue
<template>
  <c-transfer :data="data" :default-value="value">
    <template #source-title="{ countTotal, countSelected, checked, indeterminate, onSelectAllChange }">
      <div :style="styleHeader">
        Source Title {{ countSelected }}-{{ countTotal }}
        <c-checkbox :model-value="checked" :indeterminate="indeterminate" @change="onSelectAllChange" />
      </div>
    </template>

    <template #target-title="{ countTotal, countSelected, onClear }">
      <div :style="styleHeader">
        Target Title {{ countSelected }}-{{ countTotal }}
        <c-icon-delete @click="onClear" />
      </div>
    </template>
  </c-transfer>
</template>

<script lang="ts" setup>
const data = Array(8)
  .fill(undefined)
  .map((_, index) => ({
    value: `option${index + 1}`,
    label: `Option ${index + 1}`,
  }))
const value = [{ value: 'option1' }, { value: 'option3' }, { value: 'option5' }]

const styleHeader = {
  display: 'flex',
  alignItems: 'center',
  justifyContent: 'space-between',
  paddingRight: '8px',
}
</script>
```

## Large datasets

### Large Data

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration               | Purpose                              | Related examples |
| --------------------------- | ------------------------------------ | ---------------- |
| `data`                      | Data of the transfer                 | Large Data       |
| `virtual-scroll`            | Whether virtual scrolling is enabled | Large Data       |
| `source-filterable`         | Show the source search input         | Large Data       |
| `source-filter-placeholder` | Source search placeholder            | Large Data       |

<!-- demo-config-notes:end -->

- `data`: Data of the transfer

Example source: src/transfer/__demos__/large-data.vue

```vue
<template>
  <c-transfer
    v-model="value"
    :data="data"
    virtual-scroll
    source-filterable
    source-filter-placeholder="搜索 42,000 项"
  />
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const data = Array.from({ length: 42000 }, (_, index) => ({
  value: index,
  label: `Option ${index}`,
  disabled: index % 5 === 0,
}))
const value = ref(Array.from({ length: 50 }, (_, index) => ({ value: index })))
</script>
```

## API

### Empty values and reading placeholders

`empty-values` recognizes empty data; `empty-value` keeps existing clear output. `empty-text` defaults to `'-'` under `read-pretty`, with Field > FormItem > Form precedence and custom read slots first. With explicit empty-values, built-in required uses the policy; custom validators receive original data. See the [shared guide](llms/en-US/guide/empty-values.md).

| Prop         | Type               | Default and scope                                                           |
| ------------ | ------------------ | --------------------------------------------------------------------------- |
| empty-values | readonly unknown[] | Field > FormItem > Form > component-family default; replaces the whole list |
| empty-text   | string             | Field > FormItem > Form > '-'; explicit '' is valid                         |

These props belong to field presentation; pure panels do not gain reading mode. Form and FormItem provide inherited settings. The existing empty-value type and clear fallback remain component-specific.

### `<transfer>` Props

| Parameter                 | Description                                          | Type                                                        |             Default             |
| ------------------------- | ---------------------------------------------------- | ----------------------------------------------------------- | :-----------------------------: |
| data                      | Data of the transfer                                 | `TransferItem[]` / `(query, { signal }) => Array / Promise` |           `undefined`           |
| model-value **(v-model)** | Complete ordered target-side state                   | `TransferTargetItem[]`                                      |               `-`               |
| default-value             | Complete uncontrolled target-side state              | `TransferTargetItem[]`                                      |              `[]`               |
| disabled                  | Whether disabled                                     | `boolean`                                                   |             `false`             |
| virtual-scroll            | Whether virtual scrolling is enabled                 | `boolean`                                                   |             `false`             |
| target-draggable          | Whether the target list can be reordered by dragging | `boolean`                                                   |             `false`             |
| target-operation          | Target actions shown as a remove icon or action menu | `'remove' \| 'menu'`                                        |           `'remove'`            |
| clear-text                | Target clear-button text                             | `string`                                                    |             `清空`              |
| target-actions            | Custom actions appended to the target menu           | `TransferTargetAction[]`                                    |              `[]`               |
| source-filterable         | Show the source search input                         | `boolean`                                                   |             `false`             |
| target-filterable         | Show the target search input                         | `boolean`                                                   |             `false`             |
| show-search               | Show both search inputs                              | `boolean`                                                   |             `false`             |
| filter                    | Custom filter callback                               | `TransferFilter`                                            | Case-insensitive label matching |
| source-filter-placeholder | Source search placeholder                            | `string`                                                    |               `-`               |
| target-filter-placeholder | Target search placeholder                            | `string`                                                    |               `-`               |
| show-selected             | Keep selected items in the source list               | `boolean`                                                   |             `true`              |
| source-title              | Source list title                                    | `string`                                                    |               `-`               |
| target-title              | Target list title                                    | `string`                                                    |               `-`               |
| show-select-all           | Whether show select all checkbox on the header       | `boolean`                                                   |             `true`              |
| title                     | Source/target list titles                            | `string[]`                                                  |     `['Source', 'Target']`      |
| source-search-props       | Source Search configuration in Cedar                 | `object`                                                    |               `-`               |
| target-search-props       | Target Search configuration in Cedar                 | `object`                                                    |               `-`               |

### `<transfer>` Events

| Event         | Description                             | Arguments                                     |
| ------------- | --------------------------------------- | --------------------------------------------- |
| change        | Emitted when target state changes       | value: `TransferTargetItem[]`                 |
| search        | Emitted on user search                  | value: `string`<br>type: `'target'\|'source'` |
| rename        | Emitted when renaming is confirmed      | value: `TransferValue`, label: `string`       |
| target-action | Emitted when a custom action is clicked | key: `string`, item: `TransferItem`           |

### `<transfer>` Slots

| Slot           |       Description        | Arguments                                                                                                                                                                                             | Version |
| -------------- | :----------------------: | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------ |
| source         |       Source panel       | data: `TransferItem[]`<br>selectedKeys: `string[]`<br>onSelect: `(value: string[]) => void`                                                                                                           | 2.39.0  |
| source-title   |    Source-title slot     | countTotal: `number`<br>countSelected: `number`<br>searchValue: `string`<br>checked: `boolean`<br>indeterminate: `boolean`<br>onSelectAllChange: `(checked:boolean) => void`<br>onClear: `() => void` | 2.45.0  |
| to-target-icon | Move-to-target icon slot | -                                                                                                                                                                                                     | 2.52.0  |
| to-source-icon | Move-to-source icon slot | -                                                                                                                                                                                                     | 2.52.0  |
| target         |       Target panel       | data: `TransferItem[]`<br>selectedKeys: `string[]`<br>onSelect: `(value: string[]) => void`                                                                                                           | 2.39.0  |
| target-title   |    Target-title slot     | countTotal: `number`<br>countSelected: `number`<br>searchValue: `string`<br>checked: `boolean`<br>indeterminate: `boolean`<br>onSelectAllChange: `(checked:boolean) => void`<br>onClear: `() => void` | 2.45.0  |
| item           |         Options          | value: `TransferValue`<br>label: `string`<br>item: `TransferItem`                                                                                                                                     |         |

### TransferItem

| Parameter | Description                                        | Type                           | Default |
| --------- | -------------------------------------------------- | ------------------------------ | :-----: |
| value     | Option value                                       | `string \| number`             |   `-`   |
| label     | Option label                                       | `string`                       |   `-`   |
| disabled  | Whether disabled                                   | `boolean`                      | `false` |
| group     | Source-group title                                 | `string`                       |   `-`   |
| tip       | Option hint                                        | `string \| (() => VNodeChild)` |   `-`   |
| required  | Whether required; required items cannot be removed | `boolean`                      | `false` |

### Type definitions

The component exports the following types

```ts
import type {
  TransferFilter,
  TransferFixed,
  TransferInstance,
  TransferItem,
  TransferTargetAction,
  TransferTargetItem,
  TransferTargetOperation,
  TransferValue,
} from "@cedar-design/ui";
```

### Form field presentation and confirmation

This component supports `edit-mode` with field > FormItem > Form precedence. When unset, it defaults to `direct` and preserves `direct` editing. Supported values: `direct / click / dblclick`. Non-`direct` modes open the editor through the field value trigger and keep one draft; v-model updates only after confirmation. Cancel, reset or enabling readPretty discards the draft.

Cedar uses edit-mode="click" / "dblclick" to open an editor popup near the field. Enter/F2 also opens it; cancel/Escape discards the draft, and confirmation commits it. readPretty is an independent reading setting, separate from readonly and disabled.

`before-commit(value, { previousValue, signal })` can reject an overlay save. FormItem validates the candidate first and keeps the editor open on failure. `open / default-open / update:open` control the editor. Use `#read="{ value, text }"` to customize display. See the full field comparison in Form.

`read-pretty` is an independent boolean alongside `readonly` and `disabled`. It inherits from field to FormItem to Form; explicit `false` overrides the parent. The default is `false`. Reading mode renders no editor.

`data` accepts an array or (query, { signal }) => array/Promise. The component manages loading, cancellation and stale-result isolation; failures emit load-error. Single/multiple groups initialize with an empty query; searchable fields reload when queries change. Tree root loading is independent of existing load-more child loading.

## Reading direction and keyboard interaction

Transfer places candidates at inline-start and selected items at inline-end. Direction changes preserve selected identity/order, filters and frozen state. Native checkboxes and removal buttons support keyboard interaction. Vertical drag ordering and existing left/right freeze values keep their business meaning.

---

Document: llms/en-US/components/tree-select.md

<!-- Source: src/tree-select/README.en-US.md; locale: en-US; page: /en/components/tree-select/ -->

# TreeSelect

A tree-backed selection field with explicit search fields and controlled selection.

## Reading direction

Inherits source dir. Horizontal keys expand, enter children, return or collapse according to reading direction; vertical keys and Home/End keep logical order. Search uses the actual active match. Values and multiple-value arrays are not reversed. Portaled content retains source direction in custom containers.

## Search migration

filterable replaces allowSearch. The old object retainInputValue option is now the independent retain-input-value boolean. filterable enables search; retain-input-value only retains query text after selecting. Default single selection disables search and multiple selection enables it.

Default local matching now searches label and ignores case. Restore the previous matching with search-fields=['value'] and case-sensitive=true. Multiple configured fields use OR matching. Custom filter-tree-node owns its matching rules. disableFilter bypasses built-in filtering.

## Basic examples

### Basic

Example source: src/tree-select/__demos__/basic.vue

```vue
<template>
  <c-space direction="column">
    <c-tree-select v-model="value" :data="data" selectable placeholder="选择部门" />
    <p role="status">当前部门：{{ value || '未选择' }}</p>
  </c-space>
</template>
<script setup lang="ts">
import { ref } from 'vue'
const value = ref<string>()
const data = [
  { value: 'design', label: '设计部' },
  { value: 'engineering', label: '研发部' },
]
</script>
```

### Api Review

## Data and options

### Search Matching

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration        | Purpose                                    | Related examples                                  |
| -------------------- | ------------------------------------------ | ------------------------------------------------- |
| `data`               | Data                                       | Search Matching, Retain the query after selecting |
| `filterable`         | Whether to allow searching                 | Search Matching, Retain the query after selecting |
| `case-sensitive`     | Case-sensitive built-in search             | Search Matching                                   |
| `multiple`           | Whether to support multiple selection      | Retain the query after selecting                  |
| `retain-input-value` | Keep search text after selecting an option | Retain the query after selecting                  |

<!-- demo-config-notes:end -->

Example source: src/tree-select/__demos__/search-matching.vue

```vue
<script setup lang="ts">
import { computed, ref } from "vue";
const value = ref("");
const mode = ref("label");
const caseSensitive = ref(false);
const modes = [
  { value: "label", label: "默认：只匹配 label" },
  { value: "both", label: "配置：value 或 label" },
];
const options = [
  { value: "USER_A", label: "Apple" },
  { value: "USER_B", label: "Banana" },
];
const searchFields = computed<("label" | "value")[]>(() =>
  mode.value === "both" ? ["value", "label"] : ["label"],
);
</script>
<template>
  <c-space direction="column" align="stretch" fill>
    <c-form-item layout="vertical" size="sm" label="匹配字段">
      <c-radio-group
        v-model="mode"
        aria-label="匹配字段"
        :options="modes"
        variant="button"
        size="sm"
      />
    </c-form-item>
    <c-space
      ><c-switch v-model="caseSensitive" /><span>区分大小写</span></c-space
    >
    <c-tree-select
      v-model="value"
      :data="options"
      :case-sensitive="caseSensitive"
      :search-fields="searchFields"
      filterable
      placeholder="输入 Apple、apple 或 USER_A"
    />
    <p>
      默认搜索 label，不区分大小写；配置两字段后，USER_A 和 Apple
      都能找到同一个选项。
    </p>
  </c-space>
</template>
```

### Retain the query after selecting

Type Al, then select Alice: the selected model contains Alice in both examples. Without retain-input-value the search text becomes empty; with it enabled, Al remains so Alan is still easy to select next. This does not control the selected label or whether the field is searchable. filterable enables searching.

Example source: src/tree-select/__demos__/en-US/retain-input-value.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const cleared = ref<string[]>([])
const retained = ref<string[]>([])
const clearQuery = ref('')
const retainedQuery = ref('')
const data = [{ key: 'alice', title: 'Alice' }, { key: 'alan', title: 'Alan' }, { key: 'bob', title: 'Bob' }]
</script>
<template>
  <c-space direction="column">
    <p>Type Al and select Alice. Both fields select Alice; only the remaining query text differs.</p>
    <c-tree-select v-model="cleared" v-model:input-value="clearQuery" :data="data" filterable multiple placeholder="Clear query after selecting" />
    <output>Selected: {{ cleared }}; query: {{ JSON.stringify(clearQuery) }}</output>
    <c-tree-select v-model="retained" v-model:input-value="retainedQuery" :data="data" filterable multiple retain-input-value placeholder="Keep query after selecting" />
    <output>Selected: {{ retained }}; query: {{ JSON.stringify(retainedQuery) }}</output>
  </c-space>
</template>
```

The candidate `data` prop accepts an array or `(query, { signal }) => array/Promise`. Components own loading, cancellation and stale results, and emit load-error on failure. Choice groups initialize with an empty query; searchable fields load when queries change. Root tree loaders remain independent of existing load-more child loading.

## Lifecycle and edge cases

### Passthrough Options

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration         | Purpose                                                                                                                          | Related examples    |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
| `data`                | Data                                                                                                                             | Passthrough Options |
| `tree-props`          | Can accept Props of all [Tree](vue/component/tree) components                                                                   | Passthrough Options |
| `open-trigger-target` | Pointer opening target: the whole field or only the suffix icon. Explicit keyboard opening and controlled open remain available. | Copying and editing |
| `filterable`          | Whether to allow searching                                                                                                       | Copying and editing |

<!-- demo-config-notes:end -->

Example source: src/tree-select/__demos__/passthrough-options.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import type {
  TreeSelectTriggerOptions,
  TreeSelectTreeOptions,
} from "@cedar-design/ui";
const open = ref(false);
const triggerOptions: TreeSelectTriggerOptions = {
  placement: "top-start",
  popupOffset: 8,
};
const data = [
  {
    value: "fruit",
    label: "水果",
    children: [{ value: "apple", label: "Apple" }],
  },
];
const treeOptions: TreeSelectTreeOptions = {
  showLine: true,
  defaultExpandAll: false,
};
</script>
<template>
  <c-space direction="column" fill>
    <c-button @click="open = !open">{{
      open ? "关闭面板" : "打开面板"
    }}</c-button>
    <c-tree-select
      edit-mode="direct"
      v-model:open="open"
      :data="data"
      :tree-props="treeOptions"
      :trigger-props="triggerOptions"
      aria-label="透传配置示例"
    />
    <p role="status">顶层 open：{{ open }}；嵌套配置：向上展开并调整偏移。</p>
  </c-space>
</template>
```

### Copying and editing

With open-trigger-target="icon", use the input area to edit or copy and the suffix button to open. Existing text remains copyable when editing or search is disabled.

Example source: src/tree-select/__demos__/open-trigger-target.en-US.vue

```vue
<template>
  <c-space direction="column">
    <c-radio-group
      v-model="target"
      :options="[
        { label: 'Whole field', value: 'field' },
        { label: 'Suffix icon only', value: 'icon' },
      ]"
    />
    <label><c-switch v-model="editable" /> Allow editing / search</label>
    <c-tree-select
      v-model="value"
      edit-mode="direct"
      :open-trigger-target="target"
      :filterable="editable"
      :options="[
        { value: 'a', label: 'Alpha' },
        { value: 'b', label: 'Beta' },
      ]"
    />
    <p>
      Disable editing to copy existing text. In icon mode, editing does not open
      the panel.
    </p>
  </c-space>
</template>
<script setup lang="ts">
import { ref } from "vue";
const target = ref<"field" | "icon">("icon");
const editable = ref(true);
const value = ref("a");
</script>
```

### TreeSelect Props

| Prop                  | Description                                                                                                                      | Type                                                      | Default                       |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | ----------------------------- |
| `open-trigger-target` | Pointer opening target: the whole field or only the suffix icon. Explicit keyboard opening and controlled open remain available. | `'field' \| 'icon'`                                       | `'field'`                     |
| model-value           | Value                                                                                                                            | string / number / array                                   | undefined                     |
| data                  | Data                                                                                                                             | TreeNodeData[] / `(query, { signal }) => Array / Promise` | `undefined`                   |
| multiple              | Whether to support multiple selection                                                                                            | boolean                                                   | false                         |
| filterable            | Whether to allow searching                                                                                                       | boolean                                                   | Single: false; multiple: true |
| retain-input-value    | Keep search text after selecting an option                                                                                       | boolean                                                   | false                         |
| case-sensitive        | Case-sensitive built-in search                                                                                                   | boolean                                                   | false                         |
| filter-tree-node      | Custom node filter function                                                                                                      | Function                                                  | undefined                     |
| tree-props            | Can accept Props of all [Tree](vue/component/tree) components                                                                   | TreeProps                                                 | undefined                     |

### TreeSelect Events

| Event                                  | Description                              | Arguments     |
| -------------------------------------- | ---------------------------------------- | ------------- |
| update:modelValue                      | Request a selected business value update | value         |
| change                                 | Committed selected value changes         | value         |
| search                                 | Search text changes                      | text: string  |
| update:inputValue / input-value-change | Request input text update                | text: string  |
| update:open / open-change              | Panel visibility changes                 | open: boolean |
| clear                                  | Clear selection                          | None          |

### TreeSelect Slots

| Slot    | Description            |
| ------- | ---------------------- |
| default | Custom default content |

### Shared field loading

`loading` displays the shared field indicator. `loading-mode` is `default` (indicator) or `line` (an indeterminate bottom line); it defaults to `default`. Rendering belongs to FieldDecorator. Loading does not implicitly disable editing or change readonly. Set those states separately.

## API

### Empty values and reading placeholders

`empty-values` recognizes empty data; `empty-value` keeps existing clear output. `empty-text` defaults to `'-'` under `read-pretty`, with Field > FormItem > Form precedence and custom read slots first. With explicit empty-values, built-in required uses the policy; custom validators receive original data. See the [shared guide](llms/en-US/guide/empty-values.md).

| Prop         | Type               | Default and scope                                                           |
| ------------ | ------------------ | --------------------------------------------------------------------------- |
| empty-values | readonly unknown[] | Field > FormItem > Form > component-family default; replaces the whole list |
| empty-text   | string             | Field > FormItem > Form > '-'; explicit '' is valid                         |

These props belong to field presentation; pure panels do not gain reading mode. Form and FormItem provide inherited settings. The existing empty-value type and clear fallback remain component-specific.

### TreeSelect Props

| Prop                  | Description                                                                                                                      | Type                                                      | Default                       |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | ----------------------------- |
| `open-trigger-target` | Pointer opening target: the whole field or only the suffix icon. Explicit keyboard opening and controlled open remain available. | `'field' \| 'icon'`                                       | `'field'`                     |
| model-value           | Value                                                                                                                            | string / number / array                                   | undefined                     |
| data                  | Data                                                                                                                             | TreeNodeData[] / `(query, { signal }) => Array / Promise` | `undefined`                   |
| multiple              | Whether to support multiple selection                                                                                            | boolean                                                   | false                         |
| filterable            | Whether to allow searching                                                                                                       | boolean                                                   | Single: false; multiple: true |
| retain-input-value    | Keep search text after selecting an option                                                                                       | boolean                                                   | false                         |
| case-sensitive        | Case-sensitive built-in search                                                                                                   | boolean                                                   | false                         |
| filter-tree-node      | Custom node filter function                                                                                                      | Function                                                  | undefined                     |
| tree-props            | Can accept Props of all [Tree](vue/component/tree) components                                                                   | TreeProps                                                 | undefined                     |

`disabled`/`readonly` accept explicit field values and Form/FormItem inheritance. Confirmation locks editing. Failed validation preserves drafts; reset closes the popup and discards unfinished commits.

### TreeSelect Events

| Event                                  | Description                              | Arguments     |
| -------------------------------------- | ---------------------------------------- | ------------- |
| update:modelValue                      | Request a selected business value update | value         |
| change                                 | Committed selected value changes         | value         |
| search                                 | Search text changes                      | text: string  |
| update:inputValue / input-value-change | Request input text update                | text: string  |
| update:open / open-change              | Panel visibility changes                 | open: boolean |
| clear                                  | Clear selection                          | None          |

### TreeSelect Slots

| Slot    | Description            |
| ------- | ---------------------- |
| default | Custom default content |

## Type definitions

The component exports the following types

```ts
import type { TreeSelectProps } from "@cedar-design/ui";
```

### Form field presentation and confirmation

Cedar uses edit-mode="click" / "dblclick" to open an editor popup near the field. Enter/F2 also opens it; cancel/Escape discards the draft, and confirmation commits it. readPretty is an independent reading setting, separate from readonly and disabled.

### In-place editing and keyboard precedence

`click`/`dblclick` use Form's editing inheritance. Hover/focus shows an edit icon that opens editing directly. disabled, readonly and readPretty hide edit entries. Panel clicks change only the draft.

While open, arrows navigate visible enabled nodes; Left/Right collapse/expand or move to parents/children; Home/End reach first/last nodes. Enter selects/checks the current node, or toggles an unselectable branch. Search prioritizes matching nodes; multiple selection uses Tree checking rules. Esc first closes the panel, retaining the draft and restoring input focus. With the panel closed, Enter saves and Esc cancels editing. Compare AutoComplete/PeopleSelect in Form's unified field-presentation examples.

Duplicate expansion requests for the same asynchronously loaded node are merged. Replacing nodes, closing editors or resetting Form invalidates old requests so they cannot expand/check nodes. Arrows can enter loaded children immediately. Query/candidate changes clear old filters before Enter can choose stale options. Field confirmation still validates before asynchronous commit.

### Node fields and business values

Nodes default to `{ value, label, children }`. `value` is a tree-wide unique string/number, including `0`; `label` is display content. Map other backend fields with `fieldNames: { value: 'id', label: 'text', children: 'items' }` without changing backend data. Declarative child `name`, Vue `:key` and Table `rowKey` retain separate meanings.

Independent Tree state uses `selectedValues/defaultSelectedValues`, `checkedValues/defaultCheckedValues`, `halfCheckedValues` and `expandedValues/defaultExpandedValues`, updated through corresponding named v-models. `check` event indeterminate sets use `halfCheckedValues`. Node content uses `label`; TreeSelect forwards `tree-slot-label`. `scrollIntoView({ value })` locates business values; explicit `index` remains a zero-based virtual-list array `index`.

### Search configuration

Use `filterable` to enable search: single defaults false, multiple true. `retain-input-value` separately controls whether selection retains the search query, default false.

Migration: `allow-search` becomes `filterable`; `{ retainInputValue: true }` becomes `filterable` plus `retain-input-value`. Old entries are removed without compatibility aliases and require a major release.

### Built-in search fields

`searchFields` / `search-fields` is a readonly `('label' | 'value')[]`, defaulting to `['label']`. Multiple fields use OR matching, case-insensitive by default. `['value', 'label']` searches codes and names; fieldNames maps semantic fields to business fields. An empty array matches no items for a nonempty query. Values are compared as strings; object traversal, object values and pinyin matching require a custom callback. A custom callback takes precedence and decides case handling itself. Remote results use the existing protocol for disabling local filtering. Cascader retains path semantics and checks the configured fields on each path node.

## Configuring the cleared value

`empty-value` / `emptyValue` sets the model value produced by clearing. It accepts a value in the component model type or a zero-argument factory. Omission preserves the existing default; use `() => undefined` to distinguish omission from returning undefined. Arrays are shallow-copied on every clear; selected items that cannot be cleared remain. It does not redefine emptiness, alter Form reset defaults or treat 0/false as universally empty.

---

Document: llms/en-US/components/tree.md

<!-- Source: src/tree/README.en-US.md; locale: en-US; page: /en/components/tree/ -->

# Tree

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

- `data`: Pass in `data` to generate the corresponding tree structure
- `default-expanded-values`: Nodes expanded by default
- `default-selected-values`: Tree node selected by default

Example source: src/tree/__demos__/basic.vue

```vue
<template>
  <c-tree :data="treeData" :default-expanded-values="['0-0-0']" :default-selected-values="['0-0-0', '0-0-1']" />
</template>

<script lang="ts" setup>
const treeData = [
  {
    label: 'Trunk 0-0',
    value: '0-0',
    children: [
      {
        label: 'Branch 0-0-0',
        value: '0-0-0',
        disabled: true,
        children: [
          {
            label: 'Leaf',
            value: '0-0-0-0',
          },
          {
            label: 'Leaf',
            value: '0-0-0-1',
          },
        ],
      },
      {
        label: 'Branch 0-0-1',
        value: '0-0-1',
        children: [
          {
            label: 'Leaf',
            value: '0-0-1-0',
          },
        ],
      },
    ],
  },
]
</script>
```

## Appearance and layout

### Tree density and connecting lines

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `block-node` | Whether the node occupies a row | Tree density and connecting lines |
| `checkable` | Add a checkbox before nodes | Tree density and connecting lines |
| `size` | Size | Tree density and connecting lines |
| `data` | Pass in `data` to generate the corresponding tree structure | Tree density and connecting lines |
| `default-selected-values` | Tree node selected by default | Tree density and connecting lines |
| `show-line` | Whether to display the connection line | Tree density and connecting lines |
<!-- demo-config-notes:end -->


Compare node sizes, full-row blocks and connecting lines separately from selection, dragging and asynchronous nodes.

Example source: src/tree/__demos__/appearance-comparison.vue

```vue
<script setup lang="ts">
import { ref } from "vue"
import { proxyRefs as demoProxyRefs } from 'vue'

const scene1 = demoProxyRefs((() => {


const size = ref('md')

const treeData = [
  {
    label: 'Trunk 0-0',
    value: '0-0',
    children: [
      {
        label: 'Branch 0-0-0',
        value: '0-0-0',
        children: [
          {
            label: 'Leaf',
            value: '0-0-0-0',
          },
          {
            label: 'Leaf',
            value: '0-0-0-1',
          },
        ],
      },
      {
        label: 'Branch 0-0-1',
        value: '0-0-1',
        children: [
          {
            label: 'Leaf',
            value: '0-0-1-0',
          },
        ],
      },
    ],
  },
]
return { size, treeData }
})())

const scene2 = demoProxyRefs((() => {

const treeData = [
  {
    label: 'Trunk 0-0',
    value: '0-0',
    children: [
      {
        label: 'Branch 0-0-0',
        value: '0-0-0',
        children: [
          {
            label: 'Leaf',
            value: '0-0-0-0',
          },
          {
            label: 'Leaf',
            value: '0-0-0-1',
          },
        ],
      },
      {
        label: 'Branch 0-0-1',
        value: '0-0-1',
        children: [
          {
            label: 'Leaf',
            value: '0-0-1-0',
          },
        ],
      },
    ],
  },
]
return { treeData }
})())

const scene3 = demoProxyRefs((() => {


const showLine = ref(true)

const treeData = [
  {
    label: 'Trunk 1',
    value: '0-0',
    children: [
      {
        label: 'Trunk 1-0',
        value: '0-0-0',
        children: [
          { label: 'leaf', value: '0-0-0-0' },
          {
            label: 'leaf',
            value: '0-0-0-1',
            children: [{ label: 'leaf', value: '0-0-0-1-0' }],
          },
          { label: 'leaf', value: '0-0-0-2' },
        ],
      },
      {
        label: 'Trunk 1-1',
        value: '0-0-1',
      },
      {
        label: 'Trunk 1-2',
        value: '0-0-2',
        children: [
          { label: 'leaf', value: '0-0-2-0' },
          {
            label: 'leaf',
            value: '0-0-2-1',
          },
        ],
      },
    ],
  },
  {
    label: 'Trunk 2',
    value: '0-1',
  },
  {
    label: 'Trunk 3',
    value: '0-2',
    children: [
      {
        label: 'Trunk 3-0',
        value: '0-2-0',
        children: [
          { label: 'leaf', value: '0-2-0-0' },
          { label: 'leaf', value: '0-2-0-1' },
        ],
      },
    ],
  },
]
return { showLine, treeData }
})())
</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="size">
    <h4><span lang="zh-CN">不同尺寸</span><span lang="en-US">size</span></h4>
    <div style="margin-bottom: 20px">
        <c-radio-group v-model="scene1.size" type="button">
          <c-radio value="xs">xs</c-radio>
          <c-radio value="sm">sm</c-radio>
          <c-radio value="md">md</c-radio>
          <c-radio value="lg">lg</c-radio>
          <c-radio value="xl">xl</c-radio>
        </c-radio-group>
      </div>
      <c-tree style="margin-right: 20px" :blockNode="true" :checkable="true" :size="scene1.size" :data="scene1.treeData" />
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="block-node">
    <h4><span lang="zh-CN">节点占一行</span><span lang="en-US">block node</span></h4>
    <c-tree block-node :data="scene2.treeData" />
  </section>

  <section class="demo-comparison-case demo-comparison-case--3" data-comparison-scene="show-line">
    <h4><span lang="zh-CN">显示连接线</span><span lang="en-US">show line</span></h4>
    <div>
        <c-typography-text>showLine</c-typography-text>
        <c-switch v-model="scene3.showLine" style="margin-left: 12px" />
      </div>
      <c-tree :default-selected-values="['0-0-1']" :data="scene3.treeData" :show-line="scene3.showLine" />
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

## Node selection and state

### Multiple

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `data` | Pass in `data` to generate the corresponding tree structure | Multiple, Checkable, Control |
| `checkable` | Add a checkbox before nodes | Checkable, Control, Checked Strategy |
| `multiple` | Whether to support multiple selection | Multiple |
| `check-strictly` | Whether to cancel the parent-child node association | Checkable |
| `checked-strategy` | Customized backfill method <br/> all: return all selected nodes <br/> parent: return only parent node when both parent and child nodes are selected <br/> child: return only child nodes | Checked Strategy |
<!-- demo-config-notes:end -->


- `selected-values`: Selected tree node
- `multiple`: Whether to support multiple selection
- `data`: Pass in `data` to generate the corresponding tree structure

Example source: src/tree/__demos__/multiple.vue

```vue
<template>
  <c-checkbox
    style="margin-bottom: 24px"
    v-model="multiple"
    @change="
      () => {
        selectedValues = []
      }
    "
  >
    multiple
  </c-checkbox>
  <br />
  <c-typography-text> Current: {{ selectedValues?.join(' , ') }} </c-typography-text>
  <br />
  <c-tree v-model:selected-values="selectedValues" :multiple="multiple" :data="treeData" />
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const selectedValues = ref([])
const multiple = ref(true)
const treeData = [
  {
    label: 'Trunk 0-0',
    value: '0-0',
    children: [
      {
        label: 'Leaf',
        value: '0-0-1',
      },
      {
        label: 'Branch 0-0-2',
        value: '0-0-2',
        children: [
          {
            label: 'Leaf',
            value: '0-0-2-1',
          },
        ],
      },
    ],
  },
  {
    label: 'Trunk 0-1',
    value: '0-1',
    children: [
      {
        label: 'Branch 0-1-1',
        value: '0-1-1',
        children: [
          {
            label: 'Leaf',
            value: '0-1-1-1',
          },
          {
            label: 'Leaf',
            value: '0-1-1-2',
          },
        ],
      },
      {
        label: 'Leaf',
        value: '0-1-2',
      },
    ],
  },
]
</script>
```

### Checkable

- `checkable`: Whether to add a checkbox before the node, function format is supported since `2.27.0`
- `checked-values`: Tree node with check box selected
- `check-strictly`: Whether to cancel the parent-child node association
- `data`: Pass in `data` to generate the corresponding tree structure

Example source: src/tree/__demos__/checkable.vue

```vue
<template>
  <c-checkbox
    style="margin-bottom: 24px"
    v-model="checkStrictly"
    @change="
      () => {
        checkedValues = []
      }
    "
  >
    checkStrictly
  </c-checkbox>
  <c-tree :checkable="true" v-model:checked-values="checkedValues" :check-strictly="checkStrictly" :data="treeData" />
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const checkedValues = ref([])
const checkStrictly = ref(false)

const treeData = [
  {
    label: 'Trunk 0-0',
    value: '0-0',
    children: [
      {
        label: 'Leaf',
        value: '0-0-1',
      },
      {
        label: 'Branch 0-0-2',
        value: '0-0-2',
        disabled: true,
        children: [
          {
            label: 'Leaf',
            value: '0-0-2-1',
          },
          {
            label: 'Leaf',
            value: '0-0-2-2',
            disableCheckbox: true,
          },
        ],
      },
    ],
  },
  {
    label: 'Trunk 0-1',
    value: '0-1',
    children: [
      {
        label: 'Branch 0-1-1',
        value: '0-1-1',
        children: [
          {
            label: 'Leaf ',
            value: '0-1-1-1',
          },
          {
            label: 'Leaf ',
            value: '0-1-1-2',
          },
        ],
      },
      {
        label: 'Leaf',
        value: '0-1-2',
      },
    ],
  },
]
</script>
```

### Control

- `checkable`: Whether to add a checkbox before the node, function format is supported since `2.27.0`
- `selected-values`: Selected tree node
- `checked-values`: Tree node with check box selected
- `expanded-values`: Expanded node

Example source: src/tree/__demos__/control.vue

```vue
<template>
  <c-button-group style="margin-bottom: 20px">
    <c-button status="primary" @click="toggleChecked">
      {{ checkedValues?.length ? 'deselect all' : 'select all' }}
    </c-button>
    <c-button status="primary" @click="toggleExpanded">
      {{ expandedValues?.length ? 'fold' : 'unfold' }}
    </c-button>
  </c-button-group>
  <c-tree
    :checkable="true"
    v-model:selected-values="selectedValues"
    v-model:checked-values="checkedValues"
    v-model:expanded-values="expandedValues"
    @select="onSelect"
    @check="onCheck"
    @expand="onExpand"
    :data="treeData" />
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const allCheckedValues = ['0-0', '0-0-1', '0-0-2', '0-0-2-1', '0-1', '0-1-1', '0-1-2']
const allExpandedValues = ['0-0', '0-1', '0-0-2']
const selectedValues = ref([])
const checkedValues = ref([])
const expandedValues = ref([])

function toggleChecked() {
  checkedValues.value = checkedValues?.value.length ? [] : allCheckedValues
}

function toggleExpanded() {
  expandedValues.value = expandedValues?.value.length ? [] : allExpandedValues
}

function onSelect(newSelectedValues, event) {
  console.log('select: ', newSelectedValues, event)
}

function onCheck(newCheckedValues, event) {
  console.log('check: ', newCheckedValues, event)
}

function onExpand(newExpandedValues, event) {
  console.log('expand: ', newExpandedValues, event)
}

const treeData = [
  {
    label: 'Trunk 0-0',
    value: '0-0',
    children: [
      {
        label: 'Leaf 0-0-1',
        value: '0-0-1',
      },
      {
        label: 'Branch 0-0-2',
        value: '0-0-2',
        children: [
          {
            label: 'Leaf 0-0-2-1',
            value: '0-0-2-1',
          },
        ],
      },
    ],
  },
  {
    label: 'Trunk 0-1',
    value: '0-1',
    children: [
      {
        label: 'Leaf 0-1-1',
        value: '0-1-1',
      },
      {
        label: 'Leaf 0-1-2',
        value: '0-1-2',
      },
    ],
  },
]
</script>
```

### Checked Strategy

- `checkable`: Whether to add a checkbox before the node, function format is supported since `2.27.0`
- `checked-values`: Tree node with check box selected
- `checked-strategy`: Customized backfill method <br/> all: return all selected nodes <br/> parent: return only parent node when both parent and child nodes are selected <br/> child: return only child nodes
- `data`: Pass in `data` to generate the corresponding tree structure

Example source: src/tree/__demos__/checked-strategy.vue

```vue
<template>
  <c-radio-group
    type="button"
    v-model="checkedStrategy"
    @change="
      (value) => {
        checkedValues = []
      }
    "
  >
    <c-radio v-for="item in strategyOptions" :key="item?.value" :value="item?.value">
      {{ item?.label }}
    </c-radio>
  </c-radio-group>
  <br />
  <c-typography-text style="margin: 24px 0; display: inline-block">
    Current: {{ checkedValues?.join(' , ') }}
  </c-typography-text>
  <br />
  <c-tree :checkable="true" v-model:checked-values="checkedValues" :checked-strategy="checkedStrategy" :data="treeData" />
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const checkedValues = ref([])
const checkedStrategy = ref('all')

const treeData = [
  {
    label: 'Trunk 0-0',
    value: '0-0',
    children: [
      {
        label: 'Leaf',
        value: '0-0-1',
      },
      {
        label: 'Branch 0-0-2',
        value: '0-0-2',
        children: [
          {
            label: 'Leaf',
            value: '0-0-2-1',
          },
        ],
      },
    ],
  },
  {
    label: 'Trunk 0-1',
    value: '0-1',
    children: [
      {
        label: 'Branch 0-1-1',
        value: '0-1-1',
        children: [
          {
            label: 'Leaf',
            value: '0-1-1-1',
          },
          {
            label: 'Leaf',
            value: '0-1-1-2',
          },
        ],
      },
      {
        label: 'Leaf',
        value: '0-1-2',
      },
    ],
  },
]

const strategyOptions = [
  {
    value: 'all',
    label: 'show all',
  },
  {
    value: 'parent',
    label: 'show parent',
  },
  {
    value: 'child',
    label: 'show child',
  },
]
</script>
```

## Node customization

### Node Icon

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `data` | Pass in `data` to generate the corresponding tree structure | Node Icon, Icons, Render Extra |
| `show-line` | Whether to display the connection line | Icons |
| `block-node` | Whether the node occupies a row | Render Extra |
| `checkable` | Add a checkbox before nodes | Render Extra |
| `selectable` | Whether selection is supported | Render Extra |
| `check-strictly` | Whether to cancel the parent-child node association | Render Extra |
<!-- demo-config-notes:end -->


- `data`: Pass in `data` to generate the corresponding tree structure

Example source: src/tree/__demos__/node-icon.vue

```vue
<template>
  <c-tree :data="treeData">
    <template #icon>
      <c-icon-star />
    </template>
  </c-tree>
</template>

<script lang="ts" setup>
import { IconDriveFile } from '@cedar-design/icons-vue'
import { h } from 'vue'

const treeData = [
  {
    label: 'Trunk',
    value: 'node1',
    children: [
      {
        label: 'Leaf',
        value: 'node2',
      },
    ],
  },
  {
    label: 'Trunk',
    value: 'node3',
    children: [
      {
        label: 'Leaf',
        value: 'node4',
        icon: () => h(IconDriveFile),
      },
      {
        label: 'Leaf',
        value: 'node5',
        icon: () => h(IconDriveFile),
      },
    ],
  },
]
</script>
```

### Icons

- `data`: Pass in `data` to generate the corresponding tree structure
- `show-line`: Whether to display the connection line

Example source: src/tree/__demos__/icons.vue

```vue
<template>
  <c-tree :data="treeData" show-line>
    <template #switcher-icon="{ children }">
      <c-icon-down v-if="children?.length" />
      <c-icon-star v-else />
    </template>
  </c-tree>
</template>

<script lang="ts" setup>
import { IconDriveFile } from '@cedar-design/icons-vue'
import { h } from 'vue'

const treeData = [
  {
    label: 'Trunk',
    value: 'node1',
    children: [
      {
        label: 'Leaf',
        value: 'node2',
      },
    ],
  },
  {
    label: 'Trunk',
    value: 'node3',
    children: [
      {
        label: 'Leaf',
        value: 'node4',
        switcherIcon: () => h(IconDriveFile),
      },
      {
        label: 'Leaf',
        value: 'node5',
        switcherIcon: () => h(IconDriveFile),
      },
    ],
  },
]
</script>
```

### Render Extra

- `block-node`: Whether the node occupies a row
- `checkable`: Whether to add a checkbox before the node, function format is supported since `2.27.0`
- `selectable`: Whether to support selection, function format is supported since `2.27.0`
- `check-strictly`: Whether to cancel the parent-child node association

Example source: src/tree/__demos__/render-extra.vue

```vue
<template>
  <div style="width: 500px; padding: 2px; overflow: auto">
    <c-space wrap>
      <c-checkbox v-model="leafChecksOnly">Leaf checkboxes only</c-checkbox>
      <c-checkbox v-model="leafSelectionOnly">Leaf selection only</c-checkbox>
      <c-checkbox v-model="strict">Strict checks</c-checkbox>
      <c-tag>Checked: {{ checkedValues.join(', ') || '-' }}</c-tag>
      <c-tag>Selected: {{ selectedValues.join(', ') || '-' }}</c-tag>
    </c-space>
    <c-tree
      :block-node="true"
      :checkable="leafChecksOnly ? isLeafNode : true"
      :selectable="leafSelectionOnly ? isLeafNode : true"
      :check-strictly="strict"
      :data="treeData"
      @check="keys => checkedValues = keys"
      @select="keys => selectedValues = keys"
    >
      <template #extra="nodeData">
        <c-button
          variant="text"
          size="xs"
          :aria-label="'Add child to ' + nodeData.title + ' (' + nodeData.key + ')'"
          style="position: absolute; right: 8px; top: 2px"
          @click.stop="onIconClick(nodeData)"
        >
          <template #icon><c-icon-plus /></template>
        </c-button>
      </template>
    </c-tree>
  </div>
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const leafChecksOnly = ref(false)
const leafSelectionOnly = ref(false)
const strict = ref(false)
const checkedValues = ref<(string | number)[]>([])
const selectedValues = ref<(string | number)[]>([])
const isLeafNode = (_node: unknown, info: { isLeaf: boolean }) => info.isLeaf

function onIconClick(nodeData) {
  const children = nodeData.children || []
  children.push({
    label: 'new tree node',
    value: nodeData.key + '-' + (children.length + 1),
  })
  nodeData.children = children

  treeData.value = [...treeData.value]
}

const treeData = ref([
  {
    label: 'Trunk',
    value: '0-0',
    children: [
      {
        label: 'Leaf',
        value: '0-0-1',
      },
      {
        label: 'Branch',
        value: '0-0-2',
        children: [
          {
            label: 'Leaf',
            value: '0-0-2-1',
          },
        ],
      },
    ],
  },
  {
    label: 'Trunk',
    value: '0-1',
    children: [
      {
        label: 'Branch',
        value: '0-1-1',
        children: [
          {
            label: 'Leaf',
            value: '0-1-1-1',
          },
          {
            label: 'Leaf',
            value: '0-1-1-2',
          },
        ],
      },
      {
        label: 'Leaf',
        value: '0-1-2',
      },
    ],
  },
])
</script>
```

### Field Names

- `default-selected-values`: Tree node selected by default
- `field-names`: Specify the field name in the node data
- `data`: Pass in `data` to generate the corresponding tree structure

Example source: src/tree/__demos__/field-names.vue

```vue
<template>
  <c-tree
    :default-selected-values="['0-0-2-1-0-0']"
    :fieldNames="{
      value: 'value',
      label: 'label',
      children: 'items',
      icon: 'customIcon',
    }"
    :data="treeData" />
</template>

<script lang="ts" setup>
import { IconDriveFile, IconStar } from '@cedar-design/icons-vue'
import { h } from 'vue'

const treeData = [
  {
    label: 'Trunk 0-0',
    value: '0-0',
    items: [
      {
        label: 'Branch 0-0-2',
        value: '0-0-2',
        selectable: false,
        customIcon: () => h(IconDriveFile),
        items: [
          {
            label: 'Leaf',
            value: '0-0-2-1',
            items: [
              {
                label: 'Leaf 0-0-2',
                value: '0-0-2-1-0',
                items: [
                  {
                    label: 'Leaf',
                    customIcon: () => h(IconStar),
                    value: '0-0-2-1-0-0',
                  },
                ],
              },
            ],
          },
        ],
      },
    ],
  },
  {
    label: 'Trunk 0-1',
    value: '0-1',
    items: [
      {
        label: 'Branch 0-1-1',
        value: '0-1-1',
        items: [
          {
            label: 'Leaf',
            value: '0-1-1-0',
          },
        ],
      },
    ],
  },
]
</script>
```

## Search and drag

### Search

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `data` | Pass in `data` to generate the corresponding tree structure | Search, Draggable |
| `draggable` | Whether it can be dragged | Draggable |
| `block-node` | Whether the node occupies a row | Draggable |
| `checkable` | Add a checkbox before nodes | Draggable |
<!-- demo-config-notes:end -->


- `data`: Pass in `data` to generate the corresponding tree structure

Example source: src/tree/__demos__/search.vue

```vue
<template>
  <div>
    <c-search style="margin-bottom: 8px; max-width: 240px" v-model="searchKey" />
    <c-tree :data="treeData">
      <template #label="nodeData">
        <template v-if="(index = getMatchIndex(nodeData?.title)) < 0">
          {{ nodeData?.title }}
        </template>
        <span v-else>
          {{ nodeData?.label?.substr(0, index) }}
          <span style="color: var(--color-primary-light-4)">
            {{ nodeData?.label?.substr(index, searchKey.length) }} </span
          >{{ nodeData?.label?.substr(index + searchKey.length) }}
        </span>
      </template>
    </c-tree>
  </div>
</template>

<script lang="ts" setup>
import { computed, ref } from 'vue'

let index

const originTreeData = [
  {
    label: 'Trunk 0-0',
    value: '0-0',
    children: [
      {
        label: 'Branch 0-0-1',
        value: '0-0-1',
        children: [
          {
            label: 'Leaf 0-0-1-1',
            value: '0-0-1-1',
          },
          {
            label: 'Leaf 0-0-1-2',
            value: '0-0-1-2',
          },
        ],
      },
    ],
  },
  {
    label: 'Trunk 0-1',
    value: '0-1',
    children: [
      {
        label: 'Branch 0-1-1',
        value: '0-1-1',
        children: [
          {
            label: 'Leaf 0-1-1-0',
            value: '0-1-1-0',
          },
        ],
      },
      {
        label: 'Branch 0-1-2',
        value: '0-1-2',
        children: [
          {
            label: 'Leaf 0-1-2-0',
            value: '0-1-2-0',
          },
        ],
      },
    ],
  },
]
const searchKey = ref('')
const treeData = computed(() => {
  if (!searchKey.value) return originTreeData
  return searchData(searchKey.value)
})

function searchData(keyword) {
  const loop = (data) => {
    const result = []
    data.forEach((item) => {
      if (item.title.toLowerCase().indexOf(keyword.toLowerCase()) > -1) {
        result.push({ ...item })
      } else if (item.children) {
        const filterData = loop(item.children)
        if (filterData.length) {
          result.push({
            ...item,
            children: filterData,
          })
        }
      }
    })
    return result
  }

  return loop(originTreeData)
}

function getMatchIndex(title) {
  if (!searchKey.value) return -1
  return title.toLowerCase().indexOf(searchKey.value.toLowerCase())
}
</script>
```

### Draggable

- `draggable`: Whether it can be dragged
- `block-node`: Whether the node occupies a row
- `checkable`: Whether to add a checkbox before the node, function format is supported since `2.27.0`
- `data`: Pass in `data` to generate the corresponding tree structure

Example source: src/tree/__demos__/draggable.vue

```vue
<template>
  <c-checkbox v-model="checked" style="margin-bottom: 20px"> checkable </c-checkbox>
  <c-tree class="tree-demo" draggable blockNode :checkable="checked" :data="treeData" @drop="onDrop" />
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const defaultTreeData = [
  {
    label: 'Trunk 0-0',
    value: '0-0',
    children: [
      {
        label: 'Leaf 0-0-1',
        value: '0-0-1',
      },
      {
        label: 'Branch 0-0-2',
        value: '0-0-2',
        disableCheckbox: true,
        children: [
          {
            draggable: false,
            label: 'Leaf 0-0-2-1 (Drag disabled)',
            value: '0-0-2-1',
          },
        ],
      },
    ],
  },
  {
    label: 'Trunk 0-1',
    value: '0-1',
    children: [
      {
        label: 'Branch 0-1-1',
        value: '0-1-1',
        checkable: false,
        children: [
          {
            label: 'Leaf 0-1-1-1',
            value: '0-1-1-1',
          },
          {
            label: 'Leaf 0-1-1-2',
            value: '0-1-1-2',
          },
        ],
      },
      {
        label: 'Leaf 0-1-2',
        value: '0-1-2',
      },
    ],
  },
]

const treeData = ref(defaultTreeData)
const checkedValues = ref([])
const checked = ref(false)

function onDrop({ dragNode, dropNode, dropPosition }) {
  const data = treeData.value
  const loop = (data, key, callback) => {
    data.some((item, index, arr) => {
      if (item.key === key) {
        callback(item, index, arr)
        return true
      }
      if (item.children) {
        return loop(item.children, key, callback)
      }
      return false
    })
  }

  loop(data, dragNode.key, (_, index, arr) => {
    arr.splice(index, 1)
  })

  if (dropPosition === 0) {
    loop(data, dropNode.key, (item) => {
      item.children = item.children || []
      item.children.push(dragNode)
    })
  } else {
    loop(data, dropNode.key, (_, index, arr) => {
      arr.splice(dropPosition < 0 ? index : index + 1, 0, dragNode)
    })
  }
}
</script>
```

## Async data and virtualization

### Load More

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `data` | Pass in `data` to generate the corresponding tree structure | Load More, Virtual |
| `load-more` | A callback for loading data asynchronously, returning a `Promise` | Load More |
| `block-node` | Whether the node occupies a row | Virtual |
| `checkable` | Add a checkbox before nodes | Virtual |
| `virtual-list-props` | Pass virtual list properties, pass in this parameter to turn on virtual scrolling, [VirtualListProps](#VirtualListProps) | Virtual |
<!-- demo-config-notes:end -->


- `data`: Pass in `data` to generate the corresponding tree structure
- `load-more`: A callback for loading data asynchronously, returning a `Promise`

Example source: src/tree/__demos__/load-more.vue

```vue
<template>
  <c-tree :data="treeData" :load-more="loadMore" />
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const treeData = ref([
  {
    label: 'Trunk 0-0',
    value: '0-0',
  },
  {
    label: 'Trunk 0-1',
    value: '0-1',
    children: [
      {
        label: 'Branch 0-1-1',
        value: '0-1-1',
      },
    ],
  },
])

const loadMore = (nodeData) => {
  return new Promise((resolve) => {
    setTimeout(() => {
      nodeData.children = [{ label: `leaf`, value: `${nodeData.key}-1`, isLeaf: true }]
      resolve()
    }, 1000)
  })
}
</script>
```

### Virtual

- `block-node`: Whether the node occupies a row
- `checkable`: Whether to add a checkbox before the node, function format is supported since `2.27.0`
- `data`: Pass in `data` to generate the corresponding tree structure
- `virtual-list-props`: Pass virtual list properties, pass in this parameter to turn on virtual scrolling, [VirtualListProps](#VirtualListProps)

Example source: src/tree/__demos__/virtual.vue

```vue
<template>
  <c-button status="primary" :style="{ marginBottom: '20px' }" @click="scrollIntoView">
    Scroll to 0-0-2-2, i.e. the 26th.
  </c-button>
  <c-tree
    ref="treeRef"
    blockNode
    checkable
    :data="treeData"
    :virtualListProps="{
      height: 200,
    }" />
</template>

<script lang="ts" setup>
import { ref } from 'vue'

function loop(path = '0', level = 2) {
  const list = []
  for (let i = 0; i < 10; i += 1) {
    const key = `${path}-${i}`
    const treeNode: {
      label: string
      value: string
      children?: ReturnType<typeof loop>
    } = {
      label: key,
      key,
    }

    if (level > 0) {
      treeNode.children = loop(key, level - 1)
    }

    list.push(treeNode)
  }
  return list
}

const treeRef = ref()
const treeData = loop()
const scrollIntoView = () => {
  treeRef.value && treeRef.value.scrollIntoView({ value: '0-0-2-2' })
}
</script>
```

## API

### `<tree>` Props

| Parameter | Description | Type | Default |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | :-----: |
| size | Size | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` |
| block-node | Whether the node occupies a row | `boolean` | `false` |
| default-expand-all | Whether to expand the parent node by default | `boolean` | `true` |
| multiple | Whether to support multiple selection | `boolean` | `false` |
| checkable | Add a checkbox before nodes | `boolean\| ((    node: TreeNodeData,    info: {      level: number;      isLeaf: boolean;    }  ) => boolean)` | `false` |
| selectable | Whether selection is supported | `boolean\| ((    node: TreeNodeData,    info: {      level: number;      isLeaf: boolean;    }  ) => boolean)` | `true` |
| check-strictly | Whether to cancel the parent-child node association | `boolean` | `false` |
| checked-strategy | Customized backfill method <br/> all: return all selected nodes <br/> parent: return only parent node when both parent and child nodes are selected <br/> child: return only child nodes | `'all' \| 'parent' \| 'child'` | `'all'` |
| default-selected-values | Tree node selected by default | `Array<string \| number>` | `-` |
| selected-values **(v-model)** | Selected tree node | `Array<string \| number>` | `-` |
| default-checked-values | Tree node with checkbox selected by default | `Array<string \| number>` | `-` |
| checked-values **(v-model)** | Tree node with check box selected | `Array<string \| number>` | `-` |
| default-expanded-values | Nodes expanded by default | `Array<string \| number>` | `-` |
| expanded-values **(v-model)** | Expanded node | `Array<string \| number>` | `-` |
| data | Pass in `data` to generate the corresponding tree structure | `TreeNodeData[]` | `[]` |
| field-names | Specify the field name in the node data | `TreeFieldNames` | `-` |
| show-line | Whether to display the connection line | `boolean` | `false` |
| load-more | A callback for loading data asynchronously, returning a `Promise` | `(node: TreeNodeData) => Promise<void>` | `-` |
| draggable | Whether it can be dragged | `boolean` | `false` |
| allow-drop | Whether to allow release on a node when dragging | `(options: {  dropNode: TreeNodeData;  dropPosition: -1 \| 0 \| 1;}) => boolean` | `-` |
| virtual-list-props | Pass virtual list properties, pass in this parameter to turn on virtual scrolling, [VirtualListProps](#VirtualListProps) | `VirtualListProps` | `-` |
| default-expand-selected | Whether to expand the parent node of the selected node by default | `boolean` | `false` |
| default-expand-checked | Whether to expand the parent node of the checked node by default | `boolean` | `false` |
| auto-expand-parent | Whether to automatically expand the parent node of the expanded node | `boolean` | `true` |
| half-checked-values **(v-model)** | The keys of half checked. Only valid when checkable and checkStrictly | `Array<string \| number>` | `-` |
| only-check-leaf | When enabled, checkedValues is only for checked leaf nodes, and the status of the parent node is determined by the child node.(Only valid when checkable and checkStrictly is false) | `boolean` | `false` |
| animation | Whether to enable expand transition animation | `boolean` | `true` |
| action-on-node-click | The action triggered when the node is clicked | `'expand'` | `-` |

### `<tree>` Events

| Event | Description | Arguments |
| ---------- | -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| select | Emitted when a tree node is clicked | selectedValues: `Array<string \| number>`<br>data: `{ selected?: boolean; selectedNodes: TreeNodeData[]; node?: TreeNodeData; e?: Event; }` |
| check | Emitted when a node checkbox is clicked. `halfCheckedValues`/`halfCheckedNodes` are supported since `2.19.0` | checkedValues: `Array<string \| number>`<br>data: `{ checked?: boolean; checkedNodes: TreeNodeData[]; node?: TreeNodeData; e?: Event; halfCheckedValues: (string \| number)[]; halfCheckedNodes: TreeNodeData[]; }` |
| expand | Expand/collapse | expandKeys: `Array<string \| number>`<br>data: `{ expanded?: boolean; expandNodes: TreeNodeData[]; node?: TreeNodeData; e?: Event; }` |
| drag-start | Node drag starts | ev: `DragEvent`<br>node: `TreeNodeData` |
| drag-end | Node drag ends | ev: `DragEvent`<br>node: `TreeNodeData` |
| drag-over | Node enters a drop target | ev: `DragEvent`<br>node: `TreeNodeData` |
| drag-leave | Node leaves a drop target | ev: `DragEvent`<br>node: `TreeNodeData` |
| drop | Node is dropped on a target | data: `{ e: DragEvent; dragNode: TreeNodeData; dropNode: TreeNodeData; dropPosition: number; }` |

### `<tree>` Methods

| Method | Description | Arguments | Returns |
| ------------------- | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- | -------------- |
| scrollIntoView | Scroll a virtual-list item into view | options: `{ index?: number; value?: number \| string; align: 'auto' \| 'top' \| 'bottom'}` | - |
| getSelectedNodes | Get selected nodes | - | TreeNodeData[] |
| getCheckedNodes | Get checked nodes; accepts `checkedStrategy`, otherwise uses the component setting | options: `checkedStrategy?: 'all' \| 'parent' \| 'child'; includeHalfChecked?: boolean;` | TreeNodeData[] |
| getHalfCheckedNodes | Get indeterminate nodes | - | TreeNodeData[] |
| getExpandedNodes | Get expanded nodes | - | TreeNodeData[] |
| checkAll | Set all nodes’ checkbox state | checked: `boolean` | - |
| checkNode | Set specified nodes’ checkbox state | value: `TreeNodeValue \| TreeNodeValue[]`<br>checked: `boolean`<br>onlyCheckLeaf: `boolean` | - |
| selectAll | Set all nodes’ selection state | selected: `boolean` | - |
| selectNode | Set specified nodes’ selection state | value: `TreeNodeValue \| TreeNodeValue[]`<br>selected: `boolean` | - |
| expandAll | Set all nodes’ expansion state | expanded: `boolean` | - |
| expandNode | Set specified nodes’ expansion state | value: `TreeNodeValue \| TreeNodeValue[]`<br>expanded: `boolean` | - |

### `<tree>` Slots

| Slot | Description | Arguments |
| ------------- | :----------------: | -------------------- |
| label | Node content | node: `TreeNodeData` |
| extra | Render additional node content | - |
| drag-icon | Custom drag icon | node: `TreeNodeData` |
| loading-icon | Custom loading icon | TreeNodeData |
| switcher-icon | Custom switcher icon | TreeNodeData |
| icon | Custom node icon | node: `TreeNodeData` |

### TreeNodeData

| Parameter | Description | Type | Default |
| --------------- | ----------------------------------- | ------------------ | :-----: |
| value | Unique identifier | `string \| number` | `-` |
| label | Displayed node title | `string` | `-` |
| selectable | Whether selection is allowed | `boolean` | `false` |
| disabled | Whether the node is disabled | `boolean` | `false` |
| disableCheckbox | Whether the checkbox is disabled | `boolean` | `false` |
| checkable | Whether to show a checkbox | `boolean` | `false` |
| draggable | Whether it can be dragged | `boolean` | `false` |
| isLeaf | Whether this is a leaf; effective during dynamic loading | `boolean` | `false` |
| icon | Node icon | `() => VNode` | `-` |
| switcherIcon | Custom switcher icon; overrides Tree | `() => VNode` | `-` |
| loadingIcon | Custom loading icon; overrides Tree | `() => VNode` | `-` |
| dragIcon | Custom drag icon; overrides Tree | `() => VNode` | `-` |
| children | Children | `TreeNodeData[]` | `-` |

### TreeFieldNames

| Parameter | Description | Type | Default |
| --------------- | ----------------------------------------------- | -------- | :---------------: |
| value | TreeNodeData field mapped to value | `string` | `value` |
| label | TreeNodeData field mapped to label | `string` | `label` |
| disabled | TreeNodeData field mapped to disabled | `string` | `disabled` |
| children | TreeNodeData field mapped to children | `string` | `children` |
| isLeaf | TreeNodeData field mapped to isLeaf | `string` | `isLeaf` |
| disableCheckbox | TreeNodeData field mapped to disableCheckbox | `string` | `disableCheckbox` |
| checkable | TreeNodeData field mapped to checkable | `string` | `checkable` |
| icon | TreeNodeData field mapped to icon | `string` | `checkable` |

### VirtualListProps

| Parameter | Description | Type | Default |
| ------------------ | ------------------------------------------------------------------ | ------------------ | :-----: |
| height | Viewport height | `number \| string` | `-` |
| threshold | Item-count threshold for virtual scrolling; counts below it do not enable virtualization | `number` | `-` |
| isStaticItemHeight | Removed fixed-height flag; use `fixedSize` | `boolean` | `false` |
| fixedSize | Whether item heights are fixed | `boolean` | `false` |
| estimatedSize | Estimated item height when heights vary | `number` | `-` |
| buffer | Number of items premounted beyond viewport boundaries | `number` | `10` |

### Type definitions

The component exports the following types

```ts
import type { TreeInstance } from '@cedar-design/ui'
```

### Five densities and icons

xs/sm/md/lg/xl consume their icon-size, font-size, line-height and title-padding-vertical. Icon sizes also determine expansion-button/indent geometry; show-line follows the matching line height.

| Variable | Default |
| --- | --- |
| `--c-tree-size-xl-icon-size` | `var(--c-size-4)` |
| `--c-tree-size-xl-font-size` | `var(--c-sys-font-size-lg)` |
| `--c-tree-size-xl-line-height` | `var(--c-size-xl)` |
| `--c-tree-size-xl-title-padding-vertical` | `12px` |

### Node fields and business values

Nodes default to `{ value, label, children }`. `value` is a tree-wide unique string/number, including `0`; `label` is display content. Map other backend fields with `fieldNames: { value: 'id', label: 'text', children: 'items' }` without changing backend data. Declarative child `name`, Vue `:key` and Table `rowKey` retain separate meanings.

Independent Tree state uses `selectedValues/defaultSelectedValues`, `checkedValues/defaultCheckedValues`, `halfCheckedValues` and `expandedValues/defaultExpandedValues`, updated through corresponding named v-models. `check` event indeterminate sets use `halfCheckedValues`. Node content uses `label`; TreeSelect forwards `tree-slot-label`. `scrollIntoView({ value })` locates business values; explicit `index` remains a zero-based virtual-list array `index`.


| Focus outline token | Default |
| --- | --- |
| `--c-tree-focus-outline-width` | `2px` |

## Reading direction and keyboard interaction

Tree mirrors indentation, connectors, disclosure icons and horizontal branch keys. Up/down and Home/End navigate enabled visible nodes independently of selection. Enter selects; Space checks a checkable node or selects it. The tree keeps DOM focus through virtual scrolling using aria-activedescendant. Vertical drop semantics remain unchanged. Embedded TreeSelect retains its own focus owner.

---

Document: llms/en-US/components/trigger.md

<!-- Source: src/trigger/README.en-US.md; locale: en-US; page: /en/components/trigger/ -->

# Trigger

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

Preview configuration: `trigger="click"`, `:popup-offset="10"`, `show-arrow`.

Example source: src/trigger/__demos__/basic.vue

```vue
<template>
  <div class="trigger-demo">
    <c-trigger trigger="click" :popup-offset="10" show-arrow>
      <c-button>点击打开</c-button>
      <template #content>
        <div class="trigger-demo__panel">Trigger 只负责浮层行为，面板外观由使用者决定。</div>
      </template>
    </c-trigger>
  </div>
</template>

<style scoped>
.trigger-demo {
  display: flex;
  justify-content: center;
  padding: calc(var(--c-sys-space-8) * 2) var(--c-sys-space-6);
}

.trigger-demo__panel {
  max-width: 260px;
  padding: var(--c-sys-space-5) var(--c-sys-space-6);
  color: var(--c-sys-color-content-primary);
  background: var(--c-sys-color-surface-overlay);
  border: 1px solid var(--c-sys-color-border-default);
  border-radius: var(--c-sys-radius-md);
}
</style>
```

## Layout and arrangement

### Placement

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `trigger` | Trigger modes; may be combined | Placement |
| `placement` | Preferred popup side relative to the trigger, default bottom. With the default auto-fit-position enabled, Trigger may flip and constrain it to the viewport when space is limited; this is not a fixed final position | Placement |
| `popup-offset` | Outward distance along placement's main axis | Placement |
| `show-arrow` | Render a decorative arrow | Placement |
<!-- demo-config-notes:end -->


- `placement`: Chooses the position relative to the trigger.

Example source: src/trigger/__demos__/placement.vue

```vue
<script setup lang="ts">
const placements = ['top', 'right', 'bottom', 'left'] as const
</script>

<template>
  <div class="trigger-placement-demo">
    <c-trigger v-for="placement in placements" :key="placement" trigger="click" :placement="placement" :popup-offset="10" show-arrow>
      <c-button variant="outline">{{ placement }}</c-button>
      <template #content><div class="trigger-placement-demo__panel">{{ placement }}</div></template>
    </c-trigger>
  </div>
</template>

<style scoped>
.trigger-placement-demo {
  display: grid;
  grid-template-columns: repeat(2, minmax(100px, 1fr));
  gap: calc(var(--c-sys-space-8) * 2);
  padding: calc(var(--c-sys-space-8) * 3);
}

.trigger-placement-demo__panel {
  padding: var(--c-sys-space-4) var(--c-sys-space-5);
  color: var(--c-sys-color-content-primary);
  background: var(--c-sys-color-surface-overlay);
  border: 1px solid var(--c-sys-color-border-default);
  border-radius: var(--c-sys-radius-sm);
}
</style>
```

## Interaction and control

### Controlled

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `open` | Controlled open state | Controlled |
| `trigger` | Trigger modes; may be combined | Controlled |
| `placement` | Preferred popup side relative to the trigger, default bottom. With the default auto-fit-position enabled, Trigger may flip and constrain it to the viewport when space is limited; this is not a fixed final position | Controlled |
| `popup-offset` | Outward distance along placement's main axis | Controlled |
| `popup-translate` | Screen-axis offset, or per-placement offsets | Controlled |
<!-- demo-config-notes:end -->


- `placement`: Chooses the position relative to the trigger.

Example source: src/trigger/__demos__/controlled.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'

const open = ref(false)
</script>

<template>
  <div class="trigger-controlled-demo">
    <c-space>
      <c-button @click="open = true">外部打开</c-button>
      <c-button variant="outline" @click="open = false">外部关闭</c-button>
    </c-space>
    <c-trigger v-model:open="open" trigger="click" placement="bottom-start" :popup-offset="10" :popup-translate="[16, 0]">
      <c-button variant="text">受控触发元素</c-button>
      <template #content><div class="trigger-controlled-demo__panel">open = {{ open }}</div></template>
    </c-trigger>
  </div>
</template>

<style scoped>
.trigger-controlled-demo {
  display: flex;
  flex-wrap: wrap;
  align-items: center;
  gap: var(--c-sys-space-8);
  padding: calc(var(--c-sys-space-8) * 2) var(--c-sys-space-6);
}

.trigger-controlled-demo__panel {
  padding: var(--c-sys-space-5) var(--c-sys-space-6);
  color: var(--c-sys-color-content-primary);
  background: var(--c-sys-color-surface-overlay);
  border: 1px solid var(--c-sys-color-border-default);
  border-radius: var(--c-sys-radius-sm);
}
</style>
```

## API

### `<Trigger>` Props

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| dir | Reading direction; inherits the source scope when omitted. Physical left/right placements keep their meaning. | `ReadingDirection` (`ltr` / `rtl`) | — |
| open | Controlled open state | `boolean` | `-` |
| default-open | Initial uncontrolled state | `boolean` | `false` |
| trigger | Trigger modes; may be combined | `hover \| click \| focus \| contextMenu \| manual \| TriggerEvent[]` | `hover` |
| disabled | Prevent opening | `boolean` | `false` |
| reference | External reference element; defaults to the first actual element in the default slot | `string \| HTMLElement \| SVGElement` | `-` |
| placement | Preferred popup side relative to the trigger, default bottom. With the default auto-fit-position enabled, Trigger may flip and constrain it to the viewport when space is limited; this is not a fixed final position | `TriggerPlacement` | `bottom` |
| strategy | Positioning strategy | `absolute \| fixed` | `absolute` |
| cover | Cover the reference on the main axis | `boolean` | `false` |
| popup-offset | Outward distance along placement's main axis | `number` | `0` |
| popup-translate | Screen-axis offset, or per-placement offsets | `[number, number] \| Partial<Record<TriggerPlacement, [number, number]>>` | `-` |
| align-point | Use pointer coordinates as a virtual reference | `boolean` | `false` |
| popup-container | Mount container; `false` renders in place | `string \| HTMLElement \| false` | `body` |
| auto-fit-position | Flip and constrain to the viewport when space is insufficient | `boolean` | `true` |
| auto-fit-popup-width | Match popup width to the reference | `boolean` | `false` |
| auto-fit-popup-min-width | Match minimum popup width to the reference | `boolean` | `false` |
| auto-fix-position | Reposition automatically on size changes | `boolean` | `true` |
| update-at-scroll | Reposition while scrolling | `boolean` | `false` |
| scroll-to-close | Close when scrolling exceeds the threshold | `boolean` | `false` |
| scroll-to-close-distance | Close threshold | `number` | `0` |
| show-arrow | Render a decorative arrow | `boolean` | `false` |
| hide-empty | Do not render when content is empty | `boolean` | `false` |
| prevent-focus | Prevent popup mousedown from taking focus | `boolean` | `false` |
| unmount-on-close | Unmount content after the leave transition | `boolean` | `true` |
| animation-name | Vue Transition name | `string` | `trigger-fade` |
| duration | Transition duration | `number \| { enter: number; leave: number }` | `-` |
| auto-fit-transform-origin | Derive transform origin from final placement | `boolean` | `false` |
| opened-class | Class added to the first reference node while open | `ClassName` | `-` |
| popup-class / popup-style | Positioning-layer class/style | `ClassName / CSSProperties` | `-` |
| content-class / content-style | Content-layer class/style | `ClassName / CSSProperties` | `-` |
| arrow-class / arrow-style | Arrow class/style | `ClassName / CSSProperties` | `-` |
| mouse-enter-delay / mouse-leave-delay | Hover open/close delay in ms | `number` | `100 / 100` |
| focus-delay | Focus-open delay in ms | `number` | `0` |
| popup-hover-stay | Keep open when the pointer enters the popup | `boolean` | `true` |
| blur-to-close | Close on blur | `boolean` | `true` |
| close-on-click-reference | Close on another reference click | `boolean` | `true` |
| click-outside-to-close | Close on outside click | `boolean` | `true` |
| esc-to-close | Close on Escape | `boolean` | `true` |
| restore-focus | Restore reference focus after closing is accepted | `boolean` | `true` |

### Events

| Event | Description | Arguments |
| --- | --- | --- |
| update:open | Controlled update request from user interaction | `open: boolean` |
| open-change | User-interaction request notification | `open: boolean` |
| open / close | Actual enter/leave begins | `-` |
| opened / closed | Enter/leave transition completes | `-` |
| click-outside | The topmost popup receives an outside click | `event: Event` |
| resize | Reference size changes | `-` |

### Slots

| Slot | Description |
| --- | --- |
| default | Reference node |
| content | Popup content |

### Expose

`open()`、`close()`、`resize()`、`allowClose()`、`getReference()`、`setReference(reference?)`、`focusReference()`、`isTopLayer(event?)`。

## Keyboard and accessibility

`trigger="focus"` supports keyboard focus. `esc-to-close` lets only the topmost popup handle Escape. Trigger does not assign `role`, `aria-describedby` or business labels; semantic wrappers such as Tooltip, Popover and Menu must supply them.

## Public CSS variables

These are actual :root defaults. Prefer component variables for business customization; internal positioning variables are not public API.

| Variable | Default | Meaning and use case |
| --- | --- | --- |
| `--c-trigger-arrow-background` | `var(--c-sys-color-surface-overlay)` | Standalone Trigger arrow background; wrappers use their own variables |
| `--c-trigger-arrow-size` | `var(--c-sys-space-4)` | Arrow square size |
| `--c-trigger-arrow-radius` | `var(--c-sys-radius-sm)` | Arrow border radius |
| `--c-trigger-transition-duration` | `var(--c-sys-motion-duration-fast)` | Default Trigger fade duration |
| `--c-trigger-transition-easing` | `var(--c-sys-motion-easing-standard)` | Default Trigger easing |

Tooltip/Popover define arrow appearance themselves. Override their component variables rather than Trigger arrow-background.

With Teleport, variables must be in the actual popup scope, for example through `popup-style`. Trigger-button variables do not automatically inherit into popups.

### Reduced motion

Built-in CSS transitions follow `prefers-reduced-motion: reduce`. Removing transitions does not change final visibility, selected/expanded state or event semantics. Applications control custom animations inside slots.


### Placement semantics and configuration

placement is a preferred side; final placement may change while auto-fit-position is true (the default). It is not a position coordinate. top-start is anchor-side alignment, whereas top-left denotes a container corner. Current Trigger start/end follows physical cross-axis geometry; automatic RTL mirroring is not promised.

## Native event modifiers on the reference

Native click, mouseenter, mouseleave, focusin, focusout and contextmenu listeners, including .once, .capture and .passive, belong to the actual reference element rather than the popup. Updating a consumed once callback does not rearm it; replacing the reference or removing and readding the listener starts a new native lifetime. Suspension and unmount detach listeners. Listener promises do not control opening or loading; errors follow Vue event error handling.

---

Document: llms/en-US/components/typography.md

<!-- Source: src/typography/README.en-US.md; locale: en-US; page: /en/components/typography/ -->

# Typography

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

Preview configuration: `bold`, `:heading="2"`, `mark`, `underline`.

Example source: src/typography/__demos__/basic.vue

```vue
<template>
  <c-typography>
    <c-typography-title>Design system</c-typography-title>
    <c-typography-paragraph>
      A design is a plan or specification for the construction of an object or system or for the
      implementation of an activity or process, or the result of that plan or specification in the
      form of a prototype, product or process. The verb to design expresses the process of developing
      a design.
    </c-typography-paragraph>
    <c-typography-paragraph>
      In some cases, the direct construction of an object without an explicit prior plan (such as in
      craftwork, some engineering, coding, and graphic design) may also be considered
      <c-typography-text bold>to be a design activity.</c-typography-text>
    </c-typography-paragraph>
    <c-typography-title :heading="2">Cedar Design</c-typography-title>
    <c-typography-paragraph>
      The component library defines a set of default particle variables, and a custom theme is to
      <c-typography-text mark>customize</c-typography-text> and
      <c-typography-text underline>overwrite</c-typography-text> this variable list.
    </c-typography-paragraph>
    <c-typography-paragraph blockquote>
      A design is a plan or specification for the construction of an object or system or for the
      implementation of an activity or process, or the result of that plan or specification in the
      form of a
      <c-typography-text code>prototype</c-typography-text>,
      <c-typography-text code>product</c-typography-text> or
      <c-typography-text code>process</c-typography-text>. The verb to design expresses the process of
      developing a design.
    </c-typography-paragraph>
    <c-typography-paragraph mark underline delete>
      A design is a plan or specification for the construction of an object or system or for the
      implementation of an activity or process.
    </c-typography-paragraph>
    <c-typography-paragraph>
      <ul>
        <li>
          Architectural blueprints
          <ul>
            <li>Architectural blueprints</li>
          </ul>
        </li>
        <li>Engineering drawings</li>
        <li>Business processes</li>
      </ul>
    </c-typography-paragraph>
    <c-typography-paragraph>
      <ol>
        <li>Architectural blueprints</li>
        <li>Engineering drawings</li>
        <li>Business processes</li>
      </ol>
    </c-typography-paragraph>
  </c-typography>
</template>
```

## Content and presentation

### Title

Preview configuration: `:heading="2"`, `:heading="3"`, `:heading="4"`, `:heading="5"`.

Example source: src/typography/__demos__/title.vue

```vue
<template>
  <c-typography>
    <c-typography-title>H1. The Pragmatic Romanticism</c-typography-title>
    <c-typography-title :heading="2">H2. The Pragmatic Romanticism</c-typography-title>
    <c-typography-title :heading="3">H3. The Pragmatic Romanticism</c-typography-title>
    <c-typography-title :heading="4">H4. The Pragmatic Romanticism</c-typography-title>
    <c-typography-title :heading="5">H5. The Pragmatic Romanticism</c-typography-title>
    <c-typography-title :heading="6">H6. The Pragmatic Romanticism</c-typography-title>
  </c-typography>
</template>
```

### Text

Preview configuration: `status="secondary"`, `status="primary"`, `status="success"`, `status="warning"`.

Example source: src/typography/__demos__/text.vue

```vue
<template>
  <c-space direction="column" :size="10">
    <c-typography-text>Cedar Design</c-typography-text>
    <c-typography-text status="secondary">Secondary</c-typography-text>
    <c-typography-text status="primary">Primary</c-typography-text>
    <c-typography-text status="success">Success</c-typography-text>
    <c-typography-text status="warning">Warning</c-typography-text>
    <c-typography-text status="danger">Danger</c-typography-text>
    <c-typography-text bold>Bold</c-typography-text>
    <c-typography-text disabled>Disabled</c-typography-text>
    <c-typography-text mark>Mark</c-typography-text>
    <c-typography-text underline>Underline</c-typography-text>
    <c-typography-text delete>Line through</c-typography-text>
    <c-typography-text code>Code snippet</c-typography-text>
  </c-space>
</template>
```

### Paragraph

Preview configuration: `:heading="5"`, `status="secondary"`, `spacing="close"`.

Example source: src/typography/__demos__/paragraph.vue

```vue
<template>
  <c-typography>
    <c-typography-title :heading="5">Default</c-typography-title>
    <c-typography-paragraph>
      A design is a plan or specification for the construction of an object or system or for the
      implementation of an activity or process, or the result of that plan or specification in the
      form of a prototype, product or process. The verb to design expresses the process of developing
      a design. In some cases, the direct construction of an object without an explicit prior plan
      (such as in craftwork, some engineering, coding, and graphic design) may also be considered to
      be a design activity.
    </c-typography-paragraph>
    <c-typography-title :heading="5">Secondary</c-typography-title>
    <c-typography-paragraph status="secondary">
      A design is a plan or specification for the construction of an object or system or for the
      implementation of an activity or process, or the result of that plan or specification in the
      form of a prototype, product or process. The verb to design expresses the process of developing
      a design. In some cases, the direct construction of an object without an explicit prior plan
      (such as in craftwork, some engineering, coding, and graphic design) may also be considered to
      be a design activity.
    </c-typography-paragraph>
    <c-typography-title :heading="5">Spacing default</c-typography-title>
    <c-typography-paragraph>
      A design is a plan or specification for the construction of an object or system or for the
      implementation of an activity or process, or the result of that plan or specification in the
      form of a prototype, product or process. The verb to design expresses the process of developing
      a design. In some cases, the direct construction of an object without an explicit prior plan
      (such as in craftwork, some engineering, coding, and graphic design) may also be considered to
      be a design activity.
    </c-typography-paragraph>
    <c-typography-title :heading="5">Spacing close</c-typography-title>
    <c-typography-paragraph status="secondary" spacing="close">
      A design is a plan or specification for the construction of an object or system or for the
      implementation of an activity or process, or the result of that plan or specification in the
      form of a prototype, product or process. The verb to design expresses the process of developing
      a design.
    </c-typography-paragraph>
  </c-typography>
</template>
```

### Ellipsis

Preview configuration: `:heading="4"`, `ellipsis`, `:ellipsis="{
        rows: 2,
        showTooltip: true,
      }"`, `:ellipsis="{
        rows: 2,
        showTooltip: true,
        css: true,
      }"`.

Example source: src/typography/__demos__/ellipsis.vue

```vue
<template>
  <div>
    <c-typography-title :heading="4" ellipsis>
      A design is a plan or specification for the construction of an object or system or for the
      implementation of an activity or process.
    </c-typography-title>
    <c-typography-paragraph
      :ellipsis="{
        rows: 2,
        showTooltip: true,
      }"
    >
      A design is a plan or specification for the construction of an object or system or for the
      implementation of an activity or process, or the result of that plan or specification in the
      form of a prototype, product or process. The verb to design expresses the process of developing
      a design. The verb to design expresses the process of developing a design. A design is a plan
      or specification for the construction of an object or system or for the implementation of an
      activity or process, or the result of that plan or specification in the form of a prototype,
      product or process. The verb to design expresses the process of developing a design. The verb
      to design expresses the process of developing a design.
    </c-typography-paragraph>
    <c-typography-paragraph
      :ellipsis="{
        rows: 2,
        showTooltip: true,
        css: true,
      }"
    >
      A design is a plan or specification for the construction of an object or system or for the
      implementation of an activity or process, or the result of that plan or specification in the
      form of a prototype, product or process. The verb to design expresses the process of developing
      a design. The verb to design expresses the process of developing a design. A design is a plan
      or specification for the construction of an object or system or for the implementation of an
      activity or process, or the result of that plan or specification in the form of a prototype,
      product or process. The verb to design expresses the process of developing a design. The verb
      to design expresses the process of developing a design.
    </c-typography-paragraph>
    <c-typography-paragraph
      :ellipsis="{
        suffix: '--Cedar Design',
        rows: 2,
        expandable: true,
        showTooltip: {
          type: 'popover',
          props: {
            style: { maxWidth: '500px' },
          },
        },
      }"
    >
      <template #expand-node="{ expanded }">
        {{ expanded ? '' : 'More' }}
      </template>
      A design is a plan or specification for the construction of an object or system or for the
      implementation of an activity or process, or the result of that plan or specification in the
      form of a prototype, product or process. The verb to design expresses the process of developing
      a design. The verb to design expresses the process of developing a design. A design is a plan
      or specification for the construction of an object or system or for the implementation of an
      activity or process, or the result of that plan or specification in the form of a prototype,
      product or process. The verb to design expresses the process of developing a design. The verb
      to design expresses the process of developing a design.
    </c-typography-paragraph>
    <c-typography-paragraph
      :ellipsis="{
        suffix: '--Cedar Design',
        rows: 3,
        expandable: true,
      }"
    >
      A design is a plan or specification for the construction of an object or system or for the
      implementation of an activity or process, or the result of that plan or specification in the
      form of a prototype, product or process. The verb to design expresses the process of developing
      a design. The verb to design expresses the process of developing a design. A design is a plan
      or specification for the construction of an object or system or for the implementation of an
      activity or process, or the result of that plan or specification in the form of a prototype,
      product or process. The verb to design expresses the process of developing a design. The verb
      to design expresses the process of developing a design.
    </c-typography-paragraph>
  </div>
</template>
```

## Interaction and control

### Operations

Preview configuration: `copyable`, `editable`, `v-model:edit-text="str"`.

Example source: src/typography/__demos__/operations.vue

```vue
<template>
  <c-typography>
    <c-typography-paragraph copyable>Click the icon to copy this text.</c-typography-paragraph>
    <c-typography-paragraph editable v-model:edit-text="str">
      {{ str }}
    </c-typography-paragraph>
  </c-typography>
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const str = ref('Click the icon to edit this text.')
</script>
```

## Lifecycle and edge cases

### Scheduler Lifecycle

Example source: src/typography/__demos__/scheduler-lifecycle.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import { TypographyText } from "../index";

const active = ref(true);
const mounted = ref(true);
const copies = ref(0);
</script>

<template>
  <div>
    <c-button html-type="button" @click="active = !active"
      >切换 KeepAlive</c-button
    >
    <c-button html-type="button" @click="mounted = !mounted"
      >卸载／挂载</c-button
    >
    <p>复制通知：{{ copies }}。连续复制后等待 3 秒，或复制后停用再激活。</p>
    <KeepAlive v-if="mounted">
      <TypographyText
        v-if="active"
        copyable
        :ellipsis="{ rows: 1, expandable: true }"
        @copy="copies++"
      >
        Typography
        测量调度与复制反馈生命周期示例：重复复制只保留最新反馈，停用和卸载取消待处理工作。
      </TypographyText>
    </KeepAlive>
  </div>
</template>
```

## API

### Common Props

`Typography.Title`, `Typography.Paragraph` and `Typography.Text` share these props.

| Prop | Description | Type | Default |
| --- | --- | --- | :---: |
| status | Semantic text status | `SemanticStatus` | `-` |
| bold | Bold | `boolean` | `false` |
| mark | Mark styling | `boolean \| { color: string }` | `false` |
| underline | Underline styling | `boolean` | `false` |
| delete | Strikethrough styling | `boolean` | `false` |
| code | Code-block styling | `boolean` | `false` |
| disabled | Whether to disable link | `boolean` | `false` |
| editable | Enable editing | `boolean` | `false` |
| editing **(v-model)** | Whether currently editing | `boolean` | `-` |
| default-editing | Default editing state | `boolean` | `false` |
| edit-text **(v-model)** | Edited text | `string` | `-` |
| copyable | Enable copying | `boolean` | `false` |
| copy-text | Text to copy | `string` | `-` |
| copy-delay | Delay in ms before the copy button becomes clickable again after successful copying | `number` | `3000` |
| ellipsis | Automatic truncation; see EllipsisConfig | `boolean \| EllipsisConfig` | `false` |
| edit-tooltip-props | Edit-button Tooltip options | `object` | `-` |
| copy-tooltip-props | Copy-button Tooltip options | `object` | `-` |

### Common Events

| Event | Description | Arguments |
| --- | --- | --- |
| edit-start | Editing starts | `-` |
| change | Edited content changes | `text: string` |
| edit-end | Editing ends | `-` |
| copy | Copy | `text: string` |
| ellipsis | Ellipsis-state change | `isEllipsis: boolean` |
| expand | Expand/collapse event | `expanded: boolean` |

### Common Slots

| Slot | Description | Arguments |
| --- | --- | --- |
| expand-node | Custom expand/collapse buttons | `expanded: boolean` |
| copy-icon | Custom copy-button icon | `copied: boolean` |
| copy-tooltip | Custom copy-button tooltip content | `copied: boolean` |

### `<TypographyTitle>` Props

| Prop | Description | Type | Default |
| --- | --- | --- | :---: |
| heading | Heading level, equivalent to `h1`/`h2`/`h3`/`h4`/`h5`/`h6` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `1` |

### `<TypographyParagraph>` Props

| Prop | Description | Type | Default |
| --- | --- | --- | :---: |
| blockquote | Block quotation | `boolean` | `false` |
| spacing | Paragraph line height; use the default for long text and `close` for short text | `'default' \| 'close'` | `'default'` |

### EllipsisConfig

| Prop | Description | Type | Default |
| --- | --- | --- | :---: |
| rows | Number of displayed lines before truncation | `number` | `1` |
| expandable | Whether expand/collapse is supported | `boolean` | `false` |
| ellipsisStr | Ellipsis | `string` | `'...'` |
| suffix | Suffix | `string` | `-` |
| showTooltip | Popup options for truncated content | `boolean \| { type: 'tooltip' \| 'popover'; props: Record<string, any> }` | `false` |
| css | Use CSS truncation; currently does not support expansion, custom ellipsis or suffix | `boolean` | `false` |

### Type definitions

The component exports the following types:

```ts
import type {
  TypographyInstance,
  TypographyParagraphInstance,
  TypographyTitleInstance,
  TypographyTextInstance,
  EllipsisConfig,
} from '@cedar-design/ui'
```

---

Document: llms/en-US/components/upload.md

<!-- Source: src/upload/README.en-US.md; locale: en-US; page: /en/components/upload/ -->

# Upload

Upload UI and a headless useUploader composable. The application owns transport and server file deletion.

## Replacement and video metadata

Enable reupload for per-item replacement, or call replace(file, replacementFile). Validation and beforeRemove rejection preserve the original item. An accepted replacement occupies the same position with a new UID and emits replace/change, not remove. A failed new upload can be retried; it does not automatically restore the old server file or delete it.

Video duration is expressed in seconds and rendered as mm:ss or h:mm:ss. Local files are inspected; remote echoes provide duration from application metadata. Temporary resources are released on success, error, cancellation and disposal.

| Variable                                | Default                                  |
| --------------------------------------- | ---------------------------------------- |
| --c-upload-gap                          | var(--c-sys-space-4)                     |
| --c-upload-trigger-min-height           | var(--c-sys-control-height-md)           |
| --c-upload-trigger-padding-horizontal   | var(--c-sys-space-6)                     |
| --c-upload-trigger-draggable-min-height | calc(var(--c-sys-control-height-md) * 2) |
| --c-upload-card-size                    | calc(var(--c-sys-control-height-md) * 2) |
| --c-upload-item-min-height              | var(--c-sys-control-height-md)           |
| --c-upload-item-padding                 | var(--c-sys-space-4)                     |
| --c-upload-thumb-size                   | var(--c-sys-control-height-lg)           |
| --c-upload-border-radius                | var(--c-sys-radius-md)                   |
| --c-upload-border-color                 | var(--c-sys-color-border-default)        |
| --c-upload-background                   | var(--c-sys-color-surface-default)       |
| --c-upload-text-color                   | var(--c-sys-color-content-primary)       |
| --c-upload-secondary-text-color         | var(--c-sys-color-content-secondary)     |
| --c-upload-hover-background             | var(--c-sys-color-state-hover)           |
| --c-upload-active-color                 | var(--c-sys-color-action-primary)        |
| --c-upload-error-color                  | var(--c-sys-color-content-danger)        |
| --c-upload-action-size                  | var(--c-sys-control-touch-target)        |
| --c-upload-progress-height              | var(--c-sys-space-2)                     |
| --c-upload-disabled-opacity             | .56                                      |
| --c-upload-font-size                    | var(--c-sys-font-size-md)                |

## Basic examples

### Read Only

Example source: src/upload/__demos__/read-only.vue

```vue
<script setup>
import { ref } from 'vue'
const files = ref([])
const last = ref('')
</script>
<template><div><p>不配置 action/custom-request：只读取文件，不发送请求。</p><c-upload v-model="files" multiple list-type="picture" @read="file => last = file.name" /><p>最近读取：{{ last }}</p></div></template>
```

## Appearance and states

### State Controls

Example source: src/upload/__demos__/state-controls.vue

```vue
<script setup>
import { ref } from "vue";

const readonly = ref(false);
const disabled = ref(false);
const chooseCount = ref(0);
const previewCount = ref(0);
const initialFile = {
  uid: "state-image",
  name: "state-example.svg",
  type: "image/svg+xml",
  url: "data:image/svg+xml,%3Csvg xmlns=%22http://www.w3.org/2000/svg%22 width=%22120%22 height=%22120%22%3E%3Crect width=%22120%22 height=%22120%22 fill=%22%236750a4%22/%3E%3C/svg%3E",
  status: "success",
  percent: 100,
};
const files = ref([{ ...initialFile }]);
function choose() {
  chooseCount.value++;
}
function restore() {
  files.value = [{ ...initialFile }];
}
</script>

<template>
  <section class="upload-state-demo">
    <div class="controls">
      <c-checkbox v-model="readonly"> Readonly upload</c-checkbox>
      <c-checkbox v-model="disabled"> Disabled upload</c-checkbox>
      <c-button html-type="button" @click="restore">Restore sample</c-button>
    </div>
    <p>Local selection callback only; no file chooser or network request.</p>
    <c-upload
      v-model="files"
      data-testid="state-upload"
      :readonly="readonly"
      :disabled="disabled"
      :request-choose="choose"
      @preview="previewCount++"
    />
    <p role="status">
      Files: {{ files.length }}; choose: {{ chooseCount }}; preview:
      {{ previewCount }}
    </p>
  </section>
</template>

<style scoped>
.controls {
  display: flex;
  flex-wrap: wrap;
  align-items: center;
  gap: 12px;
}
.controls label {
  display: inline-flex;
  align-items: center;
  gap: 4px;
}
</style>
```

### State Lab

Example source: src/upload/__demos__/state-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref([]);
const __demoState = __demoReactive({ disabled: false, readonly: false });
</script>
<template>
  <c-space direction="column" :size="16">
    <c-space wrap>
      <c-checkbox v-model="__demoState['disabled']">disabled</c-checkbox>
      <c-checkbox v-model="__demoState['readonly']">readonly</c-checkbox>
    </c-space>
    <c-upload
      v-model="value"
      :auto-upload="false"
      v-bind="__demoState"
    ></c-upload>
  </c-space>
</template>
```

### Api Review

### Props

| Prop                                                         | Type                                                     | Default/Description                                                               |
| ------------------------------------------------------------ | -------------------------------------------------------- | --------------------------------------------------------------------------------- |
| model-value / default-value                                  | UploadFileItem[]                                         | Controlled value / initial uncontrolled value []                                  |
| accept / capture                                             | string / native capture                                  | Unspecified                                                                       |
| multiple / directory / draggable                             | boolean                                                  | false                                                                             |
| disabled / readonly                                          | boolean                                                  | undefined; inherits Form; explicit false wins                                     |
| action / method                                              | string                                                   | None / post                                                                       |
| headers / data                                               | object or async(file) => object                          | Request preparation remains cancellable                                           |
| name                                                         | string / (file) => string                                | file                                                                              |
| with-credentials                                             | boolean                                                  | false                                                                             |
| custom-request                                               | (UploadRequestOptions) => UploadRequest / Promise / void | Custom transport; may return an abort handle                                      |
| auto-upload                                                  | boolean                                                  | true; starts only when action or custom-request is provided                       |
| max-files / max-file-size / max-total-size                   | number                                                   | Unspecified; sizes are bytes; max-files applies when greater than zero            |
| resolve-type                                                 | file / data-url / object-url                             | object-url; all files get a URL and images also get thumbnailUrl                  |
| create-thumbnail-url                                         | (options) => string / Promise                            | Custom URLs are caller-owned and are not automatically revoked                    |
| before-add                                                   | async(files) => File[]                                   | Filter or replace a batch                                                         |
| before-read                                                  | async(file) => boolean / File                            | false/rejection rejects; replacement files are revalidated                        |
| before-upload                                                | async(item) => boolean / File / Blob                     | false/rejection cancels preparation; replacements are revalidated                 |
| before-remove                                                | async(item,list) => boolean                              | false/rejection keeps the file                                                    |
| is-success-response                                          | (xhr,item) => boolean                                    | HTTP 2xx by default                                                               |
| request-choose                                               | (chooseFile,event) => void / Promise                     | Own file selection; errors do not automatically fall back to a native file picker |
| list-type                                                    | text / picture / picture-card                            | text; supported on both platforms                                                 |
| image-fit                                                    | fill / contain / cover / none / scale-down               | cover; item.fit takes priority                                                    |
| preview                                                      | boolean                                                  | true                                                                              |
| show-file-list / show-upload-button / show-remove-button     | boolean                                                  | true                                                                              |
| show-retry-button / show-cancel-button / show-preview-button | boolean                                                  | true                                                                              |
| show-download-button                                         | boolean                                                  | false; unavailable while interaction is disabled                                  |
| elevation / ripple                                           | boolean or number / boolean                              | false / true                                                                      |

### Custom Surface

Example source: src/upload/__demos__/custom-surface.vue

```vue
<script setup>
import { ref } from 'vue'
const files = ref([])
const message = ref('')
const preview = (file, event) => { event.preventDefault(); message.value = file.name }
</script>
<template><div><c-upload v-model="files" list-type="picture-card" multiple @preview="preview"><template #trigger><span>选择图片</span></template><template #remove-button="{ remove }"><c-button variant="text" @click="remove">删除</c-button></template></c-upload><p>自定义预览：{{ message }}</p></div></template>
```

## File sources and validation

### Directory

Example source: src/upload/__demos__/directory.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
import type { UploadFileItem } from '@cedar-design/ui'
const files = ref<UploadFileItem[]>([])
</script>
<template>
  <c-space direction="column">
    <p>选择目录后查看文件列表；本例只读取本地文件，不发送请求。目录选择取决于浏览器与系统文件选择器，移动设备可使用普通多选入口。</p>
    <p>目录选择</p>
    <c-upload v-model="files" directory multiple />
    <p>普通文件多选</p>
    <c-upload multiple />
  </c-space>
</template>
```

### Clipboard

Example source: src/upload/__demos__/clipboard.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { useUploader, type UploadFileItem } from '@cedar-design/ui'
const files = ref<UploadFileItem[]>([])
const message = ref('')
const rejectionMessages: Record<string, string> = { 'max-files': '最多接收 3 张图片', 'max-file-size': '单张图片不能超过 1 MiB', accept: '仅支持图片文件' }
const uploader = useUploader({
  modelValue: () => files.value,
  onUpdateModelValue: value => { files.value = value },
  accept: () => 'image/*',
  maxFiles: () => 3,
  maxFileSize: () => 1024 * 1024,
  autoUpload: () => false,
  onRejected: rejected => { message.value = rejected.map(item => rejectionMessages[item.reason] ?? '文件未能读取，请重新选择').join(', ') },
})
function paste(event: ClipboardEvent) {
  const incoming = Array.from(event.clipboardData?.files ?? [])
  if (!incoming.length) return
  event.preventDefault()
  message.value = ''
  uploader.addFiles(incoming)
}
function addExample() {
  message.value = ''
  uploader.addFiles([new File(['<svg xmlns="http://www.w3.org/2000/svg" width="8" height="8"/>'], 'local-example.svg', { type: 'image/svg+xml' })])
}
function reset() { uploader.reset(); message.value = '' }
</script>
<template>
  <c-space direction="column">
    <p>将剪贴板图片粘贴到输入区。最多 3 张，每张不超过 1 MiB；只读取文件，不上传。普通文本粘贴仍按原生输入处理。</p>
    <c-textarea placeholder="在这里粘贴图片或文本" @paste="paste" />
    <c-space wrap>
      <c-button @click="addExample">加入本地示例图片</c-button>
      <c-button @click="reset">清空列表</c-button>
    </c-space>
    <p role="status">已接收 {{ files.length }} 个文件。{{ message }}</p>
    <ul><li v-for="file in files" :key="file.uid">{{ file.name }}</li></ul>
  </c-space>
</template>
```

### Replacement Validation

Example source: src/upload/__demos__/replacement-validation.vue

```vue
<script setup>
import { onBeforeUnmount, onDeactivated, ref, shallowRef } from "vue";
import { useUploader } from "@cedar-design/ui";

const files = ref([]);
const readDataUrl = ref(false);
const readObjectUrl = ref(false);
const pauseThumbnail = ref(false);
const pendingThumbnails = shallowRef([]);
const decoded = ref(0);
const reasons = ref([]);
const replacements = new WeakMap();
const maxFileSize = 1048576;
const maxTotalSize = 2097152;
const maxFiles = 3;
const svg =
  '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"><rect width="16" height="16" fill="#4caf50"/></svg>';
let sequence = 0;

function replace(file) {
  const mode = replacements.get(file);
  if (mode === "type") {
    return new File(["text replacement"], file.name.replace(".svg", ".txt"), {
      type: "text/plain",
    });
  }
  if (mode === "size") {
    return new File([new Uint8Array(maxFileSize + 1)], file.name, {
      type: file.type,
    });
  }
  return new File([file], file.name, { type: file.type });
}

const uploader = useUploader({
  modelValue: () => files.value,
  onUpdateModelValue: (value) => {
    files.value = value;
  },
  accept: () => "image/*",
  maxFiles: () => maxFiles,
  createThumbnailUrl: () =>
    pauseThumbnail.value
      ? () =>
          new Promise((resolve, reject) => {
            pendingThumbnails.value = [
              ...pendingThumbnails.value,
              { resolve, reject },
            ];
          })
      : undefined,
  maxFileSize: () => maxFileSize,
  maxTotalSize: () => maxTotalSize,
  resolveType: () =>
    readObjectUrl.value
      ? "object-url"
      : readDataUrl.value
        ? "data-url"
        : "file",
  beforeRead: () => replace,
  onRejected: (items) => {
    reasons.value = items.map((item) => item.reason);
  },
});

function probe(mode) {
  reasons.value = [];
  const payload = mode === "total" ? svg.padEnd(786432, " ") : svg;
  const file = new File([payload], `sample-${++sequence}.svg`, {
    type: "image/svg+xml",
  });
  replacements.set(file, mode);
  return uploader.addFiles([file]);
}

function reset() {
  uploader.reset();
  decoded.value = 0;
  reasons.value = [];
}
function settleThumbnail(fail = false, latest = false) {
  const tasks = [...pendingThumbnails.value];
  const task = latest ? tasks.pop() : tasks.shift();
  if (!task) return;
  pendingThumbnails.value = tasks;
  if (fail) task.reject(new Error("Local thumbnail failure"));
  else task.resolve("data:image/svg+xml," + encodeURIComponent(svg));
}
function cleanupThumbnails() {
  const tasks = pendingThumbnails.value;
  pendingThumbnails.value = [];
  tasks.forEach((task) => task.resolve(undefined));
}
onBeforeUnmount(cleanupThumbnails);
onDeactivated(cleanupThumbnails);
</script>

<template>
  <div class="upload-read-demo">
    <p class="thumbnail-pending">
      Pending thumbnails: {{ pendingThumbnails.length }}
    </p>
    <c-button
      html-type="button"
      :disabled="!pendingThumbnails.length"
      @click="settleThumbnail(false, true)"
    >
      返回最新缩略图
    </c-button>
    <c-button
      html-type="button"
      :disabled="!pendingThumbnails.length"
      @click="settleThumbnail()"
      >返回最早缩略图</c-button
    >
    <c-button
      html-type="button"
      :disabled="!pendingThumbnails.length"
      @click="settleThumbnail(true)"
      >拒绝最早缩略图</c-button
    >
    <c-checkbox v-model="readDataUrl" edit-mode="direct"
      >使用原生 FileReader 读取为 data-url</c-checkbox
    >
    <c-checkbox v-model="readObjectUrl" edit-mode="direct"
      >使用原生 Blob/object-url（优先）</c-checkbox
    >
    <output
      >Blob URLs:
      {{ files.filter((file) => file.url?.startsWith("blob:")).length }}</output
    >
    <p role="status">
      Data URLs:
      {{ files.filter((file) => file.url?.startsWith("data:")).length }} ·
      Decoded images: {{ decoded }}
    </p>
    <img
      v-for="file in files.filter((file) =>
        /^(data:|blob:)/.test(file.thumbnailUrl || ''),
      )"
      :key="file.uid"
      :src="file.thumbnailUrl"
      :alt="file.name"
      width="16"
      height="16"
      @load="decoded++"
    />
    <p>
      仅接受图片；单文件 1 MiB、合计 2 MiB、最多 3 个。每个示例均经过
      before-read。
    </p>
    <c-space wrap>
      <c-button @click="probe('valid')">加入小图片</c-button>
      <c-button @click="probe('type')">替换为文本</c-button>
      <c-button @click="probe('size')">替换为超大图片</c-button>
      <c-button @click="probe('total')">加入 768 KiB 图片</c-button>
      <c-button @click="reset">重置队列</c-button>
    </c-space>
    <c-checkbox v-model="pauseThumbnail" edit-mode="direct"
      >暂停本地缩略图 Promise</c-checkbox
    >
    <c-upload
      v-model="files"
      edit-mode="direct"
      :show-upload-button="false"
      :preview="false"
    />
    <p>队列：{{ files.map((file) => file.name).join(", ") || "空" }}</p>
    <p>拒绝原因：{{ reasons.join(", ") || "无" }}</p>
  </div>
</template>
```

## Queues and progress

### External State

Example source: src/upload/__demos__/external-state.vue

```vue
<script setup>
import { computed, ref } from "vue";

const files = ref([]);
const hasUploading = computed(() =>
  files.value.some((file) => file.status === "uploading"),
);
const hasRetryable = computed(() =>
  files.value.some((file) => ["error", "canceled"].includes(file.status)),
);
let sequence = 0;

function read(file) {
  file.status = "uploading";
  file.percent = 40;
}

function addExample() {
  const file = new File(
    ["Local external upload demo."],
    `external-${++sequence}.txt`,
    { type: "text/plain" },
  );
  const item = {
    uid: `external-${sequence}`,
    name: file.name,
    size: file.size,
    type: file.type,
    file,
    status: "ready",
    percent: 0,
  };
  read(item);
  files.value = [...files.value, item];
}

function complete() {
  files.value = files.value.map((file) =>
    file.status === "uploading"
      ? { ...file, status: "success", percent: 100 }
      : file,
  );
}

function retry() {
  files.value = files.value.map((file) =>
    ["error", "canceled"].includes(file.status)
      ? { ...file, status: "uploading", percent: 40 }
      : file,
  );
}
</script>

<template>
  <div>
    <p>业务端托管进度和结果；可加入本地示例项，无需选择文件，也不发送请求。</p>
    <c-space wrap>
      <c-button @click="addExample">加入外部上传项</c-button>
      <c-button :disabled="!hasUploading" @click="complete"
        >模拟外部完成</c-button
      >
      <c-button :disabled="!hasRetryable" @click="retry">模拟外部重试</c-button>
    </c-space>
    <c-upload
      v-model="files"
      edit-mode="direct"
      :show-retry-button="false"
      @read="read"
    />
    <p>
      队列状态：{{
        files
          .map((file) => `${file.name}: ${file.status} (${file.percent}%)`)
          .join("；") || "空"
      }}
    </p>
  </div>
</template>
```

### Queue Request

Example source: src/upload/__demos__/queue-request.vue

```vue
<script setup lang="ts">
import { onBeforeUnmount, onDeactivated, ref } from "vue";
import type {
  UploadFileItem,
  UploadInstance,
  UploadProgressEvent,
  UploadRequestOptions,
} from "@cedar-design/ui";

const files = ref<UploadFileItem[]>([]);
const uploader = ref<UploadInstance>();
const failOnce = ref(false);
const activeRequests = ref(0);
const timers = new Set<ReturnType<typeof setInterval>>();
const attempts = new Map<string, number>();
const exampleUrls = new Set<string>();
let sequence = 0;

function addExample() {
  const file = new File(
    ["Local upload demo; no network."],
    `example-${++sequence}.txt`,
    { type: "text/plain" },
  );
  const url = URL.createObjectURL(file);
  exampleUrls.add(url);
  files.value = [
    ...files.value,
    {
      uid: `demo-queue-${sequence}`,
      name: file.name,
      size: file.size,
      type: file.type,
      file,
      url,
      status: "ready",
      percent: 0,
    },
  ];
}

function request({
  file,
  onProgress,
  onSuccess,
  onError,
}: UploadRequestOptions) {
  const attempt = (attempts.get(file.uid) ?? 0) + 1;
  attempts.set(file.uid, attempt);
  const reject = failOnce.value && attempt === 1;
  let percent = 0;
  const stop = () => {
    clearInterval(timer);
    timers.delete(timer);
    activeRequests.value = timers.size;
  };
  const timer = setInterval(() => {
    percent += 10;
    onProgress({ percent } as UploadProgressEvent);
    if (percent >= 100) {
      stop();
      if (reject) {
        onError(new Error("Simulated first-attempt failure"));
      } else {
        onSuccess({ ok: true, attempt });
      }
    }
  }, 200);
  timers.add(timer);
  activeRequests.value = timers.size;
  return { abort: stop };
}

function cleanup() {
  uploader.value?.abort();
  timers.forEach((timer) => clearInterval(timer));
  timers.clear();
  activeRequests.value = 0;
}
onBeforeUnmount(() => {
  cleanup();
  exampleUrls.forEach((url) => URL.revokeObjectURL(url));
  exampleUrls.clear();
});
onDeactivated(cleanup);
</script>

<template>
  <div>
    <p>本地模拟请求；支持取消、重试和手动提交，不访问网络。</p>
    <c-checkbox v-model="failOnce" edit-mode="direct"
      >首次请求失败（重试成功）</c-checkbox
    >
    <c-space wrap>
      <c-button @click="addExample">加入示例文件</c-button>
      <c-button @click="uploader?.submit()">提交队列</c-button>
    </c-space>
    <c-upload
      ref="uploader"
      v-model="files"
      edit-mode="direct"
      multiple
      :auto-upload="false"
      :custom-request="request"
    />
    <p>
      队列状态：{{
        files
          .map((file) => `${file.name}: ${file.status} (${file.percent}%)`)
          .join("；") || "空"
      }}
    </p>
    <p>活动请求：{{ activeRequests }}</p>
  </div>
</template>
```

## Async hooks and requests

### Before Remove

Example source: src/upload/__demos__/before-remove.vue

```vue
<script setup lang="ts">
import { onBeforeUnmount, onDeactivated, ref, shallowRef } from "vue";
import type { UploadFileItem } from "@cedar-design/ui";

const files = ref<UploadFileItem[]>([
  {
    uid: "sample",
    name: "sample.txt",
    type: "text/plain",
    status: "success",
    percent: 100,
  },
]);
const allow = ref(false);
const manual = ref(false);
const blocked = ref(false);
const attempts = ref(0);
const removed = ref(0);
const uploadRef = ref();
const mounted = ref(true);
const pending = shallowRef<
  Array<{
    resolve: (accepted: boolean) => void;
    reject: (error: Error) => void;
  }>
>([]);
const beforeRemove = () => {
  attempts.value++;
  if (!manual.value) return allow.value;
  return new Promise<boolean>((resolve, reject) => {
    pending.value = [...pending.value, { resolve, reject }];
  });
};
function settle(accepted: boolean | "reject") {
  const jobs = pending.value;
  pending.value = [];
  jobs.forEach((job) =>
    accepted === "reject"
      ? job.reject(new Error("Local removal rejection"))
      : job.resolve(accepted),
  );
}
function replace() {
  files.value = files.value.map((item) => ({
    ...item,
    name: "replacement.txt",
    type: "text/plain",
    file: new File(["local replacement"], "replacement.txt", {
      type: "text/plain",
    }),
  }));
}
function restore() {
  files.value = [
    {
      uid: "sample",
      name: "restored.txt",
      type: "text/plain",
      status: "success",
      percent: 100,
      file: new File(["local sample"], "restored.txt", { type: "text/plain" }),
    },
  ];
}
onBeforeUnmount(() => settle(false));
onDeactivated(() => settle(false));
</script>

<template>
  <section class="remove-confirm-demo">
    <c-checkbox v-model="allow"> 允许此操作</c-checkbox>
    <c-checkbox v-model="manual"> 手动异步确认</c-checkbox>
    <c-checkbox v-model="blocked"> 禁用上传组件</c-checkbox>
    <c-button
      html-type="button"
      :disabled="!pending.length"
      @click="settle(true)"
      >确认删除</c-button
    >
    <c-button
      html-type="button"
      :disabled="!pending.length"
      @click="settle(false)"
      >取消删除</c-button
    >
    <c-button
      html-type="button"
      :disabled="!pending.length"
      @click="settle('reject')"
      >异常拒绝删除</c-button
    >
    <c-button html-type="button" :disabled="!files.length" @click="replace"
      >替换同 UID 文件</c-button
    >
    <c-button html-type="button" @click="uploadRef?.reset()"
      >重置上传队列</c-button
    >
    <c-button html-type="button" @click="restore">恢复示例文件</c-button>
    <c-checkbox v-model="mounted"> 激活上传组件</c-checkbox>
    <KeepAlive>
      <c-upload
        v-if="mounted"
        ref="uploadRef"
        v-model="files"
        :before-remove="beforeRemove"
        :disabled="blocked"
        @remove="removed++"
      />
    </KeepAlive>
    <p role="status">
      文件：{{ files.length }}；等待：{{ pending.length }}；钩子：{{
        attempts
      }}；删除：{{ removed }}
    </p>
  </section>
</template>
```

### Prepare Request

Example source: src/upload/__demos__/prepare-request.vue

```vue
<script setup>
import { onBeforeUnmount, onDeactivated, ref } from 'vue'
import { useUploader } from '@cedar-design/ui'

const files = ref([])
const reasons = ref([])
const mode = ref('valid')
const preparing = ref(0)
const requestCount = ref(0)
const pending = new Set()
const modes = [
  { label: '有效副本', value: 'valid' },
  { label: '替换为文本', value: 'type' },
  { label: '替换为超大图片', value: 'size' },
  { label: '每项替换600B，合计上限1024B', value: 'total' },
]
let sequence = 0

function beforeUpload(file) {
  return new Promise((resolve) => {
    pending.add({ file, resolve })
    preparing.value = pending.size
  })
}

const uploader = useUploader({
  modelValue: () => files.value,
  onUpdateModelValue: (value) => {
    files.value = value
  },
  accept: () => 'image/*',
  maxFileSize: () => 1024,
  maxFiles: () => mode.value === 'total' ? 2 : 1,
  maxTotalSize: () => 1024,
  resolveType: () => 'file',
  autoUpload: () => false,
  beforeUpload: () => beforeUpload,
  customRequest:
    () =>
    ({ onSuccess }) => {
      requestCount.value++
      onSuccess({ ok: true })
    },
  onRejected: (items) => {
    reasons.value = items.map((item) => item.reason)
  },
})

function add() {
  const svg = '<svg xmlns="http://www.w3.org/2000/svg" width="1" height="1"/>'
  return uploader.addFiles([new File([svg], `prepare-${++sequence}.svg`, { type: 'image/svg+xml' })])
}

function submit() {
  reasons.value = []
  return uploader.submit()
}

function finish() {
  const jobs = [...pending]
  pending.clear()
  preparing.value = 0
  jobs.forEach(({ file, resolve }) => {
    const raw = file.file
    if (mode.value === 'type') {
      resolve(new File(['text'], 'replacement.txt', { type: 'text/plain' }))
    } else if (mode.value === 'size') {
      resolve(new File([new Uint8Array(1025)], raw.name, { type: raw.type }))
    } else if (mode.value === 'total') {
      resolve(new File([new Uint8Array(600)], raw.name, { type: raw.type }))
    } else {
      resolve(new File([raw], raw.name, { type: raw.type }))
    }
  })
}

function cleanup() {
  uploader.abort()
  pending.forEach(({ resolve }) => resolve(false))
  pending.clear()
  preparing.value = 0
}

function reset() {
  cleanup()
  uploader.reset()
  reasons.value = []
  requestCount.value = 0
}
onBeforeUnmount(cleanup)
onDeactivated(cleanup)
</script>

<template>
  <div class="upload-prepare-demo">
    <p>提交后暂停 before-upload；可取消后再次提交，再统一完成准备，只有当前有效尝试可以发起本地请求。</p>
    <c-radio-group v-model="mode" :options="modes" />
    <c-space wrap>
      <c-button :disabled="files.length >= (mode === 'total' ? 2 : 1)" @click="add">加入示例图片</c-button>
      <c-button :disabled="!files.some((file) => ['ready', 'error', 'canceled'].includes(file.status))" @click="submit"
        >准备并提交</c-button
      >
      <c-button :disabled="preparing === 0" @click="uploader.abort()">取消准备</c-button>
      <c-button :disabled="preparing === 0" @click="finish">完成准备</c-button>
      <c-button @click="reset">重置队列</c-button>
    </c-space>
    <c-upload v-model="files" :show-upload-button="false" :show-retry-button="false" :preview="false" />
    <p>待返回准备任务：{{ preparing }}</p>
    <p>请求次数：{{ requestCount }}</p>
    <p>队列状态：{{ files.map((file) => `${file.status} (${file.percent}%)`).join(', ') || '空' }}</p>
    <p>队列字节：{{ files.map((file) => file.size).join(', ') || '0' }}</p>
    <p>拒绝原因：{{ reasons.join(', ') || '无' }}</p>
  </div>
</template>
```

### Metadata Request

Example source: src/upload/__demos__/metadata-request.vue

```vue
<script setup>
import { onBeforeUnmount, onDeactivated, ref, shallowRef } from "vue";
import { useUploader } from "@cedar-design/ui";
const endpoint = ref("");
const files = ref([]);
const headers = shallowRef([]);
const data = shallowRef([]);
const successes = ref(0);
const errors = ref(0);
const response = ref(null);
let sequence = 0;
function wait(queue, file) {
  return new Promise((resolve, reject) => {
    queue.value = [...queue.value, { file, resolve, reject }];
  });
}
function finish(queue, kind) {
  const jobs = queue.value;
  queue.value = [];
  jobs.forEach((job) =>
    job.resolve(
      kind === "headers"
        ? { "X-Demo-Upload": job.file.name }
        : { auditMarker: "audit-local" },
    ),
  );
}
const uploader = useUploader({
  modelValue: () => files.value,
  onUpdateModelValue: (value) => {
    files.value = value;
  },
  action: () => endpoint.value,
  headers: () => (file) => wait(headers, file),
  data: () => (file) => wait(data, file),
  name: () => "attachment",
  autoUpload: () => false,
  resolveType: () => "file",
  onSuccess: (file) => {
    successes.value++;
    response.value = file.response;
  },
  onError: () => {
    errors.value++;
  },
});
function add() {
  return uploader.addFiles([
    new File(["Synthetic upload audit only."], `metadata-${++sequence}.txt`, {
      type: "text/plain",
    }),
  ]);
}
function cleanup() {
  uploader.abort();
  finish(headers, "headers");
  finish(data, "data");
}
function finishHeaders() {
  finish(headers, "headers");
}
function finishData() {
  finish(data, "data");
}
function rejectHeaders() {
  rejectPending(headers, "headers");
}
function rejectData() {
  rejectPending(data, "data");
}
function rejectPending(queue, kind) {
  const jobs = queue.value;
  queue.value = [];
  jobs.forEach((job) => job.reject(new Error(`Synthetic ${kind} rejection`)));
}
function reset() {
  cleanup();
  uploader.reset();
  successes.value = 0;
  errors.value = 0;
  response.value = null;
}
onBeforeUnmount(cleanup);
onDeactivated(cleanup);
</script>
<template>
  <section class="metadata-upload-demo">
    <p>
      默认 XHR 请求；先配置你控制的本地接口。headers 与 data
      分别等待手动返回，默认不访问任何地址。
    </p>
    <label
      >Local upload endpoint
      <c-input v-model="endpoint" placeholder="http://127.0.0.1:4197/upload"
    /></label>
    <c-space wrap>
      <c-button :disabled="files.length > 0" @click="add"
        >加入合成文件</c-button
      >
      <c-button
        :disabled="
          !endpoint ||
          !files.some((file) =>
            ['ready', 'error', 'canceled'].includes(file.status),
          )
        "
        @click="uploader.submit()"
        >提交元数据请求</c-button
      >
      <c-button
        :disabled="!files.some((file) => file.status === 'uploading')"
        @click="uploader.abort()"
        >取消元数据请求</c-button
      >
      <c-button :disabled="!headers.length" @click="finishHeaders"
        >返回 headers</c-button
      >
      <c-button :disabled="!data.length" @click="finishData"
        >返回 data</c-button
      >
      <c-button :disabled="!headers.length" @click="rejectHeaders"
        >拒绝 headers</c-button
      >
      <c-button :disabled="!data.length" @click="rejectData"
        >拒绝 data</c-button
      >
      <c-button @click="reset">重置元数据示例</c-button>
    </c-space>
    <c-upload
      v-model="files"
      :show-upload-button="false"
      :show-retry-button="false"
      :preview="false"
    />
    <p role="status">
      headers 等待：{{ headers.length }}；data 等待：{{ data.length }}；成功：{{
        successes
      }}；错误：{{ errors }}
    </p>
    <p>
      模型：{{
        files.map((file) => file.name + ": " + file.status).join(", ") || "空"
      }}
    </p>
    <pre>{{ response }}</pre>
  </section>
</template>
```

### Late Request

Example source: src/upload/__demos__/late-request.vue

```vue
<script setup>
import { onBeforeUnmount, onDeactivated, ref, shallowRef } from 'vue'
import { useUploader } from '@cedar-design/ui'

const files = ref([])
const handles = shallowRef([])
const callbacks = shallowRef([])
const requests = ref(0)
const aborts = ref(0)
const accepted = ref(0)
let sequence = 0
let generation = 0
const uploader = useUploader({
  modelValue: () => files.value,
  onUpdateModelValue: value => { files.value = value },
  resolveType: () => 'file',
  autoUpload: () => false,
  customRequest: () => options => {
    const current = generation
    requests.value++
    callbacks.value = [...callbacks.value, options]
    return new Promise(resolve => {
      handles.value = [...handles.value, {
        resolve: () => resolve({ abort: () => { if (current === generation) aborts.value++ } }),
      }]
    })
  },
  onSuccess: () => { accepted.value++ },
})
function add() {
  return uploader.addFiles([new File(['Local delayed transport; no network.'], `late-${++sequence}.txt`, { type: 'text/plain' })])
}
function release() {
  const pending = handles.value
  handles.value = []
  pending.forEach(job => job.resolve())
}
function complete() {
  const pending = callbacks.value
  callbacks.value = []
  pending.forEach(options => options.onSuccess({ local: true }))
}
function cleanup() {
  generation++
  uploader.abort()
  release()
  callbacks.value = []
}
function reset() {
  cleanup()
  uploader.reset()
  requests.value = 0
  aborts.value = 0
  accepted.value = 0
}
onBeforeUnmount(cleanup)
onDeactivated(cleanup)
</script>

<template>
  <section class="late-upload-demo">
    <p>请求句柄延迟返回；先取消再返回句柄，旧句柄应立即 abort，迟到成功回调不能恢复取消项。不访问网络。</p>
    <c-space wrap>
      <c-button :disabled="files.length > 0" @click="add">加入本地文件</c-button>
      <c-button :disabled="!files.some(file => ['ready', 'error', 'canceled'].includes(file.status))" @click="uploader.submit()">发起模拟请求</c-button>
      <c-button :disabled="!files.some(file => file.status === 'uploading')" @click="uploader.abort()">取消模拟请求</c-button>
      <c-button :disabled="!handles.length" @click="release">返回所有句柄</c-button>
      <c-button :disabled="!callbacks.length" @click="complete">返回所有成功回调</c-button>
      <c-button @click="reset">重置模拟</c-button>
    </c-space>
    <c-upload v-model="files" :show-upload-button="false" :show-retry-button="false" :preview="false" />
    <p role="status">句柄等待：{{ handles.length }}；发起：{{ requests }}；abort：{{ aborts }}；有效成功：{{ accepted }}</p>
    <p>模型：{{ files.map(file => file.name + ': ' + file.status).join(', ') || '空' }}</p>
  </section>
</template>
```

## API

### Empty values and reading placeholders

`empty-values` recognizes empty data; `empty-value` keeps existing clear output. `empty-text` defaults to `'-'` under `read-pretty`, with Field > FormItem > Form precedence and custom read slots first. With explicit empty-values, built-in required uses the policy; custom validators receive original data. See the [shared guide](llms/en-US/guide/empty-values.md).

| Prop         | Type               | Default and scope                                                           |
| ------------ | ------------------ | --------------------------------------------------------------------------- |
| empty-values | readonly unknown[] | Field > FormItem > Form > component-family default; replaces the whole list |
| empty-text   | string             | Field > FormItem > Form > '-'; explicit '' is valid                         |

These props belong to field presentation; pure panels do not gain reading mode. Form and FormItem provide inherited settings. The existing empty-value type and clear fallback remain component-specific.

### Props

| Prop                                                         | Type                                                     | Default / description                                                        |
| ------------------------------------------------------------ | -------------------------------------------------------- | ---------------------------------------------------------------------------- |
| model-value / default-value                                  | UploadFileItem[]                                         | Controlled value / uncontrolled initial []                                   |
| accept / capture                                             | string / native capture                                  | Unspecified                                                                  |
| multiple / directory / draggable                             | boolean                                                  | false                                                                        |
| disabled / readonly                                          | boolean                                                  | undefined inherits Form; explicit false overrides                            |
| action / method                                              | string                                                   | None / post                                                                  |
| headers / data                                               | object or async(file) => object                          | Cancelable during request preparation                                        |
| name                                                         | string / (file) => string                                | file                                                                         |
| with-credentials                                             | boolean                                                  | false                                                                        |
| custom-request                                               | (UploadRequestOptions) => UploadRequest / Promise / void | Custom transport; may return abort                                           |
| auto-upload                                                  | boolean                                                  | true; requires action or custom-request to start                             |
| max-files / max-file-size / max-total-size                   | number                                                   | Unspecified; sizes use bytes, max-files applies when >0                      |
| resolve-type                                                 | file / data-url / object-url                             | object-url; all files get url, images also get thumbnailUrl                  |
| create-thumbnail-url                                         | (options) => string / Promise                            | Custom URLs belong to callers and are not automatically revoked              |
| before-add                                                   | async(files) => File[]                                   | Batch filtering/replacement                                                  |
| before-read                                                  | async(file) => boolean / File                            | false/rejection rejects; replacements are revalidated                        |
| before-upload                                                | async(item) => boolean / File / Blob                     | false/rejection cancels preparation; replacements are revalidated            |
| before-remove                                                | async(item,list) => boolean                              | false/rejection prevents removal                                             |
| is-success-response                                          | (xhr,item) => boolean                                    | HTTP 2xx by default                                                          |
| request-choose                                               | (chooseFile,event) => void / Promise                     | Own the selection entry; exceptions do not automatically open a file chooser |
| list-type                                                    | text / picture / picture-card                            | text; supported on both platforms                                            |
| image-fit                                                    | fill / contain / cover / none / scale-down               | cover; item.fit overrides                                                    |
| preview                                                      | boolean                                                  | true                                                                         |
| show-file-list / show-upload-button / show-remove-button     | boolean                                                  | true                                                                         |
| show-retry-button / show-cancel-button / show-preview-button | boolean                                                  | true                                                                         |
| show-download-button                                         | boolean                                                  | false; disabled prevents interaction                                         |
| elevation / ripple                                           | boolean or number / boolean                              | false / true                                                                 |

UploadFileItem requires uid, status and percent. name/size/type/file/url/thumbnailUrl/fit/response/error are optional. status is ready/reading/uploading/success/error/canceled/removed.

### Events

- update:model-value(files), change(files, changedFile?): queue proposal order; Form receives one change notification per change, including progress/state updates.
- read(item): reading completed; business code may take over uploading. It does not indicate server success.
- rejected(UploadRejectedFile[]): reason is accept/before-add/before-read/read-error/max-file-size/max-total-size/max-files.
- exceed(nativeFiles, acceptedList): file-count limit exceeded.
- progress(item,event?), success(item), error(item): active-request notifications. Stale/canceled callbacks have no effect.
- remove(item): removal proposal after removal hooks accept it.
- preview(item, UploadPreviewEvent): event.preventDefault() cancels built-in image/video preview. Programmatic previews are cancelable too; originalEvent is optional.

### Slots

- trigger({chooseFile,dragOver,disabled}): custom selection entry.
- item({file,index,remove,retry,abort}): custom complete item.
- remove-button({file,index,remove,retry,abort}): custom removal action.

### Expose

chooseFile(), submit(file?), abort(file?), retry(file), remove(file), reset(), clearSuccess(), clearError(), getFiles(status?), preview(file), closePreview(). useUploader(options) supplies matching UI-free logic plus addFiles(files) and input/drag handlers.

### Controlled state and lifecycle

If a controlled parent rejects an addition, only read/list proposals emit; automatic upload waits until that uid is accepted, then runs once. Same-tick proposals merge transactionally; across ticks, the actual parent list is authoritative. Rejected entries do not count toward total size. Parents own consistency of late list replacements. Explicit removal of rejected items, reset or unmount releases generated URLs; external URLs are never revoked. Built-in preview retains its own URL ownership until closing and does not close another component's later preview.

Cancellation covers before-upload, asynchronous headers/data/name and asynchronous custom-request handles. Retrying or replacing a File under the same uid invalidates old callbacks. before-read/before-upload replacements recheck limits. max-total-size counts accepted entries and the current valid prepared batch/request only. Disabled/readonly block selection, removal, submission and other mutations; readonly allows preview/download. KeepAlive deactivation cancels preparation/requests; reactivation allows new operations.

## Type definitions

UploadProps、UploadEmits、UploadSlots、UploadExpose、UploadPublicMethods、UploadFileItem、UploadStatus、UploadListType、UploadResolveType、UploadImageFit、UploadCapture、UploadRejectedFile、UploadRejectedReason、UploadRequestOptions、UploadRequest、UploadCustomRequest、UploadProgressEvent、UploadData、UploadHeaders、UploadBeforeRead、UploadBeforeUpload、UploadBeforeRemove、UploadCreateThumbnailUrl、UploadIsSuccessResponse、UploadRequestChoose、UploadPreviewEvent、UseUploaderOptions、UploadInstance。

## Style variables

Public variable suffixes match across platforms; all defaults appear below with c/mp prefixes respectively.

| Variable                                | Default                                  |
| --------------------------------------- | ---------------------------------------- |
| --c-upload-gap                          | var(--c-sys-space-4)                     |
| --c-upload-trigger-min-height           | var(--c-sys-control-height-md)           |
| --c-upload-trigger-padding-horizontal   | var(--c-sys-space-6)                     |
| --c-upload-trigger-draggable-min-height | calc(var(--c-sys-control-height-md) * 2) |
| --c-upload-card-size                    | calc(var(--c-sys-control-height-md) * 2) |
| --c-upload-item-min-height              | var(--c-sys-control-height-md)           |
| --c-upload-item-padding                 | var(--c-sys-space-4)                     |
| --c-upload-thumb-size                   | var(--c-sys-control-height-lg)           |
| --c-upload-border-radius                | var(--c-sys-radius-md)                   |
| --c-upload-border-color                 | var(--c-sys-color-border-default)        |
| --c-upload-background                   | var(--c-sys-color-surface-default)       |
| --c-upload-text-color                   | var(--c-sys-color-content-primary)       |
| --c-upload-secondary-text-color         | var(--c-sys-color-content-secondary)     |
| --c-upload-hover-background             | var(--c-sys-color-state-hover)           |
| --c-upload-active-color                 | var(--c-sys-color-action-primary)        |
| --c-upload-error-color                  | var(--c-sys-color-content-danger)        |
| --c-upload-action-size                  | var(--c-sys-control-touch-target)        |
| --c-upload-progress-height              | var(--c-sys-space-2)                     |
| --c-upload-disabled-opacity             | .56                                      |
| --c-upload-font-size                    | var(--c-sys-font-size-md)                |

### Form field presentation and confirmation

This component supports `edit-mode` with field > FormItem > Form precedence. When unset, it defaults to `direct` and preserves `direct` editing. Supported values: `direct / click / dblclick`. Non-`direct` modes open the editor through the field value trigger and keep one draft; v-model updates only after confirmation. Cancel, reset or enabling readPretty discards the draft.

Cedar uses edit-mode="click" / "dblclick" to open an editor popup near the field. Enter/F2 also opens it; cancel/Escape discards the draft, and confirmation commits it. readPretty is an independent reading setting, separate from readonly and disabled.

`before-commit(value, { previousValue, signal })` can reject an overlay save. FormItem validates the candidate first and keeps the editor open on failure. `open / default-open / update:open` control the editor. Use `#read="{ value, text }"` to customize display. See the full field comparison in Form.

Attachment confirmation commits file-list relationships; it cannot undo completed remote uploads or permanent deletion. To defer network side effects, set `auto-upload="false"` and upload after the final business submission.

`read-pretty` is an independent boolean alongside `readonly` and `disabled`. It inherits from field to FormItem to Form; explicit `false` overrides the parent. The default is `false`. Reading mode renders no editor.

## Cover attachments and video duration

`reupload` (default false) enables a per-item replacement action, including when maxFiles has been reached. `replace(file, replacement?: File): Promise<void>` opens a single-file chooser or validates the supplied File. It respects readonly/disabled and the chooser hook. Validation and beforeRemove run before an atomic in-place replacement proposal with a new UID; count and total size exclude the old item. Cancellation, rejection, guard veto and stale targets preserve the old item. A controlled parent decides acceptance. The `replace(next, previous)` event is a model proposal, not remote success or removal; remove is not emitted. Once accepted, obsolete transport callbacks are ignored; new upload failures can be retried. The item slot also exposes replace().

`UploadFileItem.duration?: number` uses seconds, displayed as mm:ss / h:mm:ss; unknown/invalid durations are hidden. Metadata reads local File objects only, waits at most 5 seconds and cleans temporary resources. Business code supplies remote durations. Video previews use popupContainer.

Duration-badge variables: `--c-upload-duration-background: var(--c-sys-color-surface-tooltip)`, `--c-upload-duration-color: var(--c-sys-color-content-on-dark)`, `--c-upload-duration-radius: var(--c-sys-radius-sm)`, `--c-upload-duration-padding: var(--c-sys-space-1) var(--c-sys-space-2)`, `--c-upload-duration-font-size: var(--c-sys-font-size-sm)`.

### Before-hook waiting feedback

Before-hook waits show visible feedback and aria-busy. Rejected or failed operations recover; duplicate submissions do not start another copy. Notification event Promises never drive loading. Independent file operations retain concurrency and share aggregate hook feedback.

`useUploader()` exposes readonly `guardPending`, aggregating currently awaited before hooks. It does not represent upload progress.

---

Document: llms/en-US/components/verification-code.md

<!-- Source: src/verification-code/README.en-US.md; locale: en-US; page: /en/components/verification-code/ -->

# Verification Code

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

Preview configuration: `aria-label="验证码"`.

Example source: src/verification-code/__demos__/basic.vue

```vue
<script setup>
import { ref } from 'vue'

const code = ref('')
</script>
<template>
  <div class="verification-demo">
    <c-verification-code v-model="code" aria-label="验证码" />
    <p>当前值：{{ code || '未输入' }}</p>
  </div>
</template>
<style scoped>
.verification-demo {
  max-width: 420px;
}
</style>
```

## Appearance and states

### Appearance

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration   | Purpose                                                      | Related examples           |
| --------------- | ------------------------------------------------------------ | -------------------------- |
| `default-value` | Uncontrolled initial value                                   | Appearance, States         |
| `length`        | Positive integer cell count, measured in Unicode code points | Appearance, Appearance Lab |
| `aria-label`    | Group name and numbered cell labels                          | Appearance, States         |
| `masked`        | Visual character masking only, not encryption                | Appearance                 |
| `mask-symbol`   | Use the first Unicode code point                             | Appearance                 |
| `variant`       | Input variant                                                | Appearance                 |

<!-- demo-config-notes:end -->

- `variant`: Selects the visual variant.
- `size`: Controls the component size.
- `align`: Controls alignment on the cross axis.

Example source: src/verification-code/__demos__/appearance.vue

```vue
<template>
  <div class="verification-demo">
    <c-verification-code
      default-value="1234"
      :length="4"
      masked
      mask-symbol="*"
      aria-label="掩码验证码"
    /><c-verification-code
      default-value="1234"
      :length="4"
      variant="filled"
      size="lg"
      align="start"
      :gutter="12"
      aria-label="填充验证码"
    /><c-verification-code
      default-value="12"
      :length="4"
      variant="standard"
      focus-color="#6750a4"
      aria-label="线条验证码"
    />
  </div>
</template>
<style scoped>
.verification-demo {
  display: flex;
  flex-direction: column;
  gap: 20px;
  max-width: 420px;
}
</style>
```

### Appearance Lab

Preview configuration: `layout="vertical"`, `aria-label="variant"`, `options`, `variant="button"`.

Example source: src/verification-code/__demos__/appearance-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref("123456");
const __demoAppearance = __demoReactive({ variant: "filled", size: "md" });

import { computed as demoComputed, ref as demoRef } from 'vue'
const demoCompareFields = [{"name":"variant","values":["filled","outline","standard"]},{"name":"size","values":["xs","sm","md","lg","xl"]}]
const demoCompareAxis = demoRef("variant")
const demoComparedOptions = demoComputed(() => demoCompareFields.find(field => field.name === demoCompareAxis.value)?.values ?? [])
</script>
<template>
  <c-space direction="column" :size="16">
    <c-form layout="vertical">
      <c-form-item layout="vertical" size="sm" label="variant">
        <c-radio-group
          v-model="__demoAppearance['variant']"
          aria-label="variant"
          :options="[
            { label: 'filled', value: 'filled' },
            { label: 'outline', value: 'outline' },
            { label: 'standard', value: 'standard' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
      <c-form-item layout="vertical" size="sm" label="size">
        <c-radio-group
          v-model="__demoAppearance['size']"
          aria-label="size"
          :options="[
            { label: 'xs', value: 'xs' },
            { label: 'sm', value: 'sm' },
            { label: 'md', value: 'md' },
            { label: 'lg', value: 'lg' },
            { label: 'xl', value: 'xl' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
    </c-form>
    <p class="demo-config-comparison-hint"><span lang="zh-CN">选择一个对比维度；其他配置和内容保持一致。输入类示例共享同一个值，便于比较外观。</span><span lang="en-US">Compare one dimension while keeping the other settings and content identical. Input specimens share the same value.</span></p>
<c-radio-group v-model="demoCompareAxis" aria-label="Compare configuration" :options="demoCompareFields.map(field => ({ label: field.name, value: field.name }))" />
<div class="demo-config-comparison">
<section v-for="sample in demoComparedOptions" :key="String(sample)">
<p><code>{{ demoCompareAxis }}={{ sample }}</code></p>
<c-verification-code
      v-model="value"
      :length="6"
      v-bind="{ ...__demoAppearance, [demoCompareAxis]: sample }"
    ></c-verification-code>
</section>
</div>
  </c-space>
</template>

<style scoped>
.demo-config-comparison { display: grid; grid-template-columns: repeat(auto-fit, minmax(min(100%, 220px), 1fr)); gap: 20px; min-width: 0; max-width: 100%; }
.demo-config-comparison > section { min-width: 0; }
.demo-config-comparison p { margin: 0 0 8px; }
html:not([lang='en-US']) .demo-config-comparison-hint > [lang='en-US'],
html[lang='en-US'] .demo-config-comparison-hint > [lang='zh-CN'] { display: none; }
</style>
```

### States

- `readonly`: Displays the current value without allowing edits.
- `disabled`: Prevents user interaction.

Example source: src/verification-code/__demos__/states.vue

```vue
<template>
  <div class="verification-demo">
    <c-verification-code default-value="123456" readonly aria-label="只读验证码" /><c-verification-code
      default-value="123456"
      disabled
      aria-label="禁用验证码"
    /><c-verification-code default-value="12" error aria-label="错误验证码" />
  </div>
</template>
<style scoped>
.verification-demo {
  display: flex;
  flex-direction: column;
  gap: 20px;
  max-width: 420px;
}
</style>
```

## Data and options

### Formatting

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration     | Purpose                                                                                                                   | Related examples |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------- | ---------------- |
| `type`            | Character set                                                                                                             | Formatting       |
| `paste-transform` | Paste preprocessing, before type/formatter                                                                                | Formatting       |
| `formatter`       | Per-character formatting: false rejects; true/undefined retains. A returned string contributes its first valid code point | Formatting       |
| `aria-label`      | Group name and numbered cell labels                                                                                       | Formatting       |

<!-- demo-config-notes:end -->

Preview configuration: `type="alphanumeric"`, `:paste-transform="transform"`, `:formatter="(char) => char.toUpperCase()"`, `aria-label="字母数字验证码"`.

Example source: src/verification-code/__demos__/formatting.vue

```vue
<script setup>
import { ref } from 'vue'

const code = ref('')
const transform = (value) => value.replace(/[-\s]/g, '').toUpperCase()
</script>
<template>
  <div class="verification-demo">
    <p>可粘贴 ab-12-cd；从当前格开始写入。</p>
    <c-verification-code
      v-model="code"
      type="alphanumeric"
      :paste-transform="transform"
      :formatter="(char) => char.toUpperCase()"
      aria-label="字母数字验证码"
      ><template #separator="{ index }"><span v-if="index === 2">−</span></template></c-verification-code
    >
    <p>{{ code }}</p>
  </div>
</template>
<style scoped>
.verification-demo {
  max-width: 420px;
}
</style>
```

## Interaction and control

### State Lab

Preview configuration: `:length="6"`.

Example source: src/verification-code/__demos__/state-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref("123456");
const __demoState = __demoReactive({
  disabled: false,
  readonly: false,
  error: false,
});
</script>
<template>
  <c-space direction="column" :size="16">
    <c-space wrap>
      <c-checkbox v-model="__demoState['disabled']">disabled</c-checkbox>
      <c-checkbox v-model="__demoState['readonly']">readonly</c-checkbox>
      <c-checkbox v-model="__demoState['error']">error</c-checkbox>
    </c-space>
    <c-verification-code
      v-model="value"
      :length="6"
      v-bind="__demoState"
    ></c-verification-code>
  </c-space>
</template>
```

## Reading direction

Inherits the nearest `dir="ltr|rtl"` and supports runtime and nested overrides. Codes form an LTR content island: display, paste and focus navigation preserve string order. Outer start/end alignment still follows reading direction. RTL never reverses code characters; numeric and text codes share this ordering contract.

## API

### Empty values and reading placeholders

`empty-values` recognizes empty data; `empty-value` keeps existing clear output. `empty-text` defaults to `'-'` under `read-pretty`, with Field > FormItem > Form precedence and custom read slots first. With explicit empty-values, built-in required uses the policy; custom validators receive original data. See the [shared guide](llms/en-US/guide/empty-values.md).

| Prop         | Type               | Default and scope                                                           |
| ------------ | ------------------ | --------------------------------------------------------------------------- |
| empty-values | readonly unknown[] | Field > FormItem > Form > component-family default; replaces the whole list |
| empty-text   | string             | Field > FormItem > Form > '-'; explicit '' is valid                         |

These props belong to field presentation; pure panels do not gain reading mode. Form and FormItem provide inherited settings. The existing empty-value type and clear fallback remain component-specific.

### Props

| Prop                                    | Description                                                                                                               | Type                                            | Default             |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | ------------------- |
| `model-value`                           | Controlled complete code                                                                                                  | `string`                                        | `undefined`         |
| `default-value`                         | Uncontrolled initial value                                                                                                | `string`                                        | `''`                |
| `length`                                | Positive integer cell count, measured in Unicode code points                                                              | `number`                                        | `6`                 |
| `type`                                  | Character set                                                                                                             | `digit / text / alphanumeric`                   | `digit`             |
| `size`                                  | Five wrapper sizes                                                                                                        | `xs / sm / md / lg / xl`                        | Inherited / md      |
| `variant`                               | Input variant                                                                                                             | `filled / outline / standard`                   | Inherited / outline |
| `disabled / readonly / error`           | State; explicit values override Form                                                                                      | `boolean`                                       | `undefined`         |
| `masked`                                | Visual character masking only, not encryption                                                                             | `boolean`                                       | `false`             |
| `mask-symbol`                           | Use the first Unicode code point                                                                                          | `string`                                        | `•`                 |
| `autofocus`                             | Focus the first empty cell after mounting                                                                                 | `boolean`                                       | `false`             |
| `gutter`                                | Cell gap; numbers are px                                                                                                  | `number / string`                               | Component token     |
| `align`                                 | Horizontal alignment                                                                                                      | `start / center / end`                          | `center`            |
| `allow-paste`                           | Allow pasting; false prevents native paste                                                                                | `boolean`                                       | `true`              |
| `paste-transform`                       | Paste preprocessing, before type/formatter                                                                                | `(text: string) => string`                      | `undefined`         |
| `formatter`                             | Per-character formatting: false rejects; true/undefined retains. A returned string contributes its first valid code point | `(character, index, value) => string / boolean` | `undefined`         |
| `separator`                             | Separator after each nonfinal cell                                                                                        | `(index, character) => VNodeChild`              | `undefined`         |
| `aria-label`                            | Group name and numbered cell labels                                                                                       | `string`                                        | `undefined`         |
| `text-color / focus-color / blur-color` | Dynamic instance colors; prefer tokens for static themes                                                                  | `string`                                        | `undefined`         |

### Events

| Event              | Arguments               | Semantics                                                                                                                                   |
| ------------------ | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| input              | character, index, event | Starting character and zero-based index of each valid native input proposal                                                                 |
| update:model-value | value                   | Complete-code proposal                                                                                                                      |
| change             | value                   | Complete-code proposal for each valid edit, not necessarily accepted by a controlled parent                                                 |
| finish             | value                   | The changed complete code was accepted and filled all cells; accepted edits to already-full codes also emit it. External assignments do not |
| paste              | text, event             | Pasted text after paste-transform/type processing                                                                                           |
| focus / blur       | FocusEvent              | Focus enters/leaves the whole component; moving between cells does not duplicate notifications                                              |
| click              | MouseEvent              | Non-disabled click                                                                                                                          |

Valid input order: input → update:modelValue → change. finish waits until the parent accepts the complete value in that render. Rejected controlled values restore native inputs; later asynchronous parent assignments do not add finish. reset() proposes empty and emits update:modelValue/change without simulating native input. Disabled, readonly or composing state prevents reset from changing values.

Paste overwrites from the current cell; pasting on the root starts at cell 1. Input beyond the first empty cell is redirected there. SMS autofill entered as a whole code distributes across later cells. Typing one character in a filled cell replaces it even with the caret after the old character. IME prefers the current compositionend text and distributes multiple code points, falling back to native value only when committed text is absent. Processing is type filter → formatter → length trim; rejected characters occupy no cells. text counts Unicode code points, not grapheme clusters. External updates affect display without formatting/writeback.

### Slots

| Slot      | Arguments            | Description                                           |
| --------- | -------------------- | ----------------------------------------------------- |
| separator | { index, character } | Overrides separator; not rendered after the last cell |

### Expose

- focus(index?): zero-based index; omission selects the first empty cell or last cell when full. Disabled prevents focusing; readonly allows focus/copy.
- blur(): remove focus.
- reset(): propose clearing, respecting controlled/disabled/readonly state.

### Keyboard and Form

Left/Right move between cells. Backspace removes the current character, or the previous one when empty. Delete removes the current character; following characters shift forward. IME composition does not trim, delete or move focus. Each native input has an SSR-stable id. Cell 1 uses autocomplete=one-time-code, others off. Provide aria-label.

InputGroup/Form state is inherited, with explicit disabled/readonly/error/size taking precedence. Internal cell Inputs do not duplicate Form notifications; the complete control notifies input/change once per edit. Both platforms implement three variants/five sizes using local FieldDecorator tokens.

## Type definitions

VerificationCodeProps、VerificationCodeType、VerificationCodeAlign、VerificationCodeVariant、VerificationCodeFormatter、VerificationCodeSeparator、VerificationCodeEmits、VerificationCodeSlots、VerificationCodeExpose、VerificationCodeInstance。

## Style variables

| Variable                              | Default              | Description                                                      |
| ------------------------------------- | -------------------- | ---------------------------------------------------------------- |
| --c-verification-code-gutter          | var(--c-sys-space-2) | Cell gap                                                         |
| --c-verification-code-cell-height     | initial              | Follows size-specific field-size-*-height when not overridden    |
| --c-verification-code-cell-max-width  | initial              | Follows size-specific field-size-*-height when not overridden    |
| --c-verification-code-input-font-size | initial              | Follows size-specific field-size-*-font-size when not overridden |

initial means no public override. CSS reads size fallbacks at the component element. Override through component style or theme. Old Cedar column-gap is removed; use gutter.

### Form field presentation and confirmation

This component supports `edit-mode` with field > FormItem > Form precedence. When unset, it defaults to `direct` and preserves `direct` editing. Supported values: `direct / click / dblclick`. Non-`direct` modes open the editor through the field value trigger and keep one draft; v-model updates only after confirmation. Cancel, reset or enabling readPretty discards the draft.

Cedar uses edit-mode="click" / "dblclick" to open an editor popup near the field. Enter/F2 also opens it; cancel/Escape discards the draft, and confirmation commits it. readPretty is an independent reading setting, separate from readonly and disabled.

`before-commit(value, { previousValue, signal })` can reject an overlay save. FormItem validates the candidate first and keeps the editor open on failure. `open / default-open / update:open` control the editor. Use `#read="{ value, text }"` to customize display. See the full field comparison in Form.

`read-pretty` is an independent boolean alongside `readonly` and `disabled`. It inherits from field to FormItem to Form; explicit `false` overrides the parent. The default is `false`. Reading mode renders no editor.

---

Document: llms/en-US/components/watermark.md

<!-- Source: src/watermark/README.en-US.md; locale: en-US; page: /en/components/watermark/ -->

# Watermark

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

Preview configuration: `:content="content"`, `:font="{ color: dark ? 'rgba(255,255,255,0.4)' : 'rgba(0,0,0,0.25)' }"`.

Example source: src/watermark/__demos__/basic.vue

```vue
<script setup>
import { ref } from "vue";
const dark = ref(false);
const shown = ref(true);
const content = ref("LOCAL DEMO 200");
const clicks = ref(0);
</script>

<template>
  <section class="watermark-contrast-demo">
    <c-checkbox v-model="dark"> Dark surface / 深色底</c-checkbox>
    <c-checkbox v-model="shown"> Show watermark / 显示水印</c-checkbox>
    <label>Watermark text / 水印文字<c-input v-model="content" /></label>
    <c-watermark
      v-if="shown"
      :content="content"
      :font="{ color: dark ? 'rgba(255,255,255,0.4)' : 'rgba(0,0,0,0.25)' }"
      :style="{
        background: dark ? '#1f2937' : '#ffffff',
        color: dark ? '#ffffff' : '#111827',
      }"
    >
      <div class="watermark-contrast-surface">
        <p>Local synthetic content / 本地合成内容</p>
        <c-button html-type="button" @click="clicks++"
          >Click through / 点击内容</c-button
        >
      </div>
    </c-watermark>
    <p role="status">
      Visible: {{ shown }} · Dark: {{ dark }} · Clicks: {{ clicks }}
    </p>
  </section>
</template>
<style scoped>
.watermark-contrast-surface {
  min-height: 240px;
  display: grid;
  place-content: center;
  gap: 12px;
}
</style>
```

## Content and presentation

### Multiline

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `content` | One or more text lines; also used when an image fails | Multiline, Image, Fullscreen |
| `image` | Image URL, preferred over text | Image |
| `width` | Mark width; measured from content by default | Image |
| `height` | Mark height; measured from content by default | Image |
| `font` | Text style | Image |
| `fullscreen` | Cover the viewport | Fullscreen |
<!-- demo-config-notes:end -->


Preview configuration: `:content="['Cedar Design', dayjs().format('YYYY-MM-DD')]"`.

Example source: src/watermark/__demos__/multiline.vue

```vue
<template>
  <c-watermark :content="['Cedar Design', dayjs().format('YYYY-MM-DD')]">
    <div style="width: 100%; height: 300px" />
  </c-watermark>
</template>

<script lang="ts" setup>
import dayjs from "dayjs";
</script>
```

### Image

- `width`: Sets the configured width.
- `height`: Constrains the component height.

Example source: src/watermark/__demos__/image.vue

```vue
<script setup>
import { computed, ref } from "vue";
const failed = ref(false);
const errors = ref([]);
const localImage =
  "data:image/svg+xml," +
  encodeURIComponent(
    '<svg xmlns="http://www.w3.org/2000/svg" width="160" height="48"><rect width="160" height="48" rx="8" fill="#0284c7"/><circle cx="80" cy="24" r="14" fill="white"/></svg>',
  );
const image = computed(() =>
  failed.value ? "data:image/png;base64,invalid-local-image" : localImage,
);
</script>
<template>
  <section class="watermark-image-failure-demo">
    <c-checkbox v-model="failed"> Fail local image / 本地图片失败</c-checkbox>
    <c-button html-type="button" :disabled="!failed" @click="failed = false"
      >Restore image / 恢复图片</c-button
    >
    <c-watermark
      content="FALLBACK 201"
      :image="image"
      :width="160"
      :height="48"
      :font="{ color: '#be123c' }"
      style="background: white"
      @error="errors.push($event.source)"
    >
      <div style="height: 240px" />
    </c-watermark>
    <p role="status">
      Mode: {{ failed ? "failure" : "image" }} · Errors:
      {{ errors.join(",") || "-" }}
    </p>
  </section>
</template>
```

### Fullscreen

Preview configuration: `content="Cedar Design"`, `:fullscreen="fullscreen"`, `:z-index="99"`.

Example source: src/watermark/__demos__/fullscreen.vue

```vue
<script setup lang="ts">
import { ref } from "vue";

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

<template>
  <c-watermark content="Cedar Design" :fullscreen="fullscreen" :z-index="99">
    <div class="watermark-fullscreen-demo">
      <c-button status="primary" @click="fullscreen = !fullscreen">
        {{ fullscreen ? "退出全屏水印" : "开启全屏水印" }}
      </c-button>
    </div>
  </c-watermark>
</template>

<style scoped>
.watermark-fullscreen-demo {
  min-height: 160px;
  display: grid;
  place-items: center;
}
</style>
```

## Customization and slots

### Custom

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `content` | One or more text lines; also used when an image fails | Custom |
| `rotate` | Rotation angle | Custom |
| `gap` | Watermark gap `[x, y]` | Custom |
| `offset` | First mark offset; defaults to half the gap | Custom |
| `font` | Text style | Custom |
<!-- demo-config-notes:end -->


Preview configuration: `size="sm"`, `:model="form"`, `auto-label-width`, `:gutter="16"`.

Example source: src/watermark/__demos__/custom.vue

```vue
<template>
  <c-form size="sm" :model="form" auto-label-width>
    <c-row :gutter="16">
      <c-col :span="24">
        <c-form-item field="rotate" label="rotate">
          <c-slider v-model="form.rotate" :min="-180" :max="180" />
        </c-form-item>
      </c-col>
      <c-col :span="12">
        <c-form-item label="gap">
          <c-input-group>
            <c-input-number
              v-model="form.gap[0]"
              placeholder="gap[x]"
              :min="0"
            />
            <c-input-number
              v-model="form.gap[1]"
              placeholder="gap[y]"
              :min="0"
            />
          </c-input-group>
        </c-form-item>
      </c-col>
      <c-col :span="12">
        <c-form-item label="offset">
          <c-input-group>
            <c-input-number v-model="form.offset[0]" placeholder="offsetLeft" />
            <c-input-number v-model="form.offset[1]" placeholder="offsetTop" />
          </c-input-group>
        </c-form-item>
      </c-col>
      <c-col :span="12">
        <c-form-item label="fontSize">
          <c-input-number v-model="form.font.fontSize" mode="button" />
        </c-form-item>
      </c-col>
      <c-col :span="12">
        <c-form-item label="zIndex">
          <c-input-number v-model="form.zIndex" mode="button" />
        </c-form-item>
      </c-col>
      <c-col :span="6">
        <c-form-item label="repeat">
          <c-switch v-model="form.repeat" />
        </c-form-item>
      </c-col>
      <c-col :span="6">
        <c-form-item label="staggered">
          <c-switch v-model="form.staggered" />
        </c-form-item>
      </c-col>
    </c-row>
  </c-form>
  <c-watermark content="arco.design" v-bind="form">
    <div style="width: 100%; border: 1px solid #e5e6eb; box-sizing: border-box">
      <c-typography-title :heading="5"> Design system</c-typography-title>
      <c-typography>
        <c-typography-paragraph>
          A design is a plan or specification for the construction of an object
          or system or for the implementation of an activity or process, or the
          result of that plan or specification in the form of a prototype,
          product or process. The verb to design expresses the process of
          developing a design.
        </c-typography-paragraph>
        <c-typography-paragraph>
          A design is a plan or specification for the construction of an object
          or system or for the implementation of an activity or process, or the
          result of that plan or specification in the form of a prototype,
          product or process. The verb to design expresses the process of
          developing a design.
        </c-typography-paragraph>
      </c-typography>
      <img
        style="position: relative; z-index: 7"
        src="https://p1-arco.byteimg.com/tos-cn-i-uwbnlip3yd/24e0dd27418d2291b65db1b21aa62254.png~tplv-uwbnlip3yd-webp.webp"
      />
    </div>
  </c-watermark>
</template>

<script lang="ts" setup>
import { reactive } from "vue";

const form = reactive({
  rotate: 0,
  gap: [50, 50],
  offset: [],
  font: { fontSize: 16 },
  zIndex: 6,
  repeat: true,
  staggered: true,
});
</script>
```

## API

### Props

| Arguments | Description | Type | Default |
| ------------- | ------------------------------------------ | -------------------- | -------------------------- |
| `content` | One or more text lines; also used when an image fails | `string \| string[]` | `-` |
| `image` | Image URL, preferred over text | `string` | `-` |
| `width` | Mark width; measured from content by default | `number` | `-` |
| `height` | Mark height; measured from content by default | `number` | `-` |
| `gap` | Watermark gap `[x, y]` | `[number, number]` | `[90, 90]` |
| `offset` | First mark offset; defaults to half the gap | `[number, number]` | `[gap[0] / 2, gap[1] / 2]` |
| `rotate` | Rotation angle | `number` | `-22` |
| `font` | Text style | `WatermarkFont` | `-` |
| `z-index` | Layer z-index | `number` | `6` |
| `alpha` | Overall opacity in the `0..1` range | `number` | `1` |
| `anti-tamper` | Restore a removed or modified layer | `boolean` | `true` |
| `grayscale` | Render in grayscale | `boolean` | `false` |
| `repeat` | Repeat the mark | `boolean` | `true` |
| `staggered` | Stagger repeated rows | `boolean` | `true` |
| `fullscreen` | Cover the viewport | `boolean` | `false` |

### WatermarkFont

| Arguments | Type | Default |
| ------------ | ----------------------------------- | ---------------------------------- |
| `color` | `string` | `var(--c-watermark-content-color)` |
| `fontSize` | `number` | `16` |
| `fontFamily` | `string` | `sans-serif` |
| `fontStyle` | `'normal' \| 'italic' \| 'oblique'` | `normal` |
| `fontWeight` | `string \| number` | `normal` |
| `textAlign` | `CanvasTextAlign` | `center` |
| `lineHeight` | `number` | `fontSize × 1.4` |

### Events

| Event | Description | Arguments |
| ------- | -------------------------- | ------------------------------------------------- |
| `error` | Image loading or Canvas rendering failed | `{ source: 'image' \| 'canvas'; error: unknown }` |

### Methods

| Method | Description | Returns |
| -------- | ---------------------- | --------------- |
| `redraw` | Regenerate the watermark from current props | `Promise<void>` |

### Slots

| Slot | Description |
| --------- | -------------------- |
| `default` | Page content covered by the watermark |

### CSS variables

| Variable | Default |
| ----------------------------- | --------------------- |
| `--c-watermark-content-color` | `rgba(0, 0, 0, 0.15)` |

---

Document: llms/en-US/guide/controlled-uncontrolled.md

<!-- Source: docs/en/guide/controlled-uncontrolled.md; locale: en-US; page: /en/guide/controlled-uncontrolled/ -->

# Controlled state, defaults and clear values: learn by interaction

Start with Input behavior, then expand v-model and finally examine emptyValue. This guide describes current workspace behavior; the proposed unified contract is discussed separately at the end.

Register components and include styles as described in Quick Start. Each complete Vue example is independent. Input examples explicitly use `edit-mode="direct"` so popup confirmation drafts do not obscure ownership.

## 1. Separate the questions

| Question                                | What determines it?                          | Example                                                |
| --------------------------------------- | -------------------------------------------- | ------------------------------------------------------ |
| Who decides the final current value?    | modelValue and the component ownership check | Parent supplies A, rejects B, final value remains A    |
| Is this only an initial value?          | defaultValue                                 | Start with Hangzhou, let the user change it later      |
| What value does a clear action propose? | emptyValue, written empty-value in templates | null, an empty string, or a configured value           |
| Does a value look empty?                | Component type, options and formatting       | Input renders null as blank, but EMPTY as literal text |

Controlled means the parent owns the final value. It does not mean disabled, unfocusable, without input events, or stored on a server. The parent is the Vue component containing `<c-input ... />`; its ref or form object holds the external state.

emptyValue answers the clear-output question. It does not automatically answer ownership or empty-value recognition. It is not a list of values considered empty.

## 2. Uncontrolled: provide a seed, let the component store later edits

```vue
<script setup lang="ts">
import { ref } from "vue";

const seed = ref("Hangzhou");
const instanceKey = ref(0);
const lastRequest = ref<string | null>();
function record(next: string | null) {
  lastRequest.value = next;
}
</script>

<template>
  <c-input
    :key="instanceKey"
    :default-value="seed"
    edit-mode="direct"
    @update:model-value="record"
  />
  <p>Initial seed: {{ seed }}</p>
  <p>Last update request: {{ JSON.stringify(lastRequest) }}</p>
  <button type="button" @click="seed = 'Beijing'">Change default only</button>
  <button type="button" @click="instanceKey++">Remount</button>
</template>
```

| Action                             | Input text   | Parent seed | Explanation                                                            |
| ---------------------------------- | ------------ | ----------- | ---------------------------------------------------------------------- |
| Mount                              | Hangzhou     | Hangzhou    | The component reads the default                                        |
| Select all and replace with Suzhou | Suzhou       | Hangzhou    | The component stores the edit; recording an event does not modify seed |
| Change default only                | Still Suzhou | Beijing     | Defaults do not overwrite current edits                                |
| Remount                            | Beijing      | Beijing     | The new instance reads the current default                             |

An update listener only observes candidates. Without binding the recorded value back through modelValue, it does not control the component. Initialization does not emit an initial value to populate the parent.

Changing defaultValue is not a reset command. Use controlled binding when the application needs to replace the current value programmatically.

## 3. Controlled and accepting updates

```vue
<script setup lang="ts">
import { ref } from "vue";
const text = ref<string | null>("A");
</script>

<template>
  <c-input v-model="text" edit-mode="direct" />
  <p>Parent value: {{ JSON.stringify(text) }}</p>
  <button type="button" @click="text = 'C'">Parent sets C</button>
</template>
```

Select A and replace it with B. Parent text becomes B and the input follows that parent value. Click the button and the parent replaces it with C.

```text
Parent text=A → input receives A
User enters B → component emits update:modelValue(B)
Parent assigns text=B → prop becomes B → final display is B
```

Writing back means assigning the parent's own ref/form field and passing that value down again. The child does not directly modify the parent variable. v-model generates the write-back binding for you. [Vue documentation](https://vuejs.org/guide/components/v-model.html)

## 4. Controlled and rejecting updates

```vue
<script setup lang="ts">
import { ref } from "vue";
const text = ref<string | null>("A");
const requested = ref<string | null>();
const count = ref(0);
function recordOnly(next: string | null) {
  requested.value = next;
  count.value++;
  // Deliberately do not assign text.value = next.
}
</script>

<template>
  <c-input
    :model-value="text"
    edit-mode="direct"
    @update:model-value="recordOnly"
  />
  <p>Parent value: {{ JSON.stringify(text) }}</p>
  <p>Candidate: {{ JSON.stringify(requested) }}; requests: {{ count }}</p>
</template>
```

Select all of A and try entering B. The candidate becomes B and the counter increases, but parent text stays A. The settled input remains A. Native editing text can appear briefly before the component reconciles; judge the final state after the current update settles.

| Item                | Before | After proposing B |
| ------------------- | ------ | ----------------- |
| Parent text         | A      | A                 |
| Candidate           | None   | B                 |
| Final model/display | A      | A                 |

An update event is not proof of acceptance. The parent can accept, reject or correct a candidate.

For an intentionally non-editable field, use readonly/disabled and their documented focus, copy and event semantics. Ignoring updates here demonstrates ownership; it is not the recommended way to implement readonly UI.

## 5. Accept conditionally

A boolean Switch makes the decision easy to see:

```vue
<script setup lang="ts">
import { ref } from "vue";
const enabled = ref(false);
const allowUpdate = ref(false);
const requested = ref<string | number | boolean | null>();
function decide(next: string | number | boolean | null) {
  requested.value = next;
  if (allowUpdate.value && typeof next === "boolean") {
    enabled.value = next;
  }
}
</script>

<template>
  <label
    ><input v-model="allowUpdate" type="checkbox" />Parent accepts
    updates</label
  >
  <c-switch :model-value="enabled" @update:model-value="decide" />
  <p>Parent value: {{ enabled }}；Candidate: {{ JSON.stringify(requested) }}</p>
</template>
```

With the native checkbox unchecked, clicking Switch proposes true but leaves the parent and Switch false. Enable the checkbox, click again, and the parent accepts true.

This uses Switch's default boolean values. Adapt the parent type and decision if checkedValue/uncheckedValue are customized. When acceptance requires asynchronous work, show pending explicitly so a request is not mistaken for a completed change.

## 6. What does v-model generate?

```html
<c-input v-model="text" />
```

The corresponding template binding is:

```html
<c-input :model-value="text" @update:model-value="text = $event" />
```

Script functions assign `text.value = next`; templates unwrap refs automatically.

| Binding                             | Passes an external value? | Writes updates back?                                          | Meaning for strict controlled components |
| ----------------------------------- | ------------------------- | ------------------------------------------------------------- | ---------------------------------------- |
| default-value only                  | No                        | No                                                            | Component stores subsequent values       |
| Update listener only                | No                        | Depends on listener, but not controlling without binding back | Observation                              |
| model-value=A only                  | Yes                       | No                                                            | Final value remains A                    |
| model-value plus recording listener | Yes                       | No                                                            | Observe candidates, keep A               |
| model-value plus assignment handler | Yes                       | Yes                                                           | Parent may filter updates                |
| v-model=text                        | Yes                       | Automatically                                                 | Usually accepts every update             |

For components checking modelValue !== undefined, a v-model ref initialized to undefined still starts uncontrolled. Local proxy exceptions also exist; see section 15.

Adding an update listener to v-model and returning false does not cancel v-model's generated assignment. Use an explicit value binding and handler when rejection matters. Returning false from change is not a guard either. Do not execute the same save twice in both update and change handlers.

## 7. Does emptyValue conflict with controlled state?

The features are compatible. The specific problem is undefined carrying two meanings in a particular binding.

For models using this ownership rule, including Input, InputNumber, Switch, Slider and Select:

```ts
// Conceptual rule, not code users need to add.
const isControlled = modelValue !== undefined;
```

An empty string, 0, false and a supported null are defined values. Validity remains component-specific: a defined 0 is not automatically a valid page number.

| Clear candidate | Parent decision                    | Returned modelValue | Result                                             |
| --------------- | ---------------------------------- | ------------------- | -------------------------------------------------- |
| null            | Accept                             | null                | Controlled if null is supported                    |
| Empty string    | Accept                             | Empty string        | Controlled                                         |
| undefined       | Accept unchanged                   | undefined           | Becomes uncontrolled                               |
| undefined       | Normalize to null                  | null                | Remains controlled                                 |
| Any candidate   | Ignore, retain A                   | A                   | Retains the original controlled state              |
| undefined       | Component was already uncontrolled | Unbound             | Internal empty state; no parent control to release |

Do not infer ownership loss from emptyValue alone. The mode changes when the parent actually passes undefined back, not merely when the factory runs or an event is observed.

## 8. The empty-value forms are different

Current resolveEmptyValue behavior uses each component's fallback when no override is provided:

| Configuration                    | Meaning                                                                 |
| -------------------------------- | ----------------------------------------------------------------------- |
| Omitted                          | Component's current default clear output                                |
| `:empty-value="undefined"`       | Same fallback; does not force undefined output                          |
| `:empty-value="() => undefined"` | Explicit undefined output, where the component type permits the factory |
| `:empty-value="null"`            | Explicit null output                                                    |
| `empty-value="EMPTY"`            | Literal EMPTY string, not necessarily a blank display                   |
| `:empty-value="0"`               | Numeric zero, if valid for this component                               |
| `:empty-value="() => []"`        | New empty array, subject to model and business constraints              |

The factory distinguishes absence from an explicit undefined result. Input's clear type is string/null or a matching factory; do not bypass its type to force an unsupported undefined factory. The next undefined example uses InputNumber, which supports it.

Vue binding matters: `empty-value="null"` is a string, while `:empty-value="null"` is null. An unbound `empty-value="0"` is not a numeric binding.

Verified current default paths:

| Component/path                               | Default candidate without an override                   |
| -------------------------------------------- | ------------------------------------------------------- |
| Input clear button                           | Empty string                                            |
| InputNumber clear button                     | undefined                                               |
| Select single without an empty-string option | Usually empty string                                    |
| Select single with a value='' option         | undefined, distinguishing that option from no selection |
| Select multiple                              | Usually []; protected disabled selections may remain    |

This is not an inventory of all component empty-value contracts. Dates, times and panels have additional paths. emptyValue does not bypass disabled/readonly, pending transactions or protected selections.

## 9. Input clears to null and stays controlled

```vue
<script setup lang="ts">
import { ref } from "vue";
const text = ref<string | null>("A");
const updates = ref<string[]>([]);
function accept(next: string | null) {
  updates.value.push(JSON.stringify(next));
  text.value = next;
}
</script>

<template>
  <c-input
    :model-value="text"
    :empty-value="null"
    edit-mode="direct"
    clearable
    @update:model-value="accept"
  />
  <p>Parent value: {{ JSON.stringify(text) }}</p>
  <p>Update log: {{ updates.join(" → ") }}</p>
</template>
```

| Action                               | Candidate    | Parent text  | Display |
| ------------------------------------ | ------------ | ------------ | ------- |
| Mount                                | None         | A            | A       |
| Click clear                          | null         | null         | Blank   |
| Type B                               | B            | B            | B       |
| Select all and delete with Backspace | Empty string | Empty string | Blank   |

null and an empty string look blank but are different model values. Current emptyValue controls the clear action; it does not transform manual deletion into null. If your business requires every empty text value to be null, assign `text.value = next === '' ? null : next` in the parent.

Likewise, an Input configured with literal EMPTY emits and displays EMPTY on clear. A clear button does not guarantee a blank final model.

## 10. Why can undefined clear change ownership?

This example observes current behavior. It is not the recommended configuration for a persistently controlled form.

```vue
<script setup lang="ts">
import { ref } from "vue";
const quantity = ref<number | null | undefined>(12);
const clearToUndefined = () => undefined;
const describe = (value: unknown) =>
  value === undefined ? "undefined" : JSON.stringify(value);
const lastRequest = ref("No update yet");
function accept(next: number | null | undefined) {
  lastRequest.value = describe(next);
  quantity.value = next;
}
</script>

<template>
  <c-input-number
    :model-value="quantity"
    :empty-value="clearToUndefined"
    edit-mode="direct"
    clearable
    @update:model-value="accept"
  />
  <p>Parent value: {{ describe(quantity) }}；Candidate: {{ lastRequest }}</p>
  <p>Controlled by the current check: {{ quantity !== undefined }}</p>
</template>
```

| Step                                                     | Parent quantity | quantity !== undefined | Final owner                                      |
| -------------------------------------------------------- | --------------- | ---------------------- | ------------------------------------------------ |
| Initially 12                                             | 12              | true                   | Parent                                           |
| Component proposes undefined, before handling            | Still 12        | true                   | Still parent                                     |
| Parent accepts unchanged                                 | undefined       | false                  | Component                                        |
| Later interaction while parent supplies no defined value | undefined       | false                  | Component may store subsequent values internally |

The trigger is the actual modelValue becoming undefined, not the blank display. A later defined parent value makes it controlled again. Current handoff retention varies between components; do not rely on mode changes for reset.

A ref's declared number/null type does not convert a runtime undefined event into null automatically.

## 11. Recommended: normalize at the parent boundary

```vue
<script setup lang="ts">
import { ref } from "vue";
const quantity = ref<number | null>(12);
const lastRequest = ref("No update yet");
function acceptNormalized(next: number | null | undefined) {
  lastRequest.value = next === undefined ? "undefined" : JSON.stringify(next);
  quantity.value = next ?? null;
}
</script>

<template>
  <c-input-number
    :model-value="quantity"
    :empty-value="null"
    edit-mode="direct"
    clearable
    @update:model-value="acceptNormalized"
  />
  <p>组件Candidate: {{ lastRequest }}</p>
  <p>Final parent value: {{ JSON.stringify(quantity) }}</p>
  <p>Controlled by the current check: {{ quantity !== undefined }}</p>
</template>
```

This handles the clear button and other update paths producing undefined: null → null, undefined → null, 0 → 0, other numbers unchanged. The parent's quantity remains defined, preserving final controlled ownership.

Why use a handler as well as empty-value=null? InputNumber's clear-button path calls resolveEmptyValue, while manual deletion followed by commit can directly produce undefined. modelEvent='input' may propose the empty value earlier. emptyValue is not an input parser or a normalizer for every submission path.

Avoid `next || null`, which also discards valid zero. Use `next ?? null` for null/undefined only. Do not apply this nullable-number example to a model such as pagination that does not accept null.

A writable computed setter can perform the same normalization behind v-model; a readonly computed cannot accept assignments. Separate local updates from persistence. Usually update the form synchronously and save on explicit submission; if acceptance must wait for approval, keep the old value and show pending deliberately.

## 12. A valid empty-string option differs from no selection

```vue
<script setup lang="ts">
import { ref } from "vue";
const selected = ref<string | null>(null);
const options = [
  { label: "All", value: "" },
  { label: "Enabled only", value: "enabled" },
];
</script>

<template>
  <c-select
    v-model="selected"
    :options="options"
    :empty-value="null"
    edit-mode="direct"
    clearable
  />
  <p>Parent value: {{ JSON.stringify(selected) }}</p>
</template>
```

| Action              | Parent selected | Meaning                        |
| ------------------- | --------------- | ------------------------------ |
| Initially           | null            | No selection                   |
| Choose All          | Empty string    | A valid selected option        |
| Choose Enabled only | enabled         | Another valid option           |
| Clear               | null            | No selection, still controlled |

Do not use selected === '' to mean both All and no selection. Element Plus illustrates a similar case but exposes separate empty-values and value-on-clear APIs. Our emptyValue does not automatically provide its empty-values functionality.

For multiple selection, initialize and clear according to the array model. A nullable single-selection example does not imply that every multi-selection should use null. Protected disabled selections can survive clear; emptyValue does not override that rule.

## 13. Value and popup visibility are separate models

```vue
<script setup lang="ts">
import { ref } from "vue";
const selected = ref<string | null>(null);
const panelOpen = ref(false);
const allowClose = ref(true);
const options = [
  { label: "Hangzhou", value: "hz" },
  { label: "Beijing", value: "bj" },
];
function acceptOpen(next: boolean) {
  if (next || allowClose.value) panelOpen.value = next;
}
</script>

<template>
  <label
    ><input v-model="allowClose" type="checkbox" />Accept close requests</label
  >
  <c-select
    v-model="selected"
    :open="panelOpen"
    :options="options"
    :empty-value="null"
    edit-mode="direct"
    clearable
    @update:open="acceptOpen"
  />
  <p>Value: {{ JSON.stringify(selected) }}; open: {{ panelOpen }}</p>
  <button type="button" @click="panelOpen = false">
    Parent closes directly
  </button>
</template>
```

The value binding accepts updates directly; the visibility handler can reject close requests. Disable Accept close requests: value changes can still be accepted while close requests are ignored. Parent closes directly changes panelOpen itself.

There is no single global controlled flag for the whole component. Each model has its own owner. v-model:open is shorthand for open plus its update assignment.

This example uses Select's direct editing mode. Confirmation presentations additionally own a draft: selecting edits the draft, confirmation submits it and cancellation discards it. A visible draft changing does not prove the committed model is uncontrolled.

## 14. Initialize, reset and serialize form data

```vue
<script setup lang="ts">
import { reactive, ref } from "vue";
const form = reactive<{ name: string | null; quantity: number | null }>({
  name: null,
  quantity: null,
});
const payloadText = ref("Not submitted yet");
function updateQuantity(next: number | null | undefined) {
  form.quantity = next ?? null;
}
function reset() {
  form.name = null;
  form.quantity = null;
}
function submit() {
  const payload = {
    name: form.name === null ? undefined : form.name,
    quantity: form.quantity === null ? undefined : form.quantity,
  };
  payloadText.value = JSON.stringify(payload);
}
</script>

<template>
  <c-input
    v-model="form.name"
    :empty-value="null"
    edit-mode="direct"
    clearable
  />
  <c-input-number
    :model-value="form.quantity"
    :empty-value="null"
    edit-mode="direct"
    clearable
    @update:model-value="updateQuantity"
  />
  <button type="button" @click="reset">Reset parent data</button>
  <button type="button" @click="submit">Build payload</button>
  <p>Payload: {{ payloadText }}</p>
</template>
```

This uses an ordinary reactive object without depending on Form layout/validation APIs. The parent initializes and resets its fields. defaultValue does not populate an empty parent form; initialize form.name directly when a name is required initially.

Serialization maps UI null to undefined object properties, which JSON omits, without changing the UI model itself. If the API expects explicit JSON null, retain null in the payload instead.

UI empty values and transport formats need not match. A backend's omitted-field convention does not require modelValue to be undefined. Empty strings are still sent unchanged in this example; omit them explicitly at the serialization boundary if your business requires it.

## 15. Current exceptions

These describe current behavior, not an implemented target contract:

| Scope                                | Difference                                                                                 |
| ------------------------------------ | ------------------------------------------------------------------------------------------ |
| Maple ActionSheet.open               | Default useVModel local proxy can change internal state                                    |
| Maple NumberKeyboard.open/modelValue | Both use the default proxy                                                                 |
| Maple FloatingPanel.modelValue       | Proxy anchor plus separate gesture display height                                          |
| Maple Popup with beforeClose         | Internal visible can intercept external open=false and emit update:open(true) on rejection |
| Both Collapse implementations        | Nullish fallback; null falls back internally, use [] to collapse all                       |

For the first three, ignoring update does not guarantee the display remains unchanged. Passing the same external value again may not trigger the proxy watcher. Both libraries have equivalent useVModel helpers, but Input/Switch/Slider manage their own ownership.

InputNumber may retain intermediate text, Input has IME composition, and Popup can retain transition DOM. Distinguish final models from editing/gesture state and animation retention.

## 16. Documentation patterns worth borrowing

These are references for explanation style, not interchangeable APIs, empty values or handoff rules. All examples above were written for our components.

| Reference                                                                                                                            | Useful teaching pattern                                                       |
| ------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------- |
| [Reka controlled state](https://www.reka-ui.com/docs/guides/controlled-state)                                                        | Place explicit write-back, v-model and defaultValue side by side              |
| [React Input](https://react.dev/reference/react-dom/components/input#controlling-an-input-with-a-state-variable)                     | Explain ownership through visible reversion when updates are ignored          |
| [Radix async Dialog submission](https://www.radix-ui.com/primitives/docs/components/dialog#close-after-asynchronous-form-submission) | Show why a parent closes only after saving                                    |
| [Element Plus Select empty values](https://element-plus.org/en-US/component/select.html#empty-values)                                | Separate empty recognition and clear output using a valid empty-string option |
| [Naive UI controlled state](https://www.naiveui.com/zh-CN/docs/controlled-uncontrolled)                                              | State how undefined affects ownership explicitly                              |

React's native controlled text input should not receive null/undefined. Our Input supports null and renders it blank. Borrow explanations, not framework-specific empty-value constraints. A value-only binding can also be intentional; it is an error only relative to an expectation of accepting edits.

## 17. Proposed design and existing emptyValue

The unified design is not implemented. The recommendation is parent-owned final state, initialize-only defaults, defined domain values for standard clear output, and separate drafts/gestures/animation.

Retain configurable emptyValue output rather than treating every () => undefined as invalid. It remains useful with explicit parent normalization, published APIs and intentional business behavior. Passing the result back unchanged as undefined must still mean uncontrolled under the chosen predicate.

Audit all empty paths separately: clear buttons, keyboard deletion, panel clearing and Form reset. Fixing the button alone leaves gaps. Changing published default empty values, ownership handoff or proxy behavior requires a versioned migration; changing documentation does not implement that behavior.

## 18. Troubleshooting order

1. Identify the exact state: modelValue, open or a draft.
2. Inspect the actual external value, not only the ref's static type or blank display.
3. Record update candidates and inspect whether/how the parent assigns them.
4. Distinguish clear button, manual deletion, panel confirmation and Form reset.
5. Check whether emptyValue is omitted, null, a string or an undefined-returning factory.
6. Check the proxy/guard exceptions in section 15.

Source references: both libraries' packages/_-ui/src/input/use-input-value.ts, input-number/use-number-value.ts, select/use-select-controller.ts and empty-value helpers; packages/_-use/src/useVModel.ts; Maple's listed proxy components and Popup. Expected-value tables explain audited paths; they are not a claim that every component and browser interaction has been verified.

---

Document: llms/en-US/guide/empty-values.md

<!-- Source: docs/en/guide/empty-values.md; locale: en-US; page: /en/guide/empty-values/ -->

# Empty recognition, clear output and reading placeholders

## Choose the setting for your task

| Task                                                       | Setting                                    | Example                               |
| ---------------------------------------------------------- | ------------------------------------------ | ------------------------------------- |
| Emit null, -1 or another supported value when clearing     | empty-value / emptyValue                   | Clear icon and manual deletion        |
| Treat API marker -1 as unselected and missing for required | empty-values / emptyValues                 | Empty markers and required validation |
| Keep an empty string as a valid All option                 | Exclude the empty string from empty-values | Valid empty-string option             |
| Show '-' or No data for empty reading content              | empty-text / emptyText                     | Reading placeholders and inheritance  |

Each prop has one job. emptyValue defines clear output, emptyValues defines empty identity, and emptyText defines reading text. They do not derive one another. Rendering or configuration changes do not write the model or change controlled ownership.

## Learn by scenario

### Clear icon and manual deletion

Clear with the icon to produce null. Restore the initial value and delete all text with Backspace to produce `''`. The model output quotes strings so the two outcomes are visible.

Example source: src/input/__demos__/en-US/empty-value.vue

```vue
<script setup lang="ts">
import { reactive } from "vue";
const model = reactive({ text: "Hello" as string | null });
</script>
<template>
  <c-space direction="column">
    <p>
      The clear icon produces null; Backspace to empty produces an empty string.
    </p>
    <c-form :model="model" layout="vertical">
      <c-form-item field="text" label="Keyword">
        <c-input
          v-model="model.text"
          edit-mode="direct"
          clearable
          :empty-value="null"
        />
      </c-form-item>
    </c-form>
    <c-button @click="model.text = 'Hello'">Restore initial value</c-button>
    <p>
      Current model: <output>{{ JSON.stringify(model.text) }}</output>
    </p>
  </c-space>
</template>
```

Manual deletion is an input event and does not invoke emptyValue. Form reset restores recorded initial values. See [Input value model and interaction](llms/en-US/components/input.md).

### Valid empty-string option

All has value `''` and remains selected. emptyValues excludes it with `[null, undefined]`, while emptyValue independently clears to null. Clear, then choose All again and compare model outputs.

Example source: src/select/__demos__/en-US/empty-value.vue

```vue
<script setup lang="ts">
import { reactive, ref } from "vue";
const model = reactive({ status: "" as string | null });
const multiple = ref(["active"]);
const optional = ref<string | undefined>("active");
const options = [
  { value: "", label: "All" },
  { value: "active", label: "Active" },
];
</script>
<template>
  <c-space direction="column">
    <p>
      All uses an empty string as a valid option value. Clearing produces null.
    </p>
    <c-form :model="model" layout="vertical">
      <c-form-item field="status" label="Status">
        <c-select
          v-model="model.status"
          :options="options"
          edit-mode="direct"
          clearable
          :empty-values="[null, undefined]"
          :empty-value="null"
        />
      </c-form-item>
    </c-form>
    <c-button @click="model.status = ''">Choose All</c-button>
    <p>
      Current model: <output>{{ JSON.stringify(model.status) }}</output>
    </p>
    <c-form layout="vertical">
      <c-form-item label="Multiple: clear to []">
        <c-select
          v-model="multiple"
          :options="options"
          edit-mode="direct"
          multiple
          clearable
          :empty-value="() => []"
        />
        <output>{{ JSON.stringify(multiple) }}</output>
      </c-form-item>
      <c-form-item label="Single: clear to undefined">
        <c-select
          v-model="optional"
          :options="options"
          edit-mode="direct"
          clearable
          :empty-value="() => undefined"
        />
        <output>{{ String(optional) }}</output>
      </c-form-item>
    </c-form>
  </c-space>
</template>
```

Select preserves empty-string options by default. Explicit settings align field and required semantics. Deleting the search query does not delete selection. See [Select value model and linked fields](llms/en-US/components/select.md).

### Empty markers and valid zero

Include -1 in emptyValues when an API uses it for missing data; also set emptyValue=-1 if clearing should emit it. The initial input is blank while the model stays -1. Set it to 0 to see a valid zero, then clear back to -1.

Example source: src/input-number/__demos__/en-US/empty-value.vue

```vue
<script setup lang="ts">
import { reactive, ref } from "vue";
const model = reactive({ quantity: -1 as number | null | undefined });
const restored = ref<number | null | undefined>(12);
</script>
<template>
  <c-space direction="column">
    <p>
      -1 means missing and renders blank; 0 remains a valid number. Clearing
      produces -1.
    </p>
    <c-form :model="model" layout="vertical">
      <c-form-item field="quantity" label="Quantity">
        <c-input-number
          v-model="model.quantity"
          edit-mode="direct"
          clearable
          :empty-values="[null, undefined, -1]"
          :empty-value="-1"
        />
      </c-form-item>
    </c-form>
    <c-space wrap>
      <c-button @click="model.quantity = 0">Set to 0</c-button>
      <c-button @click="model.quantity = -1">Set to -1</c-button>
    </c-space>
    <p>
      Current model: <output>{{ String(model.quantity) }}</output>
    </p>
    <p>This field clears to 0 without treating 0 as missing.</p>
    <c-form layout="vertical">
      <c-form-item label="Clear restores valid zero">
        <c-input-number
          v-model="restored"
          edit-mode="direct"
          clearable
          :empty-value="0"
        />
        <output>{{ String(restored) }}</output>
      </c-form-item>
    </c-form>
  </c-space>
</template>
```

0 and false are valid by default; do not classify both with `!value`. InputNumber manual empty commits retain numeric parsing rules and may emit undefined. See [InputNumber numeric input and formatting](llms/en-US/components/input-number.md).

### Empty markers and required validation

Form provides `[null, undefined, -1]` to its fields, while Select defines clear output -1. Validate the initial value, select a department and validate again, then clear and validate the missing value.

Example source: src/form/__demos__/en-US/empty-values-validation.vue

```vue
<script setup lang="ts">
import { reactive, ref } from "vue";
const model = reactive({ department: -1 as number | null | undefined });
const form = ref();
const result = ref("Not validated");
const options = [
  { value: 1, label: "Engineering" },
  { value: 2, label: "Product" },
];
async function validate() {
  const errors = await form.value.validate();
  result.value = errors ? "Required error" : "Valid";
}
</script>
<template>
  <c-space direction="column">
    <p>
      Validate the initial -1, then select a department and validate again.
      Clearing restores -1.
    </p>
    <c-form
      ref="form"
      :model="model"
      layout="vertical"
      :empty-values="[null, undefined, -1]"
    >
      <c-form-item field="department" label="Department" required>
        <c-select
          v-model="model.department"
          :options="options"
          edit-mode="direct"
          clearable
          :empty-value="-1"
        />
      </c-form-item>
    </c-form>
    <c-button @click="validate">Validate</c-button>
    <p role="status">{{ result }}</p>
    <p>
      Current model: <output>{{ String(model.department) }}</output>
    </p>
  </c-space>
</template>
```

emptyValue=-1 alone does not identify -1 as empty; emptyValues alone does not change clear output. Required runs on validation calls or configured triggers, not merely because an input looks blank. See [Form validation and submission](llms/en-US/components/form.md).

### Reading placeholders and inheritance

Initially, Name inherits Form's default `'-'`, Code uses the FormItem override, Nickname uses the field override, and Quantity remains 0. Change Form's text to No data: only inheriting empty fields change. Toggle reading/editing and observe the unchanged model.

Example source: src/form/__demos__/en-US/empty-text.vue

```vue
<script setup lang="ts">
import { reactive, ref } from "vue";
const reading = ref(true);
const emptyText = ref("-");
const model = reactive({
  name: null as string | null,
  code: null as string | null,
  nickname: null as string | null,
  quantity: 0 as number | null | undefined,
});
</script>
<template>
  <c-space direction="column">
    <p>
      Initially, reading mode shows “-” for Name, overrides for Code and
      Nickname, and the valid number 0 for Quantity.
    </p>
    <c-space wrap>
      <c-button @click="reading = !reading">Toggle reading/editing</c-button>
      <c-button @click="emptyText = 'No data'">Use “No data”</c-button>
      <c-button @click="emptyText = '-'">Use default “-”</c-button>
    </c-space>
    <c-form
      :model="model"
      layout="vertical"
      :read-pretty="reading"
      :empty-text="emptyText"
    >
      <c-form-item field="name" label="Name: inherits Form"
        ><c-input v-model="model.name"
      /></c-form-item>
      <c-form-item
        field="code"
        label="Code: FormItem override"
        empty-text="Unassigned"
        ><c-input v-model="model.code"
      /></c-form-item>
      <c-form-item
        field="nickname"
        label="Nickname: field override"
        empty-text="Unassigned"
        ><c-input v-model="model.nickname" empty-text="Anonymous"
      /></c-form-item>
      <c-form-item field="quantity" label="Quantity"
        ><c-input-number v-model="model.quantity"
      /></c-form-item>
    </c-form>
    <p>
      Current model: <output>{{ JSON.stringify(model) }}</output>
    </p>
  </c-space>
</template>
```

Precedence is **Field > FormItem > Form > '-'**. Explicit emptyText=`''` renders blank; custom read slots win. This text is separate from an input placeholder and never becomes validation or submitted data. See [Form field presentation and interaction](llms/en-US/components/form.md).

## Rules and boundaries

### emptyValues: recognize the current model

Field settings override FormItem, which overrides Form. Lists replace rather than merge. Unconfigured text fields recognize null, undefined and the empty string; Select and numeric fields retain their nullish defaults.

Scalars use includes; 0 and false remain valid by default. Objects use reference identity. Empty arrays always mean an empty collection; nonempty `[null]` does not. An explicit empty list removes additional scalar markers without turning an empty collection into a selection.

Fixed state controls and Upload consume the policy for reading and required without rewriting checked state, bounds or transport. Invalid dates and unfinished numeric drafts retain domain rules.

### emptyValue: define clear output

Omission preserves component defaults. Check each component's supported types: Input declares string/null and corresponding factories. Where undefined output is supported, such as InputNumber and date/time fields, use `:empty-value="() => undefined"`; a directly bound undefined leaves the fallback in place.

Factories run during actual clear actions, not initialization, reading or validation. Arrays follow existing independent-result rules. Output is not automatically classified as empty: clearing to 0 can restore valid data.

Some shared editing panels fall back to defaultValue. Their clear action updates a draft; confirmation commits and cancellation discards it. Clear icons, manual deletion, removing the last item and reset retain component-specific behavior.

### Required and custom rules

With explicit emptyValues, built-in required follows the primary field policy. Unconfigured validation retains each library's behavior; Cedar b-validate and Maple function/Zod validation need not agree on every boundary value.

Custom validators, Zod, min/max and enum receive raw values. A UI marker -1 does not make `number().positive()` accept it; business schemas define optional handling. Recognition also does not imply business validity.

false is valid by default, so required does not mean must agree. Classify false explicitly or require true in a custom agreement rule. Prefer one primary field per FormItem and separate independently validated values.

### Controlled ownership

Business emptiness differs from ownership. Adding -1 or removing undefined from emptyValues does not change existing controlled predicates. Do not replace every internal undefined check with isEmpty: ownership, failed parsing, invalid dates and business markers have distinct meanings.

## Relationship to Element Plus

The separation follows [Element Plus configuration](https://element-plus.org/en-US/component/config-provider.html#empty-values-configurations) and [useEmptyValues](https://github.com/element-plus/element-plus/blob/dev/packages/hooks/use-empty-values/index.ts). Our emptyValue serves the role of valueOnClear; no synonym is added.

We use Form/FormItem inheritance and action-time factories, preserving component defaults and collection rules. Array deep equality, clear-output warnings and ConfigProvider integration are not copied.

---

Document: llms/en-US/guide/llms.md

<!-- Source: docs/guide/llms.en-US.md; locale: en-US; page: /en/guide/llms/ -->

# LLM documentation

Cedar Design Web provides plain text and Markdown documentation for large language models (LLMs), including guides, component APIs and Vue examples. Give an AI coding assistant the online URLs so it can consult the documentation before writing code.

## Online documentation

Assistants that can read web pages can access these URLs directly. **Start with the index and read the component pages relevant to your task.**

| Document | Online URL | When to use |
| --- | --- | --- |
| Documentation index | [https://cedar.show/llms.txt](https://cedar.show/llms.txt) | Find guides and individual component Markdown pages; recommended starting point |
| Full documentation | [https://cedar.show/llms-full.txt](https://cedar.show/llms-full.txt) | Read all documentation and examples when the tool has enough context capacity |

Each component in the index has its own Markdown URL. Open it, give it to an assistant, or save it locally.

## Use with an AI assistant

### Provide the documentation URL

Copy this prompt and add your requirements at the end:

```text
Use Cedar Design Web and Vue 3 to implement my requirements.
Read the official documentation index first: https://cedar.show/llms.txt
Then read the quick start and relevant component pages. Check installation, imports and styles.
Use only the documented props, events, slots and examples.
If an API is not documented, say so instead of guessing.

My requirements:
```

### Add project reference material

If your coding assistant supports documentation sources, add the online index URL above. In your project instructions, ask it to consult the official documentation when using `@cedar-design/ui`.

If the tool cannot access the web, save the files you need as `.txt` or `.md` and attach them to your task. The full document may exceed tool reading limits; prefer the index and individual pages for focused tasks.

## Choose a language

| Language | Documentation index | Full documentation |
| --- | --- | --- |
| 中文 | [https://cedar.show/llms.zh-CN.txt](https://cedar.show/llms.zh-CN.txt) | [https://cedar.show/llms-full.zh-CN.txt](https://cedar.show/llms-full.zh-CN.txt) |
| English | [https://cedar.show/llms.en-US.txt](https://cedar.show/llms.en-US.txt) | [https://cedar.show/llms-full.en-US.txt](https://cedar.show/llms-full.en-US.txt) |

Language-specific files only include authored documentation in that language. Missing translations are not generated automatically. Use the combined index above to find all available pages.

## Content and updates

Files are generated from the guides and component documentation. API tables are retained and Demo references are expanded to Vue source. Relative imports inside examples remain relative to their annotated source paths.

Files are regenerated during each documentation site build and deployed with the site. Check that the documentation matches your installed library version.

---

Document: llms/en-US/index.md

<!-- Source: docs/en/README.md; locale: en-US; page: /en/ -->

## Cedar × Maple. Two platforms, one architecture.

Cedar is the desktop counterpart to Maple. The two libraries align component APIs, interaction semantics and design tokens, so familiar patterns carry across platforms while each keeps the interactions its platform needs.

| | Cedar Design Web | Maple Design Mobile |
| --- | --- | --- |
| Platform | Desktop · mouse and keyboard | Mobile · touch |
| Components | Shared API and behavior conventions | Shared API and behavior conventions |
| Themes | Semantic tokens · brand themes · light and dark modes | Semantic tokens · brand themes · light and dark modes |
| Explore | You are here | [Visit Maple ↗](https://maple.show) |

## Start with Cedar

```shell
pnpm add @cedar-design/ui
```

See the [quick start guide](en/guide/quickstart) for setup, component imports and styles. For mobile applications, explore [Maple Design Mobile](https://maple.show).

## Contributors

孟帅 · 吴甲明

---

Document: llms/en-US/showcase/loading.md

<!-- Source: docs/en/showcase/loading.md; locale: en-US; page: /en/showcase/loading/ -->

# Loading and waiting

Explore an event registration workspace. Try each component, hold all loading states, or start a two-second local wait. Labels in the live scenario are currently in Chinese.

1. Fill in registration information or use the button on its card to start a two-second wait.
2. Enable “全部保持加载” to compare every visible indicator; “重置加载” restores the state without clearing input.
3. Toggle editing independently, then compare default indicators and bottom lines on decorated fields.
4. Open the confirmation dialog to observe before-close feedback, including a rejected close.

Example source: docs/showcase/demos/loading-lab.vue

```vue
<script setup lang="ts">
import { computed, markRaw, onBeforeUnmount, reactive, ref } from 'vue'
import CButton from '../../../src/button'
import '../../../src/button/style'
import CSplitButton from '../../../src/split-button'
import '../../../src/split-button/style'
import CLink from '../../../src/link'
import '../../../src/link/style'
import CSwitch from '../../../src/switch'
import '../../../src/switch/style'
import CTag from '../../../src/tag'
import '../../../src/tag/style'
import CInput from '../../../src/input'
import '../../../src/input/style'
import CTextarea from '../../../src/textarea'
import '../../../src/textarea/style'
import CInputNumber from '../../../src/input-number'
import '../../../src/input-number/style'
import CSelect from '../../../src/select'
import '../../../src/select/style'
import CCascader from '../../../src/cascader'
import '../../../src/cascader/style'
import CAutoComplete from '../../../src/auto-complete'
import '../../../src/auto-complete/style'
import CDate from '../../../src/date'
import '../../../src/date/picker/style'
import CDateRange from '../../../src/date-range'
import CTime from '../../../src/time'
import '../../../src/time/picker/style'
import CTimeRange from '../../../src/time-range'
import CPeopleSelect from '../../../src/people-select'
import '../../../src/people-select/style'
import CSearch from '../../../src/search'
import '../../../src/search/style'
import CFieldDecorator from '../../../src/field-decorator'
import '../../../src/field-decorator/style'
import CTable from '../../../src/table'
import '../../../src/table/style'
import CList from '../../../src/list'
import '../../../src/list/style'
import CSkeleton from '../../../src/skeleton'
import '../../../src/skeleton/style'
import CLoading from '../../../src/loading'
import '../../../src/loading/style'
import CTreeSelect from '../../../src/tree-select'
import '../../../src/tree-select/style'
import CInputTag from '../../../src/input-tag'
import '../../../src/input-tag/style'
import CMention from '../../../src/mention'
import '../../../src/mention/style'
import CForm from '../../../src/form'
import '../../../src/form/style'
import { FormItem as CFormItem } from '../../../src/form'
import CDialog from '../../../src/dialog'
import '../../../src/dialog/style'
const cities = [{ label: '上海', value: 'shanghai' }, { label: '杭州', value: 'hangzhou' }]
const venues = [{ label: '上海', value: 'shanghai', children: [{ label: '设计中心', value: 'studio' }] }]
const fieldCards = [{ id: 'input', component: markRaw(CInput), title: '姓名', description: '查询报名信息', props: { defaultValue: '林小满', placeholder: '姓名' }, text: '', lockable: true },
{ id: 'textarea', component: markRaw(CTextarea), title: '备注', description: '保存报名备注', props: { defaultValue: '希望参加设计工作坊', placeholder: '备注' }, text: '', lockable: true },
{ id: 'input-number', component: markRaw(CInputNumber), title: '同行人数', description: '更新人数', props: { defaultValue: 2, min: 1 }, text: '', lockable: true },
{ id: 'select', component: markRaw(CSelect), title: '活动城市', description: '读取候选城市', props: { defaultValue: 'shanghai', options: cities, editMode: 'direct' }, text: '', lockable: true },
{ id: 'cascader', component: markRaw(CCascader), title: '活动场地', description: '读取级联场地', props: { options: venues, editMode: 'direct' }, text: '', lockable: true },
{ id: 'auto-complete', component: markRaw(CAutoComplete), title: '活动搜索', description: '查询匹配活动', props: { options: ['设计工作坊', '开发者交流'], placeholder: '搜索活动' }, text: '', lockable: true },
{ id: 'date', component: markRaw(CDate), title: '报名日期', description: '读取可选日期', props: { editMode: 'direct' }, text: '', lockable: true },
{ id: 'date-range', component: markRaw(CDateRange), title: '活动日期范围', description: '查询可用档期', props: { editMode: 'direct' }, text: '', lockable: true },
{ id: 'time', component: markRaw(CTime), title: '到场时间', description: '读取可用时间', props: { editMode: 'direct' }, text: '', lockable: true },
{ id: 'time-range', component: markRaw(CTimeRange), title: '参与时段', description: '查询可用时段', props: { editMode: 'direct' }, text: '', lockable: true },
{ id: 'people-select', component: markRaw(CPeopleSelect), title: '同行伙伴', description: '读取人员信息', props: { options: [{ label: '林小满', value: 'lin' }], editMode: 'direct' }, text: '', lockable: true },
{ id: 'search', component: markRaw(CSearch), title: '搜索报名', description: '查询报名记录', props: { placeholder: '输入姓名' }, text: '', lockable: true },
{ id: 'field-decorator', component: markRaw(CFieldDecorator), title: '通用字段容器', description: '观察容器的默认与底线反馈', props: {}, text: '容器内容', lockable: true },
{ id: 'tree-select', component: markRaw(CTreeSelect), title: '组织部门', description: '读取组织树', props: { options: [{ label: '设计部', value: 'design', children: [{ label: '体验组', value: 'ux' }] }], editMode: 'direct' }, text: '', lockable: true },
{ id: 'input-tag', component: markRaw(CInputTag), title: '活动标签', description: '保存标签', props: { defaultValue: ['设计', '交流'] }, text: '', lockable: true },
{ id: 'mention', component: markRaw(CMention), title: '邀请同伴', description: '查询提及候选', props: { options: [{ label: '林小满', value: 'lin' }] }, text: '', lockable: true }]
const actionCards = [{ id: 'button', component: markRaw(CButton), title: '提交报名', description: '业务控制按钮等待', props: {}, text: '提交报名', lockable: true },
{ id: 'split-button', component: markRaw(CSplitButton), title: '报名操作', description: '主按钮等待', props: {}, text: '保存报名', lockable: true },
{ id: 'link', component: markRaw(CLink), title: '查看报名详情', description: '链接等待', props: {}, text: '查看详情', lockable: true },
{ id: 'switch', component: markRaw(CSwitch), title: '接收短信', description: '开关保存', props: { defaultValue: true }, text: '', lockable: true },
{ id: 'tag', component: markRaw(CTag), title: '参与者身份', description: '标签状态更新', props: {}, text: '体验官', lockable: true }]
const groups = [{ title: '01 · 填写与数据选择', cards: fieldCards },
{ title: '02 · 提交与状态操作', cards: actionCards }]
const held = ref(false)
const lock = ref(false)
const line = ref(false)
const pending = reactive<Record<string, boolean>>({})
const completed = reactive<Record<string, boolean>>({})
const timers = new Map<string, ReturnType<typeof setTimeout>>()
const ids = [...fieldCards, ...actionCards].map(card => card.id).concat(['table', 'list', 'skeleton', 'loading'])

const busyCount = computed(() => ids.filter(id => isLoading(id)).length)
const status = ref('点击卡片上的「体验等待」，对照加载与恢复。')
function isLoading(id: string) { return held.value || Boolean(pending[id]) }
function run(id: string) {
  if (held.value || pending[id]) return
  pending[id] = true
  completed[id] = false
  status.value = `${id} 正在等待；2 秒后恢复。`
  timers.set(id, setTimeout(() => {
    pending[id] = false
    completed[id] = true
    timers.delete(id)
    status.value = `${id} 已完成，输入内容保留。`
  }, 2000))
}
function runAll() { held.value = false; ids.forEach(run) }
function reset() {
  held.value = false
  timers.forEach(timer => clearTimeout(timer))
  timers.clear()
  ids.forEach(id => { pending[id] = false; completed[id] = false })
  status.value = '已恢复全部加载状态，填写内容保留。'
}
const open = ref(false)
const allowClose = ref(true)
const guardStatus = ref('打开报名确认，关闭时等待 2 秒。')
const guardWaits = new Map<ReturnType<typeof setTimeout>, (allowed: boolean) => void>()
function beforeClose() {
  guardStatus.value = '正在检查报名状态…'
  return new Promise<boolean>(resolve => {
    const timer = setTimeout(() => {
      guardWaits.delete(timer)
      guardStatus.value = allowClose.value ? '检查通过，允许关闭。' : '本次未通过，弹层保留，可再次尝试。'
      resolve(allowClose.value)
    }, 2000)
    guardWaits.set(timer, resolve)
  })
}
onBeforeUnmount(() => { reset(); guardWaits.forEach((resolve, timer) => { clearTimeout(timer); resolve(false) }); guardWaits.clear() })
const columns = [{ title: '参与人', dataIndex: 'name' }, { title: '活动', dataIndex: 'event' }]
const rows = [{ key: '1', name: '林小满', event: '设计工作坊' }, { key: '2', name: '周青', event: '开发者交流' }]
</script>
<template>
  <div class="loading-lab">
    <header class="loading-lab__hero">
      <p class="loading-lab__eyebrow">LOADING / 活动报名工作台</p>
      <h2>让每一次等待都看得见</h2>
      <p>逐项填写报名信息，观察各组件如何表达等待；也可以保持全部加载，比较位置、尺寸与布局。</p>
      <CForm layout="vertical">
        <div class="loading-lab__controls">
          <CFormItem label="全部保持加载"><CSwitch v-model="held" aria-label="全部保持加载" /></CFormItem>
          <CFormItem label="等待时禁止编辑"><CSwitch v-model="lock" aria-label="等待时禁止编辑" /></CFormItem>
          <CFormItem label="文本字段使用底线"><CSwitch v-model="line" aria-label="文本字段使用底线" /></CFormItem>
        </div>
      </CForm>
      <div class="loading-lab__buttons"><CButton @click="runAll">全部等待 2 秒</CButton><CButton variant="outline" @click="reset">重置加载</CButton><span>{{ busyCount }} / {{ ids.length }} 项正在等待</span></div>
      <p role="status" aria-live="polite">{{ status }}</p>
      <small>所有等待均在本地模拟。loading 与 disabled 分别控制；切换底线只影响支持 loading-mode 的字段。</small>
    </header>
    <section v-for="group in groups" :key="group.title" class="loading-lab__section">
      <h3>{{ group.title }}</h3>
      <div class="loading-lab__grid">
        <article v-for="card in group.cards" :key="card.id" class="loading-lab__card" :data-loading-card="card.id">
          <div class="loading-lab__heading"><strong>{{ card.title }}</strong><code>{{ card.id }}</code></div>
          <p>{{ card.description }}</p>
          <div class="loading-lab__preview">
            <component v-if="card.text" :is="card.component" v-bind="card.id === 'split-button' ? { ...card.props, buttonProps: { loading: isLoading(card.id), disabled: lock && isLoading(card.id) } } : card.props" :loading="isLoading(card.id)" :disabled="lock && isLoading(card.id)" @change="run(card.id)">{{ card.text }}</component>
            <component v-else :is="card.component" v-bind="card.id === 'split-button' ? { ...card.props, buttonProps: { loading: isLoading(card.id), disabled: lock && isLoading(card.id) } } : card.props" :loading="isLoading(card.id)" :loading-mode="line ? 'line' : 'default'" :disabled="lock && isLoading(card.id)" @change="run(card.id)" />
          </div>
          <div class="loading-lab__footer"><CButton size="sm" variant="text" :disabled="isLoading(card.id)" @click="run(card.id)">体验等待</CButton><span>{{ isLoading(card.id) ? '等待中…' : completed[card.id] ? '已完成' : '就绪' }}</span></div>
        </article>
      </div>
    </section>
    <section class="loading-lab__section">
      <h3>03 · 内容区域</h3>
      <div class="loading-lab__grid">
        <article v-for="kind in ['table', 'list', 'skeleton', 'loading']" :key="kind" class="loading-lab__card" :data-loading-card="kind">
          <div class="loading-lab__heading"><strong>{{ {upload:'上传报名材料',table:'报名记录',list:'报名清单',skeleton:'初次读取占位',loading:'通用内容等待'}[kind] }}</strong><code>{{ kind }}</code></div>
          <div class="loading-lab__preview">
            
            <CTable v-if="kind === 'table'" :loading="isLoading(kind)" :columns="columns" :data="rows" :pagination="false" />
            <CList v-if="kind === 'list'" :loading="isLoading(kind)"><p>林小满 · 设计工作坊</p><p>周青 · 开发者交流</p></CList>
            <CSkeleton v-if="kind === 'skeleton'" :loading="isLoading(kind)"><p>报名信息已加载，可以继续填写。</p></CSkeleton>
            <CLoading v-if="kind === 'loading'" :loading="isLoading(kind)" tip="正在读取报名信息"><p class="loading-lab__placeholder">活动报名内容</p></CLoading>
          </div>
          <div class="loading-lab__footer"><CButton size="sm" variant="text" :disabled="isLoading(kind)" @click="run(kind)">体验等待</CButton><span>{{ isLoading(kind) ? '等待中…' : '就绪' }}</span></div>
        </article>
        
        
      </div>
    </section>
    <section class="loading-lab__section loading-lab__guard" data-loading-card="dialog">
      <h3>04 · 确认报名与关闭等待</h3>
      <p>关闭弹层时由 before-close 等待 2 秒。关闭检查不通过时保留弹层；可以切换后再次尝试。</p>
      <CForm layout="vertical"><CFormItem label="允许关闭"><CSwitch v-model="allowClose" aria-label="允许关闭" /></CFormItem></CForm>
      <CButton @click="open = true">打开报名确认</CButton>
      <CDialog v-model:open="open" title="确认报名" :before-close="beforeClose"><p>请确认活动报名信息。点击确认、取消或关闭，观察等待反馈。</p><CForm layout="vertical"><CFormItem label="允许关闭"><CSwitch v-model="allowClose" aria-label="弹层内允许关闭" /></CFormItem></CForm><p role="status">{{ guardStatus }}</p></CDialog>
      <p aria-live="polite">{{ guardStatus }}</p>
    </section>
  </div>
</template>
<style scoped>
.loading-lab { color: var(--c-sys-color-content-primary, inherit); min-width: 0; }
.loading-lab__hero, .loading-lab__guard { padding: 24px; border: 1px solid var(--c-sys-color-outline-default, #dce4e7); border-radius: 18px; background: var(--c-sys-color-surface-container, #f5f8f9); }
.loading-lab__eyebrow { letter-spacing: .12em; font-size: 12px; opacity: .7; }
.loading-lab__hero h2 { margin: 8px 0 12px; font-size: 28px; }
.loading-lab__controls { display: grid; grid-template-columns: repeat(auto-fit, minmax(180px, 1fr)); gap: 12px; }
.loading-lab__buttons, .loading-lab__footer { display: flex; align-items: center; flex-wrap: wrap; gap: 12px; }
.loading-lab__section { margin-block: 28px; }
.loading-lab__grid { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 16px; }
.loading-lab__card { min-width: 0; padding: 20px; border: 1px solid var(--c-sys-color-outline-default, #dce4e7); border-radius: 14px; }
.loading-lab__card--wide { grid-column: 1 / -1; }
.loading-lab__heading { display: flex; flex-wrap: wrap; align-items: center; justify-content: space-between; gap: 8px; }
.loading-lab__heading code { font-size: 12px; opacity: .65; }
.loading-lab__card p { font-size: 13px; opacity: .8; }
.loading-lab__preview { min-height: 72px; padding-block: 18px; min-width: 0; overflow-wrap: anywhere; }
.loading-lab__footer { justify-content: space-between; font-size: 12px; }
.loading-lab__placeholder, .loading-lab__popup { padding: 24px; }
.loading-lab__popup { min-width: 0; max-width: 90vw; }
@media (max-width: 600px) { .loading-lab__grid { grid-template-columns: minmax(0, 1fr); } .loading-lab__hero, .loading-lab__card, .loading-lab__guard { padding: 16px; } .loading-lab__hero h2 { font-size: 24px; } }
</style>
```

This page focuses on input surfaces, data selection, actions and content loading. Ordinary events do not collect Promises. Upload keeps per-file progress and before-hook feedback; Scheduler persistence guards are documented on its own page.

## More before-hook scenarios

### Drawer

Example source: src/drawer/__demos__/guard-protocol.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import type { DrawerBeforeClose } from "@cedar-design/ui";
const open = ref(false);
const mode = ref("promise");
const allowed = ref(true);
const status = ref("");
const check: DrawerBeforeClose = (payload, done, { signal }) => {
  status.value = `等待： ${payload.action}`;
  if (mode.value === "done") {
    setTimeout(() => {
      status.value = allowed.value ? "允许" : "阻止";
      done(!signal.aborted && allowed.value);
    }, 500);
    return;
  }
  return new Promise<boolean>((resolve) =>
    setTimeout(() => {
      status.value = allowed.value ? "允许" : "阻止";
      resolve(!signal.aborted && allowed.value);
    }, 500),
  );
};
</script>
<template>
  <c-space direction="column" align="stretch">
    <c-form-item layout="vertical" label="允许关闭"><c-switch v-model="allowed" aria-label="允许关闭" /></c-form-item>
    <c-form-item layout="vertical" size="sm" label="mode">
      <c-radio-group
        aria-label="mode"
        v-model="mode"
        :options="[
          { value: 'promise', label: 'Promise' },
          { value: 'done', label: 'done 回调' },
        ]"
        variant="button"
        size="sm"
      />
    </c-form-item>
    <c-button @click="open = true">打开</c-button>
    <c-drawer
      v-model:open="open"
      :before-close="check"
      @guard-error="status = 'Error'"
    >
      <p>关闭前等待片刻。可以关闭开关体验一次拦截，再在抽屉内重新允许关闭并重试。</p>
      <c-form-item layout="vertical" label="允许关闭"><c-switch v-model="allowed" aria-label="抽屉内允许关闭" /></c-form-item>
      <c-button @click="allowed = true; open = false">允许并关闭</c-button>
      <p role="status">{{ status }}</p>
    </c-drawer>
    <p role="status">{{ status }}</p>
  </c-space>
</template>
```

### Popconfirm

Example source: src/popconfirm/__demos__/guard-protocol.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import type { PopconfirmBeforeConfirm } from "@cedar-design/ui";
const open = ref(false);
const mode = ref("promise");
const allowed = ref(false);
const status = ref("");
const check: PopconfirmBeforeConfirm = (payload, done, { signal }) => {
  status.value = `等待： ${payload.action}`;
  if (mode.value === "done") {
    setTimeout(() => {
      status.value = allowed.value ? "允许" : "阻止";
      done(!signal.aborted && allowed.value);
    }, 500);
    return;
  }
  return new Promise<boolean>((resolve) =>
    setTimeout(() => {
      status.value = allowed.value ? "允许" : "阻止";
      resolve(!signal.aborted && allowed.value);
    }, 500),
  );
};
</script>
<template>
  <c-space direction="column" align="stretch">
    <c-switch v-model="allowed" />
    <c-form-item layout="vertical" size="sm" label="mode">
      <c-radio-group
        aria-label="mode"
        v-model="mode"
        :options="[
          { value: 'promise', label: 'Promise' },
          { value: 'done', label: 'done 回调' },
        ]"
        variant="button"
        size="sm"
      />
    </c-form-item>
    <c-button @click="open = true">打开</c-button>
    <c-popconfirm
      v-model:open="open"
      :before-confirm="check"
      @guard-error="status = 'Error'"
    >
      <template #default
        ><c-button v-if="true" @click="open = true">Confirm action</c-button
        ><span v-else>通过 beforeClose 关闭</span></template
      >
    </c-popconfirm>
    <p role="status">{{ status }}</p>
  </c-space>
</template>
```

---

Document: llms/en-US/themes.md

<!-- Source: src/themes/README.en-US.md; locale: en-US; page: /en/themes/ -->

# Themes

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Toggle

Example source: src/themes/__demos__/toggle.vue

```vue
<template>
  <c-space direction="column" fill>
    <c-space wrap>
      <c-button status="primary" @click="apply(Themes.default.light)">默认亮色</c-button>
      <c-button status="primary" @click="apply(Themes.default.dark)">默认暗色</c-button>
      <c-button status="primary" @click="apply(Themes.maple.light)">枫叶亮色</c-button>
      <c-button status="primary" @click="apply(Themes.maple.dark)">枫叶暗色</c-button>
    </c-space>

    <div class="preview c-rounded-md c-p-16">
      <div class="c-text-1 c-mb-8">主题预览</div>
      <div class="c-text-3 c-mb-16">主色按钮与语义文字会随 StyleProvider / cedar-theme 变化。</div>
      <c-space>
        <c-button status="primary">Primary</c-button>
        <c-button>Default</c-button>
        <span class="semantic-primary">primary</span>
        <span class="semantic-success">success</span>
        <span class="semantic-warning">warning</span>
      </c-space>
    </div>
  </c-space>
</template>

<script lang="ts" setup>
import { StyleProvider, Themes, type StyleVars } from '@cedar-design/ui'

function apply(theme: StyleVars | null) {
  StyleProvider.setStyleVars(theme)
}
</script>

<style scoped>
.preview {
  background: var(--c-color-fill-2);
  border: 1px solid var(--c-color-border-2);
}

.semantic-primary {
  color: var(--c-color-primary);
}

.semantic-success {
  color: var(--c-color-success);
}

.semantic-warning {
  color: var(--c-color-warning);
}
</style>
```